Cube Voyager Reference Guide Cube Voyager Reference GuideCitilabs® Cube Voyager Reference Guide Version 5.0 Copyright © 2007–2008 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 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 Cube Voyager Reference Guide 1 Introduction This chapter introduces you to Cube Voyager. Topics include: • • • Design concepts Program features Minimum system requirements Cube Voyager Reference Guide 1 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 1 a very complicated set of instructions, or can be as simple as computing and/or printing a number from a file. It is the user’s responsibility to design the process that is to be run. The binary files generated by Cube Voyager are designed to reduce disk storage requirements and reduce the amount of time spent on input/output. They have a proprietary format that can not be used by other software, but they can be translated to other formats by the user. Cube Voyager Reference Guide 3 1 Introduction Program features Program features Advanced features of the Cube Voyager software include: • Integration with ESRI’s ArcEngine allows reading and writing of supported file structures directly to and from a personal geodatabase Full multirouting transit system Intersection and link constrained traffic assignments Flexible scripting language for model run specifications True 32-bit system designed for operating systems such as Windows 95/98/NT/2000/XP All calculations are performed in 64-bit floating-point arithmetic Seamless file format compatibility with existing transportation planning packages such as TRANPLAN, 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) • • • • • • • • • • • • 4 Cube Voyager Reference Guide Introduction Program features 1 • Capability to link with user-generated native code Cube Voyager Reference Guide 5 . 1 Introduction Minimum system requirements Minimum system requirements Cube Voyager requires a Windows 95/98/NT/2000/XP environment in which to function. It is fairly safe to state that if a computer can run Windows. Cube Voyager is designed to run in a multitasking environment. The exact amount of RAM required can not be determined until an application actually runs and the combination of user options is diagnosed. Each cell value can be from 0 to 9 bytes in size. The largest storage requirements will be associated with matrices. most applications will not require any special RAM considerations. but Cube Voyager uses a proprietary data compression technique that helps to reduce the sizes. A matrix will contain zones × zones cells of information. it has enough RAM to run Cube Voyager. Additional disk space is required for the various files. Zonal data files are not very large. The system utilizes RAM as needed. This could possibly cause problems if one application is trying to update a file while other applications are accessing it. 6 Cube Voyager Reference Guide . networks. The user can control the matrix sizing. The largest networks will be only a few MB. A typical application will require zonal data files. and network sizes will depend upon the number of alternatives and variables that the user wishes to employ. there is a possibility that several simultaneous applications could try to access the same data files simultaneously. About 75 MB of disk space is required to install Cube Base and Cube Voyager. In such an environment. and matrices. Cube Voyager Reference Guide 2 Getting Started This chapter describes how to get started using Cube Voyager. Topics include: • • Installation Starting Cube Voyager Cube Voyager Reference Guide 7 . follow the steps outlined below: • • Install the Citilabs license CD first Once the license files are installed.2 Getting Started Installation Installation To install Cube Voyager. Cube Voyager should automatically be selected during the installation of Cube 8 Cube Voyager Reference Guide . Task Monitor sends the Cube Voyager Cube Voyager Reference Guide 9 .” in the Cube Base Reference Guide for a detailed description of this program. 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 14. point to Passenger Forecasting. When running a Cube Voyager application or program in Cube from Application Manager. See “Running application in Application Manager” on page 631 of the Cube Base Reference Guide and “Running a Cube Voyager. “Task Monitor.” in the Cube Base Reference Guide for general information on setting up an application in Application Manager. go to the Program menu. TP+. then VOYAGER to access Cube Voyager programs from the menus. “Application Manager. See Chapter 16. After creating a new Cube Voyager application or opening an existing one.Getting Started Starting Cube Voyager 2 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. 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. then type or browse for VOYAGER.EXE (the default directory is C:\Program Files\Citilabs\CubeVoyager). Run. Cube Voyager can be started from: Start Menu.2 Getting Started Starting Cube Voyager script file of the run to the Cube Voyager program to run and monitors and display status information about the run as shown in the figure below. Starting Cube Voyager from Windows If Cube Voyager has been properly installed. 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 10 Cube Voyager Reference Guide . while the Favorite button points to the Windows Favorite directory. The only difference is that the Browse button points to the current directory. 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. 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. Both buttons invoke an Open File dialog box. Cube Voyager Reference Guide 11 .Getting Started Starting Cube Voyager 2 • • • • 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. 2 Getting Started Starting Cube Voyager The Work Directory is defaulted to the directory where the job script file resides when a new job script file is selected. The default behavior is to have the Cube Voyager window maintain its current status. 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. the View Print File button can be pushed to view the resulting run print file. minimized or maximized. after the execution is completed. The Notify When Done check box can be used to bring the Cube Voyager window back on top when it’s done. respectively. When the application is finished. The Pause button can be used to pause the execution. 12 Cube Voyager Reference Guide . while the Abort button allows for pre-mature termination of the execution. if it has been minimized during execution. The window can be minimized or left open as Cube Voyager is executing. periodic messages will be written to the window. During execution. Cube Voyager Reference Guide 13 . 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.Getting Started Starting Cube Voyager 2 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.” for a detailed description of this process. 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. The following statement will initiate a Cube Voyager run from a command line with the appropriate parameters and options: Voyager. The path to 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: 14 Cube Voyager Reference Guide . Starting Cube Voyager from the command prompt You can run Cube Voyager completely from a command prompt (if this capability is available).EXE should be added to the PATH system variable. so that. it can be run from any working directories.2 Getting Started Starting Cube Voyager The About Voyager button can be used to get License and maintenance information and the version and date of all Cube Voyager programs as well as some standard machine information as shown on the About Voyager dialog below. the program will assign one based upon the following criteria: If there is a pppp.+-*/&|). If there is no pppp. Some files will always contain these characters (maximum 4 characters) as part of their name. The name may have a complete path in the typical operating system format.Getting Started Starting Cube Voyager 2 • scriptfile is the name of the file that contains the Cube Voyager script control statements.PRJ file in the working subdirectory: the prefix will be set to the last prefix in the file. If it is not specified. The pageht. • pppp is a prefix (or project) that is pertinent to this application.PRJ file that Cube Voyager reads is a valid Cube Voyager PRJ file. and are not a Cube Voyager operator ('". • pagewdth is the maximum length a printed line can have. pagewdth. it will generate a file by that name. In some operating environments (such as Windows). Warning: Be sure that any pppp. and runid parameters can be reset dynamically by Cube Voyager control statements within individual Cube Voyager programs. This will default to 58. The program will generate a print file and a var file with this prefix as its first characters. nor greater than 255. When set within the individual programs. The program automatically associates a unique sequence number with the prefix. Most individual programs will allow the prefix to be substituted directly for the ? character in their file names. The maximum value is 32767. The characters must be those that are acceptable as part of filenames to the operating system. This file may be in a different subdirectory than the -Spath argument. It may not be less than 72.PRJ. and a width can not be found from the Cube Voyager Cube Voyager Reference Guide 15 . it may be necessary to provide a fully qualified file name (path\filename). • pageht is the height (number of print lines) for a printed page of output. If the prefix is not designated. if the program can not find a height from the Cube Voyager PRJ file. their effect may be valid for only that program. in some operating environments. it may not be possible to log on to a subdirectory before starting the program.2 Getting Started Starting Cube Voyager PRJ file. Command line options: • • • • • • • • • /Startfor example to auto start the run. the user will log onto the desired subdirectory. Normally. and workdir will not need to be specified. and if so. (Windows may cause some problems in this area. they will be written with the appropriate length. changes to that subdirectory before it processes the other arguments (excluding filename). • runid can be used to specify a starting ID for the application. it will default to 132. 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 • • 16 Cube Voyager Reference Guide . But. it will try to obtain a starting ID from the Cube Voyager PRJ file with matching prefix.) When the program starts. Note that pagewdth will not cause longer length lines to be truncated or folded. If ID is not specified. 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. it checks if workdir is specified. Pressing Ctrl-Break can be normally used to prematurely terminate the run if the run dialog has been hidden. control will return to the windows command line interpreter. the Abort button on the Cube Voyager run dialog can be used. Cube Voyager Reference Guide 17 . periodic messages will be written to the Cube Voyager run dialog if /Hide is not on. Otherwise. When the Cube Voyager job is completed.Getting Started Starting Cube Voyager 2 • /WinHeight:xx As the Cube Voyager job is executing. 2 Getting Started Starting Cube Voyager 18 Cube Voyager Reference Guide . Cube Voyager Reference Guide 3 General Syntax This chapter describes the general syntax found in Cube Voyager. Topics include: • • • Introduction to Cube Voyager control statements Control statement syntax Standard control statements Cube Voyager Reference Guide 19 . spaces. and then the value(s) to be associated with the keyword./ * ^ & | = ). is logical here sfdus = 51-55 & . + . valid: . Valid continuation characters are: comma and mathematical and logical operators: ( . All control statements have the same general format. z=2-4.is logical here 48. the statement MUST continue onto the next line. A statement can be continued onto the next line by breaking it after a valid operator for the statement. continuation of previous line ZDATI=myfile. or more..3 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. Following the control word and one. . invalid: & doesn’t fit here mfdus= 61-65 20 Cube Voyager Reference Guide . valid: . valid: + is logical at this point d + e / f . A keyword is always followed by an equals (=) sign. invalid: = is not in proper context COMP a = b + c + . Each statement begins with a control word to tell the program what type of statement it is. If the last character on the statement (prior to any comments) is a valid operator for the statement. Example COMP a = b + c = . There may be as many keywords as are applicable to the control type. emp=21-30 pop=40. the character must be one that is in proper context for the statement. are keywords and their values. If no matching Cube Voyager variable is found. Topics include: • • • • • • • • • • Statement tokens (%. and is a literal replacement.. if there is a name in the environment that matches the string between the token symbols (case insensitive). A Cube Voyager variable is one that has been defined within the Cube Voyager Pilot program..General Syntax Control statement syntax 3 Control statement syntax This section describes the syntax. The replacement occurs ONLY when the statement is read..@ token. When the system reader finds a @.. of control statements. or has been added via a LOG statement in a RUN program.. When the Cube Voyager system reader routine finds a %.@) Any statement may contain tokens for substitution....% and @..% token. the token is not modified.. the entire token is replaced with the value from the environment. or components... the token is replaced with the contents of the Cube Voyager variable that matches the string. Cube Voyager Reference Guide 21 ..@... It should be noted that the environment is a copy of the environment when Cube Voyager began..@) Comments Null blocks Control blocks Control fields Keywords Subkeywords Keyword values and documentation descriptions Expressions Variable naming convention (general syntax) Statement tokens (%. There are two types of tokens: %.%) and (@. Any Cube Voyager *SET statements will NOT have altered the environment.%) and (@. retrieve value of xxx as set by prior matrix PRINT LIST=’ijk from Cube Voyager PILOT=’. If a statement is continued onto subsequent lines. and the line following the last blank line is considered as the continuation. will be OK Comments There may be comments appended to any control statement/line.). it is skipped over when the program reads the control statement. and 22 Cube Voyager Reference Guide . . each line may have comments.nam. Example FILEI NETI=myfile. The statement could also have been coded as: FILEI NETI=myfile. thus providing a document for the program application. Blank lines can be used for spacing purposes. I/P network. The block begins with /* and ends with */.dat . Zonal data As a program reads each control statement. retrieve value from Cube Voyager xxx = @matrix. Comments are very helpful and should be used whenever it helps to clarify the application. they are ignored. ijk . the record is not processed. Blank lines following a line with a continuation character are ignored. A semicolon (.xxx@ . this entire line is a comment In the previous example. ZDATI=zonal. it is diagnosed.) as the first character of a statement sets the entire statement as a comment. I/P network ZDATI=zonal. Zonal data .nam.dat . There may be any number of spaces before and/or after the semi-colon. If the first nonblank character of a data record is a semi-colon.3 General Syntax Control statement syntax Example ijk = @ijk@ . Comments must be preceded by a semi-colon (. Null blocks The null block is a section of the input stream that is not processed by the program. and listed to the system print file. the FILEI control statement is continued because a comma follows the network filename. . The statement will terminate with the {} character. Currently a control block may be on one line. The statement can optionally be continued onto subsequent lines by use of a continuation character.dat . A null block can be used to block out stream terminators and even portions of a control stream specifying other programs to be run. Hint: to run only the first portion of an input stream. and must be followed by at least one key word. A control block begins with the control word. Control blocks A control block can be used to block a control statement.. or it follows a semicolon (. place an unmatched /* record after the last desired statement.. but not recommend ** FILEI NETI=ipfile. {} . if another /* appears before the terminating */ is read. Zonal data */ FILEO .nam. All data up to the next {} character are considered as part of the statement. If a matching */ is not found.dat . the end of the block is set to the end of file on the control stream. it will not be recognized.net */ FILEI NETI=myfile. but planned revisions Cube Voyager Reference Guide 23 . The rule is that each /* must have a matching */.. The standard format for a control statement requires that the first word of the statement must be a valid control word. ** valid.nam. I/P network /* ZDATI=zonal. 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. white space. the program assumes that there is another null block within the current one.) on a line. Zonal data . Therefore. If multiple lines are used. because FILEI is to be continued. they need not contain continuation characters... the remainder of the input stream will be appended to the current statement. care must be exercised when null blocks are used. /* I/P network */ ZDATI=zonal.. {} . Examples FILEI NETI=myfile. and the {} character.").' or ". will be an error. If the terminating {} is embedded within a literal string ('. Alternatively. a control block can be used.net /* FILEO NETO=opfile.General Syntax Control statement syntax 3 blocks may be nested. Care must be taken: if there is no {}. . . because they are also the same as a minus sign.. The field does not contain the delimiter.5 or 1. ZDATI = ..4. } FILEI {NETI = . . In this system. The rules applied when a dash is between fields are: • • If the dash touches the first field. comma.2. however. input network } . 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. .. so it is advisable to not code them that way. that tradition is carried over to this system. Likewise 1 2 3 4 5 is the same as 1. MATI = . Thus. Because many transportation-planning programs have traditionally used a dash as a field separator. If a field is terminated by a dash. FILEI { NETI = . 24 Cube Voyager Reference Guide . it is the beginning of a range. the blank will suffice. or delimiter. dash. fields are thought of as the characters that begin a word and continue until a field terminator. Control fields A field is a number. or it touches neither field. the dash is the sign for the second field. it is a negative value. which is the same as A= B.. The standard field delimiters are blank.. When a field is followed by a blank. is detected.3 General Syntax Control statement syntax will probably preclude this capability. that stands by itself on a control statement. unless it could also be construed as a range. valid: the {} is on a separate line. continuation character not required. A=B is the same as A = B. so care must be taken. If a field is begun by a dash. invalid: comment precedes the {}. or any mathematical operator (+-*/|&).. If the dash touches the second field without touching the first field. input network } . } . it is a range. A dash is therefore used to specify ranges of values. There is no reason to have a control block on a single line... equals sign. 4 5..3... not recommended – possible future change FILEI {NETI = . Dashes do cause some ambiguity. FILEI {NETI = . 2 3. and to specify negative values. . or character string. the data is entered beginning at the first location in the array. so that the values are loaded into the array beginning at a specified location. Optionally. error! value 1 and value -5 value 1 and range: 3 through 5. three ways of specifying: value 1 and value 5. -5 13–5 -1-5 -1--5 -8--5 -8 .. and results of numeric expressions. strings. and there is another dash between the first field and the dash. ranges are invalid in such expressions. and value -5. the vector keyword may be subscripted. value 1. ELSEIF . but less confusing. When a vector keyword is specified.-5 1 . This is described in more detail in “IF . 1 . It should be noted that this syntax is somewhat different for numeric expression fields as noted below. 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. range: -8 through -5.. it is a range with the second field being negative.5.. descending.. 5 1. Select expressions do allow ranges for single variables. Examples of numbers specified as single or range values Expression 1-5. 1. so it is suggested that parenthesis be used to remove any ambiguities in expressions.General Syntax Control statement syntax 3 • If the dash touches the second field.. 1 – 5 1 –5 1 5. range: –1 through +5 range: -1 through -5. A subscript is specified by inclosing it within Cube Voyager Reference Guide 25 . ENDIF” on page 48.-5 Meaning three ways of specifying range: 1 through 5.5. ELSE . and could be an error.. 1. range: -8 through -5. Keywords may sometimes specify vector data (multiple values for successive entries in a curve or array). but doesn’t look nice. 50 . but a level 3 keyword may be used only following a level 2. When a keyword is subscripted. this is usually only when the keyword is on a COMP (or similar type of statement). For example: capacity stratified by lanes (row) and spdclass (column). Some keywords allow double subscripts to indicate a matrix of rows and columns. the data spills into the next row (beginning at that row’s column 1). single value format VAL=10. there may be no special characters prior to the right bracket (]). Examples LINKI= LIINKI[3]= NOX[2][7]= NOX[3]= . VAL[6]=50 VAL[55]=770. Most keywords that are subscripted are specific to the program. One is the minimum value for rows and columns.3 General Syntax Control statement syntax square brackets []. the subscript must fill the space between the []. it is assumed to be one. but it will not fill beyond the end of the array. but they are rare. Level 4 is the maximum. If there is no column designation. keyword. 3.35.20.1250 . there are two sets of brackets [row][column]. and the subscript must be an integer constant. A level 2 keyword may be used at any time. and each of those sub keywords may possibly have another sub keyword (level 4) associated with them. VAL[1]=10. In certain cases. If there is more input data than is allowed in a row. Some programs allow certain vectored keywords to have a variable as the subscript. VAL[2]=20. VAL[84]=1250 VAL(2) .40. A level 4 keyword may be used 26 Cube Voyager Reference Guide . or 4. …. VAL[83]=1200. In such cases. VAL[83]=1200. the subscript must be [2] Subkeywords Some keywords (internal level 2) may have further descriptive keywords (level 3) associated with them.30. 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. and will be more fully defined in the specific program documentation. invalid. three-dimensional arrays are allowed. name. With the comma.General Syntax Control statement syntax 3 only following a level 3 or 4 keyword. var=a. can not be specified (4) MAX= . beg=6. the same level.b. These subkeywords (4) BEG= . LINKI[2]=myfile2. used only if LINKI has proceeded them. Cube Voyager Reference Guide 27 . var=dist. beg=1. len=3.dist. and (4) MIN= . since LINKI is a valid FILEI invoking keyword. (4) TYP= . The layering is as follows: Example (1) FILEI (2) LINKI= (3) EXCLUDE= . These are same level (3). Without the comma. beg=14.len=5. An example is the Network program FILEI statement. are all at (4) LEN= . The typ=c applies only to street. A sub level keyword applies only to the prior higher ranking keyword.typ=c. var=street. the comma following typ=c on the third line is not necessary. and can be (3) VAR= . DBF file In this example. they form two FILEI statements. the four lines form a single FILEI statement.dbf. var=a.len=5. unless VAR= is LINKI=myfile. If a filename contains a question mark (?). MYFILE. With such values.true/false character.ext). In English.) Integer -.23E-2).numbers that are entered without decimal points. In some cases. the ? is immediately revised to PPPP. False). . (Single quotes may be used.numbers that may contain decimal points..MAT. but only the first character is used.) (For example. True). .NET. where PPPP is the Cube Voyager prefix that has been set by the user. Programs may accept various responses depending upon the native language of the user. but if the operating system allows single quotes in the filename. the entire field must be enclosed within '. double quotes are required). Any of the following letters (case sensitive) within the criteria list indicate what type of data must be entered for the keyword. the system reader doesn’t know if the dash is an exponent sign or a field separator. only the first character will be processed. To preclude the program from appending an extension. and the negative response could be (No. If the name is to contain any special characters that may be in conflict with the system delimiters. '1. the name must be enclosed within double quotes. 0.23E-2'). Real numbers are entered as single precision values: precision is restricted to the 6-7 most significant digits (system dependant). a true response could possibly be any of (Yes . the value will be processed as the nearest integer.any valid text string.filenames in a format acceptable to the operating system. for example.|.DBF... Letter C D F Description Character -. Boolean Response -. In the documentation.1. Filename -.). if the filename does not contain an extension (. each keyword description begins with a criteria list enclosed within |.3 General Syntax Control statement syntax Keyword values and documentation descriptions What may follow the = for a keyword depends upon the criteria for the keyword. Double — Double-precision real numbers. the program may want to append an appropriate extension (. I R ? 28 Cube Voyager Reference Guide .. If the number is to be entered with a negative exponent (for example. If a decimal point is entered. 1.' (for example. etc. This same restriction does not apply to constants within an expression because ranges are not allowed. the file name should end with a dot (. Real -. The keyword is vectored. you may specify trigger keywords as the first word on a statement.. it must be enclosed within '. See “Selection expressions” on page 36 for details of expressions. If [n] follows n. For example. the keyword is doubly dimensioned...".. multiple values may be entered. usually IF statements. the program treats the entire statement as if the first word was the appropriate control statement.). If it is to contain a '.. S Other characters in the criteria list provide more information about the keyword. The expression must be enclosed within (.'. Trigger keyword -. The data are loaded into successive locations in the vector. selection expression -. it must be within ". If the string is to contain any of the delimiter characters (including space). and the [n] is the size of the second dimension. The repetition operator * may be used to enter the same value multiple times for a V keyword.The program recognizes the keyword directly without specification of the control statement.. it is the maximum index allowed for the keyword array.expressions that will result in a number.) Vector -. usually used for naming or identifying something. V10[20] means the array referenced as the keyword has 10 rows with 20 columns each. String -.text string. Therefore. Pairs -. An index may be appended to the keyword to indicate the loading point in the keyword array. V100 means the highest index may be 100. Possible characters and their meanings are: Character a K Description Ascending order — Values must be listed in ascending order.General Syntax Control statement syntax 3 Letter N s Description Numeric expression -.a special form for establishing complex selection criteria. and any index may not exceed the value of the number. An index should not be appended if a number does not follow V. P V # * [n] Cube Voyager Reference Guide 29 . See “Numeric expressions” on page 30 for details of expressions. If a number follows V.The values may be entered as single values or as pairs of numbers (two numbers separated by a dash. For example. 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. functions with their associated arguments enclosed within (.3 General Syntax Control statement syntax Expressions Expressions are either numeric formulas or selection criteria. character constants. variables.. and sub numeric expressions enclosed within (.. Standard hierarchy rules are followed. Numeric constants are entered as standard floating point numbers in the format: 30 Cube Voyager Reference Guide . and contain operands separated by operators. computation is performed from left to right. and expressions within (…) are evaluated to a single value. "+" is a concatenator) 1 2 2 2 3 Operators are preceded and succeeded by operands. Selection expressions may contain embedded numeric expressions.). which may be numeric constants.. This section discusses: • • Numeric expressions Selection expressions Numeric expressions Numeric expressions are written as traditional formulas..). if the subscripts are incorrect. At times. constants. and when MW is within an expression.. and/or which cell in the matrix to reference. Cube Voyager Reference Guide 31 . it is the user’s responsibility to ensure that the computed subscripts are within the correct ranges. the subscripts may be expressions. and terminate with a fatal condition.] [fmt] optional digits (0-9) optional decimal point optional e or E Character constants are entered as strings enclosed in '.] [ddd] [fmt[sn]ddd]. A program that deals with a variable number of matrices may have the work matrices referenced by using MW[] or MW[][]. The Xth cell in work matrix #. Unpredictable results could be obtained. it may be beneficial to use a computed variable to indicate which work matrix to reference. # is a hard-coded constant.'. The Jth cell in work matrix W. matrices are referenced within a J loop (J refers to the destination. but that is not always the case. X and W may be dynamically computed (user’s responsibility). The nth cell in work matrix #. or column. When that format is used. Most programs will detect an invalid index. or the program could fatally terminate.General Syntax Control statement syntax 3 [ddd] [. Function MW[#] MW[#][n] MW[#][X] MW[W] MW[W][X] Description The Jth cell in work matrix #. The Xth cell in work matrix W. 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.. where: [ddd] [. cell in the matrix). and/or variables. Usually. expression arguments enclosed within parenthesis ().3 General Syntax Control statement syntax Built-in functions are predefined processes that return a value to the expression. This expression can be nested. V2. they must be followed by one. 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.R1. NOTE: If the arguments are expressions. The number of arguments must match the requirements of the function. the expressions must be resolved before the function is called to determine which value is returned. or more. 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.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.OP. EXP(x) Exponential e to the x (-103 < x < 88) 32 Cube Voyager Reference Guide .V2. R1 and R2 can be numeric expressions or numeric values. To convert radians to degrees: Cube Voyager Reference Guide 33 . If str contains illegal syntax. 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. 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.) POW(x.) MIN(x. or non-numeric values. the function will try to ignore such errors.y) RAND() RANDOM(n) RANDSEED(n) ROUND(x) SQRT(x) Trig functions NOTE: Trig functions are applied to values that are in degrees.General Syntax Control statement syntax 3 Function INLIST(n.. Truncated integer value Natural logarithm (x > 0) Common logarithm (x > 0) Maximum value from the list Minimum value from the list Power (x=base... the PARAMETERS MAXSTRING= might be required if str is long. Please note that the size of str may depend upon the specific program in which INLIST is used. and perform the search on only valid values.str) Description Returns 1/0 to indicate if the value of n is found/not found in any normal paired list represented in str. Str can be dynamically modified in the program. where n is an integer between 1 and 2147483647.y...y. Formats number (x) with width=w. or string of. Returns the SIN of x where x is in degrees. decimals=d.s2. "dd/mm/yy abcm" will result in "07/02/13 abc2.str) Description Deletes n2 characters in s1 starting at n1 (1 is the first character). any other string of y will cause a four-digit result. or d occur. Returns the TAN of x. The str pattern can contain any characters. or y in the pattern will cause x (first argument) to be treated as a date in the format of yyyymmdd.n) Inserts s1 into s2 at n. and its corresponding element formatted in place of the m. Example VAR2=ARCSIN(0. If multiple occurrences of any of the y. Returns the ARCSIN (inverse SIN) of x. "abc m:d:y" would result in "abc 2/3/2007". m. the year is formatted in two digits. ARCSIN(SIN(x))=x Returns the ARCTAN of x.n1. or y string. d. m.3 General Syntax Control statement syntax Degrees=Radians*180/ð Function ARCCOS(x) ARCSIN(x) Description Returns the ARCCOS of x. ARCTAN(X) COS(x) SIN(x) TAN(x) Character functions Function1 DELETESTR(s1. the rightmost digit is used.n2) DUPSTR(str.d. Returns the COS of x. return s2+s1. If m or d is a single character.5) would return a value of 30. d. result must be less than 100 chars. but any single." INSERTSTR(s1. any other string of m or d will cause a two-digit result. Duplicates str n times. Example VAR1=SIN(30) would return a value of 0. if n < 2. the result will contain multiple values. if n1 or n2 is < 1. For example: yy/mm/dd will result in 07/02/13 if n=20070213. 34 Cube Voyager Reference Guide . if n > length of s2. format=str. return s1+s2. then return s1. If y is 2.5.w.n) FORMAT(x. General Syntax Control statement syntax 3 Function1 LEFTSTR(s1. 0 means all.d) STRLEN(str) STRLOWER(str) STRPOS(str. but starts the search from position n1 in s2 instead of from the beginning of s2. or a character variable Cube Voyager Reference Guide 35 . Returns the position of s1 in s2. or n is < 0. returns s1.. Returns n characters from the right side of s1.n) REVERSESTR(s1) RIGHTSTR(s1.s2. returns 0. str is either a character constant '.s2. if n1 < 1 or n1 > length of s2. str is not permanently changed.. w must be less than 30. Sets str to uppercase for immediate use.n) LTRIM(str) REPLACESTR(s1. Returns the numeric value contained in str.s3. Sets str to lowercase for immediate use. and continuing for n characters.'.n) Description Returns n characters from the left side of s1. and d less than w .s3. returns 0.w.n) TRIM(str) VAL(str) 1. if the length of s1 is less than n. Extracts a substring from str. where n is the number of replacements. Deletes trailing spaces from str. REPLACESTRIC(s1. return s1. if n < 0.n) STR(v. beginning at position b. with d decimal places. Returns the position in str2 where str begins. if the length of s1 is less than n.b. Reverses s1. Returns the length of str. or n is < 0.2. str is not permanently changed. Returns 0 if not found.str2) STRPOSEX(s1. Converts the variable v to a string that is w characters wide. Both strings are case sensitive. returns s1.s2. Same as REPLACESTR but ignores case when searching for s2 within s1.n1) STRUPPER(str) SUBSTR(str. b must be greater than 0. Replaces n occurrences of s2 with s3 in s1. Deletes leading spaces from str. then no replacements. If str does not exist in str2. but there are some exceptions. and. Expression A=B A == B A != B Description A equals B.8. The statement must contain the source of the lookup data. results in a single true or false value. The following comparison operators are used to determine the relationship between the expressions on either side of the operator (the left expression is A. when evaluated. The expression may contain nested and/or a series of comparisons.4.25. The syntax is similar to standard C language. See “LOOKUP” on page 51 for a details about the control statement.). A is not equal to B.' + City + DUPSTR(' '. and optional parameters to control the actual lookup of data. The expression is always enclosed within (. A equals B. Examples of valid expressions x + 1 (1.5/distance) + (sqrt(AreaType)*abs(FacilityType]) ) Street + '.3 General Syntax Control statement syntax Lookup functions Lookup functions are defined by a LOOKUP control statement.V1-V2. 36 Cube Voyager Reference Guide . In some cases. '10-15.3) SUBSTR(street.'.V2-V1) Selection expressions Selection expressions are used to specify criteria for selecting something.V2. the name to give the function. and the right expression is B):. the user will be allowed to define specific functions for use by the program.6) FORMAT(volume. Those functions will be described with the specific program documentation.. Functions that look up a value in an array or in a set of curves are examples of user functions. Each program may have a list of functions that are unique to the specific program.31-35') CmpNumRetNum(V1.'abcde') INLIST(32.2.'>='.') STRPOS('cd'.. On the other hand.. ('abcde' = 'ab') is equivalent to ('ab' = 'ab').5-1. A is less than. Since a blank. or falls within any of the ranges. B may be expressed as a series of values. the number of characters compared is the string length on the right-hand side. For example. It will always be true for equality comparison and false for other types of comparisons. it is wise to enclose them within (. A or B can be a numeric expression enclosed within (. or equal to. it is not always necessary. ('ab' = 'abcde') is false.). For example: I=1-5.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.General Syntax Control statement syntax 3 Expression A >= B A <= B A>B A<B A <> B Description A is greater than.15. or equal to. With the = operator. and/or ranges.9. but it helps to eliminate ambiguity.27. ' '. A is greater than B. A Cube Voyager Reference Guide 37 . 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 (||).212 means if I is 15.. or 212. When logical combinations are made. A is less than B.. B.. For example: (((a+b)/3 * k) = 0. is less than any printable character in ASCII code value.). B. In other words. One should never use an empty or null string on the right-hand side of a comparison expression. A is not equal to B.30-99. which is true. 888-993. 'this is a name' NETI=?2005. expands to PPPP2005. 38 Cube Voyager Reference Guide . nor is it equal to 12. For example: !(i=5-10.37 && j=150.5/i) + (sqrt(MW[3])*abs(MW[m][j-1]) ) Street + '. CBD) .net. expands to .201-299) || (j=1-10. if (I<2) will return 0.12) means if I is not within the 5-10 range.3) SUBSTR(street..ext".3 General Syntax Control statement syntax comparison enclosed within (.NET Examples of expressions n + 1 (1. CBD must be a string variable Randseed(12345) Rand() Random(I) . AND and OR can currently be specified as single & and |.\SUBDPPPP\ALTAPPPP.’1-5. 1.. .4.23E2 name=abcde. .37 && i=150-201-299) || ( (I=j & !(i=87-100..6.) can be preceded with the NOT operator (!) to cause the comparison result to be inverted.99. Example of complex selection ( (i=1-10.-".13’) Inlist((k*2+j).5002.6) Inlist(I.net .35. but this could change in the future.203) ) || ((a+sqrt(5*j)) >= (j + sqrt(6/a)) ) )) Examples of keyword variables int = 1 float = 1.' + City + DUPSTR(".\subd?\ALTA?.net (prefix = PPPP) "d:\test\alta\myfile.. If a database file (. the following rules should be adhered to. Rule Length: Description Any reasonable length. 0-9. If a file variable is to be referenced directly. In a matrix program. they could reference certain matrices. J. Z=ZonalData). M=Matrix. There are some basic rules that must be followed in assigning a name to a variable. variable names can be most any length. where: Prefix T I # Description File type (L=Link. they could reference the variables associated with a network.#. it must be preceded with a prefix to indicate which file to use. Convention is to use underscore ”_” as the first character.dbf ) is to be written. _$#@ Insensitive. but if the variable is to be associated with an input or output file.General Syntax Control statement syntax 3 Variable naming convention (general syntax) Variables used in expressions must have a valid name. its length must be restricted to no more than 15 characters. except 0-9. N=Node. A-Z.). Input file variable prefixes are always in the format 'TI. but to prevent any problems. the program will truncate the name to 10 characters (the maximum for the dbf ). I. They also may reference variables defined specifically for the program (that is. Some programs might relax the rules a bit. In a network-processing program. etc. Any of the valid characters. M. network variables may not exceed 15 characters. Indicates Input Index (explicit or implied) number of the file type named on a FILEI control statement. Cube Voyager Reference Guide 39 . a-z. Usually.'. Valid Characters: Case: First Character: Temporary variables: Variables are also used to reference items specific to a program. or variables defined by the user in a prior assignment control statement. 3. If varname is a number.varname Description refers to the matrix named varname found on the file designated by MATI[3]= on the FILEI control statement. 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.5. Zonal data are read into zonal arrays. each variable is an array with zones cells.varname LI.POP[I]. ZI.2.varname NOTE: LI. for example.5. NI. refers to the variable named varname found in the link portion of the network file designated by NETI[2]= on the FILEI control statement.3.varname ZI.3 General Syntax Control statement syntax The possible filename variables formats (illustrated by example) are: Filename format MI. refers to the array named varname generated by the file designated by ZDATI[5]= on the FILEI control statement.name are used when there is only one NETI allowed in the program (currently applies to only the Highway program). the reference to a zonal value would also include a subscript. 40 Cube Voyager Reference Guide . Usually.name and NI. 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.. 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. ELSEIF . ENDIF LOG LOOKUP PRINT PRINTROW READ SORT Control statement introduction (general syntax) Many programs will share the same type of control statements. however.. However. the data entered on them may vary between programs. Topics include: • • • • • • • • • • • • • • Control statement introduction (general syntax) COMP CONSOLE FILEI FILEO GLOBAL ID IF .. ELSE .General Syntax Standard control statements 3 Standard control statements This section discusses details about specific control statements. the first word is the ControlWord... Cube Voyager Reference Guide 41 . Usually. GGG may follow the values for FFF. and may appear any place a keyword is allowed. A keyword that is valid only if it follows the values for its Key1. or any key3 or key4 (for the same Key1). They must be followed directly by an equals sign and the associated values. and may appear only following the values for either BBB. ControlWord is the statement type and must be the first keyword on each statement. The general format for describing Control Statements in this document is: ControlWord Key1 Key1 Key1 (Key2 Key2 (Key3 Key3) ) Key1 (Key2) . A keyword must always be followed by an equals sign and appropriate value(s).. and FFF are all valid keywords. HHH and III are level 3 42 Cube Voyager Reference Guide . Key Key1 Key2 Key3 Description A keyword that must be followed by an equals sign and appropriate value(s). CCC. HHH. EEE. they are not coded on the statement. III.|.. and KKK. A keyword that is valid only if it follows the values for its Key2.. an equal level Key2. denoted by K within the |.3 General Syntax Standard control statements Those keywords (termed “trigger” keywords) are identified in their respective program detailed descriptions. CCC and DDD are valid level 2 keywords. unless the statement contains “trigger” keys. See the keyword description below for details about trigger keys. an equal level Key3. and the first keyword is a trigger keyword followed by an equals sign. GGG. JJJ. or a key4 (for the same Key2). The parenthesis () are used only to indicate the key level. BBB.. or DDD. 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. or III. When the statement contains either. or both. HHH. it is a character expression. COMP COMP statements are used to dynamically assign values to variables and/or matrices. Often a variable is defined by its presence as a keyword in another COMP statement. declares name as a variable that is 4 characters long. If there are multiple expressions on a COMP statement. declares namx as a character variable that is 12 characters long. Invalid: DDD must follow BBB or CCC Invalid: KKK must follow JJJ. Every term within the expression must be known to the expression at the time the COMP statement is to be compiled.General Syntax Standard control statements 3 keywords. or if the first term is a character function or literal character string (beginning with a quote). K = j + 2 . All numeric variables that are declared by the user in this manner are internally treated as double precision floating point variables.1.4.1) . name=' ' .3)+'abcde'+str(k. it means that the statement will be subjected to a zonal Cube Voyager Reference Guide 43 . its mode is usually determined by the first term in the expression. namx=substr(name. and may appear only following the values for GGG.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. Each expression results in a number or a character string. it is a numeric expression. keywords with associated numerical and/or character expressions. defines K as a numeric variable. of these keywords. COMP statements contains one. Some programs (mostly those involving zonal matrices) may allow the use of INCLUDE and EXCLUDE keywords on the COMP statement. or more. If the first term is a number. Keyword values AAA=3 BBB=5 DDD=2 EEE=25. Invalid: HHH must follow GGG Valid. they are solved in left to right order. KKK is also a level 3 keyword and may appear only after the values for JJJ or KKK. or numeric variable. [1] is assumed. If it meets the EXCLUDE list specifications. if there is no FILEI statement. ?03. Typical keywords on a FILEI statement are NETI. the keyword may contain [i]. the statement is bypassed.mat . When the program accepts FILEI vectored keywords.3 General Syntax Standard control statements filter before being processed. If [i] is not specified.mat. MATI. such as MATI in various programs. CONSOLE A CONSOLE statement is used to set certain switches relative to dynamic display of messages in the message area of the window. and ZDATI. If it fails the INCLUDE list specifications. Some FILEI keywords may allow sublevel keywords that are associated with the file keyword.mat. FILEI FILEI tells the program which input files to process. all FILEI statements must be in the beginning of the control stream. the statement is bypassed.mat NETI=??. FILEI MATI=?01.mat. MATI[3]=?03. Turns off the ONLINE=Y switch Causes text to be written to the console. 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.mat. if there is an EXCLUDE. the zone number will be checked against the zones in the INCLUDE list. In some programs. If an INCLUDE is present.mat. Most times the statement may begin with the keyword itself. NETI=??. thus eliminating the need to code FILEI. 44 Cube Voyager Reference Guide . this would be the same as the above FILEI statement. The zonal filter will refer to either I (origin zone) or J (destination zone). or simulate certain required defaults. In most cases.mat MATI[1]=?01. Then. the zone is checked with the EXCLUDE list. MATI[2]=?02. The exact format of the FILEI statement will vary between programs. the program definition will clarify which. the program will assume a default statement. ?02. 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. (See Chapter 14. Abc=def . . NOTE: Application Manager automatically writes all FILEO statements to the script file when you define content for output file boxes. The exact format of the FILEO statement will vary between programs. . do not manually edit the file path or file name elements of the FILEO statements. Hint: It is relatively easy to miscode FILEI statements by either omitting or including line delimiters. Editing the file path or file name will result in a mismatch between the file the script writes during runs and the file Application Cube Voyager Reference Guide 45 . 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. but it is wise to form the habit of placing all FILEI statements first in the control stream. For example: FILEI MATI[1]=… MATI[2]=… MATI[5]=….app file stores this information. it names the output files to be written by the program. . If you use Application Manager. If there is no FILEO statement.) FILEO FILEO is the counterpart to FILEI. as both the script file and the application’s . The documentation for each program will indicate where the FILEI statements are valid. Generally.” in the Cube Base Reference Guide.app file stores this information. some program will simulate an appropriate statement. If you use Application Manager. until it is absolutely necessary. the programs will delay opening the FILEI files. “Application Manager.General Syntax Standard control statements 3 because later control statements may reference variables that are to come directly from the files. do not manually edit the file path or file name elements of the FILEI statements. as both the script file and the application’s . Resets the maximum number of characters to be printed on a single line. Example PAGEHEIGHT=32767 . The value must be in the range 50-250. preclude insertion of page headers ID An ID statement is used to revise the page headings for each printed page. you need not specify “GLOBAL. Hint: If the print file is going to be viewed primarily on-line (instead of actually being printed). The keywords are trigger keywords. PAGEWIDTH |KI| If these parameters are specified. so that the system knows when to start a new page with appropriate headers. (See Chapter 14. The PAGExxxx values can also be set when Cube Voyager is initially launched from its menu. Usually this value is either 80 or 132 to accommodate most character printers. The ID is revised in one of two ways: with the ID statement. they remain in effect through subsequent programs until revised.) GLOBAL Alters the size of a page on the standard print media.” GLOBAL keywords Keyword PAGEHEIGHT |KI| Description Resets the maximum number of lines on a page. The ID is specified as: ID=newid string. it is suggested that PAGEHEIGHT be set to a large number to reduce the number of interspersed page headers.3 General Syntax Standard control statements Manager opens when you double-click an output file box.” in the Cube Base Reference Guide. and (in some programs) 46 Cube Voyager Reference Guide . “Application Manager. The value must be in the range 1032767. The length of the ID text will be truncated to 60 characters. so it can form the report properly. It only comes into play when certain reporting processes need to know the width of a print line. This can cause the sign-on ID to be revised at a time different than what might be expected. parts of the ID can be computed. the ID can be computed. and it is revised at that time (but will not be reflected in the headers until a new page is required). the sign-on IDs would be correct. the first page (sign-on) for the Matrix application will not contain the “this is the MATRIX ID” as its header. 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.2. In the COMP statement. That way. 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 sign-on page for the application program will contain the desired ID.5 COMP ID=’This is Pass’+str(PASS. Because of this situation. This would most likely be used in a Cube Voyager loop situation: Example of Computing the ID LOOP PASS=1. If the RUN and ID statements were reversed. When ID is specified as the destination in a COMP statement.General Syntax Standard control statements 3 by a COMP ID=text expression. ID statements in Cube Voyager Pilot program are dynamic. but the first page of the Highway section would contain it.0) RUN PGM= … ENDRUN ENDLOOP Example ID=This is the new Page Header Cube Voyager Reference Guide 47 . it is suggested that ID statements be used before a RUN statement. there may be any number of ELSEIF statements.. ELSEIF ( I>=0 & I<5 ) s2... or ENDIF statement. • IF/ELSEIF expression is false — The next statement to be executed is the next associated ELSEIF.). ELSEIF ... For each IF statement.. The next statement executed is the one following the associated ENDIF statement. optionally... the statements would be executed as: Value of I -1 3 9 >9 Statements executed S1 S2 S3 S4 48 Cube Voyager Reference Guide . ELSE. ELSE.. ELSEIF (I==8) s3. The ELSEIF statement has the same format as the IF statement. ELSE . Example IF (I<0) s1. ELSE s4. Flow is outlined as: • IF/ELSEIF expression is true — The statements following the statement are executed until an ELSEIF. and the ELSE statement. there must be a matching ENDIF later in the input stream. ENDIF IF statements control the flow of user defined operations for those programs that provide for them.... Program flow is determined by the results of the condition evaluations of the IF and ELSEIF statements.. IF is followed by a selection expression enclosed within (. Between the IF and its matching ENDIF..3 General Syntax Standard control statements IF . ENDIF For varying values of I. The expression is evaluated and will result in a true or false condition.. or ENDIF is encountered.. and one ELSE statement. So. and this will continue it . . the error diagnostic stated about the line may be somewhat confusing. so it doesn’t know exactly where to place the blame because it is diagnosing the IF statement at the time. It is diagnosing an IF statement. because there is no associated IF. Generated the ENDIF here ENDIF .General Syntax Standard control statements 3 If. cnter = cnter + 1 . and this is OK ENDIF . in the example. 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. Note: if a short IF is used and the statement appended to the statement is not acceptable in that context or is mis-structured. LOG Writes values to the log file PREFIX VAR Cube Voyager maintains a file called the log file. the program automatically generates the required ENDIF. IF (j==3 & k==5) k=3. it has a filename with an extension of . This shortcut statement is provided to help reduce the amount of coding required. this will be an error. This statement will be OK. IF (j==3 & k==5) k=3 . there were no ELSE statement. 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 . This statement will be OK cnter = cnter + 1 . ENDIF generated.VAR file with Cube Voyager Reference Guide 49 . but the appended statement has errors. In such cases. then any time I is greater than 8. This is because the system can not always fully ascertain exactly what the problem is. Whenever a RUN statement is encountered. This will fail.. no statements between the IF and the ENDIF statement would be executed. Cube Voyager updates the values in the .VAR. VAR file can be retrieved by other Cube Voyager programs (including the Pilot program) in the same job. (Cube Voyager tests the value from MATRIX): ZONES=5 MW[1] = 1 TOTMW1 = TOTMW1 + ROWSUM(1) LOG VAR=TOTMW1 ENDRUN IF (MATRIX. the value from the . ENDRUN 50 Cube Voyager Reference Guide . the values can be retrieved by the use of the @…@ token process.3 General Syntax Standard control statements the values for all the variables that Cube Voyager is maintaining plus the values that were logged by any programs.VAR file. and Cube Voyager retrieves the values when the program terminates. (HIGHWAY obtains a value from MATRIX): . If a program is requested to LOG any values.) in other programs. The variables in the .VAR is substituted directly into the control statement as it is read. the variable can be accessed directly. Examples may help to clarify this process. The values in the .TOTMW1 == 0) ABORT MSG=’Nothing in MW1’ RUN PGM=HIGHWAY . 2. A LOG statement is used to have a program write values to the . RUN PGM=MATRIX . In the latter case.) in Cube Voyager.TOTMW1@ . the program appends values to the .VAR file.VAR file can be accessed in two different ways: 1. X = @MATRIX. When the function is referenced in an expression. the correct number of arguments enclosed within parenthesis must follow it. LOG PREFIX=MATRIX1. prior to their actual use. FILE or R keywords. AVEMW LOG VAR=GRANDTOTAL . will be written as MATRIX1. they are processed at the appropriate time by the program. Lookup functions are referenced from within numerical expressions. In most cases. Indicates which variables will have their values written to the . The current version of Cube Voyager truncates . a lookup statement will define a single set of lookup data. The statements are not dynamic. but if a LOOKUP subkeyword follows the NAME. LOG keywords Keyword PREFIX |S| Description Sets the prefix of the logged variable(s). the function will be Cube Voyager Reference Guide 51 .General Syntax Standard control statements 3 The records that are written to the file are written as PREFIX.VAR=value. This could be confusing if different applications of the same program log the same values. This is scheduled for revision in a subsequent release of the system.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. VAR |S| Example RUN PGM=MATRIX . VAR=TOTMW1.VAR string values with embedded or trailing spaces at the first space when it reads the values. the program name will be used. This string is added to the start of the names of all variables that follow PREFIX. A lookup array is allocated and initialized with the data referenced by the LOOKUPI.VAR file. If PREFIX is not specified. The function returns a single value to the expression solver. respectively. Indicates if the program is to format and list the lookup table.” in the Cube Base Reference Guide for information about this wizard. MDB. Data referenced by LOOKUPI or FILE keywords can be either in DBF. Note that versions prior to 1. FILE. If a call to the function has more arguments than is required. the result for the lowest value in the table is returned. and LOOKUPI are mutually exclusive. unless FAIL[2] is specified. meaning that there must be a direct match in the table. FAIL[3] (default value is 0) is returned. This latter format is useful for entering friction factors for use in the Distribution program. “Job Script Editor Window. unless R or LOOKUPI is specified. the result for the highest value in the table is returned. 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. Indicates if the returned function value is to be the result of interpolating between rows in the lookup table. if the value is less than the lowest value in the table. If FAIL[1-2] were not specified. the argument following the required arguments is the value that will be returned if the lookup fails for any reason.5 did not return the extreme results of the data for low and high failure. they were set to 0. If the value is greater than the highest value in the table.3 General Syntax Standard control statements defined as one that requires at least two arguments (curve number and the value to be searched for). By default. or delimited ASCII format. unless FAIL[1] is explicitly specified. See Chapter 12. If the value is not found within the data. they returned FAIL[1] and FAIL[2]. This keyword must be specified. FILE |F| Name of the file that contains the data to be associated with the function. 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.5. R. The default value is false. INTERPOLATE |?| LIST |?| 52 Cube Voyager Reference Guide . The returned value from the function would be placed in the variable X. or more. ASCII data MUST be delimited with either spaces or commas. and a value to be searched for). LOOKUPI and R are mutually exclusive. Field number or name of the field from the data record that contains the result to be returned when the function is called. DBF. The use of the LOOKUP keyword implies that the call to the lookup function must contain at least two arguments (a curve number. NAME NAME LOOKUP |S| |S| NAME RESULT |S| NEAREST |?| Cube Voyager Reference Guide 53 . and its value must be followed by RESULT=value. Note that FILE. Used when data for one. 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 of the lookup function that the statement defines. 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). LOOKUP[1]=1 RESULT=2. The values provided for the LOOKUP and RESULT keywords are either the field numbers in the input data (ASCII.General Syntax Standard control statements 3 LOOKUP keywords (continued) Keyword LOOKUPI Subkeyword Type |I| Description The # of the FILEI LOOKUPI[#] file where this LOOKUP statement is to obtain values. The LOOKUP index indicates the curve number and the LOOKUP value indicates which column or field in the input data file holds the lookup values for the indexed curve. or MDB data) or the field names when the input data is in DBF or MDB format. The data formats supported for LOOKUPI= and FILE= when referencing data from an external file are ASCII and DBF.5) implies for curve 1 (first argument in the function call). 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. curves is to be obtained from a single data record. For example on the LOOKUP statement with NAME=FUNC1. The LOOKUP keyword must be indexed [1-n]. a call to this function like X=FUNC1(1. SETUPPER takes precedence over INTERPOLATE. and only comes into play for rows without both limits explicitly provided. Any number of R records can be entered. SETUPPER |?| SIZE |I| TOLERANCE |R| 54 Cube Voyager Reference Guide . and the function can not find an exact match. FILE. Optional variable that specifies the total number of entries in a LOOKUP array. 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.3 General Syntax Standard control statements LOOKUP keywords (continued) Keyword R Subkeyword Type |SV| Description Used in place of the FILE or LOOKUPI keywords to enter data records for the function. Each R value must be enclosed within single quote marks '. The string values following R represent data records that are in the same format as the FILE records would be. However. otherwise the return would be error.1 of Cube Voyager and TP+ systems. This option is useful when the data is input with single values. Specifies a tolerance to be applied to the lookup value. If R is specified. and it is to return a value based upon the lower of two ranges. it is maintained to insure backward compatibility with previous versions of the software. the return value would be computed. FILE or LOOKUPI may not be specified.. 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. if SETUPPER were true. or multiple R= records may be entered. A single R= may specify the entire file. For example. LOOKUPI and R are mutually exclusive.. As of v4. In such cases.5 would fail. A lookup for 1. the result for 1 would be returned. The value should be the number of resulting values to be searched for multiplied by the number of records. 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. If INTERPOLATE were true.'. a curve is entered with single values that begin at 1 and increment through 10 by 1. Specifies that the function is to simulate an upper limit for a lookup row when only a single value is entered for the row. When a function is referenced. the return value is the result of interpolating between the high limit of the lower row and the low limit of the upper row. the call to the function requires at least two arguments: the lookup curve number and the lookup argument. If the argument is less than the lowest value for the lookup number the return value is set to FAIL[1]. For either a single or double value function (functional call with 1 or 2 arguments) and additional argument value can be provided. If the value is not found in any range. This in effect gives you the ability to override the default FAIL values for specific situations. If the function can not find a match for the lookup curve number. and the function returns a value for the argument. the function requires only one argument: the lookup argument.General Syntax Standard control statements 3 Lookup functions are referenced in numerical and selection expressions. The returned value is obtained by searching the lookup function data table for the lookup argument. If two numbers are separated by a dash. The table is composed of rows of data. 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. Numbers not separated by dashes are entered as both the low and high limits of a row. but the upper limit of a Cube Voyager Reference Guide 55 . The first field on a record is the lookup result. If the argument is higher than the highest value. If interpolation is used. Otherwise. it is supplied a lookup argument within parenthesis. they form the low and high limits of a row. 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. the return value is set to FAIL[3] unless INTERPOLATE is set to true. Ranges may not overlap. the return value is set to FAIL[2]. If the LOOKUP subkeyword is in effect. regardless of the value of INTERPOLATE. and the fields following it are the lookup values. or commas or may be separate fields on a DBF file. FAIL[3] is returned. 5. 2. they form a row with the low and high limits equal to the value from the LOOKUP field. v1. 305 56 Cube Voyager Reference Guide . 202. The first two fields should be numeric fields but character fields are ok as long as the content can be converted to numerics. . . 3. For example. The result for 2 would be obtained from the second row. assume the following records: T. second row limits =2-3. Blank fields are not treated as zeroes. 303 104. If the argument matches a high limit of a row and the low limit of the next row. If either field number exceeds the number of fields on the record. If both fields exist. 301 102. 201. special consideration is given to blank fields. first row limits=1-2. When the lookup format designates multiple curves.) • 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 data for each LOOKUP is obtained from the record according to the field numbers or names specified for the LOOKUP and RESULT keywords. but indicate there is no data point. 1. • Data records when LOOKUP subkeyword is used: Each data record may have any number of fields delimited by white space. the result is obtained from the upper row. 204 . (For example. or commas or may be separate fields on a DBF or MDB file.3 General Syntax Standard control statements row may be equal to the lower limit of the next row. v2. there is no row generated for that curve. v3 101. otherwise the program will report a lookup input error. The first field is the lookup result and the second field is the lookup value. 302 103. 4. and V3 will have points for T=1-3. Example: Single value function COPY FILE=C:\LOOK1. The V1 curve will have points for T=1-4. the V2 curve will have points for T=1-2. The result for a lookup of T=3 in V2.V2. and no more points appear on the record.V2. the T=3 record would appear as “3 103 303”. DISTRICTS(50) results in 15. the first empty field indicates the end of the record. 5. space delimited records don’t have any way to designate null fields.DAT .V1. INTERPOLATE. Be aware that this situation exists only for comma delimited and dbf data. this is the data for the function 1 2 3 4-8 23 15 50 2 1 3 9-10 ENDCOPY LOOKUP NAME=DISTRICTS.4. With space delimited records. V3 would be blank.V3. which would be interpreted as points for V1 and V2. T=5. or none). and T=5.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. T=4.General Syntax Standard control statements 3 There will be no data points for T=3. DISTRICTS(9) results in 3. FILE=C:\LOOK1. will depend upon the options of the LOOKUP statement (SETUPPER. Cube Voyager Reference Guide 57 . a friction value of 0 will preclude distribution between the zones.DAT LOOKUP NAME=DISTRICTS. and a record for the highest time value that you feel is reasonable. but that may not be what is expected. LOOKUP[1]=1. the friction factor obtained from the lookup would be the FAIL[2] value. 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 58 Cube Voyager Reference Guide . and the subsequent fields are the factors for the various purposes that are being distributed. To circumvent these potential problems. it is possible to have times that are below the minimum time and greater than the highest time. Because the Cube Voyager distribution process is generic. The factors of the two first records should be the same. RESULT=2. but there are zone-to-zone times that are greater than 100 minutes. Thus. for zone-to-zone movements for which there is no path (inaccessible). or possibly zero. 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. . The lookup values can be set so that only trips within a certain item range can be distributed. users may wish to have values for times that extend beyond the limits of the values entered. The normal (default) process would return a 0 for those values (from the FAIL values). For example: a table might have factors for times from 1 through 100.01). RESULT=3. and the factors for the last records should also be the same. . if a time of 110 is encountered. be sure to include a record for a very low time value (say 0. this may not be what was wanted. LOOKUP NAME=FF. The time matrix might also have very large values. The limits of the curve would control this operation. A similar situation would occur if the time were less than 1. .3 General Syntax Standard control statements Example: Single value function using LOOKUPI FILEI LOOKUP[1]=C:\LOOK1. but greater than 0. In most situations. . LOOKUP[2]=1. . This example illustrates that typical process. RESULT=4.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.888) . . . '120 50 100 100' FFX = FF(1. R= '0.01 1 4 120 Upper Limit 0. .150.1. '1 1200 1000 800'.01 1 3 4 5 120 0. RESULT = 300 FFX = FF(3. . 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 */ .01 1 3 4 120 0. '4 100 100 100'.01 1 3 4 120 0.3) .01 1200 1000 800'. '5 50'.2) .01 1 3 4 5 120 0.General Syntax Standard control statements 3 LOOKUP[3]=1.0. RESULT = 888 since 150 > highest value in field 1 FFX = FF(2.01 1 4 120 Result Value 1200 1200 300 100 50 50 1000 1000 500 100 100 800 800 100 100 Cube Voyager Reference Guide 59 . '3 300 500'. FAIL=2000. Curve 3 lookup value is in field 1 Result (FF) for curve 3 is in field 4 return 2000 if any lookup < 0. INTERPOLATE=Y. INTERPOLATE=F .4132 3.5665 0.cc = county code (1=LA. LOOKUP[3]=TAZ.5=VN) . LOOKUP[5]=1.DBF" FILEI LOOKUPI[1] = "C:\MTA_GEN\CFACS. LOOKUP[8]=TAZ. LOOKUP[1]=1. LOOKUP[4]=TAZ. LOOKUP[5]=TAZ. . RESULT=4. example of use: v=TAZ(10. RESULT=3.4137 3.2) c2[cc]=CFAC(cc. LOOKUP[9]=TAZ.4108 3. RESULT=TOTAL_JOBS. RESULT=OTH_JOBS. RESULT=SERV_JOBS.6088 0. .1) cv[cc]=CFAC(cc. RESULT=AGE_5_14.5757 0. LOOKUP[4]=1. RESULT=2.1.2=OR. 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. RESULT=ACRES.DAT" cc=zi. LOOKUP[2]=1.a the value from ACRES LOOKUP[2]=TAZ. LOOKUP[7]=TAZ. lookup county correction factors O&D Survey LOOKUP LOOKUPI=2 LIST=Y NAME=CFAC.3=RV.3) ENDLOOP /* .2278 2 0.name for this function LOOKUP[1]=TAZ.6389 0.4=SB.6505 0.lookup a value in TAZ return . RESULT=ENROL_HS. RESULT=AGE_15_17.DBF" LOOKUP LOOKUPI=1.6759 3 0. LOOKUP[6]=TAZ. RESULT=RET_JOBS.6518 0.3 General Syntax Standard control statements Example: Double value function — LOOKUP with DBF LOOKUPI file FILEI LOOKUPI[1] = "C:\CUBETOWN\TAZ\TAZ. fill arrays for factors by county LOOP cc=1. RESULT=POPULATION. dimension user arrays to 5 array c0=5 cv=5 c2=5 . LOOKUP[3]=1. LOOKUP[10]=TAZ. RESULT=ENROL_ELEM. . INTERPOLATE =N . RESULT=6.6767 0.7070 3. RESULT=5.5 c0[cc]=CFAC(cc.external LOOKUPI file in this example 1 3.25) .references the input DBF file NAME=TAZ.5778 0.cc .6642 60 Cube Voyager Reference Guide . TIME . LOS=MW[20]. Put the friction factors into a LOOKUP for distribution LOOKUP LOOKUPI=1. RESULT=EXT_INT.’EI_Trips’ . LOOKUP[3]=TRVLTIME. Set a maximum number of iterations and convergence criterion PARAMETERS MAXITERS=99. MO=1-4. NAME='Home_Based'.A3. RESULT=SCHOOL.1.DBF file contains: Cube Voyager Reference Guide 61 . MAXRMSE=5 .General Syntax Standard control statements 3 */ Example: Double value function — Using LOOKUP with DBF data in a trip Distribution application RUN PGM=DISTRIBUTION PRNFILE="DISTRIBUTION.1. RESULT=HOMEBASED. FFACTORS=FRICTIONFACTORS ENDRUN Where the FRICTIONFACTOR. A[2]=ZI.A2.1. P[3]=ZI.P1. FFACTORS=FRICTIONFACTORS GRAVITY PURPOSE=3. LOS=MW[20].DBF" FILEI MATI[1] = "TRAVEL TIMES. FFACTORS=FRICTIONFACTORS GRAVITY PURPOSE=2. RESULT=NONHOME. Distribute trips using a standard gravity model formulation GRAVITY PURPOSE=1. LOOKUP[4]=TRVLTIME.P2. INTERPOLATE=T . LOOKUP[1]=TRVLTIME.P3. A[3]=ZI.'School'.A1.PRN" FILEI ZDATI[1] = "TRIP ENDS. Link the input production and attraction values to internal variables SETPA P[1]=ZI.1. A[1]=ZI. LOOKUP[2]=TRVLTIME.P4.MAT". A[4]=ZI. LOS=MW[20].DBF" FILEO MATO[1] = "PERSON TRIP TABLE.'NonHome_Based'. P[2]=ZI. Put the travel time matrix into a working matrix for distribution MW[20]=MI.1. LOS=MW[20].1. FFACTORS=FRICTIONFACTORS GRAVITY PURPOSE=4. P[4]=ZI. NAME=FRICTIONFACTORS.1.A4 .MAT" FILEI LOOKUPI[1] = "FRICTIONFACTORS.1.1. 3 General Syntax Standard control statements PRINT Formats data items and writes them as a single line to the standard printed output. If specified. the program writes the standard printed output file. The length of the printed line is determined by the formatting of each listed item. This default format is effective until the program reads the next CFORM value. CSV |?| Optional. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) PRINT keywords Keyword CFORM Subkeyword |S| Description Optional. a file. 62 Cube Voyager Reference Guide . File where the program writes the formatted list. You might need to add a “\n” to the end of the file if you concatenate the file with another file. or both. Optional. Thus. If not specified. The program writes each formatted list to one record. The program prints one line for each PRINT statement. the program writes only to the specified file unless subkeyword PRINT is set to T. with commas between each LIST item F — Do not print in CSV format Default value is F. Default value is 0. See “Defining a character print format” on page 67. Default format for subsequently appearing character strings. 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. specified with the LIST keyword. the endof-file character is at the end of the last record. Explicit formats defined for particular items take precedence. except for literal values. Cube Voyager Reference Guide 63 . even if other statements set APPEND to F. Flag indicating whether to write record to standard printed output in addition to specified file. Default value is 10. F — Overwrite the existing file when writing the formatted list. Explicit formats defined for particular items take precedence. Default value is F. Optional. See “Defining a numeric print format” on page 66. Default format for subsequently appearing numbers specified with the LIST keyword. 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. therefore.General Syntax Standard control statements 3 PRINT keywords (continued) Keyword FILE Subkeyword APPEND |?| Description Optional. Possible values: • • T — Append the formatted list to the specified file. FORM |S| Optional. 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. FILE PRINT |?| Optional. Program overwrites previous contents. NOTE: If set to T for a file at least once in a step. This default format is effective until the program reads the next FORM value. Flag indicating whether to overwrite or append to the specified file. REWIND is dynamic.2. Default value is F. you can control the rewinding on each PRINT statement. F — Write to the current position in the file. then all PRINT statements executed at that step will append to that file. I(L). For example: I. the program will supply one. For example. 'abcde'. lowercase). NOTE: MW[n] normally implies MW[n][J]. J. See “Defining a numeric print format” on page 66 and “Defining a character print format” on page 67. For example: P[i*3-1]. The \\ will not be printed. you can avoid this issue by using LIST="C:\N2020\output". or valid expressions. and the printing will continue from the current line position. Append appropriate subscripts to any array and matrix variables in the list. Enclose expressions in parentheses. Because the special control is case sensitive and directory folder names are not. 64 Cube Voyager Reference Guide . and phase. depending on the variable. program. place the format in parentheses next to the item. NOTE: Because special characters are treated as these special controls. List of items (variables. 'i='(8R). As long as a PRINT statement has at least one LIST item. where J is the current value of J. (sqrt(4))(8C). ITEM1(6). problems can arise when printing strings for a system path due to the "\" character. You can override the automatic newline character by making the first LIST item a literal string that begins with the “\\” characters. To assign an explicit format to a particular item in the list. The format only applies to that item. upon reading LIST="C:\n2020\output\" the program would treat the embedded \n as the new-line control and insert a new line at the location. the program automatically inserts a newline character prior to the first item. to generate a new line at that location (the \n will not be printed). strings.3 General Syntax Standard control statements PRINT keywords (continued) Keyword LIST Subkeyword |KS| Description Optional. Subscripts may be constants. The PRINT statement recognizes four special character strings as special control characters: • • • • "\n" — new line control "\f" — new page control "\t" — tab control "\\" — ignore new line control For example. and expressions) to format and write to a printed line. a literal string may contain the newline character string ("\n" . Specify no more than 500 items. If you do not specify a subscript. variables. Flag that indicates whether to write record to standard printed output in addition to specified PRINTO file. you can control the rewinding on each PRINT statement. The string functions might provide some flexibility that is better suited to the specific task. Flag indicating whether the program repositions to the start of the file before writing contents.0CDLRS LIST=I.General Syntax Standard control statements 3 PRINT keywords (continued) Keyword LIST (continued) Subkeyword Description In some cases.3). LIST=N. TOTAL3 FILE=PRINTFIL. APPEND=T • Output to file and rewind file at the end. TOTAL1. J. JLOOP_J. Possible values: • • T — Reposition to start of file before writing formatted list. J. |I| PRINT |?| Optional. TOTAL2. REWIND is dynamic.2CS) FORM=LRCD. Optional. Examples • Report a mixture of numeric and character variables. PRINT FORM=6. Program overwrites previous contents. Index number of the FILEO PRINTO file where the program writes this output.001. 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. 'ABCDE'(6. Optional. Default value is F. REWIND=T • Interpret sqrt(6) as a variable “sqrt” with form=6 Cube Voyager Reference Guide 65 . you might prefer to form character variables using the string functions of a COMP character expression and include those variables in the list. • Use LIST keyword without the control statement name. TOTAL(6. LIST= I(6) J(6) TOTAL1. PRINT FORM=0 LIST=I. F — Write to the current position in the file. TOTAL2 FILE=PRINTFIL.002. therefore. 0L).0L). ' J='. T — Truncate numbers on the left if they cannot fit the field width. number of leading spaces printed.MW[2](8. For strings. w must be wide enough to accommodate the number. specify print format as: w. Normally. the program formats such numbers with all asterisks. MW[1]='. The program sets d to 0 if the format begins with w. B overrides D. • d — For numbers.MW[3](5.3 General Syntax Standard control statements PRINT FORM=LRS LIST= 'I ='.csv If (I=1) PRINT CSV=T LIST=’I’. J. For FORM or individual numeric LIST items.dCDBTLRS where: • w — Total field width. I.MW[1](8. MW[1][2]. you might set w to 0.’COST’. if both are coded.’J’. C — Insert commas into numbers. number of digits printed after the decimal point. indicating that the field width depends on the string length. B — Display zero-value numbers as blanks.2L) PRINTO=1 Defining a numeric print format Use FORM to format numeric items.’TIME’. D — Display zero-value numbers as a pair of right-justified dashes. MW[1][3].4L).J(6.4L).’DISTANCE’ PRINTO=1 PRINT CSV=T LIST=I(6. for strings. time+dist/sqrt(xyz). and you do not specify d. MW[1][1]. NOTE: If the format specifies L. • • • • 66 Cube Voyager Reference Guide . (sqrt(6)) ' • Output directly to CSV format FILEO PRINTO[1]=c:\data\mydata. For CFORM or individual string LIST items. specify print format as: w.General Syntax Standard control statements 3 • L — Trim numbers on the left and print the result beginning with the left-most digit. If necessary. R — For numbers. If printing an unknown range of values. w indicates the field’s maximum width. the number must fit within the specified w. With L. otherwise the program truncates. When values do not fit the specified field width.d.4LRS is probably adequate. The program attempts to accommodate fixed formats. R. • • All characters are optional. For strings. Citilabs recommends using a varying length format unless you must align reported values. S — Insert a space before the digits of any numbers formatted with L. if possible.dCDBTLR where: Cube Voyager Reference Guide 67 . and then reduces the number of decimal places. and S. However. For delimitedformat output. The CDBTLRS characters (case insensitive) may be in any order. right justify. do not specify L. Program replaces zeros after normal formatting and removes decimal point if there is no trailing 0. but must follow w. the program drops commas. the program reformats with scientific notation (1E+ppp). replace a number’s trailing 0s (right side of decimal point) with spaces. the result will be left justified and only as long as required. When printing fixed fields. FORM=16. if w and d are specified. FORM must have a width adequate to accommodate all possible ranges. Defining a character print format Use CFORM to format text items. if w and d are specified. Valid values range from 0 through 9. the program uses the last value. w must be wide enough to accommodate the number. If a format string specifies multiple d values. The default value is 0. Specify d anywhere in the format string. When text does not fit the specified field width. any number not preceded by a period specifies w. the program truncates. • d — Number of leading spaces printed (or periods. order of w and d is not fixed with CFORM. If L is specified. If R is specified. R — Right-justify text item (truncating beginning characters if length exceeds field width). C overrides L or R. Specify w anywhere in the format string. Unlike FORM. If a format string specifies multiple w values. but must follow w. any digit preceded by a period specifies d. Set to 0 to indicate that the field width depends on the string length. • • • • • • All characters are optional. delete leading spaces. T — Trim leading or trailing spaces from text item.) in the d characters preceding the field. delete trailing spaces. C — Center-justify text item. The CDBTLR characters (case insensitive) may be in any order. if D specified).d. D — Print periods (. 68 Cube Voyager Reference Guide . The program attempts to accommodate fixed formats.3 General Syntax Standard control statements • w — Total field width. B — Replace blanks with underscore characters (_). L — Left-justify text item. If both L and R are specified. NOTE: If the format specifies L. Citilabs recommends using a varying length format unless you must align reported values. delete leading and trailing spaces and center-justify text item. the program uses the last value. Program applies T first. BASE1 has no effect. Default format for row values. use this statement judiciously. F — Begin each printed line with appropriate zone number based on FORM and page width. For printing traditional integer boxes. See “Defining a numeric print format” on page 66.5LRD The default value (20. Flag indicating row format when using non-varying print format (that is. See also “PRINT” on page 62.5LRD) provides efficient reporting while maintaining precision. PRINTROW keywords Keyword BASE1 |?| Description Optional. Row formatting can be quite voluminous. set FORM to 7D.General Syntax Standard control statements 3 PRINTROW Formats and prints all cells or selected cells of a matrix row to the main print file. FORM does not contain L). MAXPERLINE takes precedence over BASE1: if MAXPERLINE is specified and is not modular ten. Default value is 20. 8 FORM=LRD TITLE='form=LRD' PRINTROW MW=1-21 FORM=8 BASE1=Y MAXPERLINE=10 FORM |S| Optional. Possible values: • • T — Begin every printed line with a zone number ending in 1. (The L in the format value triggers varying-formatted numbers separated by a single space. Cube Voyager Reference Guide 69 . None of the PRINTROW keywords are “trigger” keys.) Three spaces precede zone values ending in 1. providing zone distinction. For example: PRINTROW MW=1-2. You must code all on a PRINTROW statement. 10. setting BASE1 to true. Default value is no work matrices. Citilabs suggests specifying FORM without the LD. For neat-appearing reports. Valid values range from 1 to the number of zones. provided line length does not exceed the standard page width."). List of work matrices to print. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. even if printing multiple MWs. Delimit each number or pair with a comma. and setting MAXPERLINE to some integral of 10. MAXPERLINE |I| Optional. the program prints no title.10. For example J=1. If MAXPERLINE is specified. program ignores page width. Maximum number of columns printed on a line.. For example MW=1. Title printed at the beginning of each MW. Delimit each number or pair with a comma. regardless of specified order. 13 selects work matrices 1. Program sets excluded zones (those not listed) to zero. MW |IP| Optional.8 form=LRD title='form=LRD' PRINTROW mw=1-21 form=6D base1=y maxperline=10 70 Cube Voyager Reference Guide . Default value is all zones. Example PRINTROW mw=1-2.3-5. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. By default.. List of zone numbers formatted for printing. Enclose the value within quotes ('.12-20 selects zones 1. You may specify only one title per PRINTROW statement.. TITLE |S| Optional..') or literal marks (". 3-10. Program prints matrices in ascending order.3 through 10.3 General Syntax Standard control statements PRINTROW keywords (continued) Keyword J |IP| Description Optional. The program truncates titles longer than fourteen characters. program allows any number of values to be printed on a line. By default. and 12 through 20 for printing.3 through 5. and 13 for printing. . If it does. A nested READ may not point to a file that is already in the nest.. and the scan is continued. but it is not mandatory. Character string that will replace oldstring in the records in FILE that contain oldstring.. It is suggested that strings always be enclosed within '. the string is replaced with newstring. The replacement process is designed to not allow a replacement string to replace an earlier replacement. it is scanned to see if oldstring exists in it.. ‘MODE=5’ = ‘MODE=3’ Cube Voyager Reference Guide 71 . READ keywords Keyword FILE Description File to be read. When the end of file is encountered on that file. oldstring=newstring... If either oldstring or newstring contains any special characters it must be enclosed with '..'. Example READ FILE=BUSLINES. Replacements are done in the left to right order as specified in the READ statement. reading of control statements will continue with the statement following this READ statement. Newstring is case sensitive. There is no specific limit to the length and number of replacement strings.General Syntax Standard control statements 3 READ Switches reading of control statements to a different file. . newstring oldstring READ statements can be nested up to five levels.'. The format is: READ FILE=filename. oldstring=newstring. Character string (not case sensitive) that is to be replaced by newstring. As each record is read from the file. it will be replaced directly. The format is: SORT ARRAY=name.'+C' . if one wanted to see a sorted listing of the number of households per zone.3 General Syntax Standard control statements SORT Sorts an array. a signed array may not follow an array without a sign.C . or series of arrays.B. '+myarray'). If a leading + sign is used. same as above. the sign and name must be enclosed within quotes (for example.B. If there is no sign for the first name.C .D. two arrays would be required: ZONENO and HH. Unsigned arrays are carried along in parallel with the sorted records.E . descending C SORT ARRAY=-A. name. All names must be declared in an ARRAY statement or as a DBI AUTOARRAY name. Signs need not be specified. For example. ascending B.ZONENO. and a “–” means descending. sort on descending on A. This would sort the HH array in a descending order and keep the ZONENO array records parallel to it. ascending is assumed. or an integer number.B. All the arrays in a SORT statement must be declared with the same size. A “+” means ascending. it may be either the name of a variable. The SORT statement would be SORT ARRAY=-HH.-C. but if they are. *** ERROR *** signed name (+C) follows unsigned (B) 72 Cube Voyager Reference Guide .'+B'. Sort on ascending values in A. but sort order for A is descending SORT ARRAY=-A. It may not exceed the length of the arrays.… NUMRECS=x SORT keywords Keyword ARRAY |S| Description Names of the arrays to be sorted. Example 1 SORT ARRAY=A. NUMRECS |S| Specifies the number of records to sort. 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). carry B & C along with A SORT ARRAY=-A. 1.VMT[_K](10. INCOME[J]. INCOME=ZONES .2c) ENDLOOP ENDPHASE Cube Voyager Reference Guide 73 . SORT ARRAY=-INCOME. NUMRECS=_L LOOP _K=1.BN[_K](6). only want to see the highest 30 LIST=AN[_K](6). AN. the number of entries will be less than the original number of links. .ZONENO LIST=’ Zone Income HHs’ JLOOP PRINT FORM=8. VMT=LINKS .BN.INCOME[I] . BN=LINKS. Generation) ARRAY ZONENO=ZONES. .30 .General Syntax Standard control statements 3 Example 2 (Matrix. */ PHASE=SUMMARY SORT ARRAY=-VMT.-HH. Fratar. HH=ZONES. LIST=ZONENO[J]. Distribution. HH[J] ENDJLOOP Example 3 (Network) ARRAY AN=LINKS.1. ZONENO[I] = I HH[I] = ZI.HH[I] INCOME[I] = ZI. 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. 3 General Syntax Standard control statements 74 Cube Voyager Reference Guide . the basic driver for Cube Voyager application programs.Cube Voyager Reference Guide 4 Pilot Program This chapter describes the Pilot program. Topics include: • • • Using Pilot program Control statements Examples Cube Voyager Reference Guide 75 . 4 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 76 Cube Voyager Reference Guide Pilot Program Using Pilot program 4 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 Cube Voyager Reference Guide 77 4 Pilot Program Using Pilot program balance, or until it is decided that a proper balance can not be achieved. That is only a simple portion of the capabilities of Cube Voyager. As the user learns more of its capabilities, he/she will find that he/she can control the process in many innovative ways. The input is comprised of computational, flow control, program, and system statements. The program begins by reading and editing the Cube Voyager specific statements. The non-Cube Voyager statements (system statements, and the statements that follow a RUN statement until its terminating statement) are not edited by Cube Voyager. When all Cube Voyager statements have been edited for basic syntax, and have been stored in the control stack, the program builds a list of variables and their values from all the COMP and LOOP statements and the variables found in the optional VARI file. The list is stored in the Vars array. It then begins processing the control stack at the beginning. Each stack statement is executed, and flow branches to the next appropriate stack statement. When the end of the stack or an EXIT statement is reached, the program terminates. Stack statements fall into several categories: • Computational statements — Cause variable values to be updated. Typical control statements are: COMP (often invoked by simply: var = ) • Flow control statements — Help to determine which statement is to be performed next. Typical flow control statements are: GOTO :LABEL ONRUNERRORGOTO CLEARERROR LOOP BREAK CONTINUE ENDLOOP IF ELSEIF ELSE ENDIF EXIT 78 Cube Voyager Reference Guide Pilot Program Using Pilot program 4 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: Cube Voyager Reference Guide 79 4 Pilot Program Using Pilot program Warning: Do NOT use a system statement to initiate another Cube Voyager application. With the capabilities of these statements, the user can cause the stack to be processed in almost any order desired. With the flow control capabilities, stack segments can be repeated until desired results are achieved. A typical example would be the repeated application of a series of programs beginning with trip distribution and progressing through assignment. If the adjusted speeds from the assignment program differ too much from the speeds that were used in the distribution process, the series should be repeated. Another example could be the repeated application of a program with a slightly different set of parameters, or different input files. It is up to the user to control the flow. Statement tokens (%...% and @...@) Any statement may contain tokens for substitution. There are two types of tokens: %...% and @...@. If a Cube Voyager control statement contains a %...% token, the token is replaced by the value of the operating system (OS) environment variable between the % signs. If there is no matching variable name in the environment, the token is unchanged (the variable name is case insensitive). It should be noted that the environment is a copy of the environment prior to the execution of Cube Voyager. (NOTE: Any *SET statements will NOT alter the environment; it is suggested that *SET statements not be used.) There is not much use for %...%, but there might be times where it can be quite helpful. The @...@ tokens are processed only when the statement is being processed by a program called via the RUN PGM= statement. When a program is called, it is provided access to the .VAR file with the current values from the Cube Voyager Vars array. The program can update the file when it terminates, but the Vars array is not updated until Cube Voyager is back in control. If the program reads a control statements that contains a @...@ token, the token is replaced by the value of the file variable named between the @ signs. (NOTE: the 80 Cube Voyager Reference Guide Pilot Program Using Pilot program 4 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. Cube Voyager Reference Guide 81 4 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 82 Cube Voyager Reference Guide Pilot Program Control statements 4 *command A statement whose first field begins with a *, and is more than 2 characters long, is considered as a command for the operating system. Cube Voyager will invoke the COMSPEC processor to execute the command. The command will return a code that will be stored in the ReturnCode variable. It is the user’s responsibility to test ReturnCode, since Cube Voyager does not know the meaning of the return codes. It should be noted that some system commands return 0, even if they are unsuccessful. For example: “COPY source dest” will return a 0, even if one of the filenames is illegitimate. NOTE: The *command will be executed in a minimized command window. This prevents disruption of the display, allowing other tasks to be performed more comfortably while the script is running. If it is required that the command window appear on the display, use the alternate **command rather than *command; for example, '**pause' rather than '*pause'. The '**' approach will be appropriate if the command requires some interaction with the user, or perhaps if it displays some progress which the user always wants to be able to view. 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. Cube Voyager Reference Guide 83 4 Pilot Program Control statements Example LOOP i=1,3 IF (condition) statements ELSE BREAK ; get out of loop ENDIF ENDLOOP CLEARERROR CODE RESUME The CLEARERROR statement is used primarily in conjunction with the variable ONRUNERRORGOTO. When the statement is encountered, it automatically resets the internal error code value to 1 and the resume switch to false. It is then the user’s 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 84 Cube Voyager Reference Guide Pilot Program Control statements 4 :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 couldn’t find a variable at that time. However, this causes a problem with using variables returned from a Cube Voyager program invoked by the RUN PGM= statement. Cube Voyager does not know the mode of the variable and can not edit it prior to actual application. To avoid this problem, Cube Voyager automatically assumes any variable that contains a dot (".") within its name as numeric. • 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. Cube Voyager Reference Guide 85 4 Pilot Program Control statements • ID is a special case variable that allows the user to compute a new ID. Because of the potential conflict with the Cube Voyager system ID control statement, ID may not be the first keyword on a COMP statement. If the result of the expression is not numeric, then the resulting character string is copied to the system ID area. In any event, ID then becomes a working variable. • Lambda is a special case variable, and Lambda must also be a variable within the expression. When this form is specified, the program solves the expression for various values of Lambda between 0 and 1.0 in hopes of determining a Lambda that will result in a value of 0. The logic for searching is as follows: Set a min and max Lambda (0 and 1.0) Divide the difference between min and max into equal intervals. Solve for all the interval points between min and max. Find the interval that surrounds 0; if none do, it is an error. If more than one interval surrounds 0, the solution is ambiguous, and it is an error. Reset the min and max Lambdas to the interval points that contain 0. If the interval size is not within the accepted tolerance, repeat steps 2-5. When the interval size is within tolerance, perform a straight line interpolation to zero. Store the results into Lambda. This is not a perfect solution, but if the expression is appropriate (does not contain any transverse slopes, and crosses zero one time), a Lambda between 0 and 1 will be found. The current process works on a bisecting principal for developing the test ranges and uses an tolerance interval of 0.000001. For obvious reasons, an expression that contains Lambda as an expression multiplier without any other terms, will always result in Lambda = 0. A division by Lambda will cause program failure when Lambda is tested for 0. 86 Cube Voyager Reference Guide Pilot Program Control statements 4 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 Cube Voyager Reference Guide 87 4 Pilot Program Control statements ENDCOPY, they are copied as a data records to the designated file. The copy process does not scan the records for special features (/*...*/ %...% etc.). If there is no filename, or the filename is invalid, the error is not diagnosed until the COPY statement is actually processed. For that reason, it may be better to place most COPY statements near the beginning of the input file. The primary use of COPY is to allow the user to include small data files within the input file, so that they can be always be associated directly with the control statements. If the COPY fails, ReturnCode is set to 255; an IF statement can be used to test the results. COPY and ENDCOPY keyword Keyword Description |F| Name of the file onto which the records are to be copied. Must be an acceptable name for the operating system. FILE=filename Example COPY FILE=temp1; copy lookup file for HIGHWAY . . ENDCOPY COPY FILE=temp2 ;copy with imbedded COPY ... will be copied to temp2 COPY FILE=temp3 ; " " " " " ... " " " " " ENDCOPY " " " " " ENDCOPY signals that the prior record was last IF (ReturnCode==255) ... DOWNLOAD URL FILEO CLEARFILEO 88 Cube Voyager Reference Guide Pilot Program Control statements 4 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. Cube Voyager Reference Guide 89 4 Pilot Program Control statements VARI=filename FILEI keywords Keyword LOOKUPI |FKV999| Description Name of file containing records for a lookup function implemented with the LOOKUP control statement. Equivalent to the FILE keyword of the LOOKUP control statement. You must index LOOKUPI. VARI |KF| Specifies the name of the file which is to be read to initialize variables. If not specified, no file is read. The data extracted from the file are stored in the Vars array. If duplicate variables are encountered, the latest one read prevails. Each record from the file contains two fields: a variable name, and its value. The fields may be separated by any number of space(s), with, or without, an = sign. The names may be any reasonable variable names. The statement need not contain the FILEI control word; it may begin directly with VARI. Normally, VARI is not used; it is used only if there are many variables to be initialized. This could be the case if the application is the continuation of a previous application. A var output file will always be written at the termination of the application. Example VARI=XXXX.VAR FILEO Specifies an output file for the PRINT PRINTO capability when printing from Pilot. PRINTO[#]=filename FILEO keyword Keyword PRINTO |KF| Description Specifies the name of the file where the output from the PRINT statement is to be directed 90 Cube Voyager Reference Guide Pilot Program Control statements 4 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 Cube Voyager Reference Guide 91 4 Pilot Program Control statements Example 2 GOTO hwybuild :hwybuild IF (expression) GOTO :hwybuild ;It is permissible to go backwards. IF ... ELSEIF ... ELSE ... ENDIF Performs certain operations based on conditions. There are two forms of this control statement: • • A single statement: IF (expression) statement A block of statements: IF (expression) ELSEIF (expression) ELSE (expression) ENDIF You must predefine any expression variables in an earlier COMP VAR statement. (The program automatically defines any variables not predefined, but with a dot (.) in their name as numeric variables.) You may nest but not overlap IF ... ELSEIF ... ELSE ... ENDIF blocks. They may not overlap LOOP ... ENDLOOP blocks. You may append the following control statements to a single IF statement: • • • • • BREAK COMP CONTINUE EXIT GOTO Example ; Single IF examples: 92 Cube Voyager Reference Guide Pilot Program Control statements 4 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. • • • Cube Voyager Reference Guide 93 4 Pilot Program Control statements If the result of the comparison is true, the program branches back to the statement following the LOOP statement. If it is false, control is passed to the statement following ENDLOOP. Processing of the ENDLOOP statement depends on the value of Incr: • If Incr is positive, when the value of Var is less than or equal to End, the module goes to the statement following LOOP, otherwise the module goes to the statement following ENDLOOP. If Incr is negative, when the value of Var is greater than or equal to End, the module goes to the statement following LOOP otherwise the module goes to the statement following ENDLOOP. • The module tests the ENDLOOP condition (without incrementing the variable value) when initializing the loop-control variable. If the test fails, the module does not perform any statements within the LOOP block. Example 1 Executes the code within the LOOP block 10 times. LOOP iter=1,10 . . ENDLOOP Example 2 A nested loop, with the innermost loop executing twice for each value of variable xyz: 10,8,6,4,2. LOOP xyz=10,1,-2 LOOP abc=1,2 . . ENDLOOP ENDLOOP 94 Cube Voyager Reference Guide Pilot Program Control statements 4 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” Cube Voyager Reference Guide 95 The job failed to run to completion and generated on or more fatal error messages. the user can provide additional statements to further control what is to happen with the run. 96 Cube Voyager Reference Guide . See “GOTO” on page 91 for a description of defining a LABEL.4 Pilot Program Control statements statement is executed. if the user has set the string variable named ONRUNERRORGOTO to point to a legitimate LABEL statement in the script. The CLEARERROR statement also provides a keyword to allow the user to resume executing script at the point following the RUN statement that caused control to be switched to the label specified by ONRUNERRORGOTO. Typically. 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. This code value is stored in a variable named RETURNCODE. However. the run will continue at the labeled statement if the return code is 2. At the labeled statement. and possibly request a response from the user 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 job was aborted by user conditions with the ABORT statement. To continue the run. the program sets a return code that indicates what type of message the program returned on closing. If the RETURNCODE value is greater than 1. 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. the user will set up a PRINT statement to write a message to the run print file or use a PROMPT statement to issue a message. the run is automatically terminated. The CLEARERROR statement is used to reset the internal return code. it can not be cleared by setting RETURNCODE=. Example 1 RUN PGM=MATRIX ENDRUN At this point the job will terminate because there was an error in the Matrix program (no operations).At this point control will transfer to :MYERROR if the MATRIX step fails :STEP2 RUN PGM=…. Note that an EXIT statement should be used just prior to the :label referenced by the ONRUNERRORGOTO. Run will terminate from here with a final completion code of 2 Example 3 ONRUNERRORGOTO = 'MYERROR :STEP1 RUN PGM=MATRIX ENDRUN . ENDRUN EXIT . Refer also to the CLEARERROR statement (see “CLEARERROR” on page 84). if program gets to this point then exit. no errors were encountered :MYERROR PRINT LIST='Special Message' . ENDRUN :STEP3 RUN PGM= ENDRUN Cube Voyager Reference Guide 97 .At this point control will transfer to :MYERROR if the MATRIX step fails RUN PGM=….Pilot Program Control statements 4 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. 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. Example 2 ONRUNERRORGOTO = 'MYERROR' RUN PGM=MATRIX ENDRUN . 4 Pilot Program Control statements EXIT . MAXSTRING 98 Cube Voyager Reference Guide . if program gets to this point then exit. At this point. 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 . or all errors cleared :MYERROR PRINT LIST='Special Message' CLEARERROR CODE=0 RESUME=T .At this point control will transfer to :MYERROR if the MATRIX step fails :STEP2 RUN PGM=…. ENDRUN :STEP3 RUN PGM= ENDRUN EXIT . no errors were encountered . control will return to :Step2 PARAMETERS Specifies basic parameter values for the Pilot run. Versions 3. Example 1 LIST= ITER(6) TIMEPERIOD(6) TOTAL1. and violations of this length were not detected. this parameter must be specified.TOTAL1. TIMEPERIOD. a large value could cause excessive RAM to be allocated. TOTAL2. TOTAL1.0.) Specifying a reasonable length will help to preserve RAM.TOTAL2 FILE=PRINTFIL.0CDLR LIST=ITER. Default value is 255. PARAMETERS keyword Keyword MAXSTRING |KI| Description Specifies the maximum length to use for all string variables. TIMEPERIOD. 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). had a maximum length of 127 characters. PRINT Formats and prints a line of information. If one has many string variables.0CDLR LIST= ITER. a fatal error message will be issued. If a variable is computed to exceed this length. This proved to be too short for some users who were developing strings with considerably longer path names in them. TOTAL2 Cube Voyager Reference Guide 99 . and lower.001 PRINT FORM=6. TOTAL3 FILE=PRINTFIL. (We have seen users’ jobs with more than 200 string variables. and if a string really needs to be longer than 250. Now the user can specify what the longest string variable is to be.Pilot Program Control statements 4 <…> is the program default value.002 Example 2 PRINT PRINTO=1 FORM=6. When the PROMPT dialog box opens. if it contains any delimiters. which the user can test via an IF 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. When encountering a PROMPT statement. Question to prompt the user with. The response must select one of the answers. The ANSWER number is returned to Pilot in the variable named ReturnCode. The program will not continue until a proper selection is made. Enclose with quotes ‘…’ or "…". PROMPT keywords Keyword ANSWER |S5| Description Possible answers. QUESTION |KS| 100 Cube Voyager Reference Guide . the user can peruse the output from any of the previous step(s) to decide how to respond to the question. The same rules about quotes in QUESTION also apply here. There may be up to 5 ANSWERs. The use of the keyword PRNFILE on the RUN statement allows the user to redirect the print file for any job steps. it must be within quotes.4 Pilot Program Control statements PROMPT QUESTION= ANSWER= WAIT= Poses mid-run questions that can alter the flow of the job. the program continues with that selection without requiring a press of the Enter key. and the user responds by selecting a button. the program will then wait until a valid number is entered. If the user makes a choice before WAIT seconds have expired. 2 ABORT . WAIT is disabled. and WAIT is disabled. When Pilot is launched a Windows dialog box opens. ‘Sum Too Low’. . ‘Sum Acceptable – Get Out of Loop’ IF (RETURNCODE==3) break PROMPT Cube Voyager Reference Guide 101 . Once any choice is made. Example QUESTION=’What do you want to do?’. enter an invalid key. and the user can make a choice and then click on the OK button to proceed.Pilot Program Control statements 4 PROMPT keywords (continued) Keyword WAIT |R| Description Number of seconds to wait before automatically continuing using ANSWER [1] as the response.txt to determine response to’. ANSWER=Continue. the program will not continue until a valid choice is made. When in windows mode. 1 ‘Break out of Loop’. a dialogue box is opened. To gain more response time in command mode. . 0< WAIT < 50000 When running in command line mode.txt . ANSWER=’Sum Too High’. as soon as a valid number is entered. ENDRUN PROMPT QUESTION=’Examine myfile. . 3 IF (ReturnCode==3) abort IF (ReturnCode==2) break RUN PGM=MATRIX PRNFILE=myfile. the control statement name. Controls the listing of the stack statements as they are processed. but can be useful for relating TRACE information to internal notation. additional information. ENDRUN Loads and executes a program. if set to true. and. STACK is static. TRACE is a trigger key. This is mostly used for program debugging.4 Pilot Program Control statements REPORT VARS STACK TRACE REPORT keywords Keyword STACK |?| Description Writes the internal stack. in most cases. thus controlling the amount of output as desired. Each statement will be listed with an internal number. TRACE can be turned on and off at any time. the program lists the current variables and their values from the VARS array. When set to true. turn stack tracing on REPORT Trace=n . PGM=name CTLFILE=name PRNFILE=name REDIRECTIN REDIRECTOUT PARAMETERS 102 Cube Voyager Reference Guide ... turn stack tracing off RUN . TRACE |K?| VARS |?| Example REPORT Vars=y REPORT Trace=y . writes occur at the beginning of stack processing. Optional. The program name may be a standard OS file name (path is optional. Pilot attaches any control statements between the RUN and ENDRUN command to the specified program. semi-colon). the associated DLL and TDF files must be directly accessible. you may use additional keywords. */) or by using a GOTO statement. a !RUN statement requires a corresponding ENDRUN.. CTLFILE is ignored. If you are running a non–Cube Voyager program. Parameters that the program expects to find on the invoking command line. Citilabs recommends always using ENDRUN. For example. File be used as the program’s standard input.Pilot Program Control statements 4 Pilot loads and executes the program specified by PGM. If a parameter will contain any special characters (comma. but is recommended for non-TRIPS programs)... Only the specified program will read and edit these statements.. However. or. dash. You can also disable a RUN statement by placing the statement in a null block (/* . ENDRUN signals the end of the RUN statement. space.. a clientdeveloped program to run in accordance with Citilabs specifications. as one string of many parameters enclosed within one set of quotes. a Cube-related program. the quoted parameter must be enclosed by the opposite quote. enclose the parameter within quotes (‘…’ or "…").. in most cases. PARAMETERS |SV| Cube Voyager Reference Guide 103 . or if it requires "def ghi". You can disable a RUN statement by changing it to !RUN. if the program requires ‘abc’ to be passed to it.) or another RUN statement also signals the end of a RUN statement. If CTLFILE is not specified. math operator. it is assumed that the data follows the RUN statement (up to. Though optional. RUN keywords Keyword CTLFILE |F| Description Optional. but not including. If a parameter is to contain quotes. If there are no data records following the RUN statement. and the those records are copied to a temporary file. the next ENDRUN statement). or a standard OS executable RUN file. Pilot expects to load a Cube Voyager program. it should be coded as "’abc’". The program may be a TRIPS program. A system command (*. it should be coded as ‘"def ghi"’. Parameters may be coded as a series of values. and then the directories as registered with the operating system If program*. Switch to indicate that the program is to direct its output to PRNFILE. REDIRECTIN REDIRECTOUT |?| |?| If it is determined that a TRIPS program is being run (by the presence of &FILES OPRN keyword in the CTLFILE).DLL” and “program.4 Pilot Program Control statements RUN keywords (continued) Keyword PGM |S| Description Program to be run.exe” to program. PRNFILE will be ignored if it is determined that a TRIPS program is being run. Pilot determines if it is a Cube Voyager program by searching for both “program. and to locate the directory where it resides.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.). If program has no file extension and the last character is not a dot (. Optional. append “.exe and use the highest # file. and REDIRECTOUT are ignored. Optional. if PRNFILE is also specified.exe are all found.exe will be assumed. PRNFILE |F| Optional. and name3. locate the program by searching the directory from which Pilot was loaded. File where the program expects to write its standard system print output. 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. use that path If program does not contain path information. 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. look in that directory for the latest version of the program by assuming program#. name1. if name. name3.exe is found. Thus. PRNFILE.exe. There may be programs 104 Cube Voyager Reference Guide . REDIRECTIN. If program contains path information (has a \ or :).exe. Switch to indicate that CTLFILE is to be directed into the program. tprn is a temporary file which is copied to the Cube Voyager print file. it is possible that the use of the Pilot * statement will allow the direct running of the command. If ctlfile has no length.Pilot Program Control statements 4 whose basic operations will not allow this type of integration.exe ctlfile=datain prnfile=dataout parameters=’abc’ Command: Path\abc.exe datain dataout abc RUN PGM=ME ctlfile=datain parameters="/m=20" "/demo" Cube Voyager Reference Guide 105 . The RUN statement for non-Cube Voyager programs generates a system command that is structured and executed based upon the following decision table. it is not placed on the command line 2. • • 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. In those situations. DRI/RDO = redirectin/redirectout Examples RUN PGM=program parameters=datain. dataout Command: Path\program.exe datain dataout RUN PGM=abc. 3. zip t*.". will be copied to tfile Command: Path\MVESTM70.4 Pilot Program Control statements Command: Path\MVESTM70.EXE tfile RUN PGM="c:\util\pkzip. standard Cube Voyager run SENDMAIL SMTPSERVER FROM TO CC SUBJECT MESSAGE ATTACHMENTS USERNAME PASSWORD PORT 106 Cube Voyager Reference Guide .EXE datain /m=20 /demo RUN PGM=ME .exe junk.exe" parameters="junk. "-v –c". -v –c >zip. redirectout=t Command: c:\util\pkzip.zip t*.txt RUN PGM=MATRIX . ctlfile follows this statement.txt. prnfile=zip. SENDMAIL keywords Keyword ATTACHMENTS CC FROM MESSAGE |S| |S| |S| |S| Description List of file names sent as attachments. which t allows you to mask the password for security. Password for the account specified in USERNAME.sbcglobal. Each string is a separate line. Name of the send-mail server. FROM. Use to transmit the status of a job or job step to a recipient. Cube opens a Password Entry dialog box.com Cube Voyager Reference Guide 107 . There is a maximum of 1000 attachments. The typical SMTP server uses PORT number 25.Pilot Program Control statements 4 Immediately sends an e-mail. An example might be: smtp.yahoo. The keywords SMTPSERVER. if the SMTP server requires secure logon. E-mail address(es) for copied recipient(s). and SUBJECT must be specified. E-mail address to be sent as the return List of individual lines to send in the message area of the e-mail. you can insert the password value with the Insert menu command then selecting Password for email. TO. PASSWORD |S| PORT SMTPSERVER |I| |S| <25> is the TCP PORT number. There is a maximum of 1000 messages. If coding your script in Cube. E-mail messages can also be sent as text messages to a cell phone. the others are optional. 4 Pilot Program Control statements SENDMAIL keywords (continued) Keyword SUBJECT TO |S| |S| Description Subject of e-mail. USERNAME |S| User name for mail account.com Verizon: {phone#}@vtext. set LABEL to jump to if an error occurs StepName='Step 1 . if the mail SMTP server requires logon. FROM='
[email protected] ZONES=24 ENDRUN StepName='Step 2 .======================================================================== ONRUNERRORGOTO='ONERROR' .DBF NETO=DTWNTPP1. Separate multiple recipient addresses with a comma. Example Using SENDMAIL with ONRUNERRORGOTO. RETURNCODE. You can also send mail as a text message to a phone and account that supports text messaging.yourname. 108 Cube Voyager Reference Guide . and CLEARERROR to generate e-mail with attachments for various conditions . Examples of cell phone provider messaging e-mail addresses are: • • • T-Mobile: {phone#}@tmomail.Network' RUN PGM=NETWORK NODEI=xDTWNNOD.sprintpcs.com'.DBF. LINKI=DTWNLNK.Network' RUN PGM=NETWORK NODEI=DTWNNOD. E-mail address(es) of the recipient(s).NET ENDRUN SENDMAIL SMTPSERVER='smtp.com Check with his/her cell phone service provider to verify the appropriate address.DBF. LINKI=DTWNLNK.net Sprint: {phone#}@messaging.com'.DBF NETO=DTWNTPP1. returncode:'.yourname. ATTACHMENTS='DTWNTPP1. Message='There is a run error. ignore the error. FROM='ken@yourname. Message='There is a run error.NET' Exit . Subject='Email from Voyager. Run Error'. Also text message a cell phone SENDMAIL SMTPSERVER='smtp. CC='The Boss<boss@yourname. if no errors then this step gets executed and terminates the run :ONERROR .StepName . TO='ken@yourname. Run Error'.Pilot Program Control statements 4 TO='
[email protected]'. Run Completed. Subject='Email from Voyager. returncode will have value=0. TO='5106635200@messaging. 'There is no run error'.com'.Network') CLEARERROR resume=t code=0 endif Cube Voyager Reference Guide 109 . if an error occurs the processing jumps to this location rcode=str(returncode.com'.com'. 'On Step '.rcode.3 SENDMAIL SMTPSERVER='smtp. FROM='
[email protected]. If the error happens on step 2.2. No Error'.com'. Message='Voyager Run Completed'.1.com'.com'. 'On Step '.com>'. Subject='Email from Voyager.0) .com.sprintpcs. returncode:'. resume the run if (StepName='Step 2 .yourname.StepName .jill@yourname. 4 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. data for HIGHWAY to load trips to highway network ENDRUN RUN PGM=NETWORK .5 COMP ID='This is iteration' + str(iter.0) RUN PGM=NETWORK 110 Cube Voyager Reference Guide . data for NETWORK to analyze assignment ENDRUN Pilot example 2 /* Example 2: A little more complicated. They are excluded. */ LOOP iter=1. data for HIGHWAY to build LOS files ENDRUN RUN PGM=DISTRIBUTION .2. All the RUN statements would have statements following them (including an ENDRUN statement). so that process can be presented more briefly. with no logic. data for NETWORK to build a network ENDRUN RUN PGM=HIGHWAY . data for DISTRIBUTION to distribute trip ends ENDRUN RUN PGM=MATRIX . data for MATRIX to combine and factor matrices ENDRUN RUN PGM=HIGHWAY . */ RUN PGM=NETWORK . * r: RUN PGM=PUBLIC TRANSPORT read r:altx01.02) GOTO Early_Converge ELSEIF (NETWORK.04) LIST=' exit early ' + str(iter.RESULT <= 0. list current variables Newpage BEFORESYS=y.2.2.set ENDRUN IF (RETURNCODE > 0) EXIT *COPY r:trnnet d:\transit\neta Cube Voyager Reference Guide 111 .0) + ' iterations' :TRANSIT ID=BEGIN TRANSIT PROCESSING REPORT vars=y . */ LOOP iter=1.0) RUN PGM=NETWORK RUN PGM=HIGHWAY RUN PGM=DISTTRIBUTION RUN PGM=MATRIX RUN PGM=HIGHWAY RUN PGM=NETWORK ENDRUN IF ( NETWORK. criteria already satisfied ENDLOOP Pilot example 3 /* Example 3: more capabilities.5 COMP ID='This is iteration' + str(iter.02) BREAK . AFTERSYS=y .0) + ' iterations’ GOTO TRANSIT ENDIF ENDLOOP LIST='Speeds did not converge' EXIT :Early_converge LIST='Convergence after ' + str(iter. copy transit files to ramdisk *COPY d:\transit\neta\altx*.Pilot Program Examples 4 RUN PGM=HIGHWAY RUN PGM=DISTTRIBUTION RUN PGM=MATRIX RUN PGM=HIGHWAY RUN PGM=NETWORK ENDRUN IF ( NETWORK.2.RESULT <= 0.RESULT <= 0. 4 Pilot Program Examples 112 Cube Voyager Reference Guide . Topics include: • • • Using Fratar Control statements Examples Cube Voyager Reference Guide 113 . a process for modifying a matrix values.Cube Voyager Reference Guide 5 Fratar This chapter discusses Fratar distribution. When the criteria for convergence is met. In such cases. the program will fatally terminate. but the column totals will most likely not match their targets. A complete convergence (target row and column totals obtained for all zones) can be obtained only if the target grand control totals for rows and columns are the same. The program makes adjustments to guarantee that the target grand totals do match. but the row totals may not match their targets. the row and column totals should converge towards the target totals. This section discusses: • • • • Specifying target values Controlling target totals Convergence — Iteration control Multiple purposes 114 Cube Voyager Reference Guide . The process is a relatively simple iterative one: In the first iteration. the process is complete. each row in the matrix is factored according to its production factor. the column totals will match the target column values.5 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. This process continues for some number of iterations. the row totals will match the target row values. It is possible that the user input values and specifications can preclude obtaining matching totals. At then end of the iteration. At the end of the iteration. In the second iteration each column in the modified matrix is factored according its attraction factor. Example 1 SETPA P[1]=ZI. of these filters are specified on a SETPA statement. the term “value” will be used to mean either direct values or growth factors.1. They are input to the program via P. To simplify this description. All specifications are via the SETPA control statements. the program revises it to a growth factor of 1.EXTW/2 AGF[1]=PGF[1] INCLUDE=501-550 Cube Voyager Reference Guide 115 . and AGF[]= expressions are computed for corresponding arrays. the SETPA statement may include the basic INCLUDE and EXCLUDE filter specifications. A[1]=ZI.Fratar Using Fratar 5 Specifying target values There are several typical ways in which the control totals can be specified: direct values. each would have its own zonal filter set. If the sets overlap. PGF. Each of the keyword expressions is computed for an array of values for all zones. To provide the capability of mixing P and PGF for a purpose. An array of production values (Ps) and an array of attraction values (As) are maintained for each purpose.0. and AGF expressions. If the final value for a P or A is 0. the latest SETPA values replace any prior values. or both. the PGF and AGF expressions are used. Direct values and growth factors can be mixed for a purpose.1.HBWP2000 would cause the program to simulate the expression: JLOOP J=1. the P and A expressions are used. To specify P and PGF for the same purpose. If direct values are to be input. or some combination of both.HBWP2000[J] . ENDJLOOP Similarly. If either.2.HBWA2000 INCLUDE=1-500 SETPA PGF[1]=ZI. There must be a set of production values and attraction values for each matrix to be factored.1.1. growth factors (explicit and implicit). PGF[]=. separate SETPA statements are used. but a complete understanding of the SETPA statement is necessary. If growth factors are to be input. A[]=. P[1] = ZI.ZONES P[1][J] = ZI.HBWP2000. they apply to all expressions on that statement. A. After all SETPA P. the target totals for any growth factor values can be fully determined (value = gf * input)..A.input a specific value SETPA A[1]=sqrt(J/2+25**3. INCLUDE=1-500 . Again. the values for zones 1-500 would be the direct values obtained directly from the ZI. the program performs a zonal (I) loop.1. but that is not an absolute requirement. Sometimes. it is desirable to input specific values. Controlling target totals After processing the input matrix. Example 2 SETPA P[1]=5000 INCLUDE=255 . Standard numerical expressions (J being the only viable variable that could be included) are used to compute the values. but applied for each I zone. but weird. but care must be exercised. Therefore the filters will apply to both the I and J zones.would be possible. the program adjusts the values to insure that the P and A totals match for each purpose.5 Fratar Using Fratar In this example. The matrices are obtained by solving the SETPA MW[]= expressions. Example 3 SETPA MW[1]=. if they are specified. and the values for zones 501-550 would be the growth factors obtained from the ZI. The MW expressions are array notation.5) . the INCLUDE and EXCLUDE filters are employed.PGF. and AGF expressions are processed.2. Next.EXTW array (divided by 2). A special feature of these expressions is that if the result is less than zero. it is not stored. will compute only the I=1-500 to J=1-500 portion of the matrix. There may be a CONTROL specification for each purpose. they are specified by the use of the CONTROL keywords on the SETPA statement. There are several options for adjustment. or LOOKUP functions. obtaining the matrix values for each purpose. and if the CONTROL for any purpose is specified more 116 Cube Voyager Reference Guide .HBWP2000 array. In most cases the values will be obtained from ZDATI (zonal data) files.. The changed zones in the P array will be factored so that the final P total will match the A total. The A totals control. some modelers would scale a matrix by a value (usually 10. The valid values for CONTROL are: P. 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. the program will fatally terminate. AL. all values in the P array will be factored so that the P totals will match the A totals. column. and PAL. lead to a situation where a matrix grand total can not be properly computed. the latest value prevails. Sometimes only certain zones are to be modified. If no CONTROL is specified it defaults to PA. Value PL AL PAL Description The P totals control. 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. PL. Use of the this feature can. If the letter “L” is appended to any of the CONTROL values. If a target value is specified for a zone that initially had no total. that has zero to begin with. Traditionally. The changed zones in the A array will be factored so that the final A total will match the P total. or 100). The values in P array for zones that have P changes. all values in the A array will be factored so that the A totals will match the P totals. or bad. and the remainder of the zones are to be kept constant. PA. zero accountability is not included in this program Cube Voyager Reference Guide 117 . solution. The A totals control. All values in both the P and A arrays will be factored so that their totals will match the average of the initial totals. or row. If that is the case. because of the potential problems associated with this approach. A. and then fill in all empty cells with one.Fratar Using Fratar 5 than one time. But. This is not necessarily a good. in some cases. The meanings are: Value P A PA Description The P totals control. a warning message is issued. It is impossible to modify any cell. it indicates that the modifications are Limited to only the zones that have change. If the scaling scheme is to be applied.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 118 Cube Voyager Reference Guide . The user can specify a maximum number of iterations. the “solved” matrices are held steady. If this happens. the program detects the oscillation. due to some unforeseen conditions. and terminates the process at the minimum RMSE. Convergence — Iteration control A concern is when to stop the iterating process. column total differences are checked. there are several ways to control it. A small example of this process: After Iteration 1: RMSE = 22. It could also be achieved by setting the SETPA MW expression to: max(1. and after even iterations. row differences are checked. After odd iterations. the program computes an RMS error value based upon the integer differences between the computed and target row or column totals.n.5 Fratar Using Fratar directly.mi. It is believed that this process will eventually reach convergence. so that no matter how the convergence is progressing. After each iteration. the process will not exceed that number. If the RMSE value is less than the MAXRMSE parameter value.n*10). the solution is achieved. and the others continue to be processed. But if. the RMSE value begins to oscillate. If there are multiple matrices being factored. a prior application of the Matrix program can be used to scale and fill in a matrix in any desired manner. they may reach optimum solutions at different times. back and forth.Fratar Using Fratar 5 As dictated by row factoring. This process goes on. After Iteration 5: RMSE = 0 Zone 1 2 3 Total 1 60 70 113 240 2 25 190 64 200 3 16 26 118 160 Total 102 206 292 600 All values are shown to the nearest integer and thus may not total exactly. until either the RMSE drops to the MAXRMSE level. the row totals are correct. and the results appear as: After Iteration 2: RMSE = 7. AGF. monotonically. The distribution is performed prior to entering the main Matrix program I loop.94 Zone 1 2 3 Total 1 61 69 110 240 2 25 111 64 200 3 16 26 118 160 Total 102 206 292 600 The column totals are now on target. the values are carried with more precision. Internally. When the main I loop is processed. the column totals do not quite match the target. A. or the number of iterations reaches the MAXITERS value. through that highest index. MW[1] through MW[highest purpose] Cube Voyager Reference Guide 119 . the final solution is reached after 5 iterations (MAXRMSE=0. but the row totals are not quite on target.01 and MAXITERS=10). The program assumes that there will be purposes from one. But. PGF. or MW index found on any SETPA control statement. Another iteration is performed. In this example. Multiple purposes The number of purposes is determined by the highest P. 5 Fratar Using Fratar are initialized with the final matrices from the Fratar distribution. a standard Matrix program I loop is performed. 120 Cube Voyager Reference Guide . After the factoring process is complete. For descriptions of other control statements see Chapter 9.Fratar Control statements 5 Control statements All the standard Matrix statements are valid in Fratar. “Matrix Program. MATOEVERY MAXITERS MAXPURPS MAXRMSE ZONES Cube Voyager Reference Guide 121 .” 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. This section only describes the differences between the Matrix and Fratar control statements. Fratar is a subset of the Matrix program. and a few additional ones are available. If the MAXRMSE criterion is met. 122 Cube Voyager Reference Guide . If you anticipate that there will be many iterations before reaching convergence. For large systems. not writing output matrices for each iteration saves considerable computer time. and the max is 99. The default is 9. 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. MAXITERS |KI| Maximum number of iterations. but forces another processing iteration to write the matrices after reaching convergence. Writing output matrices for each iteration increases run times for each iteration. set this switch to false. you may specify the parameters described here. the number of iterations actually performed could be less than this value. but prevents the program from having to run another iteration to write the output matrices after reaching convergence. set this switch true.5 Fratar Control statements In addition to the standard Matrix parameters (see “PARAMETERS” on page 518). If you anticipate that the process will involve only a few iterations. MAXRMSE |KR| REPORT PCOMP ACOMP In addition to the REPORT keywords available for Matrix. so this keyword should not be required. and the minimum is 0. The default is 10. a fatal message will be issued. a solution is assumed for the purpose. but refers to productions. or the value will default to 100. Cutoff criteria. and it conflicts with the SETPA statements. If the number of zones cannot be ascertained from the project file or from any binary input matrices. but they are reported for all odd iterations. Only the purposes specified by the keyword are reported. But. and refers to only even iterations. ZONES |KI| Highest zone number to process. ZONES must be provided. The keyword is not required. if this value is provided.Fratar Control statements 5 PARAMETERS keywords (continued) Parameter MAXPURPS |KI| Description Number of purposes to process in this application. there will be an input matrix file. Normally. this value controls the application. If present. because the program will determine the value from the detection of the values on the SETPA statements. The values are reported as nearest integers (without decimal places). The report is in a format that is similar to the MARGINS report. the following are also available for Fratar: REPORT keywords Keyword ACOMP |KIP| Description Requests report comparing computed to target attractions for specified purposes. Same as ACOMP. PCOMP |KIP| Cube Voyager Reference Guide 123 . If the RMSE for a purpose does not exceed this value. In a purpose where the Ps and As are the same for each zone. and then set the As equal to the Ps. The highest index encountered establishes the number of purposes. if it is not included. but the use of any variables in the expression could cause unpredictable results. the program will issue a warning statement. Duplication of purposes might be helpful if values for different zones for a 124 Cube Voyager Reference Guide . The SETPA expressions are computed in the order in which they appear in the control stream. the expression is solved in a loop of J=1-Zones. The keywords may not have a zone index in the SETPA statement.P.MW [n][J] cells. and the results are stored in the A. For each array. monotonically. Complex expressions are allowed. and how many purposes are to be processed. These statements define how the production and attraction factors are to be obtained. If there are any holes in the purpose scheme. until all purposes are defined. it is acceptable to set the Ps.5 Fratar Control statements Example ACOMP=1-3.prior to the first iteration. There should be a P[]= and A[]= and MW[]= expression for every purpose beginning with 1 and continuing.5 . the subsequent values will replace the prior values. and they are computed only one time -. the expression will simply point to a ZDATI file variable.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. The Ps and As are computed from the expressions that are supplied. the program will fatally terminate. In most cases. If the same purpose is referenced more than one time. Same as P. SETPA keywords Keyword A AGF |NV| |NV| Description Expression solved to set the target attraction totals for the indexed purpose. If it is used. or if different INCLUDE/EXCLUDE filters are to be used (different SETPA statements must be used for different filters). The final totals are obtained by multiplying the growth factors by the initial input matrix totals.Fratar Control statements 5 purpose are to be obtained from different sources. String indicating how to adjust final target totals to enable convergence. the loop will not be processed for any zones in the list. Processed the same as INCLUDE on COMP statements (see “COMP” on page 43). the loop will not be processed for any zones not in the list. but only adjustable zones will be adjusted EXCLUDE |IP| Processed the same as EXCLUDE on COMP statements (see “COMP” on page 43). INCLUDE |IP| Cube Voyager Reference Guide 125 . Expression solved to set the target attraction growth factors for the indexed purpose. EXCLUDE filtering follows any INCLUDE filtering. Ps will be adjusted Both Ps and As will be adjusted to the average of the P and A totals. but only Ps in adjustable zones will be adjusted PAL Same as PA. but only As in adjustable zones will be adjusted CONTROL |SV*| AL Same as A. If it is used. As will be adjusted Attraction totals control. INCLUDE filtering precedes any EXCLUDE zones. The possible values are: P A PA PL Production totals control. Usually.P1) A3=(ZI. but that is not required.1. MW[1]=mi. AGF[1]=PGF[1].P1) A1=(ZI.1.1.A1) MW3=1 CONTROL[3]=PA 126 Cube Voyager Reference Guide .n.P1) A2=(ZI.1.1.1 CONTROL=PAL Using multiple CONTROL keywords: SETPA P[1]=(ZI.1. this expression will be a single variable name such as MI. Expression solved to set the target production growth factors for the indexed purpose.A1) MW1=1 CONTROL[1]=A SETPA P[2]=(ZI.5 Fratar Control statements SETPA keywords (continued) Keyword MW |NV| Description Expression solved for each zone during the first iteration. P PGF |NV| |NV| Example Using single CONTROL keyword: SETPA PGF[1]=zi. Expression solved to set the target production totals for the indexed purpose.n. The result is the matrix row for that zone.1.1.A1) MW2=1 CONTROL[2]=P SETPA P[3]=(ZI.xifac. LOOKUP[1]=1.LOOKUP[2]=1. The MATRIX step generates a 3 zone matrix.MAT. '2 200 200'. and the FRATAR step modifies it.MAT MATO=3ZONEF. R='1 100 240'.RESULT=2. '3 300 160' MAXRMSE=0.Fratar Examples 5 Examples /* The following two steps (MATRIX and FRATAR) setup and run the small example used in the Introduction to illustrate convergence.J) A[1]=TOT(2. */ RUN PGM=MATRIX ZONES=3 MATO=3ZONE.J) MW[1]=MI.MO=1 LOOKUP NAME=TOT. It is a good example of different ways to “play” with MATRIX.PCOMP=1 MARGINS=1 ENDRUN Cube Voyager Reference Guide 127 .01 MAXITERS=10 SETPA P[1]=TOT(1.1 ACOMP=1.1.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.RESULT=3. 5 Fratar Examples 128 Cube Voyager Reference Guide . “Intersection Modeling. For information about the junction file. Topics include: • • • • • Using the Highway program Phases Control statements Theory Examples The junction file is part of the Highway program.Cube Voyager Reference Guide 6 Highway Program This chapter discusses the Highway program. see Chapter 7.” Cube Voyager Reference Guide 129 . “Intersection Modeling. This makes many forms of path based analysis directly accessible in Cube without having to rerun the assignments with specific commands in the scripts. final junction delay and reports can be output. See the description of PATHO in “FILEO” on page 196 and “PATHLOAD” on page 223. and a loaded network. Refer to Chapter 7. The descriptions below refer to link based traffic assignment. but the user can control much of the process 130 Cube Voyager Reference Guide . 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. The Highway program now can write the full path file from an assignment run including full results from every iteration. Junction-constrained assignment requires the coding of the junction or intersection movements and controls. There are basic default operations. zonal matrices. The Highway program’s primary function is to assign trips to highway network links. junction data and turn penalties can be input. new matrices. A highway network.” for a detailed description of intersection modeling and the data requirements. turning volumes.6 Highway Program Using the Highway program Using the Highway program This section provides helpful information about using Cube Voyager’s Highway program. also refer to “Highway path display” on page 278 of the Cube Base Reference Guide for information about path-based analysis in Cube. zonal data. Various options are usually available to provide the user with additional outputs. and usually writes them to output matrices. Normally. the LINKREAD phase can be used and formulated to provide these values. the user must supply the process to obtain them.Highway Program Using the Highway program 6 A typical assignment program builds paths based upon link costs (impedances) and assigns trips to those paths for each origin zone. Almost all of the operations follow a fixed pattern. Cube Voyager Reference Guide 131 . There are several ways to obtain the free flow time (T0). Select link analysis is a major tool for most users. Different criteria are used to determine when enough iterations have been performed. and are driven by basic parameters. In that case. but since there is no fixed format of the network. This process “traps” the trips that meet the select link criteria. the cost is time. In addition to phase operations. The program operates by processing in various phases. there must be a way of computing certain required values for each link. For normal processing. and global parameters are used sparingly. in the description of the LINKREAD phase. The underlying assumption is that path building and capacity restraint are based upon a generalized cost on each link. the required variables may not be present. and the initial path time (T1). If there is no automatic way for the program to determine these values. The volumes from each iteration are combined to form a weighted assignment. In most cases. The Highway program provides the same capabilities as a traditional assignment program. but functions somewhat differently. The hierarchy of the processes to obtain T0 and T1 is outlined below. There are only a few automatic operations. After all origin zones have been processed. and optionally processes a stack of operations provided by the user for that phase. link costs are updated based upon the level of congestion on each link. This process continues until some criteria for termination is reached. 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. the values are computed directly from the variables in the input network. Then the entire path and assignment process is repeated. In each phase the program performs certain specific operations. If the variables DISTANCE. If such a network is used directly. LANES. SPDCLASS. and CAPACITY. and is not necessarily a true T0 (free flow time). not absolutely necessary T0 = LI. TIME1. DISTANCE and TIME1 are usually in hundredths of miles and hundredths of minutes.CAPACITY * CAPFAC . LANES. T0 can be computed from the DISTANCE and the values from the SPDTAB speed table. If the network distance is properly scaled. ProductName converted networks will be in nearly the correct format.DISTANCE/100 . The major phases in the process are: • • • • SETUP — Optionally. TIME1 is the starting time for assignment. 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. the LINKREAD stack should contain the following statements: DISTANCE=LI. factor to get on same scale with trips In reality. or that it contains variables so that DISTANCE and SPEED information can be easily obtained. it will usually contain variables named DISTANCE. If the network is the result of conversion from a TRANPLAN network. T0 will be computed from the DISTANCE. so that it is not necessary to remember to deal with them in the Highway program.TIME1/100 C = LI.6 Highway Program Using the Highway program The best advice is that the network should contain a variable that can be used directly for T0. and SPDCLASS are in the network. CAPACITY is normally the total capacity for the link. and the SPEED portion of the SPDCAP tables. respectively. it would be better to rename and scale the variables appropriately during the network conversion process. but the user should also be aware to scale the variables to the correct values. test for convergence and adjust link values for next iteration 132 Cube Voyager Reference Guide . Highway Program Using the Highway program 6 • 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. Examples include: FILEI and FILEO which define the input and output data FUNCTION LOOKUP PARAMETERS • Computational statements — Update variable values. Examples include: Cube Voyager Reference Guide 133 . However. For more information about phases. Highway program control statement overview There are several types of control statements in the Highway program: • Definition statements — Define static processes. see “Phases” on page 150. A PHASE will also be closed if an new PROCESS PHASE=PhaseName or PHASE=PhaseName statement is encountered prior to an ENDPROCESS or ENDPHASE. The phases are specified by using PROCESS PHASE=PhaseName statements. A PHASE is closed with either an ENDPROCESS or an ENDPHASE statement. These two statements are interchangeable. Examples include: COMP PATHLOAD SET • Reporting statements — Accumulate or dynamically display values. most users simply use the short form: PHASE=PhaseName without the PROCESS control word. for simplistic purposes. the program will terminate with an appropriate message. if there is no explicit ILOOP phase. 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. 134 Cube Voyager Reference Guide . See “FUNCTION” on page 206. see “Control statements” on page 174. arrays. Examples include: GOTO :label LOOP BREAK CONTINUE ENDLOOP JLOOP ENDJLOOP IF ELSEIF ELSE ENDIF EXIT For details about control statements. You can also use FUNCTION statements to enter single expressions for computing certain values. but capitalization may make them a bit more meaningful.6 Highway Program Using the Highway program PRINT PRINTROW REPORT • Flow control statements — Set statement order. Functions and built-ins This section lists built-in variables. Its value is checked at the end of the current I. usually 1. by default. Variable _SKIPTOI Description In the ILOOP phase.Highway Program Using the Highway program 6 Built-in variables Only the variables with a * may be stored into by the user. If specified. Link free flow time. Link speed. Total link volume used in ADJUST. Lambda value computed for this iteration. C* DISTANCE* I ITERATION J LAMBDA LASTITERATION LINKCLASS* LINKNO LOWCNT NODES NUMLINKS PROJECTLINK SPEED* T0* T1* V* ZONES Cube Voyager Reference Guide 135 . Number of nodes. the others are reserved. Column index. Current iteration number. Link distance expressed in miles or kilometers. it is the sum of all VOL[] sets. Zero value means do not include in equilibrium. and varies (1-Zones) for MW[] and JLOOPs. Current row’s zone (ILOOP). See “Example of _SKIPTOI” on page 141. Capacity used in congestion expressions. The specified value must be greater than the current I. you can modify in LINKREAD. Initial iteration time. Cube Voyager sets I to that value. usually set to the MAXITERS parameter Class of the current link. Last iteration indicator. Link number (available during any implied link loops) Result of LOWEST(). you can modify in LINKREAD. jump to the specified zone immediately. Number of links. Number of zones. do not be reset. Convert mw to integer values (start at column intrazonal + 1).s1. Most times. Multiply mw[d] by mw[s]. Factors the row by fac. Link distances. B-nodes for each link.name LW. The names with a * can be stored into. Number of cells whose values != 0. Add matrixes mw[1] + … + mw[sn] into mw[d]. Link cost values. Array A B COST DIST* LI.name* MW[]* TIME* VOL[]* Description A-nodes for each link. A work matrix. Maximum value in the row.s) Description Row total. Built-in functions These built-in functions are described in “COMP” on page 177. Average cell value where value!=0. the default [linkno] is supplied by the program. Link volumes. the others are reserved. 136 Cube Voyager Reference Guide . Minimum value in the row. see “COMP” on page 177 for more details.…. Function ROWSUM(mw) ROWCNT(mw) ROWMIN(mw) ROWMAX(mw) ROWAVE(mw) ROWFIX(mw) ROWFAC(mw.6 Highway Program Using the Highway program Built-in arrays There are arrays that can be referenced with […] to indicate a specific value from the array. Link times. Link values from the network. User generated values for links (currently accepts numeric values only).sn) ROWMPY(d.fac) ROWADD(d. the link-oriented arrays need not be referenced with an index. class) CAPACITYFOR(lanes. Actual number of cells found by LOWEST function. LI. Initialized to the value PARAMETERS RELATIVEGAP. The RMSE for the current iteration. Built-in variables available in the CONVERGE phase There are various variables available for testing in the CONVERGE phase. Cost. Converge phase variables Variable GAP RGAP AAD RAAD PDIFF RMSE BALANCE GAPCUTOFF* RGAPCUTOFF* AADCUTOFF* Description The GAP for the current iteration. Must be indexed for previous iterations.s) LOWEST(mw.b) Description Divide mw[d] by mw[s]. The PDIFF for the current iteration. Speed from spdtab. See “CONVERGE phase” on page 166 for examples of usage. Link number for link a-b. may be reset anytime. The RAAD for the current iteration. Must be indexed for previous iterations. Initialized to the value PARAMETERS AAD. Initialized to 0 and set to 1 when convergence criteria have been met. Capacity from captab. may be reset anytime Cube Voyager Reference Guide 137 . Sum of link values (Time. Must be indexed for previous iterations.) on path for I to J.class) PATHTRACE(value) LINKNUM(a. The RELATIVEGAP for the current iteration. Must be indexed for previous iterations. Initialized to the value PARAMETERS GAP. Must be indexed for previous iterations.#) LOWCNT SPEEDFOR(lanes. The AAD for the current iteration. may be reset anytime.Highway Program Using the Highway program 6 Function ROWDIV(d. Must be indexed GAP[] for previous iterations. or LW. Sum of lowest valued cells in a matrix row. may be reset anytime. See “CONVERGE phase” on page 166 for examples of usage. where n = the number of iterations to process. 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.6 Highway Program Using the Highway program Converge phase variables (continued) Variable RAADCUTOFF* PDIFFCUTOFF* RMSECUTOFF* Description Initialized to the value PARAMETERS RAAD. Maximum GAP between the last n iterations. Built-in functions available in the CONVERGE phase There are various functions available that return a value for testing in the CONVERGE Phase. may be reset anytime Initialized to the value PARAMETERS PDIFF. GAPCHANGEMIN 138 Cube Voyager Reference Guide . Function that results in the average GAP between the last n iterations. where n = the number of iterations to process. may be reset anytime Initialized to the value PARAMETERS RMSE. Minimum GAP between the last n iterations. Change in RAAD between the specified iteration (the required argument) and the previous iteration. where n = the number of iterations to process. Change in AAD 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 RELATIVEGAP between the specified iteration (the required argument) and the previous iteration. Minimum change in GAP between the last n iterations. where n = the number of iterations to process. Change in RMSE between the specified iteration (the required argument) and the previous iteration. 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. Minimum RAAD between the last n iterations. where n = the number of iterations to process. Maximum RAAD between the last n iterations. Average change in GAP between the last n iterations. Minimum AAD 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. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. Average AAD between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. Minimum change in RAAD between the last n iterations. Average RELATIVEGAP 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. Minimum change in RELATIVEGAP between the last n iterations. where n = the number of iterations to process. Average RAAD between the last n iterations. Maximum change in AAD between the last n iterations.Highway Program Using the Highway program 6 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. Average change in AAD between the last n iterations. Minimum change in AAD between the last n iterations. where n = the number of iterations to process. Cube Voyager Reference Guide 139 . Minimum RELATIVEGAP between the last n iterations. where n = the number of iterations to process. Minimum change in RMSE between the last n iterations. In many applications. 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. where n = the number of iterations to process. where n = the number of iterations to process. Minimum PDIFF between the last n iterations. Minimum change in PDIFF between the last n iterations. For example. Average change in PDIFF between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. 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. where n = the number of iterations to process.6 Highway Program Using the Highway program Converge phase functions (continued) Function RAADCHANGEMAX RAADCHANGEAVE PDIFFMIN PDIFFMAX PDIFFAVE PDIFFCHANGEMIN PDIFFCHANGEMAX PDIFFCHANGEAVE RMSEMIN RMSEMAX RMSEAVE RMSECHANGEMIN RMSECHANGEMAX RMSECHANGEAVE Description Maximum change in RAAD between the last n iterations. Average RMSE between the last n iterations. Maximum PDIFF between the last n iterations. Average change in RAAD between the last n iterations. where n = the number of iterations to process. only a few ILOOP statements will be required. where n = the number of iterations to process. Average PDIFF between the last n iterations. Minimum RMSE between the last n iterations. where n = the number of iterations to process. an assignment would require only the following statements: 140 Cube Voyager Reference Guide . Maximum RMSE between the last n iterations. Maximum change in PDIFF between the last n iterations. While the program bases its computations upon generalized costs. PHASE=ILOOP PATHLOAD VOL=MI. In our examples Cube Voyager Reference Guide 141 . the first zone will be processed and then jump to I=100. 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. most users tend to think of assignments in terms of time. RUN PGM=HIGHWAY FILEI NETI=. PATH=TIME ENDRUN Example of _SKIPTOI /* In this example.Highway Program Using the Highway program 6 Example of most simple assignment Assume NETI contains values to obtain T0.... but it can be somewhat more difficult if deviations from the normal procedure is desired... */ .1... Therefore... PHASE=ILOOP PATHLOAD VOL=MI. MATI=. MATI=. FILEO NETO=. To accommodate this..1.1.. zones 2-99 will be skipped.. If the network is in the proper format (contains the required variables) only a few statements are required.1. unless the user specifies otherwise. all that is needed is an input network and a trip matrix.. 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. RUN PGM=HIGHWAY FILEI NETI=. FILEO NETO=. the program assumes that cost is equal to time. it will stop sooner if equilibrium convergence is reached before 10 iterations. VOL[1]=mi. our illustration script would look like this: PHASE = ILOOP PATH=TIME. In the following examples we will work from this same template and to keep reading to a minimum.net PHASE = ILOOP PATH=TIME. and the network has the following variables.6 Highway Program Using the Highway program we will assume that time is the basis for the process.1 ENDRUN This script will assign the trips from MATI[1] to the paths based upon TIME. we will not include the RUN. and ENDRUN statements. peak O-D trips NETO = loaded. By default. NETO. simple case NETI = mybase. Thus. we wish to do a peak-hour assignment.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 142 Cube Voyager Reference Guide . MATI. It will adjust link times between iterations based upon the congestion levels.1. VOL[1]=mi. up to 10 iterations of assignment and capacity restraint will be run. but useful for certain statistics Link capacity in veh/hr Base case is therefore: RUN PGM=HIGHWAY . NETI.net MATI = mytrips. Variable T0 DISTANCE C Description Link free flow time Optional.mat . Cube Voyager Reference Guide 143 . MW[1]=mi. So. and we wish to do a daily assignment. where n is the highest volume set in the setup. We can do this in one of several ways.1. The volume used in each link’s capacity restraint is determined by the program by performing the V function which by default is: V=VOL [1]+… VOL[n]. Because we supplied the V function.Highway Program Using the Highway program 6 • • Separate trips on separate paths Assignment of trips to HOV facilities Daily assignment Now let’s add a few complications: The trip matrix contains daily trips.1. VOL[2]=mw[1] In this case. 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. by adding a capacity factor. That matrix is then assigned to volume set 2 (VOL[2]).1. SELECTLINK=(L=2001-2002).1. but let’s just do the simplest. We have to tell the program to not add the selected link volumes. capacity restraint will only involve VOL[1]. VOL[1]=mi. PARAMETERS CAPFAC=10. but add an additional select link assignment to the typical assignment. The only thing that we need to do is to get the capacity into the correct units (we’ll assume that daily capacity is 10 times the hourly capacity). We do this by the typical process.1. we merely replace the function in the following manner: FUNCTION V=VOL[1] PHASE = ILOOP PATH=TIME. 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.1 Add select link loading Back to base case. factor NETI capacity by 10 to get daily capacity PHASE = ILOOP PATH=TIME. work matrix 1 (MW[1]) is computed to be only the trips from MATI whose paths use the selected link. VOL[1]=mi. 1. and you wish to use the volumes (plus 30 percent to get passenger car equivalency) in determining total congestion.6 Highway Program Using the Highway program Add truck assignment on same paths Base case plus assigning the trucks from the second matrix on MATI.TRKVOL = LI.V_1 . the link times are different then the times used for the first matrix.1 ENDPHASE Separate trips on separate paths This involves more planning and a bit more script to set up the process. PHASE = LINKREAD LW.2 Use preloaded truck volumes Base case but include the volumes from a prior assignment on the network as additional volumes.1 PATH=LW. VOL[1]=mi. A typical situation occurs when 144 Cube Voyager Reference Guide . Trucks use a variable from NETI as their base path times.1. but when the paths for the other matrix are developed. PHASE = ILOOP PATH=TIME. we will assume that one matrix will be assigned to the minimum time paths. PHASE = LINKREAD LW.1.1. those times will remain constant throughout the assignment. VOL[1]=mi. In this scenario. Assume that truck trips were assigned.TRKVOL*1. VOL[2]=mi.1.TRUCKTIME PHASE = ILOOP PATH=TIME. VOL[2]=mi.3 PHASE = ILOOP PATH=TIME. Trucks use same paths as cars and the combined volumes are used in the capacity restraint.TRKTIME. save the prior assignment volumes ENDPHASE FUNCTION V=VOL[1]+LW.TRKTIME = LI. VOL[1]=mi.2 Add truck assignment on separate paths Base case plus assign the trucks from the second matrix on MATI.1. 75) TRKFAC = 1.Highway Program Using the Highway program 6 trucks basically operate at a lower speed than cars.2. EXCLUDEGROUP=3. PHASE = LINKREAD T0 = LI.3 PHASE = ILOOP PATH = TIME.HOV==2) ADDTOGRP=2 IF (LI. but there is no automatic way to adjust the truck times.1. VOL[2] = mi.SPEED TRKFAC = 1. the program would automatically adjust the car times.3 Cube Voyager Reference Guide 145 .TRKTIME = T0 * TRKFAC ENDPHASE FUNCTION V = VOL[1] + VOL[2]*1. VOL[2]=mi. mi. 25. So. and those that could use 3+ facilities.TRKTIME = TIME * TRKFAC ENDPHASE Assignment of trips to HOV facilities Base case plus LINKREAD to flag HOV links.2 PATH=TIME. The LINKREAD phase will establish an array (LW.45.1. stored in mi. We will use 2+ and 3+ facilities. we have to introduce an ADJUST phase.55.TRKTIME) of times to be used in assignment of the truck trips. In this example. in which we do the truck time adjustment for the next iteration. The trip matrices have been previously split into matrices that could not use any HOV links.1.FUNCTYPE == 15.1 PATH = LW.1.0 IF (LI.1.1 PATH=TIME.1. VOL[3]=mi. respectively.DISTANCE * 60 / LI. we will establish a time factor to adjust the time on all links.1.2 LW. EXCLUDEGROUP=2-3. and mi.TRKTIME. VOL[1] = mi.HOV==3) ADDTOGRP=3 PHASE = ILOOP PATH=TIME. which are flagged in the network variable named HOV. After the first iteration.2 ENDPHASE PHASE = ADJUST LW.1.PHASE = LINKREAD IF (LI.1. those that could use 2+ facilities.3.65.35. VOL[1]=mi. A link can have a non-zero value for at most one of these attributes. • Each network link must have three attributes. value is not 0). This section discusses: • • Network development Path development Network development To use the path-based tolling TOLLMATI function. Every off-gate must have a unique number (1-999). You specify the attribute names in a FILEI TOLLMATI statement. you must follow several rules when coding closed toll systems. You specify toll records in a FILEI TOLLMATI file. which designate the link’s role in the toll system. Every on-gate must have a unique number (1-999). • Each toll facility must operate as a completely closed system where users can access and egress the facility only by crossing specified toll gates.6 Highway Program Using the Highway program Path-based tolls This section describes how to incorporate path-based tolls. Every toll-road link must be identified as such (that is. 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. Violating any of these rules causes Cube Voyager to terminate. Toll access rules: Toll on-ramps: • 146 Cube Voyager Reference Guide . or a delimited text file. specify the keyword TOLLMATI= on a PATHLOAD statement. Inbound link must be a toll-road link or a toll on-ramp. The first value for TOLLMATI refers to the FILEI TOLLMATI[#]. Outbound link must be a toll-road link or a toll off-link. An optional second value can specify which toll set from the TOLLMATI records to use. 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. For DBF or MDB files. and TOLLS must name the fields containing the toll values.road link or a toll onlink. the values are field numbers Cube Voyager Reference Guide 147 . Outbound link must be a toll-road link or a toll off-link.and off-gate numbers. Outbound link must be a non-toll. an MDB-element. Inbound link must be a toll-road link or a toll on-link. you must name ENTRYGATE and EXITGATE to indicate which fields on the record contain the on.Highway Program Using the Highway program 6 • • • • Inbound link must be a non-toll-road link or a toll offlink. For delimited text files. The specification for the TOLLMATI records is as follows: FILEI TOLLMATI[#]=filename. ENTRYGATE= EXITGATE= TOLLS= NETIENTRY= NETIEXIT= NETITOLLROAD= The file may be a DBF. and so forth. The first value for TOLLS is toll set 1. the second value is set 2. 6 Highway Program Using the Highway program instead of names. the default is the relative field on the record (ENTRYGATE is 1. they must have the same values. the application does not consider 148 Cube Voyager Reference Guide . The program will fatally terminate if: • • • • • A link has a nonzero value on more than one of the required toll attributes. Cube Voyager assumes a toll value of zero. altering the array would probably not cause a different routing between on-off ramps. but since the toll routings and costs are fixed for the iteration. keywords indicate the NETI link attributes that contain the values for the ramp and road links. At the beginning of each iteration.. If you use the keywords on more than one such statement. and TOLL is 3). TOLLROAD. the program determines the onoff combinations that are possible for each PATHLOAD statement. it fatally terminates. and if not. Zero is an acceptable value. If any are unnamed. You can use these keywords on any FILEI TOLLMATI statement. and up to ten toll sets. but.. The NETI. EXITGATE is 2. More than one link has the same off-ramp value. TOLLEXIT. It saves those on-off combinations and uses them during the PATHLOAD statement. With most toll systems. There is a violation of the above access rules. but does not contain a specific toll (value missing or blank). More than one link has the same on-ramp value. changes in the path array might cause a different on-off routing. It checks if there is a toll for each of those combinations. In some systems. the defaults names are: TOLLENTRY. There may be up to ten TOLLMATI record numbers. NOTE: If a record exists for a gate-to-gate combination (for the TOLLMATI#). therefore. A possible on-to-off route does not have a toll specified. do not revise the PATH=array within the iteration. If any of these values is not specified. the on-off travel costs could become incompatible with the array costs. Cube Voyager Reference Guide 149 . During path building. the process uses the predetermined combinations. see “Highway example 8” on page 259. For an example of a script using TOLLMATI. instead.Highway Program Using the Highway program 6 such changes. The PATHLOAD path-building process does not directly use the toll facility links. Any I-J path that traversed one or more combinations of entry and exit gates will have the accumulated toll along the path placed in the matrix. the new PATHTOLL keyword value can be used to skim the toll values for the paths (MW[1]=PATHTOLL). TOLLTIME = LI. it is the phase that precedes the first actual PHASE= statement. The values obtained directly from the network are referenced using the network name prefixed by “LI. LINKREAD phase This phase follows the SETUP phase. and to compute link values that the user can reference in other phases. other than those obtained directly from the network. The primary purpose is to obtain the initial values that are required from the input network.TOLLTIME / 100 would generate a value that is available for every link at any stage in the 150 Cube Voyager Reference Guide .” Any variables.6 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. It is used to initialize certain variables and/or arrays.” The statement: LW. LinkWork variables must be given names that begin with “LW. that the user wishes to reference later in any phase must be named as LinkWork variables. The only operational statements allowed in this stack are COMP and SET. There is no specific header for SETUP. If LINKCLASS < 1. the statement: TOLLTIME = LI. LINKCLASS = LI.DISTANCE. 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. The logic that the program uses is described below. Else if there is a LI.LINKCLASS. if the user has set T0 directly. and then compute T0 from them. Else LINKCLASS = 1. There are different ways that these variables can be set. SPEED (possibly used to compute T0): If set by LINKREAD. NumLinks). On the other hand. and processes the LINKREAD phase stack. For each value of Linkno. If DISTANCE < 0. set DISTANCE = 0. LINKCLASS (essential for selecting appropriate Functions): If set by LINKREAD. After the LINKREAD stack is finished. Note that while DISTANCE and SPEED are examined. Usually.Highway Program Phases 6 application. Else if there is a LI.LINKCLASS.DISTANCE. the values of DISTANCE and SPEED are merely academic. set LINKCLASS = 1. use that value. On the other hand. DISTANCE = LI. Else DISTANCE = 0. Cube Voyager Reference Guide 151 . T1. If they are not set by the user stack statements. and C) are set and fills in the link TIME and COST values. they need not be specified by the user.TOLLTIME / 100 would generate a variable that has no meaning beyond the current link. it ensures that certain link variables (T0. if present. The LinkWork variables are stored as LinkWork arrays (see “Built-in arrays” on page 136). the program will try to obtain DISTANCE and SPEED values. An internal loop is processed based upon the Linkno variable which loops from the first link through the last link (Linkno=1. T0 is computed by dividing DISTANCE by SPEED. the program will try to set them. the program obtains a link data record from the input network (NETI). Therefore. use that value. use that value. SPEED = LI. T0 = LI. Note: the program treats a link capacity of 0 (zero) as infinite capacity. Else If there are LI.LI. use that value. C = CAPACITYFOR(LI. T0 = DISTANCE*60/SPEED If T0 < 0. Else C = 0.CAPCLASS and their values are valid (1-9.LANES and LI. T0 = 0. used later in restraining process in the ADJUST phase): If set by LINKREAD.LI.SPEED.LANES and LI.TIME1 Else if SPEED > 0. If C < 0.CAPACITY.TIME Else if there is a LI. 152 Cube Voyager Reference Guide .CAPCLASS) * CAPFAC. Else If there are LI. T0=LI. Else T1 = T0. T1 (initial iteration time): If set by LINKREAD.TIME. C = LI. SPEED = SPEEDFOR(LI. and 1-99).6 Highway Program Phases Else if there is a LI.TIME1. set C = 0. T0 = LI. use that value.SPEED. Else if there is a LI. and 1-99). Else if there is a LI.CAPACITY* CAPFAC.T0 Else if there is a LI.SPDCLASS and their values are valid (1-9.T0. Else SPEED = 0.SPDCLASS).LANES. C (capacity. T0 (free flow time): If set by LINKREAD. use that value.LANES. the TIME. of T1 values): TIME is set equal to T1 after the LINKREAD stack is processed. See “SETGROUP” on page 244 for more details about this capability. Another important function of LINKREAD is to allow the user to specify GROUP codes for links. COMP statements can be used to alter. the user may not reference TIME in LINKREAD because its value is unpredictable at that time. without the required “LW. The user may not reference COST in LINKREAD. (See “PATHLOAD” on page 223 for more details. without the required “LW. DIST (a LinkWork variable. of cost values): COST is ALWAYS computed by the COST function for the LINKCLASS after the user LINKREAD statements are exhausted. COST (a LinkWork variable. Paths which use links with certain GROUP codes can be easily identified and used for extracting matrices. There are additional types of applications that can take advantage or this capability.” prefix. Links with certain GROUP code values can be disabled during path building to preclude those links from being included in the path. link values in LINKREAD. GROUP codes can be very useful in select link processing. Group codes can be used in various applications. or combination of levels. the user may not reference DIST in LINKREAD. When the LINKREAD stack is processed for each link in the capacity restraint process. COST and DIST values are not touched following the stack operations. without the required “LW.” Prefix. of DISTANCE values): DIST is set equal to DISTANCE after the LINKREAD stack is processed. It is even possible to identify the paths that have a certain level. of GROUP coded links.Highway Program Phases 6 TIME (a LinkWork variable.” prefix. or set. it is possible to build low occupancy vehicle paths by precluding the use of HOV links. Cube Voyager Reference Guide 153 .) For example. The following examples illustrate the PATHLOAD statement: • • • • Volume sets Stratifying vehicle distance traveled by average trip speed Select link Selected zone loading 154 Cube Voyager Reference Guide . It should be noted that listing TIME. Almost all control statements are valid within this stack. MW[#]= statements are performed for all Js (J=1. If there are no special LINKREAD operations to be performed. It specifies a set of values that are to be assigned to the links in a specified path set. there need not be any stack statements in this PHASE. 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. the PATHLOAD statement is the most important. Zones). it could alter the internal arrays that are being used and dynamically altered by the capacity restraint process. That is primarily why the user may not reference TIME. The ILOOP stack is executed one time for each value of I. In order to ensure consistency. COST and DIST will display meaningless values during LINKREAD. There MUST be a PHASE=ILOOP statement. unless the statement occurs within a JLOOP block. COST and DIST in LINKREAD. and the stack MUST have at least one PATHLOAD statement.Zones). Almost all the functions of the Matrix program can be performed within this stack. or both indices (MW[][]) are specified. ILOOP phase This phase performs a zonal loop (I = 1. the LINKREAD stack is also processed for each link as it is read and processed in the ADJUST (capacity restraint) phase also.6 Highway Program Phases PRINT statements can be useful for listing information about individual links. For assignment. but set numbering need not be monotonic.2.6 instructs the program to route the values from the expression “MI. and each of these is cleared at the beginning of each iteration.1.DISTANCE. the value (normally trips) for I to J from MI. PATH=LW. (A value will be assigned for each J in: J=1. Example 2 PATHLOAD PATH=LI.) Example 3 PATHLOAD VOL[4]=MW[5]+MW[6]+MI. 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. In the example. Example 1 PATHLOAD VOL[1]=MI. In example 1.zones.1.8.6 will be routed along the path from I to J.TOLLTIME Cube Voyager Reference Guide 155 .6. There may be up to twenty volume sets. the highest set number is 20.Zones. A VOL[] = expression implies an internal loop of J=1. as J loops.6” along the paths from the origin zone (I) to each of the destination zones (J). The volume sets are addressed as VOL[#].DISTANCE.1. VOL[1]=MI. 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.1.Highway Program Phases 6 • Subarea trip extraction Volume sets A volume set is an array in which assignments for each link are accumulated. Values are entered into the VOL sets by using PATHLOAD VOL[] = expressions. However. The user can specify multiple stratification schemes. the REPORT VDTSPD must be requested. Stratifying vehicle distance traveled by average trip speed During a multiple iteration assignment. considerably more processing must be undertaken. the final link times are used to obtain the individual trip time and distance. and they are all initiated via the PATHLOAD statement.2. A PATH keyword specifies the link values that are to be used to develop the paths. additional schemes do not require additional resources. There are those who believe that emission estimation based upon individual link volumes. Select link There are several ways in which select link processing can be undertaken. The average speed for the trip can then be calculated.8”. 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.6 Highway Program Phases Example 3 specifies that a PATH is to be built based on the link values from LW. the paths are retrieved and the all the assigned trips are retraced along the paths they used in assignment. the final link volumes. The paths are based upon the times on each link in effect in that iteration. The speed is used to stratify the vehicle distance of travel. Following the assignment. and a considerable amount of disk space might be required. Any MW[]= expressions that are followed by SELECTLINK=. or SELECTLINKGROUP= will solve the MW= expression for only those destination zones (J) where any 156 Cube Voyager Reference Guide . With this option. The program saves the paths for each I-J movement during normal assignment. SELECTGROUP=. the trips from any I to J may use various paths. along with the travel times associated with those volumes are used to obtain vehicle time. After all iterations.TOLLTIME. and the values to be assigned to those paths are obtained by solving the expression: “MW[5] + MW[6] + MI. distances. And. INCLUDEJ=. and then that matrix is referenced by the PATHLOAD VOL statement. & J=. and INCLUDE and /or EXCLUDE keywords to select the Js.. && b=.. another way is to use the SelectLink option.. SelectLink=(a=. Example (most efficient) IF (I=..1....) ) MW[1] = MI... && b=.) || (I=.path=. Another alternative is to use IF statements to do I testing.1.. Subarea trip extraction To obtain matrices of trips that have some portion of travel in a selected region (subarea network polygon) of the network. any of the select link matrices can be assigned at that point. MW[1]=MI. VOL[1]=MI... If a subsequent VOL= is used. VOL[1]=MI. the IF process would probably be faster if the zonal ranges are not too complicated... & J=.. Since solving complicated selections can be somewhat time consuming.1..... specifying: (a=range of Is && b=range of Js).. One way would be to establish a work matrix with the trips to be loaded... this illustrates selective gathering IF ((I=. Example (using SelectLink) PATH=.). The “unwanted” I-J pairs are cleared.1 ENDJLOOP VOL[1]=MW[1]. Selected zone loading Many times it is desirable to load only the trips between selected zone pairs.)..1. There are several ways to do this. SelectLink=(a=. the following keywords must be used: Cube Voyager Reference Guide 157 ...1. Example (simple code – inefficient) MW[1]=0 JLOOP .1.Highway Program Phases 6 of the SELECT… expressions results in a true condition....) PATH=.ODTRIPS. 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. and the B node of the cordon link used to exit the subarea becomes the destination zone. the values computed from the SUBAREAMAT expression for each J zone are traced along the path from I to J. crossing the cordon line only 2 times. When a path exits the subarea. path has origin inside the subarea and destination outside the subarea. the internal zone where the path began. the A node of that link becomes the origin zone of the extracted record. The A node of the origin zone becomes the origin. In this process. but never crosses the cordon line. or the A node of the cordon link that was used to enter the subarea. and the B node of the exit cordon link becomes the destination zone. path has origin outside the subarea and destination inside the subarea.6 Highway Program Phases • • • 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 value for J is placed into the subarea matrix. 158 Cube Voyager Reference Guide . a single I-I record is extracted. both ends of the path are inside the subarea. If the path terminates at an internal zone. If the path uses any links that are in the subarea network. becomes the origin zone of the extracted record. the internal zone becomes the destination zone. If a path begins and ends inside the subarea. When a path enters the subarea by crossing a cordon link. The intrazonal value for an internal zone will be extracted even though there is no path. and the destination zone becomes the destination. (See “Functions and built-ins” on page 134 for a description of the built in functions. the program does not know the intention of the user. a path begins outside.1.Highway Program Phases 6 Multiple records can be extracted for a path. 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.value is based upon any values that are revised by the ADJUST process (most likely Time and/or Cost). If an LW.value should be re-calculated by the user at this time. and those values need to be updated to reflect the change that were made in TIME. Example (subarea trip extraction) PATHLOAD PATH=TIME. For example. The subarea network is obtained from the Viper software. 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.) The final matrices are combined values from all iterations of assignment. If some special processing on each link is to be performed following the normal adjustment process.TOLLTIME. assume that there is a set of LW. or terminates an internal zone. only 1 iteration is processed. Cube Voyager Reference Guide 159 . It is permissible to alter TIME values with ADJUST statements.TOLLTIME values. and either exits again. After the user ADJUST statements are completed. SUBAREAMAT[1]=MI. the program recalculates the COST values using the Cost Function. SUBAREAMAT[2]=1 ADJUST phase This phase is automatic. the Phase=ADJUST control must be input and followed by a stack of control statements that are to be performed. but it is not advised. variables and arrays the program uses. enters. but if requested during a non-assignment application. so it can not make any adjustments automatically. (For example. exits. It is the user’s responsibility to make the changes in LW. enters. LW. values. and follows the ILOOP phase in each iteration.1. using the Polygon Subarea network extraction process. and the final volumes are obtained by combining the volumes from each iteration. V is the sum of all VOL[]s that appear on any PATHLOAD statements. Various combination processes can be specified. By default. multiple iterations are performed. it is the user’s responsibility to properly initialize them at the beginning of the link loop. the term “equilibrium assignment” is somewhat of a misnomer.6 Highway Program Phases The ADJUST phase runs an automatic LINKLOOP across all links on the input network. which is computed for each link. If summary values are to be accumulated during the link loop. This can be done by testing for the value of Linkno: IF (Linkno=1). but it is usually better to let the program determine when more iterations will not result in any assignment improvements. Most users tend to think of equilibrium assignment as the process of determining a weight factor for an iteration. some volumes would be duplicated. 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.. so a FUNCTION V= statement can be used to override the default computation of V.. 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 160 Cube Voyager Reference Guide . The maximum number of iterations can be specified. If the term assignment is used to indicate the actual accumulation of trips on link volumes. Congestion is based upon the variable V. (Hint: Iteration and LastIteration can also be tested by the user). All control statements coded in this phase are executed once per link. The default Function for V should not be used if a standard assignment is being made along with a select link assignment. This may not be exactly what is desired. In most cases. The user can select one of two Lambda search processes using the PARAMETERS COMBINE LAMBDASEARCH = AREA/EQUATION. the estimation process could be considerably more efficient. Cube Voyager Reference Guide 161 . a factor λ (generally referred to as Lambda) is estimated for the iteration. If the AREA search process is used. equilibrium is reached when there is no ability for individual I-J path costs to improve.” and the appropriate processes are included.Highway Program Phases 6 behaved. That state is reached when further adjustments in the link costs used for routing. To determine the weight to apply to each iteration’s volume in the volume combining process. it may be difficult (practically impossible) to reach a true state of equilibrium. If a system has a significant degree of congestion. so it is estimated using a linear approximation method. The basic measure of equilibrium is total system user cost. cost involves some measure of time. will not produce significant differences in the system as a whole. If a standard function for computing TC is used. Note that both processes estimate Lambda so the results might be slightly different. the results will be quite similar. without causing degradation in other parts of the network. Time is generally the measurable quantity that can be directly related to congestion. most equilibrium formulations are based upon time. This process provides a Lambda calculation that is up to 6 digits in precision. In theory. Lambda is a factor between 0 and 1. and in most situations. It is impossible to solve directly for Lambda. In most cases. eventually a state of equilibrium is reached. but the EQUATION method can save considerable computation and I/O time. Thus. the program minimizes the area under all the V vs. Cost curves computed for incremental estimates of lambda for every link. the program solves the expression for only a limited number of Lambdas.TCCOEFF. where V’= Vk-1 + λ * (VOLk . and the appropriate values of TCCOEFF and TCEXP. The resulting curve is examined.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’. and the Lambda which provides Y=0 is obtained by interpolation. 162 Cube Voyager Reference Guide .TCCOEFF.TCEXP) is the TC functions evaluated for link volumes V’.λ)*Vk-1. This value is then used to weight the current volumes: Vk = λ * VOLk + (1. 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 .6 Highway Program Phases If the EQUATION search process is used.TCEXP) Where TC(V’.Vk-1). Cube Voyager Reference Guide 163 . Iterative assignment keeps only last iteration volumes are output.Highway Program Phases 6 There are several iteration volume combination processes available. This is traditionally known as incremental loading. EQUI is the default. Weighted Average assignment is the same as Average. Average assignment simply keeps a running average of the volumes on each link. but the user can specify a specific weight for each iteration. prior iteration volumes are not considered. the PARAMETERS COMBINE= specifies the one to use. Sum assignment is one in which the final volumes are the result of adding the volumes from each iteration. Iteration volumes are factored by the equilibrium weights computed for each iteration. The available processes are: Process EQUI AVE WTD ITE SUM Description Equilibrium assignment. 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. Root mean squared error of the differences in V between iterations. 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. There are several tests that can be made to determine if more iterations are necessary. if appropriate. NumLinks (multiple passes if equilibrium is specified): Obtain link values (as in LINKREAD and LINKREAD stack. Apply the appropriate TC and Cost Functions (based on LinkClass) to compute revised Time and Cost. obtain prior combined iteration volumes (CVOL is prior V). 164 Cube Voyager Reference Guide .6 Highway Program Phases Convergence testing is not performed for Combine=Sum assignment. except TIME is not altered). RGAPk (SUML(VEk-1*COSTEk-1) . Sets a fixed maximum number of iterations for convergence The ADJUST phase process is as follows: • Major Link loop: Linkno = 1. If Iteration > 1. 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. 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.SUML(VAk*COSTEk-1) –)/ SUML(VEk-1*COSTEk-1) Where VAk is the link volume from an all or nothing assignment to the minimum cost paths based on COSTEk-1. For example: Cube Voyager Reference Guide 165 . • Determine if this is to be the last iteration: If Iteration = MaxIters: LastIteration = 1. Note that all of these PARAMETERS have default values so they do have minimum targets even though the user has not explicitly coded them. the assignment may stop in less then 10 iterations and before GAP<0. Else if Iteration > 1. compute link contribution (Y) to Lambda estimations. the assignment may stop after 10 iterations because the default value of MAXITERS=10 is reached before reaching a GAP<0.Highway Program Phases 6 If this is an Equilibrium pass. Or.001 because one of the other PARAMETERS has reached its default minimum. End Major Link Loop.001. 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. convergence is considered to be achieved if ANY of the above PARAMETERS minimum values are obtained. and recompute Cost. 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. 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. combine V with prior combined Vs Process LinkAdjust stack (if present). 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. follows the ADJUST phase in each iteration. GAP=0. if specified. RELATIVEGAP=0. See “CONVERGE phase” for examples of specifying alternate convergence rules. VEk is the equilibrium weighted volumes for iteration k and COSTEk is the cost based on the equilibrium volumes VEk. 166 Cube Voyager Reference Guide .6 Highway Program Phases PARAMETERS MAXITERS=99. process the stack statements in the CONVERGE Phase until BALANCE=1 or MAXITERS is reached.001. this can now be achieved by using the CONVERGE phase. If you would like to specify alternate rules for when the program determines convergence is reached.001 or 99 iterations were preformed. AAD=0. • CONVERGE phase This phase. There are several tests that can be made to determine if more iterations are necessary. or LastIteration: Write Neto. the turning movements in the network. RAAD=0. At the end of the ADJUST phase. Convergence testing is not performed for Combine=Sum assignment or for Iteration=1. RMSE=0 Would continue performing iterations until GAP<=0. • If PHASE=CONVERGE is present. If Convergence satisfied by BALANCE=1 (LastIteration set to Iteration. the program checks if additional iterations are necessary. if true). if appropriate. That will indicate to the program that further iterations are not to be undertaken. or there is insufficient capacity in certain parts of the network. or if further assignment iterations will improve the assignment depending on the assignment method used. When the results are satisfactory. Root mean squared error of the differences in VE between iterations.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. 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. 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. the script should set the variable BALANCE to 1. The user can write script to determine if the desired measure has been met. 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. and may never reach a desired result. the test statistics will begin to oscillate near the desired test limit. The CONVERGE phase process is provided to allow the user to program his/her own method of setting convergence. Cube Voyager Reference Guide 167 . Some networks may never be able to reach a true balance because there is too much congestion.Highway Program Phases 6 RGAPk (SUML(VEk-1*COSTEk-1) . Must be indexed for previous iterations The PDIFF for the current iteration. various variables and functions are available. Variables available for BALANCE Variable GAP RGAP AAD RAAD PDIFF RMSE Description The GAP for the current iteration. the standard tests are not performed. may be reset anytime GAPCUTOFF RGAPCUTOFF AADCUTOFF RAADCUTOFF PDIFFCUTOFF RMSECUTOFF 168 Cube Voyager Reference Guide . To help the user set BALANCE. may be reset anytime A variable initialized to the value Parameters RELATIVEGAP. may be reset anytime A variable initialized to the value Parameters AAD. Must be indexed for previous iterations The RAAD for the current iteration. the program will continue until MAXITERS is satisfied. may be reset anytime A variable initialized to the value Parameters RMSE. Must be indexed for previous iterations The RMSE for the current iteration. Must be indexed for previous iterations The AAD for the current iteration. Must be indexed for previous iterations A variable initialized to the value Parameters GAP. Must be indexed GAP[] for previous iterations The RELATIVEGAP for the current iteration.6 Highway Program Phases Note that if PHASE=CONVERGE is detected within the script. may be reset anytime A variable initialized to the value Parameters PDIFF. may be reset anytime A variable initialized to the value Parameters RAAD. BALANCE is automatically set to 0 when the phase begins. termination will be determined by the value of BALANCE after the phase is completed. If BALANCE is never set to 1. Function that results in change in PDIFF between the specified iteration (the required argument) and the previous iteration. where n = the number of iterations to process. Function that results in the maximum change in GAP between the last n iterations. Function that results in the minimum GAP between the last n iterations. Function that results in the average change in GAP between the last n iterations. Function that results in change in RELATIVEGAP 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 the minimum change in GAP between the last n iterations. Function that results in change in RMSE between the specified iteration (the required argument) and the previous iteration. where n = the number of iterations to process. RGAPCHANGE AADCHANGE RAADCHANGE PDIFFCHANGE RMSECHANGE GAPMIN GAPMAX GAPAVE GAPCHANGEMIN GAPCHANGEMAX GAPCHANGEAVE Cube Voyager Reference Guide 169 . where n = the number of iterations to process. Function that results in change in AAD between the specified iteration (the required argument) and the previous iteration. where n = the number of iterations to process. where n = the number of iterations to process. Function that results in the maximum GAP between the last n iterations.Highway Program Phases 6 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 the average GAP 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. Function that results in the minimum change in AAD between the last n iterations. Function that results in the average RELATIVEGAP between the last n iterations. RGAPMAX RGAPAVE RGAPCHANGEMIN RGAPCHANGEMAX RGAPCHANGEAVE AADMIN AADMAX AADAVE AADCHANGEMIN AADCHANGEMAX AADCHANGEAVE 170 Cube Voyager Reference Guide . 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 maximum AAD between the last n iterations. Function that results in the average change in RELATIVEGAP between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. 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.6 Highway Program Phases Functions available for BALANCE (continued) Function RGAPMIN Description Function that results in the minimum RELATIVEGAP between the last n iterations. Function that results in the minimum change in RELATIVEGAP between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. Function that results in the average change in AAD between the last n iterations. Function that results in the minimum AAD between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. Function that results in the maximum change in AAD between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process.Highway Program Phases 6 Functions available for BALANCE (continued) Function RAADMIN Description Function that results in the minimum RAAD between the last n iterations. Function that results in the maximum PDIFF between the last n iterations. Function that results in the average change in RAAD between the last n iterations. RAADMAX RAADAVE RAADCHANGEMIN RAADCHANGEMAX RAADCHANGEAVE PDIFFMIN PDIFFMAX PDIFFAVE PDIFFCHANGEMIN PDIFFCHANGEMAX PDIFFCHANGEAVE Cube Voyager Reference Guide 171 . where n = the number of iterations to process. where n = the number of iterations to process. Function that results in the maximum change in PDIFF between the last n iterations. 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 minimum change in PDIFF between the last n iterations. Function that results in the average PDIFF between the last n iterations. where n = the number of iterations to process. Function that results in the maximum RAAD between the last n iterations. Function that results in the average RAAD between the last n iterations. Function that results in the average change in PDIFF between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. 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. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. Function that results in the minimum PDIFF between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. Function that results in the average RMSE between the last n iterations. Function that results in the maximum change in RMSE between the last n iterations.6 Highway Program Phases Functions available for BALANCE (continued) Function RMSEMIN Description Function that results in the minimum RMSE between the last n iterations.009 && ABS(GAPCHANGEMIN) < 0. PHASE=CONVERGE IF (GAP<GAPCUTOFF & RGAP<RGAPCUTOFF & AAD<AADCUTOFF & 172 Cube Voyager Reference Guide . 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.009) BALANCE = 1 ENDPHASE Example . Function that results in the minimum change in RMSE between the last n iterations. 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. 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. In this example the assignment would stop only when ALL criteria fall below their specified values.006 && GAPCHANGEMAX(3) < 0. 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. Highway Program Phases 6 RAAD<RAADCUTOFF & RMSE<RMSECUTOFF & PDIFF<PDIFFCUTOFF) BALANCE = 1 ENDIF ENDPHASE Cube Voyager Reference Guide 173 . 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..... ELSEIF . 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 174 Cube Voyager Reference Guide . “General Syntax”) Define a user controlled loop Set static parameters Build path.6 Highway Program Control statements Control statements The following control statements are available in the Highway program... 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.. ENDLOOP PARAMETERS PATHLOAD PRINT PRINTROW PROCESS . ELSE . ENDJLOOP LINKLOOP ..... Control statement ABORT ARRAY BREAK COMP CONTINUE EXIT FILEI FILEO FILET FILLMW FUNCTION GOTO IF .. ENDIF JLOOP . ENDLINKLOOP LOOKUP LOOP .. MSG Use ABORT to terminate the program and return a fatal code to Cube Voyager. When an array is referenced. the run should be aborted.Highway Program Control statements 6 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. Values stored to arrays must be numeric. String values cannot currently be stored in an array. VAR=size Use ARRAY to allocate user arrays that are to be used in the process. it should include an index []. MSG Example IF (MW[1][I] != 0) ABORT . An array is different than a variable in that it represents vectored data. ARRAY statements are not dynamic (stack oriented). It normally is not used. Arrays can be useful for different processes. VAR=size. the program may fatally terminate. ABORT keyword Keyword Description |S| Optional message that can be printed when the program terminates. but allows for termination due to some conditions that can be detected in the process. and if the index exceeds the size. they Cube Voyager Reference Guide 175 .Intrazonal present in MW[1] ARRAY Declares user single dimension arrays. For example: if it is discovered that an LOS matrix is empty when it should have data. jump to IF statement 176 Cube Voyager Reference Guide .3 IF (condition) statements ELSE BREAK ENDIF .CLASS] = sum_toll[NI. Size may be either a numeric constant. When an array variable appears in a SET statement. VAR must be a unique name.. LINKS (or NUMLINKS). Special names are: ZONES.CLASS] + VOLTOT ARRAY VMT=LINKS BREAK Breaks out of a loop. If BREAK is within a LOOP .. If BREAK is not within a LOOP or JLOOP block.6 Highway Program Control statements are allocated prior to any stack operations. ENDJLOOP block. ARRAY keyword Keyword Description |I| Name of the variable that is to be allocated according to the specified size. Upon encountering BREAK. VAR Example ARRAY sum_toll=20 sum_toll[NI. control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J is reset to 1). ENDLOOP or JLOOP . The size following the keyword is the highest index possible for VAR. the script terminates processing for the I zone but does not bypass output and zonal reporting statistics.. the script immediately passes control to the statement after the associated loop.. all the cells in the array are set to the same value. NODES. or a special name. Example LOOP L1=1. filtering values indicated by any INCLUDE or EXCLUDE lists on this statement. The second index. VAR=expression MW[n]=expression. with J being the value of the loop’s current J. Within a JLOOP statement. COMP keywords Keyword MW Subkeyword |KN| Description Value for a working matrix. • MW[n][c] — Defines the value for column c in row n. as indexed by n. or matrix element from an expression. The program solves the expression one time only. with J being the loop’s J if within a JLOOP. EXCLUDE=list of J zones Use the COMP statement to compute variable and work matrix values. must be between one and Zones.Highway Program Control statements 6 ENDLOOP IF (condition) BREAK . no more processing for this origin zone COMP Computes a variable. Cube Voyager Reference Guide 177 . the program only solves the expression one time only. Matrices can contain up to MAXMW rows. if not. You can specify this keyword in two formats: • MW[n] — Defines the value for row n of a working matrix. or 1. The index n may be either a constant or a variable name. c. INCLUDE=list of J zones. matrix. The program solves the expression for all values of J (1 through Zones). As the program internally loops on J.. the program does not evaluate or store the expression for that J. By default no zones are excluded.. INCLUDE |IP| Optional.. the program does not evaluate or store the expression for that J. Not permitted if COMP statement within JLOOP . the program compares J to the values in the EXCLUDE list. Values of J excluded when computing the MW[n] expression. ENDJLOOP block. Filter applies to all MW[n] values on the COMP statement. As the program internally loops on J. Specified values can range from 1 to the highest zone number. By default all zones are included.. If the current J is not on the list. Filter applies to all MW[n] values on the COMP statement. Always processed after INCLUDE subkeyword. If the current J is on the list.6 Highway Program Control statements COMP keywords (continued) Keyword Subkeyword EXCLUDE |IP| Description Optional. Specified values can range from 1 to the highest zone number. Values of J included when computing the MW[n] expression. 178 Cube Voyager Reference Guide . the program compares J to the values in the INCLUDE list. Not permitted if COMP statement within JLOOP . ENDJLOOP block. valid abc = abc + def . unless their first appearance as a result in a COMP statement is with an expression that results in a character string. All variables are assumed to be numeric variables. invalid: abc has been declared a string abc = abc + '456' . jkl is declared numeric .n. or the value of the JLOOP J.Highway Program Control statements 6 COMP keywords (continued) Keyword VAR Subkeyword |KN| Description Name of a variable where the result of expression is to be stored. xyz is declared a string If a COMP statement includes any INCLUDE or EXCLUDE filters.matnum Cube Voyager Reference Guide 179 .don’t mix jkl = 1 jkl = xyz xyz = 'xyz' . Examples: abc = '123' def = 123 abc = def . EXCLUDE is processed after INCLUDE.name MI. The expression is solved one time for each encounter. Special matrix variables MW[] MI. If expression results in a character string. with J being either one (not in JLOOP). no matter where they appear on the statement. INCLUDE and EXCLUDE may not be specified within a JLOOP. messy -. invalid: xyz is declared a string (later) . the variable must be a character string variable. and special matrix functions on the statement. the filters apply to all MW[]= values.n. The name may be as long as desired (within reason). The matrix-oriented functions process all cells in a matrix (subject to the restrictions of any INCLUDE and EXCLUDE lists).name[Cexpression] is a variation.n. log. must be a constant. Value from the ZDATI[n]. ZI. min.name matrix. int. MI. the zone index is computed. The row index [n]. the column index is computed. then you must include the entire MI matrix reference in double quotes to recognize the name.” for more details). sqrt — see Chapter 3. Valid matrix names contain only alphanumeric characters. some special purpose functions are available. max.name MI. spaces.name matrix.6 Highway Program Control statements The expression is a standard Cube Voyager numeric expression. round.1HBW TRIPS" MI. The row index [n] and the matnum must be constants. exp. and should not be used within JLOOP blocks and MW[]= expressions. 180 Cube Voyager Reference Guide . the column index (not explicitly expressed) will be supplied as J. and underscores (_).matnum[Cexpression] is a variation. the zone index (not explicitly expressed) will be supplied as I. Rexpression may contain nested MW[].n. If matrix names have spaces. but there are some special variables that may be used within it: Matrix variables Variable MW[Rexpression] Description Value from any work matrix.n.n. MI. Normally.matnum Value from the MI[n].matnum matrix.name[Cexpression] is a variation. the column index (not explicitly expressed) will be supplied as J. Value from the MATI[n]. “General Syntax.n. they should be used only as VAR = ROWFUNC(#). ln. the column index (not explicitly expressed) will be supplied as J. ZI. be careful! MW[Rexpression][Cexpression] is the value from any work matrix for zone Cexpression. For example: MW[1]="MI.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. the column index is computed. ..z.1..hi” is allowed.hi) LOWEST(mw. and processing is more efficient. normally.5) + ROWFIX(3) will factor matrix 3 and then convert it to integer. Sum of lowest n cells. including only cells with values greater than or equal to lo. the intrazonal cell (I) would be excluded. they will be processed in appropriate order.. caution should be exercised when applying LOWEST function with no range specified. and less than or equal to hi. it is possible to exclude possible dummy zones that may appear as zero in the row.n. without any diagnostics. In the following matrix function descriptions. This exclusion is in addition to any that may be on an EXCLUDE list.. If “lo. Warning: Dividing by LOWCNT if it is 0. and exclude the values for J=z.Highway Program Control statements 6 Most of these functions could be duplicated with a combination of MW[]= statements.sn) Add matrix mw[1] + … mw[sn] into mw[d] Same as: MW[d] = MW[s1] + MW[s2] + MW[sn] LOWEST(mw. specific zones can be excluded. Since all MWs are initialized to zeros. will cause a program error message (too many will be fatal). NOTE: Zeros are treated as regular numbers in LOWEST function. Sum of lowest n cells. the function will return a zero. and lo is supplied.z. Example: DUMMY = ROWFAC(3. The function format has two advantages: coding is much easier. ROWADD(d. If an invalid argument is detected by a function.. the first argument (mw) indicates the work matrix to process. The range of arguments is to provide for most types of situations.. Sum of lowest n cells. and hi is not. Lo and hi are inclusive values. With lo and hi.lo.) Cube Voyager Reference Guide 181 . hi will be set to lo.hi.lo. Combining functions on a single statement is permissible. LOWEST is quite useful for computing an intrazonal value based upon the proximity to the nearest zones.n) LOWEST(mw. and less than or equal to hi. including only cells with values greater than or equal to lo. With z. Matrix functions Function LOWCNT Description The actual number of cells that was used in the summary is stored in the variable LOWCNT.z.s1.n. and must be specified.. n. With a rounding factor of 0. Same as: JLOOP IF (MW[s] == 0) MW[d] = 0 ELSE MW[d] = MW[d] / MW[s] ENDIF ENDJLOOP ROWFAC(mw. can include 0. 182 Cube Voyager Reference Guide .lo. with rounding factor = 0). and less than or equal to hi. using specified rounding factor).hi) ROWCNT(mw) ROWCNT(mw.s) Description Average cell value. Same as MW[mw] = MW[mw] * fac Convert mw to integer values (start at column intrazonal + 1.6 Highway Program Control statements Matrix functions (continued) Function ROWAVE(mw) ROWAVE(mw. Convert mw to integer values (start at column n. Divide MW[d] by MW[s] making all divided-by-zero cells equal to 0. ROWFIX converts the values in each cell of the matrix to integers (that is.lo.n) ROWFIX(mw. With a rounding factor of 0 each cell is truncated and its fractional remainder is carried to the next cell. including only cells with values not equal to 0. but include only cells with values greater than or equal to lo. and less than or equal to hi. Average cell value.rnd) Factors the row by fac. It converts each cell to an integer value after adding the rounding factor and the accumulated fractional portions from the previously treated cells. Number of cells with values not equal to 0 Number of cells with values greater than or equal to lo. with rounding factor = 0). drops all fractional portions of the number) in such a manner to ensure the integer total is consistent with the original total.fac) ROWFIX(mw) ROWFIX(mw.hi) ROWDIV(d.5. Convert mw to integer values (start at column n. each cell is rounded to the nearest integer and the difference (original – rounded) is carried to the next cell. 0.452 .3 MW[21]=MI.1.93. 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.2.3 CONTINUE Jumps to the end of a loop.Highway Program Control statements 6 Matrix functions (continued) Function Description If the process always began at zone 1.1.hi) Row total. EXCLUDE=90.1. MW[A]=A+B INCLUDE=1-5. MW[22]=MI. but include only cells with values greater than or equal to lo. The optional second argument specifies which cell the process is to end with. MW[4]=MW[3]*2.LOWCNT)/2 Example 2 MW[2]=J MW[K]=MW[2] * MW[5]) / SQRT(A*MW[3][MW[22]]) A=1.47-93 MW[3]=5*A. applies to the MW[]s= ABC=LOOKUP(DEF)*3 /* move input matrices to work areas */ MW[11]=MI.lo. Minimum value in the row. MW[13]=MI.2. the lowest numbered zones would never get their fair share of the fractions.4.1. INCLUDE=1-100. B=2. Cube Voyager Reference Guide 183 . Multiply MW[d] by MW[s] Same as: MW[d] = MW[d] * MW[s] ROWSUM(mw) ROWSUM(mw. and less than or equal to hi.s) Maximum value in the row.I)/max(1.2.01.8. ROWMAX(mw) ROWMIN(mw) ROWMPY(d.2. MW[12]=MI.1. Example 1 MW[mw][I] = LOWEST(mw.401-500.1.5. MW[K][I%10+1]=ODD. To eliminate this bias. bypassing all intermediate statements. MW[23]=MI. Row total. . When the program encounters an EXIT statement. jump to ENDLOOP for L3 ENDLOOP ENDLOOP EXIT Terminates stack processing. control passes to the appropriate ENDLOOP or ENDJLOOP statement. Otherwise.K2..3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE . Example LOOP L1=1. processing for the I zone is terminated. but output statistics will not be bypassed.6 Highway Program Control statements If CONTINUE is within a LOOP . no more processing for this origin zone LOOP L2=K1.. ENDJLOOP block.L2+5 IF (condition) CONTINUE ..KINC LOOP L3=L2. Input data files MATI NETI SUBAREANETI TURNPENI (MISSINGLINK LIST) 184 Cube Voyager Reference Guide . the program goes to the end of I loop processing. ENDLOOP or JLOOP . Example IF (expression) EXIT FILEI NOTE: See “FILEI” on page 44 for general information about FILEI and for important limitations when using Application Manager. Data from MATI and ZDATI files are accessed via stack statements. it references the nth item in the vector. and need not be in any specified order.n. ZI. file2. the vector form of ZDATI (ZDATI=file1. spaces.6. For matrices. and underscores (_). name designates the matrix name or number.POP indicates the POP variable from ZDATI[6] file. Zonal data can be viewed as having zones rows with one column per zone. defaults to MATI[1]. specified. whereas zonal data is read prior to the initiation of the I loop. and zonal data files have names only.1HBW TRIPS" On the FILEI statement the subscript is either explicitly. and are identified as MI.n. and for zonal data. When an input file is used in an expression.Highway Program Control statements 6 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). Since it is required that ZDATI files have variables explicitly defined for them. it doesn’t matter). or as one row having zones columns (user’s choice. MATI=. the subscript references the column within a row.) will be treated as an error. or implicitly. If there is no subscript specified.. it may have an additional subscript appended to it to specify a zone number. The n designates subscript of the file. Example: MI. MATI[4]. Valid matrix names contain only alphanumeric characters.. Cube Voyager matrices can have names and/or numbers. and must be in origin zone (I) order. then you must include the entire MI matrix reference in double quotes to recognize the name..name and ZI.name. other matrices have only numbers. J will Cube Voyager Reference Guide 185 . For example: MW[1]="MI. If matrix names have spaces. and MATI[5]..name4. and MATI[3]=name3.3 indicates matrix number 3 on the MATI[1] file. the current value of J is used.1.name5 sets up MATI[3]. Example: MI. T is the total volume for the movement. This file may be read and kept in memory for use during any path development processes (specified with PATH on PATHLOAD statements).6 Highway Program Control statements always be in the range 1-zones. respectively. the user must specify which penalties are to be applied on each PATH selection. PrevPen. Turn functions are designated as numeric expressions that may contain constants and the variables: T. ZI.TRMTIME[J] reference the origin and destination terminal times. If a function contains a C variable (movement capacity).3[I] accesses the intrazonal cell. T is vectored (that is. and the penalty to be assessed.1.6. It is the user’s responsibility to make sure that the penalty values are in the proper scale and units as the paths to which they are being applied. TURNPENI designates a file that contains intersection movement functions and penalties. the penalty will be revised between iterations in the ADJUST phase. C. T is the turn volume at the intersection (it may alternatively be named TURN). Even if the file is designated on a FILEI statement. a set identifier for the movement. it may contain an index []). C is the capacity of the movement. Each record in the movement section designates a specific movement (a-b-c). a fixed unit penalty. and PrevPen is the penalty that was used in the previous iteration. the penalties will not automatically be applied during path development. it is 0 at the first iteration. 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. but allows the user to specify that a penalty is to be computed from an expression. but is the result of the T=expression on the 186 Cube Voyager Reference Guide . The function section is optional.1.TRMTIME[I] and ZI. The file has two sections: functions and movements. or a reference to a function in the function section. For example. A prohibition is designated as the constant -1. C. and C is the exit node. A is the entry node to the intersection. In this example.Highway Program Control statements 6 TURNS statement after the first iteration. with C=500. If a T is specified with an index for which there is no PATHLOAD VOL[index]. (Warning: Be careful not to create divided-by-zero errors when applying functions with C=0. since T would be 0 on the first iteration. and then dynamic values are to be used after the first iteration. Set is a number in the range of 0-8. the C would be considered as 0 in the computations. the expression would be: Func1=2+ T/C *5. the movement record would be coded as: 100 200 201 0 Func1(500). it is applied any time that penalties are in effect. If there is no TURNS statement. For example: Func1=MAX(2. During path building. PrevPen. C is obtained from the record in the movement section as an argument of the function. If the set number is 0. T will automatically be the sum of all loadings. and the expression is any valid numeric expression that may contain numbers. To apply the above Func1 (2+T/C*5). Care must be taken if a fixed penalty is to be established for the first iteration. and it would vary after the first iteration.00.00). standard functions. TURNPENI movement records are structured as: A B C Set Penalty (one set per record). If there were no C affixed to the Func1 on the movement record. There may be up to 9 records (sets 0-8) for the same movement. T. the initial penalty would be 2. 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.) TURNPENI function records are structured as: FuncName=expression. comma). T[0] and T are the same variable. B is the intersection node. and be increased according to the T/C ratio. the value of T[] in the expressions will be 0. The records are white space delimited (space. when the movement is detected and PENI= is Cube Voyager Reference Guide 187 . This is usually done by using the MAX function in the expression. The name is what the user desires. T[1] would indicate the turning volume associated with any PATHLOAD VOL[1] statements.T/C*5. If the 2 unit penalty was to remain in effect for all iterations. no matter what the designated sets are. 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. Executing a junction model produces turning delays that may be applied during the next iteration of capacity restraint. It is used to convert the assigned volumes into units of per hour. The input demand matrix should be in units of vehicles (or PCU) per model period. the penalty is assumed to be 0. and it is one of parameters of the queuing delay equation. Specifies the nodes where intersection modeling is to be invoked. Only those nodes that both have a model description and are listed in this list are actually modeled. Then it will check all the other possible sets for the movements.6 Highway Program Control statements specified in the PATHLOAD statement. and will be reported on the TURNVOLO file. However. the penalty process will automatically apply set 0. JUNCTIONI designates a file containing descriptions of junction models. Invoking intersection modeling where there is no junction described has no effect. and the turn penalty set numbering system applies. This form of output is similar to a set of turn penalties. Turn penalty records may be applied with higher or lower priority (that is. If there is no set 0. JUNCTIONI PERIOD |R| 188 Cube Voyager Reference Guide . The SET keyword designate the turn penalty set to contain the model results. “Intersection Modeling.” N specifies a list of nodes where the intersection modeling is to be invoked during the ADJUST phase. The format of the file is discussed in Chapter 7. Duration of the model period in minutes. set number) than the calculated delays. A junction model that is not invoked has no effect. invoking intersection modeling for a node where there is no model description has no effect. if there is a set 0 for the movement. PERIOD is the model period in minutes. 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. FILEI keywords Keyword JUNCTIONI JUNCTIONI N Subkeyword |KF| |IP| Description Specifies the input junction file. The link variables from the network are referred to as LI. Equivalent to the FILE keyword of the LOOKUP control statement. or a Cube geodatabase network stored in an MDB file.name. In most cases the network will be one created by the Polygon SubArea Network Extraction process in Cube. the subarea will be set up properly. The records also contain the variable SUB_TYPE that indicates the type of node with relationship to the original network. with the proper node renumbering and cordon link specification. Cube Voyager Reference Guide 189 . It MUST be a Cube Voyager or TP+ binary network. the results will be unpredictable. MINUTP. This keyword is used in conjunction with the FILEO SUBAREAMATO = and PATHLOAD SUBAREAMAT[] = expressions.Highway Program Control statements 6 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. If specifying a Cube geodatabase network stored in an MDB file. TP+. 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. You must index LOOKUPI. the NETI keyword designates the filename followed by a backslash and the name of the Cube geodatabase network. If Cube is used to create the subarea network. Specifies a file that contains subarea network information. or Tranplan binary matrices. 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. Specifies the input highway network file. The files must be Cube Voyager. MATI NETI |KFV20| |KF| Specifies the input matrix files. See “ILOOP phase” on page 154 for details about subarea processing. The specified files are toll-point to toll-point records and may be input as DBF. Valid value range for exit toll gate numbers is 1-999. If the input file is a DBF or MDB table. The numbers in this link attribute correspond to the numbers in the ENTRYGATE field of the TOLLMATI file. the first field on the input file will be used. If the input file is a delimited ASCII file then the ENTRYGATE value is a field number on the input file. MDB table or delimited text records. If the input file is a delimited ASCII file then the EXITGATE value is a field number on the input file. Field name or field number on the input TOLLMATI file that holds the exit toll gate numbers. If EXITGATE is not specified. 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. See “Path-based tolls” on page 146. If the input file is a DBF or MDB table. the EXITGATE value must be a field name from the input table. 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. the ENTRYGATE value must be a field name from the input table. NETI link attribute that contains the entry gate numbers. If ENTRYGATE is not specified. the second field on the input file will be used.6 Highway Program Control statements FILEI keywords (continued) Keyword TOLLMATI Subkeyword |KF10| Description Specifies the input toll matrix files. NETI link attribute that contains the exit gate numbers. TOLLMATI EXITGATE |S| TOLLMATI NETIENTRY |S| TOLLMATI NETIEXIT |S| 190 Cube Voyager Reference Guide . Valid value range for entry toll gate numbers is 1-999. The numbers in this link attribute correspond to the numbers in the EXITGATE field of the TOLLMATI file. TOLLMATI ENTRYGATE |S| Field name or field number on the input TOLLMATI file that holds the entry toll gate numbers. Tolls can be coded as true toll values or in any units the user desires. If the input file is a delimited ASCII file then the TOLLS value(s) is a field number on the input file. The TOLLFACTOR provides a method for quickly factoring tolls for sensitivity analysis. The numbers in this link attribute can be used to correspond to one or more unique toll systems in the network. and a TOLLFACTOR of 1.. All links with a non-zero value for this attribute are considered part of one or more closed toll systems in the network. rounded to the nearest US quarter dollar). For example if a toll. the TOLLS value(s) must be a field name from the input table. the factored toll value would be US$1. Field name(s) or field number(s) on the input TOLLMATI file that holds the toll values.75 (that is. the third and subsequent fields on the input file will be used for up to 10 toll sets. By specifying TOLLROUND=0. Up to 10 toll value sets may be coded. the applied toll value for this movement would then be US$1.Highway Program Control statements 6 FILEI keywords (continued) Keyword TOLLMATI Subkeyword NETITOLLROAD |S| Description NETI link attribute that contains the toll road indicator. one for each toll set. If the input file is a DBF or MDB table. coded in the TOLLMATI file for a particular entry to exit movement is US$1. Allows for rounding of tolls or factored tolls to the nearest units specified.25. If NETITOLLROAD is not specified the name will default to TOLLROAD and it is assumed this link attribute name is available on the input NETI network. If specified the factor is applied to all toll values in the TOLLMATI file for the set.50. If TOLLS is not specified. 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| |?| Cube Voyager Reference Guide 191 . Specifies the input file that contains the turn penalty functions and movement records. Up to 10 toll factors may be specified.2 has been specified to test a 20% toll increase.80. 6 Highway Program Control statements FILEI keywords (continued) 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 192 Cube Voyager Reference Guide . MDB. ZONA. TAZ}. DBF. All fields will be extracted and can be referenced. the specified field will be used to extract zone number. or a Cube Voyager or TP+ binary network. by existing field names from the input file. MDB. node numbers (N) will be used as zone numbers by default. it is recommended to specify zone number field explicitly to ensure the correct field is used. any fields from the record can be extracted and used by the program. The field that contains zone number must be specified using 'Z=' keyword. If the file is of ASCII format. it opens the node database portion of the file as zonal data.) For Cube Voyager or TP+ network files. If it can not identify the file as a DBF. or by exact column positions on the records. it is not necessary to name the fields to be extracted. Average of all records. or a Cube Voyager or TP+ network. The first matched name will be used to extract zone number.Highway Program Control statements 6 FILEI keywords (continued) Keyword ZDATI Subkeyword |KFV10| Description Specifies the input files containing zonal data. Cube Voyager Reference Guide 193 . J. There can be up to 10 zonal data files. For DBF and MDB files. (Note: For files with more than one possible zone field from the list above. I. Aside from the zone number. Otherwise. When the program detects a Cube Voyager or TP+ network file. The program will try to detect what type of file it is. The file format can be any of: ASCII. in the script. Every zonal record must include a field that identifies the zone to which the record data applies. the fields to be extracted must be named and identified on the ZDATI statement by either relative field number. Zonal data is data which is specific for each zone. where the value from the file records is not 0. ZDATI ZDATI AVE1 AVEX01 |SV| |SV| Average of all records. the program will try to determine the zone number field based on file type. The specification of zone number field is optional for those two file formats. it will assume ASCII. the program will go through all field names to find a match with one of the following possible zone field names. ZONE. If 'Z=' is present. in the given order: {Z. If the file is a database or a Cube Voyager or TP+ network. POP=#2 would be invalid because Z specifies fixed format. but it is not necessary to keep the same names. Directly from the record from the FILEI with the lowest index[]. this value will be used. because Z specified triggered delimited format. or the field is blank on a record. Only the variables named will be extracted. the first name value (including Z) establishes the format. the value assigned to name is either a field number (delimited format). In most dbf cases. delimited format is assumed.POP=#2. For text files. If delimited format is specified. Identifies a data variable that is to be extracted from each record. Minimum value from all the records. or the columns (fixed format) where the variable is located on the record. the value for each name is the name from the dbf dictionary. If the first value is a number. All names must be specified with the same format. if there are no records for a zone. These are all be valid. each name value MUST end in a number. Example: Z=#1. ZDATI ZDATI ZDATI ZDATI ZDATI FIRST1 LAST1 MAX1 MIN1 NAME |SV| |SV| |SV| |SV| |S| 194 Cube Voyager Reference Guide . name=name would be the standard. If the file is a dbf. Directly from the record from the FILEI with the highest index []. Z=1-5. Value with which to initialize the array for the named variable. Maximum value of all the records. fixed format is assumed. AREA=3. otherwise. SALES=xxx4. It doesn’t matter what string precedes the number (the value need not be prefixed with a string). Then.6 Highway Program Control statements FILEI keywords (continued) Keyword ZDATI ZDATI Subkeyword CNT1 DEFAULT |SV| |R| Description Count of the records that contain the variable. the required length can not be estimated exactly. but with delimited format. Sum of all the records. Indicates a process to use in obtaining the value for the variables that are listed following the keyword.Highway Program Control statements 6 FILEI keywords (continued) Keyword ZDATI Subkeyword SELECT |S3| Description Used to cause selective reading of zonal data records from ASCII files. Z MUST be specified.net . the record length is estimated by multiplying the highest field number by 10. A variable may appear in only one keyword list. it is assumed that the value indicates a relative field number on the data record. If the estimated length is inadequate.dat . ZDATI ZDATI SUM1 Z |SV| |S| 1. even if the file is a dbf. The program will compare a field from each record with the string specified in SELECT[1]. Example NETI=network. It has to know how long a buffer is required. This selection is not used if SELECT is not specified. and an optional third value can be specified to designate the ending column. any variables that are not in any list will be set to LAST. If the second field is not numeric. If the value is a number. MINUTP binary matrix files Cube Voyager Reference Guide 195 . The third value is ignored if the second value is a free field definition. a dummy variable with a high field number can be specified to generate a larger record length. With DBFs and fixed format records. For delimited files. Caveat: The program establishes a buffer to read file records into. and if the comparison fails. TPP binary network file MATI=test11. The values for the variables will be obtained only from file records that contain the variable. but ends with a number (Example: #1). the record is bypassed. Z is a special case for name= (below). The second and third values must both be numeric and should be separated by a dash. the required length is known. The second SELECT value specifies the field to be compared with. test12. that field is the comparison string.dat. Identifies where the zone number identifier is found on each data record. it designates the beginning column of the comparison field on the input record. MULTI_FAMILY=4.DUPLEX=3.6 Highway Program Control statements MATI[4]=tppltrips. There MUST be a NETO specified if assignment is to be made. popyouth=36-45. VC.poptotal=6-15. A turning volume file must be requested if a TURNS statement is used. Requested matrices are written for every origin zone for every iteration. MISSINGLINK=1 ZDATI[1]=housing.popsr=56-65. popmale=cnt FILEO Specifies files that the Highway program outputs.pop19-65=46-55. poptotal=sum. VT. TPP or MINUTP matrix file TURNPENI=time.RETIREMENT=6 ZDAT[4]=pop. CONDO=5. CSPD 196 Cube Voyager Reference Guide .txt.popmale=16-25.popfemale=26-35.mat .Z=1-5.pen. TIME.DU1=#2. By default the NETO file will contain all the input variables from NETI plus the variables V. but are combined into a single “combined” matrix at the end of the application. 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. A single network with appended volumes and associated variables is written at the end of the application. Z=#1. there would be no use in running the program if there was no way to obtain the results.txt. If the NETI file contains any variable whose name ends in _#.Highway Program Control statements 6 (congested speed). the NETO appended variables will have an appended number that is one greater than the highest _# from NETI. TIME_1. FILEO keywords Keyword ESTMDATO ESTMDATO NAME Subkeyword |F| |SV| Description Specifies the file name for the output screenline data file (*. the assignment number will be 1. Specifies the file name for the output intercept file (*. VT_1. V1_1. Specifies the link array that contains the count confidence values. Links that have values in this array will be trapped for inclusion in the matrix estimation. If there were no prior assignment result variables appended to the link records.array or an li. If using COUNTVAR. VDT (vehicle distance traveled).ICP) that is required by Cube Analyst. and VnT for every VOL[n] specified on any PATHLOAD statements. but it is suggested that they be included to help in documentation of the file.array. the source geometry for links in the output network will come from the geometry of the input network. Thus. VT and VnT are the non-directional (twoway) counterparts of V and Vn. A default name of “SL A-B” will be supplied by Cube Voyager if no NAME is provided for a screenline. V1T_1 etc.array or li.DAT) that is required by Cube Analyst. the first assignment variables will be named V_1. ESTMICPO ESTMICPO ESTMICPO CONFVAR COUNTVAR |F| |S20| |S20| Cube Voyager Reference Guide 197 . VHT (vehicle hours traveled) and a Vn. then do specify VAR. VC_1. 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.) These appended variables will have an assignment number appended to their names.array. If the input network is a binary network. Specifies the names for the screenlines in the ESTMDATO file. Alternate to using VAR. If the NETO file is being written to a Cube geodatabase network in an MDB file. The value may be an lw. There need not be a name for each screenline. The value may be an lw. (Non-directional volumes can be turned off using NETO EXCLUDE=T_. Specifies the link array that contains the counts. do not use COUNTVAR. If using VAR. Specifies the filename for the MATO specified.array or an li. Valid range is 1 to 10.array.6 Highway Program Control statements 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). Replaced by COUNTVAR. the program will assign a screenline number to it automatically. Specifies the link array that contains screenline numbers for the links. JUNCTIONO MATO MATO COMBINE |F| |FV20| |?| Specifies the file name where the results of junction modeling may be stored for display.000.array. the link is ignored in the matrix estimation. ESTMICPO VAR |S20| 198 Cube Voyager Reference Guide . If there is no value in the array for a link that has a count. Links that have values in this array will be trapped for inclusion in the matrix estimation. but does not have a value in the VAR array. The most common application would be with selected link matrices. However. The value may be an lw. 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. Citilabs recommends replacing all instances of VAR with COUNTVAR.array or an li. If SCREENLINE is not specified. The value may be an lw. If a link has a value in the SCREENLINE array. Specifies the link array that contains the counts. the program will assign a unique screenline number to each link with a value in the VAR array. but including names helps document the file. while S indicates single precision floating point.11-15. Cube Voyager programs reading the file can reference the matrices by name and/or number. Specifies the names for the TP+ and Cube Voyager matrices. Each MO does not require a name. The highest implicit or explicit index establishes how many matrices will be included in the file. MO[6]=31 establishes that 20 matrices will be written. A number value indicates the output matrix cells are to be integerized with that many decimal places preserved. “Matrix Program. The letter D indicates that the cells are to be stored in double precision floating point format. and underscores (_). All internal work matrices are maintained in double precision floating point format (eight bytes per cell).” for a more detailed explanation of the possible binary options. DEC is not applicable when FORMAT=MINUTP is specified. The reader is urged to read the description of FILEO MATO DEC in Chapter 9. If no DEC value is defined for a matrix. MO[20]=1. the default value will be integer with 2 implied decimal places. Example: MO=1-5. The same MW may be included more than one time.Highway Program Control statements 6 FILEO keywords (continued) Keyword MATO Subkeyword DEC |SV*| Description Specifies the format for the MOs. Nine of the matrices (11-19) will be dummy because no data was entered for them. Valid matrix names only contain alphanumeric characters. The value can be a number (0-9) or the character D or S. The output matrices are numbered monotonically beginning with 1. MATO FORMAT |S| MATO NAME |SV| Cube Voyager Reference Guide 199 . MW may be indexed. 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. but care should be taken to not leave holes in the final list. spaces. but can be written to MATO files in different formats in order to keep the storage requirements to a minimum. There is a separate DEC for each MO. this allows for more efficient compressing of the data. The variable will appear as name_# in NETO.V1. VC_5.vars named by this keyword will appear in the NETO as LW_NAME_# (# is the assignment number value). V1_5. Specifies that the NETI variables that have names ending with the specified strings are to be excluded when copying NETI records to NETO. Specifies the number of decimal places to written to the NETO Volume fields. APPEND=5 would cause V. but this only adds a variable that has the same value in each record. Specifies the name of a file upon which paths from a PATHLOAD statement are to be written. All LW. Values in the range 1-5 are valid. Specifies that certain new variables are to be included in the NETO file. VC. Alternatively. The link cost values will be rounded to this many decimal places. You can specify a single variable with INCLUDE. 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.TIME. NETO can point to a Cube geodatabase network stored in an MDB file by designating the file name followed by a backslash and the Cube geodatabase network name.. The value must range from 1-5.. there must be NETO if assignment is being performed. The intent of this keyword is to allow the user to compute LW. Specifies how many decimal places are to be maintained in the cost values when they are written to the PATHO file.6 Highway Program Control statements FILEO keywords (continued) Keyword NETO Subkeyword |F| Description Specifies the file name for the NETO.vars and selectively include them in the NETO. Specifies that the variables that are appended to NETO will have their assignment number set to this value. etc. TIME_5. EXCLUDE=_1 will exclude all the first assignment variables. to be named V_5. NETO APPEND |I| NETO NETO DEC EXCLUDE |I| |S20| NETO INCLUDE |S20| PATHO PATHO COSTDEC |F10| |I| 200 Cube Voyager Reference Guide . Thus. The NETO can be a binary Cube Voyager/TP+ network. Default value is 2. The matrices on the file will be the final combination of values from all iterations. This keyword is ignored if the format is not TPP. The number of matrices will be set by the highest PATHLOAD SUBAREAMAT[] index. S for a single-precision number. or any other value is coded. 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. This keyword is ignored if the format is not TPP. Possible values are TPP. Specifies the individual names for the SUBAREAMATO matrices. The zonal configuration for the O/P matrices will be based upon the renumbering scheme obtained from the FILEI SUBAREANETI file. the default is TPP. or it is not specified at all (normal). 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.Highway Program Control statements 6 FILEO keywords (continued) Keyword PATHO Subkeyword ITERS |I| Description Indicates which iterations to write the PATHO file. Specifies the desired output format for SUBAREAMATO matrices. If not specified. the values will default to 2. Specifies the maximum number of decimal places to retain in the SUBAREAMATO matrices. if anything else is specified. Specifies the file where binary matrices of values from subarea processing are to be written. or D for a doubleprecision number. PRINTO SUBAREAMATO APPEND |?| |KF| SUBAREAMATO DEC |SV20| SUBAREAMATO FORMAT |C| SUBAREAMATO NAME |SV20| Cube Voyager Reference Guide 201 . The values may be 0-9. and TRANPLAN. MINUTP. each may have a different format. 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. If this keyword is specified. the file will be delimited with this character. See “Example using TURNVOLO” on page 205.junct TURNVOLO |F| Specifies the filename where the turning volumes are to be written.6 Highway Program Control statements FILEO keywords (continued) Keyword TURNPENO Subkeyword |F| Description Specifies the file name where the movement delays from the junction model and/or the turn penalties from the turn penalty file will be written. If the value is a character.00 0. Character that is written in a TXT file. An example of the output is show below. the file will be fixed-field format. Users must also specify TURNS to instruct program to accumulate turning volumes. The default format for this file is binary so that Cube can display it directly. Specifies the number of decimal places to preserve when the file is either DBF of TXT.junct -1. but it may also be specified as a number that represents the desired character (for example. If it is not specified. 9=TAB).junct 0. 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. it should be enclosed within quotes. 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. 2606 2635 2635 2635 2635 2621 2621 2621 2621 2621 2773 2606 2615 2615 2773 1 1 1 2 1 0. Please note that the presence of the VARS keyword may alter the overall application of this statement.junct 0. TURNVOLO TURNVOLO DEC DELIMITER |I| |c| 202 Cube Voyager Reference Guide . the TURNVOLO will be empty.15 .15 .15 .08 . There may be more than one TURNVOLO specified. otherwise. NOTE: FORMAT=BIN will automatically be reset to TXT if VARS= is specified on the statement. o if not 3-31 same for T[3]..” 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. T[0]. or TXT).. The DBF header will name the variables that are in the data records. 7-64 ”Cube Voyager TURNVOL pppp. and any appropriate T# values. Cube Voyager Reference Guide 203 . DBF. 0 if not in data record 1 if T[2] present. • 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.Highway Program Control statements 6 FILEO keywords (continued) Keyword TURNVOLO Subkeyword FORMAT |S| Description Specifies the format for the file (must be BIN.nnnn HIGHWAY date.. Bnode.. ExitNode. Note that if VARS is specified. If no DELIMITER. It does not make sense to have ESTMO=T on a 204 Cube Voyager Reference Guide . FORMAT=TXT. the variable name may have a standard PRINT form appended to it (enclosed within parenthesis). TURNVOLO INCLUDE0 |?| Flag that when set false indicates that a turn movement with T values all equal to 0. T. Specifies which variables are to be written to the file. that it will default to TXT. Optionally. If decimals are to be printed with the values. Note that VARS= will cause this format to change. There is no header for this file. If DELIMITER is specified. FORMAT=BIN will be reset to FORMAT=TXT.T# — (The user has to know which individual Ts are written to the file). Bnode. If a delimiter is desired. Each volume will be formatted appropriately. and may even be repeated): A B C T T1 T2…Tn. the structure of each record is: Anode. 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. where n is the highest VOL in the application. the fields will be written with only the delimiter separating them. There may be more than one PATHLOAD statement with ESTMO=T on it. the NAMES may be indexed [] to set the alignment for renaming only specific variables. is to not be written to the file. The names are aligned with the VARS fields and then placed into the created dbf file. or if there is no FORMAT specified. Optionally.6 Highway Program Control statements FILEO keywords (continued) Keyword TURNVOLO Subkeyword FORMAT (continued) Description • TXT — ASCII format either in fixed format or delimited. Any of the following variables may be specified (in any order. it is suggested that an appended format be specified instead of DEC=. the program will determine the size. the fields will be in fixed width format. ExitNode. The default value is true. The T values will be determined either by the DEC keyword. DELIMITER= must be specified. May be used if both VARS= and FORMAT=DBF are specified. or internally by the program. TXT.Trn.'SL#3'.MAT. Cube Voyager Reference Guide 205 . VARS=b(5) a(6) c(6) t(10. PATHLOAD PATH=TIME.'SL#2'.Trn. costdec=2.COMBINE=Y MATO[3]=DEMO12. ALLJ=T FILET Specifies where the Highway program writes various temporary files.b(5). DEC=2*2 NAME=SLINK1. format=DBF.'. iters=0 . DEC=0 TURNVOLO=AlternateA.pth. MO=1.2) t1(10. DEC=0 ESTMICPO=ESTMO. _#2 TURNVOLO=AlternateA. _#2 TURNVOLO=AlternateA. . format=BIN TURNVOLO=AlternateA. format=BIN TURNVOLO=AlternateA. NAME=TIME_PATH.DAT.TOLL1.DBF. VAR=LI.Trn. . FORMAT=MINUTP.TXT.Bin. NAME[5]='SL#5' Example /* Commands to generate a path file.Trn.DBF.c(5).COMBINE=Y MATO[3]=DEMO12.2) TURNVOLO=AlternateA.TXT. MO=1-2. FORMAT=MINUTP. NAME='SL#1'.3. DEC=0 TURNVOLO=AlternateA.5-7 NETO=ALTERNATE.TOLL1.DAT.COUNT.TXT.Trn. PATHLOAD must have the keyword PATHO=# in order to output the path file specified with FILEO PATHO= Example using TURNVOLO MATO=TPPTEST. format=dbf. format=TXT.Bin. vars=a(5).t(8.Trn.Trn. MO=1-2. PATHO=1.MAT. DELIMITER='.Highway Program Control statements 6 PATHLOAD statement that does not have VOL[]= on it. DEC=0 TURNVOLO=AlternateA.ICP. t1(8. names= Enter thru exit Total Cars Trucks Example MATO=TPPTEST.5-7 NETO=ALTERNATE.NET. format=DBF.'.NET.Trn.3. MO=1.2). DELIMITER='. format=TXT. SCREENLINE=LW.2).t2(8. EXCLUDE=_#1.SCREENLINE ESTMDATO=ESTMO. EXCLUDE=_#1. INCLUDECOST=F. */ FILEO PATHO[1]=myfile.2) t2(8. DEC=2*2 NAME=SLINK1.2).DAT. . the program dictates when they will be processed. PATH The value for PATH is entered as a standard operating system path. If not specified. Example PATH=' ' PATH=. and opening the files is: • • • • If the PATH=' '. or TEMP. The statements are inoperable by themselves. use current directory . and can be anywhere in the input stream. up a directory . V TC COST Use FUNCTION statements to enter single expressions for computing certain values. use TMP. If the operation fails. Fatal. See “FILLMW” on page 510 for a complete description. It is recommended that they 206 Cube Voyager Reference Guide .6 Highway Program Control statements PATH FILET keyword Keyword Description |S| Specifies the path to the disk area where any temporary files are to be written. If not specified. and TMP is.\ PATH=c:\ . If the PATH is specified. use current directory. it will default to the path in the environment variable named TMP. FUNCTION Defines special functions. The logic for determining the appropriate path. root of c: FILLMW Fills work matrices. use it. Specifying TC[1] alters the function. If no TC functions are defined then a default TC function is applied. some users may wish to code the functions on a single FUNCTION statement with a block control. TC |NV999| Cube Voyager Reference Guide 207 . a default function will be used. usually following a TC application. In general. This is the only way to alter the cost values. Each of the other functions is entered with an index [] to indicate which LinkClass it is to be applied to. or some combination of both.15 and TCEXP defaults to 4 if values are not specified with PARAMETERS. it is applied during capacity restraint. V/C. If there is no function for a type. The V function may be defined one time only. and after the user stack statements are completed. COST is processed in LINKREAD and ADJUST to compute the cost. it is applied after the stack statements.Highway Program Control statements 6 be placed prior to the first PHASE statement or within the major phase in which they will be processed. or they can be on individual statements. To reduce confusion. Computes the congested time on a link by LINKCLASS. TC[#]=f(T0. TCCOEFF. The default TC function is the standard BPR with the form: TC[1] = T0 *(1 + TCCOEFF * (V/C) ^ TCEXP) where TCCOEFF defaults to 0. FUNCTION keywords Keyword COST |NV999| Description Computes the cost for a link. The user can also code their own functional form if the BPR form is not what is desired. In ADJUST. The TC functions can be indexed by LINKCLASS to specify different volume delay relationships for different classes of facility. All the functions can be on one FUNCTION statement. In LINKREAD. TCEXP) but the user is free to experiment with any forms that make sense to them for their application. If no LINKCLASS is defined for a link it defaults to LINKCLASS=1. TC functions are the labels in the software given to volume delay functions (commonly referred to as VDFs). The LINKREAD Phase of this program allows the user to associate every link in the network with an internal LINKCLASS variable. TC stands for congested time. Example GOTO buildhwy GOTO :buildhwy 208 Cube Voyager Reference Guide . T0 * (1.3 TC[1] = T0 * (1 + 0. named “:label.5 + 0.6 Highway Program Control statements FUNCTION keywords (continued) Keyword V |N| Description Computes the total volume on a link after an iteration. + V[n]).” Each GOTO statement must have an associated :label statement... Example FUNCTION { V = VOL[1] + VOL[3] + VOL[10]*1. you can use a GOTO statement inside a JLOOP to jump to a :label statement outside the JLOOP. GOTO label When GOTO is processed. If there is no V function. 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. It is applied in the ADJUST phase. Some times the total volume should not be the sum of all the VOLs. However. V is assumed to be the sum of all the VOL sets (V[1] + V[2] + . The target statement must begin with a semicolon (:).18 * (V/C) ^ 4)) COST[255] = TIME * 2 } GOTO Jumps immediately to a named statement.20 * (V/C) ^ 6) TC[201] = MIN(T0*5. You cannot place a :label statement inside a JLOOP statement. that VOL set should be excluded from the total volume. For example: if a separate select link VOL set is being accumulated in addition to the total VOL set. NOTE: GOTO is not valid in the SETUP phase. Use care when the :label statement is within a different IF or LOOP block. flow immediately branches to the target statement. IF (expression) GOTO :tolls . ELSE .b. IF expression ELSEIF expression ELSE expression ENDIF Use IF/ENDIF blocks to determine if certain operations are to be performed.name. Lengthy IF expression solutions could be time consuming.. :tolls . It is permissible to go backwards.. use them judiciously.n. MI. If a variable in the expression is MI. IF blocks may be nested. or other IF blocks...Highway Program Control statements 6 Example GOTO tolls . You may append the following control statements to a single IF statement: • • • • • • BREAK COMP CONTINUE EXIT GOTO PRINT Example IF (LI. JLOOP... ENDIF Performs certain operations based on conditions. but they may not overlap LOOP.LI.n.n. single IF with process Cube Voyager Reference Guide 209 . ELSEIF . the same rules for indexing in a COMP statement are applied. ZI.name. sometimes INCLUDE and EXCLUDE filters may provide a much more efficient selection process (see the examples below). Although IF expressions can be quite powerful for zonal selection.. IF ..DIST< 20) LIST=a. or MW[].dist...name or MW[] should realistically only be used within a JLOOP. List of origin zones that the program will process. • • Because the list of values for J can be expressions.. Jinc defines the increment for the loop’s control variable. and may not overlap other JLOOP. the program will only process statements for these zones. If not specified. and Jinc defaults to 1. and Jinc defaults to 1. Enclose expressions containing commas in parentheses. ELSEIF (loop_cntr > 10) . ELSEIF (loop_cntr > 5 && diff. List of up to three integers that define the value of the loop control variable. JLOOP blocks may not be nested. depending on the direction from Jbeg to Jend. ENDJLOOP Controls a loop through the columns of a matrix row. Jend defines the terminal value of the loop’s control variable.. Default value is 1. J. Jend defaults to Jbeg. If not specified. J.57 & k=(2*j-4) ) || ((J*k) = 14-20. LOOP. INCLUDE |I| Optional. or IF blocks. 210 Cube Voyager Reference Guide . you cannot define Jend or Jinc. In that case. Jinc where: • Jbeg defines the initial value of the loop’s control variable. If you include this keyword. ENDIF JLOOP . JLOOP keywords Keyword J |I| Description Optional. you must separate the values with commas. set to 1 or -1. J. You may define each integer with an expression.6 Highway Program Control statements IF (expression) EXIT IF ( ( j=3-5. you use JLOOP . Each row represents an origin zone and each column represents a destination zone. Specify as: J=Jbeg.6-30.time < 32) .56) ) .. ELSE . ENDJLOOP blocks for matrix computations that you cannot complete with a single COMP MW control statement. Typically.. Valid values range from 1 to the network’s maximum number of zones. If you do not define Jbeg. Jend. Jend defaults to the number of zones in the network. If you include this keyword. Jend=Zones. Jinc=1. moving J from Jbeg to Jend in increments of Jinc. If (Jinc < 0 and J >= Jend) go to statement following JLOOP. establish values for Jend and Jinc. The program processes all statements between the JLOOP and ENDJLOOP statements. If (statement contains EXCLUDE keyword and J is among listed EXCLUDE keyword values) go to ENDJLOOP. If (Jinc > 0 and J <= Jend) go to statement following JLOOP.Highway Program Control statements 6 JLOOP keywords (continued) Keyword EXCLUDE |I| Description Optional. with the current value of J. terminate fatally. else set J=1. and instead skip to the next zone. Control passes to statement following ENDJLOOP. the program will not process statements for these zones. List of origin zones that the program will not process. Process statements within JLOOP. A JLOOP block causes the program to loop between the JLOOP statement and its ENDJLOOP statement. If (J < 1 or J > Zones or Jend <1 or Jend > Zones). • At ENDJLOOP: Add Jinc to J. including COMP MW statements. The logic for JLOOP and ENDJLOOP processing is: • At JLOOP: If J is specified. If (statement contains INCLUDE keyword and J is not listed among INCLUDE keyword values) go to ENDJLOOP. The following statements are valid within a JLOOP block: • BREAK COMP • Cube Voyager Reference Guide 211 . .process only intra zonal values. but you cannot overlap them with IF blocks. ENDLINKLOOP Controls a link loop for processing link records in the ILOOP phase. a GOTO statement cannot jump into a JLOOP. to reference the current link number. double LW. the link loop processes through all link records at an increment of one. However. Example . Example . but exclude externals JLOOP J=I EXCLUDE 500-535 .... the default loop index. you can place a GOTO statement inside a JLOOP to jump to a :label statement outside the JLOOP.. ELSEIF .. By default. ENDIF PRINT REPORT SET NOTE: You cannot place a :label statement inside a JLOOP. You can nest LINKLOOP blocks... ENDJLOOP ROWSUM1 = 0 ROWSUM3=0 JLOOP .. get rowsums for matrices ROWSUM1 = ROWSUM1 + MW[1] ROWSUM3 = ROWSUM3 + MW[3] ENDJLOOP LINKLOOP .6 Highway Program Control statements • • • • • • • CONTINUE EXIT GOTO IF . You can use LINKNO. The program supplies all link arrays the default [LINKNO] in a LINKLOOP block. ELSE .VAR for even number zones 212 Cube Voyager Reference Guide .. .VAR=LW.VAR*2 . If not specified. Lend and Linc. You can nest LOOP blocks. program. Cube Voyager Reference Guide 213 . no comparison is made and loop ends at ENDLOOP statement. Lvar is not protected during the loop. and optionally. Lvar must be followed by Lbeg. If not specified. but you can overlap them with IF blocks.Highway Program Control statements 6 IF (I%2==0) LINKLOOP LW. Drop through to next statement.Linc . ENDLOOP Controls a general variable loop.. computational.. Linc is set to 1 (or -1 if Lbeg and Lend are both constants and Lbeg < Lend. ENDLOOP compares the contents of the variable to another value. Linc — Optional. • • • Use LOOP…ENDLOOP blocks to repeat a series of statements.Lend. a backwards loop). The logic is as follows: • At LOOP: Initialize Lvar to Lbeg. no [LINKNO] subscript needed ENDLINKLOOP ENDIF LOOP . LOOP Lvar=Lbeg. Numeric expression added to Lvar before making the ENDLOOP comparison. The process differs considerably from JLOOP. Lbeg — Numeric expression that initializes Lvar. LOOP initializes a variable. Numeric expression that Lvar is compared to when processing the ENDLOOP statement. Lend — Optional. and branches back to the statement following the LOOP statement if the comparison fails.. ENDLOOP where: • Lvar — Name of the loop control variable. and other LOOP statements can alter its value. 5. perform 10 passes . The loop will be processed at least one time regardless of Lend and Linc values.-2.mno/pqr LOOP abc=xyz. otherwise compute Linc.. ENDLOOP ENDLOOP LOOP jj=10. 7. 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. Because Lvar values can be expressions. Example LOOP pass=1. Add Linc to Lvar. ENDLOOP 214 Cube Voyager Reference Guide ..3.ghi+jkl. and Linc must be separated by commas (standard white space delimiting cannot be interpreted properly).. Lend. nested LOOP . Lbeg. and Lbeg > Lend). Compute Lend.. 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. If Linc not specified.5 . On the other hand. 5. set Linc to 1 or –1(if Lbeg and Lend are constants. jump to next statement. the flexibility provides for powerful control.2 .xyz+2.6 Highway Program Control statements • At ENDLOOP: If Lend not specified. Most uses will involve constants.10 . ENDLOOP LOOP xyz=abc*def. 10. Compare Lvar to Lend..0 .. Highway Program Control statements 6 PARAMETERS Sets general parameters. Cube Voyager Reference Guide 215 . Default value is 0. 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.5. the delays might have an important impact upon the assignment convergence. (See “SETUP and LINKREAD phases” on page 150 for details on how Cube Voyager obtains capacity from input network. Intersection delays are not directly dependent upon the volumes on them. But. C = CAPFAC * input capacity. but there is no equivalent process for including turning volumes. When intersection modeling is being undertaken (triggered by the presence of a FILEI JUNCTIONI statement). there are several options that can be specified by the subkeyword LAMBDASEARCH (see“LAMBDASEARCH” on page 218). It is not used if C is specified in the LINKREAD phase. they are influenced by the total intersection traffic. When C is not specified in the LINKREAD stack and is obtained directly from the input network.6 Highway Program Control statements PARAMETERS keywords (continued) Keyword CAPFAC Subkeyword |KR| Description Specifies a value to convert input capacity to the same unit as V. standard Lambda estimation processes are used for the link volume evaluations. 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. 216 Cube Voyager Reference Guide . Lambda estimation includes the turning delays multiplied by this value.) Default value is 1. Default value is EQUI. 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. COMBINE |KS| Specifies the method to combine the results of iteration volumes. The sum of all the values should be 1. the V/C ratio used in adjustment is based upon a partial assignment. ITER SUM COMBINE FRACTIONS |RV*| Specifies the fractions to be when COMBINE is set to SUM. Weighted average. a warning message will be issued. If it is desired to use a “projected full” V/C. V will be factored according to the FRACTIONS for that iteration. That will not preclude the program from executing. Only the last iteration volumes are used for output to NETO. if the sum is not 1. it must be followed by the FRACTIONS subkeyword. This can be accomplished in the LINKREAD phase. Thus. When SUM is specified. MAXITERS will be set according to the number of weights specified in WEIGHTS. Cube Voyager Reference Guide 217 .00. This process can be used to perform traditional incremental loading. This is similar to AVE. and added to the V accumulated for the prior iterations. During the ADJUST phase for each iteration. The number of fractions sets the value for MAXITERS.Highway Program Control statements 6 PARAMETERS keywords (continued) Keyword COMBINE (continued) Subkeyword Description AVE WTD Average all the iteration loadings. The V at the end of each iteration is the accumulated V for all the iterations to that point.) processes or by using an array of C scales. All the Iteration volumes are summed to form the final volume.. then C must be computed differently depending upon which iteration it is.. by use of IF (ITERATION=. but the required weights are used to favor specific iterations.00. it is true only on the last iteration. COMBINE WEIGHTS |RV*| Specifies the weights to be used when COMBINE is set to WTD. Default value is 0.005. EQUATION Default value is AREA.6 Highway Program Control statements PARAMETERS keywords (continued) Keyword COMBINE Subkeyword LAMBDASEARCH |S| Description Specifies alternate methods for computing Lambda in EQUI processing. This value is used only if: there are turning volumes and COMBINE is set to EQUI. If the default value (0) is used. If CONSOLIDATE is set to 3 then links of three or more strings will be consolidated. Cost curves computed for incremental estimates of lambda for every link. 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. GAP1 |KR| Specifies the cutoff point based upon the relative difference in system cost (volume * cost) between two iterations. turning volumes and delays from JUNCTIONI processing are not included in the estimation. If the default is used (2). Specifies minimum string length for link consolidation. EQUITURNCOSTFAC |KR| Factor used to convert turn delays from minutes to cost for estimating Lambda in the equilibrium process. You can select one of two Lambda search processes: AREA Indicates to minimize the area under all the V vs. The number of weights sets the value for MAXITERS. Estimates lambda by solving an expression based on the TC functions. if CONSOLIDATE=T is specified on the PATHLOAD statement. Default value is 0. CONSOLIDATE |I| 218 Cube Voyager Reference Guide . then links of two or more strings will be consolidated. this value typically specifies the same value as TURNCOSTFAC. and so on. When use. Default value is 2. Specifies the maximum length for a string variable. The input demand matrix should be in units of vehicles (or PCU) per model period. If disk space is scarce or you are not concerned about run times.00. Maximum index for work matrices (MWs). A higher number results in faster processing. Default value is 5 (the matrices are combined every five iterations). Otherwise. Default is 100. Default value is 1.Highway Program Control statements 6 PARAMETERS keywords (continued) Keyword MATOADJUST Subkeyword |KI| Description Specifies how often MATO matrices are combined during assignment. If you expect to compute longer strings. Optional. All string variables will have this possible length. you must define a larger number. using the same factors used to combine volumes. Valid values range from 1 to 999. Specifies the value to be used with PDIFF. Normally. Duration of the model period in minutes.0. a default of sixty minutes (one hour) will be used. If no value is specified. Citilabs recommends setting this value to 1 (matrices will be combined after each iteration). Enter number of iterations to combine at once. but requires more disk space to store intermediate matrices. 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. Citilabs recommends using the default value. Default value is 10. MAXSTRING |KI| MODELPERIOD |KR| PDIFF1 |KR| PDIFFVALUE1 |KR| Cube Voyager Reference Guide 219 . MAXITERS1 MAXMW |KI| |KI| Specifies maximum number of assignment iterations to be performed. With a high number and numerous iterations. or in an AVENUE run. Default value is 999. This value is only used if junctions are being modelled. Default value is 0. you do not specify this keyword and override default value. you could exhaust disk space. A lower number requires less disk space but more processing time. Specifies the cutoff point based upon the root mean squared error of the differences in volumes between two iterations. Specifies an alternative GAP measure as the cutoff point. Default value is 0. Default value is 0.005.005.1. RELATIVEGAP1 RMSE1 |KR| |KR| 220 Cube Voyager Reference Guide . Default value is 0.6 Highway Program Control statements PARAMETERS keywords (continued) Keyword RAAD1 Subkeyword |KR| Description Specifies the cutoff point based upon the relative average absolute difference in volumes between two iterations. If no TC functions are defined then a default TC function is applied. If no LINKCLASS is defined for a link it defaults to LINKCLASS=1. TCCOEFF[2]=0. For example. TCEXP[1]=4.Highway Program Control statements 6 PARAMETERS keywords (continued) Keyword TCCOEFF Subkeyword |RV*| Description Represents the coefficient term in a LINKCLASSspecific TC function relating congested volumes from the assignment to congested travel times on the links. Then these LINKCLASS-specific values of TCCOEFF and TCEXP are substituted into TC[1] for the appropriate LINKCLASS of a given link. TCEXP[1]=6. Default value is 0. TCCOEFF[3]=0. This allows you to have one common functional form but apply different coefficient and exponent values by LINKCLASS. TCEXP[1]=4. TCCOEFF. TCEXP[1]=8.18. TCEXP) but the user is free to experiment with any forms that make sense to them for their application. TC[#]=f(T0. V/C. if four LINKCLASSes are defined in the LINKREAD phase.15.17.16.15. TC stands for Congested Time or TC. 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. If the user codes: PARAMETERS TCCOEFF[1]=0. The TC functions can be indexed by LINKCLASS to specify different volume delay relationships for different classes of facility. TC functions are the labels in the software given to volume delay functions (commonly referred to as VDFs).5. Cube Voyager Reference Guide 221 . The LINKREAD Phase of this program allows the user to associate every link in the network with an internal LINKCLASS variable. In general. You can also code your own functional form if the BPR form is not what is desired. TCCOEFF[4]=0. and no TC functions are specified then TC[1] as specified above is in effect for all links. 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. With a value of 10. A value of 1 indicates that each movement is to be considered with the same weight as a link.exe. Program writes to the run monitor when initiated through Application Manager or voyager. Factor to convert turn times to equivalent costs for use in summary statistics and GAP calculations. TURNCOSTFAC |KR| TURNGAPWT |R| 222 Cube Voyager Reference Guide . Default value is 1. Value corresponds to number of zones. with a value of 1. the summary report will not include turn volume costs. Specify a larger value to reduce run times. the program writes no zonal messages. Default value is 4. With a value of 0. the program writes a message for every zone. If the value is 0. For example. Constant that indicates how much weight each turn movement should have when turn cost is used in GAP calculations.exe. Valid values are greater than or equal to zero. ZONEMSG |KI| Optional. the program writes a message for every 10 zones. Frequency with which the program writes zonal timing messages to the run monitor or console.0. See the discussion for TCCOEFF above for usage. 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).6 Highway Program Control statements PARAMETERS keywords (continued) Keyword TCEXP Subkeyword |RV*| Description Represents the exponential term in a LINKCLASSspecific TC function relating congested volumes from the assignment to congested travel times on the links. The program writes to the console when initiated through runtpp. Default value is 1. Default value is 1. 30.2. GAP is a commonly used criteria. the process is to terminate. These keywords are used to control when to not do any more assignment iterations. It is suggested that MAXITERS always be used to preclude endless processing.2...5. this implies that when the system costs do not change by more than one percent. Normally.. and loads path links. MAXITERS=30 PARAMETERS COMBINE=SUM. Thus. SAMPLE INCREMENTAL ASSIGNMENT WITH “PROJECTED” RESTRAINT PARAMETERS COMBINE=SUM. CSCALE[2]=.3*3. FRACTIONS=. The first of these criteria that is satisfied controls the process. the NETI or MATI matrices will establish the number of zones. generates related matrices. the results printed at the end of the program should be examined to determine if oscillation has occurred.10 .01. 7 iterations COMBINE=EQUI.. CSCALE[4]=1 PHASE=LINKREAD C = LI.Highway Program Control statements 6 PARAMETERS keywords (continued) Keyword ZONES Subkeyword |KI| Description Establishes the number of zones to process.9. WEIGHTS=1.1. 1. CONSOLIDATE ESTMO (ALLJ) EXCLUDEGROUP Cube Voyager Reference Guide 223 . it will be set to 100. If MAXITERS ends up being the controlling value.20. FRACTIONS=. In the USA. and oscillations may start. CSCALE[3]=. but there could be cases where the user wishes to use a different value.7.CAPACITY * CSCALE[ITERATION] PATHLOAD Builds a path. Some networks may never converge.5.1 ARRAY CSCALE=4 CSCALE[1]=. or if more iterations are really needed.Incremental . if GAP=0.5*.2. Example ZONES=3000 COMBINE=WTD. If ZONES is not specified.5. and the program has no other way to identify the appropriate number of zones. 7 Iterations . Using MAXITERS can prevent useless processing. Default value is taken from NETI. MW — Processed in the input order 224 Cube Voyager Reference Guide . and then complete other processes based on that path.6 Highway Program Control statements EXCLUDEJ INCLUDEJ LINKIDARRAY (LINKIDCNTMW LINKIDMW LINKIDLASTUSE LINKID#MW) MW (NOACCESS SELECTLINK SELECTGROUP SELECTLINKGROUP) PATH (DEC) PATHO (ALLJ INCLUDECOST NAME PATHOGROUP (FULLPATH)) PENI PENIFACTOR SUBAREAMAT (MAXMSG) TOLLFACTOR TOLLMATI THRUNODE TRACE (PRINTO (REWIND PRINT) CSV CFORM FORM LIST) VOL (VALUENAME) Use a PATHLOAD statement build a path. matrices can be generated based upon path criteria. TRACE 3. LINKIDARRAY 4. the statement is processed in the following specific order: 1. Although any of the keywords on the statement can be in any order. Selected I-J path traces can be written to the standard output print file. link volumes can be obtained by routing matrix values along the path. PATH — Built using any EXCLUDEGROUP and PENI values specified 2. but they can be combined. if HOV links were assigned to group 4. For example. Default value is FALSE. mostly likely resulting in longer processing times and larger output files. then none of the paths would contain HOV links. and than the EXCLUDEJ follows. Cube Voyager Reference Guide 225 . Default value is F. it must be either an LI. Thus. When both are used. LINKIDARRAY LINKIDARRAY LINKIDCNTMW |S| |I| Specifies an array of link attributes. if INCLUDEJ=100-200 and EXCLUDEJ=140-150. Specifies the MW[] in which to store the number of links in the list. The INCLUDEJ is processed first.Highway Program Control statements 6 5. EXCLUDEGROUP |IP| Specifies that links that have any of the designated group codes will be excluded from the path building process. EXCLUDEJ INCLUDEJ |IVP| |IVP| Specifies that the processes for the named keywords will exclude the specified destination zones.array or an LW. 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. If the value is TRUE.array. or for only the I-J paths where an actual assignment is performed. Default value is F. 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. reductions in runtime could be significant. and 4 were one of the excluded values. Depending on the level of inefficiency in the input network. zones 100-139 and 151-200 would be the only destination zones processed. no link consolidation. 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. Consolidating the links reduces the size of the link table and the thus reduces pathbuilding time. Flag that indicates if ESTMO processing is used for all I-J paths. all potential paths are considered. This is often referred to as a LOS (level-of-service) matrix.8 means that the number of the first link will be stored in MW[10]. To obtain zone-zone values. For example. MW[] |N| Generates a matrix row. the second link’s information will be stored in MW[11]. The primary difference is that this expression has access to the values from the I-J paths that result from the PATH keyword. MW[1] = PATHTRACE(TIME). such as distance. the excluded cells will not be altered. If there are INCLUDEJ and/or EXCLUDEJ values on the statement.6 Highway Program Control statements 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. cost. and so on. 226 Cube Voyager Reference Guide .8 means that the first link’s information will be stored in MW[10].6. There may be multiple MWs specified on the statement. the value will be a big number. For example. When the PATHTRACE for the intrazonal value (J=I) cell or a cell with no access is obtained. because the values are “skimmed” from the network. LINKID#MW=10-13. time. the computation implies a J=1. For example. the PATHTRACE(name) function is used. only those corresponding columns in the MW will be processed. Link arrays can then be addressed directly by using these values. the fifth link’s information will be stored in MW[6].6. List of MW numbers where the monotonic succession of link crossing information (beginning at 1) is to be stored. LINKIDARRAY LINKID#MW |IP| List of MW numbers where the monotonic succession of numbers of the links (beginning at 1) is to be stored. etc.xyz[MW[2]]. Typical types of matrices computed include: • Path-based matrix — A matrix with I-J path values. because there is no path between the zones. to obtain zone-tozone times. the fifth link will be stored in MW[6]. ANODE = A[MW[1]] xxx = LW. Two-level indexing is not allowed here. they will be processed in the order they appear on the statement. the second link will be stored in MW[11]. almost in the same manner as a regular COMP MW[]= statement. For example. LINKIDMW=10-13.Zones loop. Many traditionalists refer to such matrices as “skim” values. the MATO will contain the values obtained during the last iteration -. the argument list to PATHTRACE may include the penalty set numbers that should be added to the values for the first argument to PATHTRACE. and no paths or matrices are built from the final network link values. because it obtains the values without tracing paths.not after the iteration. Thus. if “skims” had been written in each iteration. Warning: The program determines when the last iteration has been performed. you can use the subkeyword NOACCESS to specify a value to be returned from the PATHTRACE function when there is no path. because PATHTRACE actually traces the path and sums the value from the network links that are in the path. This is normally done for trip matrices. it also contains any penalty values that were included in building the paths. MATOs written during normal iteration processing are combined according to the COMBINE option on the MATO statement. Cube Voyager Reference Guide 227 .Highway Program Control statements 6 PATHLOAD keywords (continued) Keyword MW[] (continued) Subkeyword Description In some cases. This is different than PATHTRACE. and in other cases. a big number is acceptable. The keyword PATHCOST may be used to obtain the value directly from the path tables. it is not. If COMBINE=F. and COMBINE=T. PATHCOST is much faster. To solve this dilemma. the final skim mato will be the weighted values from all the iterations. but it may be useful for specific travel cost matrices. To provide similar capabilities with PATHTRACE. Following the last 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. 7.DISTSNCE). and SELECTLINKGROUP. penalties added MW[4]=PATHCOST . the MW= expression is computed. SELECTGROUP. zone-to-zones times MW[2]=PATHTRACE(LI.5. and if any of them is true. or 7. There are several different subkeywords that can be used to specify the select-link criteria: SELECTLINK. if any of the SELECT criteria is satisfied for a given J. All the SELECT. SELECTLINK=(L=1000-1001 && L=20002001). Default value is 1.. Their detailed descriptions are below.000. If the selection is 1-3. .1. A path has to include at least one link that has any of the specified group codes. zone-to-zone distances MW[3]=PATHTRACE(TIME. MW[3] for that J will be computed to be the value from MI.1. MW[] SELECTGROUP |s| 228 Cube Voyager Reference Guide .. . MW[1]=PATHTRACE(TIME). MW[3]=MI. Each results in a true or false condition. .6 Highway Program Control statements PATHLOAD keywords (continued) Keyword MW[] (continued) Subkeyword Description Example of PATHTRACE PATH=TIME. Example of Select Link PATH=COST. 3. same as MW[1].TRIPS.2). In the following example. keywords are combined for the MW that they directly follow. SELECTGROUP=1-3. Specifies the group codes for selection. 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.000. 2. then at least one link in the path has to have a group code of either 1. same as MW[3] • Select-link matrix — A matrix of values for the zones that meet select link criteria.TRIPS. 200-205 means if N is 100. Each link/node is processed. Cube Voyager Reference Guide 229 . Any of these variables can have multiple values specified for them. The expression must be enclosed within parenthesis. the implication is a logical OR amongst the values. only useful to select links with a path ends at B. and as long as it does not fail any conditions. B. or if N is a value between 200 and 205.Highway Program Control statements 6 PATHLOAD keywords (continued) Keyword MW[] Subkeyword SELECTLINK |s| Description Expression used to determine if the I-J path uses certain facilities. In the total path basis. Examples may better illustrate the process. Links are coded as A-B (directional) or A-B* (non-directional – link may be traversed in either direction). Nodes (A. on both an individual link and a total path basis. The selection is processed by examining each link/node in the path. only useful to select links with a path begins at A. it is considered as a candidate for processing in the total path. L can have multiple links specified. N) can be specified as single values and/or as ranges. When the multiple value specification is used. Example: N=100. and can contain any of the following variables: A B N L The A-node of a link. The process is from left to right.105. inclusive. A link that must be used in the path. The B-node of a link. A node that must be used in the path. or if N is 105. the link/node is considered in conjunction with other links/nodes in the path. 57 || L=105-104)) The path crosses any node 100-105. most any desired combination of path usage can be specified. Example SELECTLINKGROUP=((grp[1]>3 && grp[2]>=1)|| grp[7]>=5 || grp[6]=2) 230 Cube Voyager Reference Guide . If L=104-105* instead of L=104-105. nothing else is really appropriate. or Link 104-200 is on the path: true (L=102-101*) The path contains link 101-102 or link 102101: true (L=101-102* && L=104-105*) The path contains link (101102 or 102-101) and link (104-105 or 105-104): true (N=101 && N=105-110 && L=101-102*) The path contains node 101 and any node in the range of 105-110. The expression should contain mostly GRP[] values and perhaps I and J. The tracing mechanism accumulates how many links of each group code are used in the path. Those totals are available to the expression. and (it crosses node (8 or 57) or link 105-104): false. 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 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.6 Highway Program Control statements PATHLOAD keywords (continued) Keyword MW[] Subkeyword SELECTLINK (continued) Description Sample path: 1-101-102-103-104-105-2 (A=1) Node 1 is on the path in any link except the last: true (A=1 && B=102) Node 1 is on the path in any link except the last. and node 102 is on the path in any link but the first: false (L=101-102. the expression would be true. Citilabs recommends using nested parentheses to help categorize the comparison sets. and link (101-102 or 102-101): true ((N=100-105) && (N=8. With this type of Boolean selection.104-200) Link 101-102. The file will contain I-J paths generated by this PATHLOAD statement. The generated file can be very large and writing it can cause a considerable increase in running time. LI. The number of I-J paths will be determined by the value of the PATHLOAD PATHO ALLJ keyword. or for various post processing capabilities. If an attempt to write the same NAME to a file for the same I zone is made. unless this application is path building only (No FILEO NETO=value and no PATHLOAD VOL= value). and there will be no message indicating that this attempted duplication occurred. 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. Switch that indicates if PATHO write processing is to be invoked for all I-J paths. Time. Dist. 4. respectively. this can cause a considerable increase in the size of the file.Highway Program Control statements 6 PATHLOAD keywords (continued) Keyword PATH PATH DEC Subkeyword |KS| |S| Description Specifies the link value on which the paths are to be built. 1. T/F flag used with PATHOGROUP to keep partial or full paths for the specified GROUP(s). The path file can be used in Cube for analysis of what happened during this assignment. PATHO ALLJ |?| PATHO PATHO FULLPATH INCLUDECOST |?| |?| PATHO NAME |S| Cube Voyager Reference Guide 231 . 4 decimal places and floating point. 2. the PATHO file will not be written for this statement. or recreation of parts of the assignment. Specifies the accuracy of the link value on which the paths are to be built. such as selected link analysis. However. 2. Valid values are: Cost. If PATHO is not specified. especially for larger networks.name.name. 1. and F. Using lower accuracy will speed up the assignment process considerably. the same NAME path set may not be written to a file more than one time for an I zone. By default this value is false. only the first set will be written. Default value is F. A PATHO file may have multiple path sets written to it by different PATHLOAD statements. which represent 0. PATHO |I| Number (#) to specify that a path file is to be written to FILEO PATHO[#]. or for only the I-J paths where an actual assignment is performed. or LW. Name to be applied to the paths written for this statement. 3. Valid values for DEC are: 0. 3. 6 Highway Program Control statements PATHLOAD keywords (continued) Keyword PATHO Subkeyword PATHOGROUP |IP| Description List of numbers (1-32). If a JUNCTIONI file is provided. The numbers are associated with GROUP ADDTOGROUP= process in LINKREAD. If the path does contain a specified link in the group(s). and the FULLPATH subkeyword is T. The ADDTOGROUP numbers are typically associated with specific LI. If the path does contain a specified link in the group(s). A set number must be 1-8. the valid numbers on the TURNPENI file. and J. all the nodes of any path that uses any of the specified links in the group(s). 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. When the trace of a path is examined. This is not specifically related to JUNCTION. PENIFACTOR |N| 232 Cube Voyager Reference Guide . then the SET keyword is required to reserve one penalty set numbers for use with the junction delays. You can specify any combination of valid PENI indices. the nodes of the specified links in the group(s). values via a conditional statement thus links are either associated with the group or not. This can considerable reduce the size of the stored path file. it applies to all penalties (TURNPENI and SET=). 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. or LW. PENI |IP| Specifies the PENI set(s) that are to be used in building this path. if the trace does not contain any of the selected links in the group(s) nothing is written to the PATHO file. the trace will contain I. the trace will contain only I. and the FULLPATH subkeyword is F. Expression that specifies a factor for all penalties during path building. and J. If a generalized COST function is used for path building. a value is to be inserted to the subarea matrix. This process is described in “ILOOP phase” on page 154. at the 50th message. Two values are allowed: • • The first value specifies how many messages are printed for the SUBAREAMAT. Units must be (path cost units)/(toll cost units). SUBAREAMAT MAXMSG |I2| Specifies how many messages to print about improper cordon crossings and the error level to assign to the messages. For example: MAXMSG=50. There must be an index for the keyword. The highest index is used to set the number of matrices on the SUBAREAMAT file. An assumed traveler value of time of US$15/Hour would be implemented by setting TOLLFACTOR to 4 (60/VOT). Generally paths are built on TIME and TIME is in the units of minutes. then the TOLLFACTOR expression must specify a value in minutes/$US. Cube Voyager Reference Guide 233 . For example. 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. if tolls are coded in $US and path costs in minutes. The second value specifies the error level to assign to the message when the number of messages reaches the first value. but the program will terminate with error level 2.Highway Program Control statements 6 PATHLOAD keywords (continued) 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. The printed messages will be assigned an error level of 1 less than the second value for all messages except the last one.2 indicates that the first 50 improper crossings are to be printed at error level 1. TOLLFACTOR |N| Expression that specifies a factor for converting tolls to COST units. all components of this function are typically appropriately factored to be in generalized minutes. 6 Highway Program Control statements PATHLOAD keywords (continued) 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. and Iteration. The default value is ZONES+1. The select expression must be enclosed within parenthesis. Specifying TOLLMATI=1. The value has to be a positive integer.) array or it can be set to _pathcost to list the accumulated value of the COST function along the path trace. Most likely. 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. See “Path-based tolls” on page 146. The LIST subkeyword may be any valid input (li. The TRACE expression is evaluated for J=1. THRUNODE |I| Sets the minimum node number allowed to be included in the path building process. Specifies if any paths from I to the selected destinations are to be formatted and reported for this path. J. the variables used in the expression would be I.) or work (lw.2 indicates to use toll set 2 on TOLLMATI file 1. The default value excludes centroids as intermediate points of a path. but any valid variable can be used. The following additional subkeywords can be used: PRINTO (REWIND PRINT) CSV CFORM FORM LIST See “PRINT” on page 238 for details on these subkeywords.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. See “TRACE example” on page 236. 234 Cube Voyager Reference Guide . In that case. The index range is 1-20. only the hot running portion of the trip would be assigned. VOL[] Valuename |S| Cube Voyager Reference Guide 235 . Specifies the name of a link value that should be used in restricting the links that should be included in the VOL assignment. perhaps it is desired to assign all vehicles. but there are many cases. In the 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.5 is 50% of the way from 6 minutes to 9 minutes). VOL[2]=MI. A single range of numbers is required for this keyword. The values are added to the volumes. only 50% of the trip value would be added to the link volume (7. but if it is not. 7.Highway Program Control statements 6 PATHLOAD keywords (continued) Keyword VOL[] Subkeyword |N| Description Specifies an expression to be solved for J.1. For example. you must specify the FUNCTION V so the program knows which VOL combinations are to be used for capacity analysis. Normally. where it will be advantageous to have more than one VOL. and to determine what types of trips make up the volumes on each link. It should be noted that when specifying multiple VOL keywords. but if the range were say.TRIPS. Or. there will be a single VOL for a PATHLOAD statement. An example would be to obtain what portion of the volume on a link is in cold start mode. TIME=0-7. In most cases. VOL should be indexed []. The primary use of this keyword is for air quality analysis. the range would be 0-some number. the index is implied to be 1. that is easily accomplished. there may be up to 20 volume sets in a single application of Highway.5-99999.5 would mean to assign only to the links that are within 7. if a 3 minute link’s A node were 6 minutes from I.5 minutes from the origin zone. and that the result of the expression is to be assigned to the links in the path generated by the PATH keyword. The examples below illustrate these capabilities. 'DISTANCE' PRINT CSV=T. speeds up process IF (I=FromNode) . FROM._pathcost(8.2) .ToNode(5.3). LIST='FromNode'.TIME(8. DISTANCE PRINT CSV=T.NET PHASE = LINKREAD FromNode=1500 ToNode=1875 lw. build paths for select I PATHLOAD PATH=li.TIME mw[1]=PATHTRACE(li. TIME.0). 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. LIST=I.2).TIME).0). TO.mw[1](10.DISTANCE lw. TRACE=(I=FromNode & J=ToNode) PRINTO=2 PRINT=T F=6.Print results to formatted file to check against TRACE JLOOP IF (J=ToNode) . 236 Cube Voyager Reference Guide . PRINTO=1.DISTANCE(8. li.DISTANCE).flag1=1 ENDPHASE PROCESS PHASE=ILOOP if (I < FromNode) _skiptoI=FromNode .0). mw[2]=PATHTRACE(li. LIST=FromNode(5.fac_dist(10.mw[2](10.CSV FILEO PRINTO[2] = PATH_TRACE_RPT. lw.0.4).'TIME'.B.lw.fac_dist=10*li. PRINTO=1.J.flag1(3.'ToNode'.li.A.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.6 Highway Program Control statements TRACE example RUN PGM=HIGHWAY FILEO PRINTO[1] = PATH.3).DAT FILEI NETI = TEST. The comments illustrate how to properly skim a path when penalties should be incorporated. The values from MW[3] are assigned to the COST paths and added into VOL[1] volumes.ODTRIPS PATHLOAD PATH=COST. 2. */ PATH=LI. the MW[6] values could be incorrect.DISTANCE).5 This first PATHLOAD statement causes the COST paths to be built. 5. The values from MW[6] (the selected link trips) are assigned to the COST paths and added into VOL[2]. but if the user caused any values to be set into MW[6] prior to this statement. MW[1] and MW[2] are the same in this case PATH=TIME.MW[2]=PATHCOST Cube Voyager Reference Guide 237 . The values from MW[3] are assigned to only the links that are within 7.Highway Program Control statements 6 PATHLOAD example PATHLOAD PATH=COST.ODTRIPS are assigned and added to VOL[1]. VOL[1]=MI.1. Note that MW[6] was cleared at the beginning of the ILOOP for I. MW[6] is set equal to the values in MW[3] for the Js whose path from I crosses link 2001-2004.MW[1]=PATHTRACE(LI.1. 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. SELECTLINK=(L=2001-2004). 4. MW[6]=MW[3].DISTANCE. VOL[2]=MW[6].TIME=0-7.MW[2]=PATHCOST . The second PATHLOAD statement causes the following sequence of events: 1. and then the values from MI.3 MW[1]=PATHTRACE(COST).VOL[3]=MW[3]. VOL[1]=MW[3]. 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. 3. COST paths are built.5 minutes from I and added into VOL[3] (these are the cold start volumes). PENI=1. The steps are: 1. (This is to illustrate a method of application. Divert = 0 RelativeSaving = TimeSaved / MW[2] IF (TimeSaved > 10 && RelativeSaving >.1. If the time saved exceeds 10 minutes and the relative saving (time saved / total trip time) is greater than 15 percent. EXCLUDEGROUP=1 MW[2]=PATHTRACE(TIME) . In this example the link is already in the network.they would be the same. VOL[1]=MI. and the remaining trips to the other path set. MW[1]and MW[2] could be different because penalties are used . CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) 238 Cube Voyager Reference Guide . /* Following is an example of trip splitting based upon the relative difference of time if a link (say. 2. 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].MW[1]. MW[1]=PATHTRACE(TIME) . */ PHASE=LINKREAD If ((A=1001 & B=1002) | (A=1002 & B=1001)) ADDTOGROUP=1 PHASE=ILOOP PATHLOAD PATH=TIME. and it can be unavailable to the path builder by excluding links with group code 1.3). Assign a portion of the trips to the one path set. Compute the time path with the bridge included and extract the times along the path into MW[1]. VOL[1]=MI. MW[3] = the fraction of trips diverted to the bridge path TimeSaved = MW[2] . 2 is always >= 1.15)Divert = RelativeSaving MW[3] = Divert ENDJLOOP . If MW[1]=PATHTRACE(TIME. EXCLUDEGROUP=1.w bridge PATHLOAD PATH=TIME. in the path.TRIPS*MW[3] PATHLOAD PATH=TIME.6 Highway Program Control statements . Compute a path split based upon the total times for the two sets of paths. a bridge) is added to the network.TRIPS*(1-MW[3]) PRINT Formats and prints a line of information. but.assign bridge trips PATHLOAD PATH=TIME. and is not meant to imply any type of realistic diversion. they could have just as easily be kept separate.1.) 4. Compute another path with the bridge excluded (group=1)and extract the times along the path into MW[2] 3.1. The two assignments are made to the same volume set.wo bridge JLOOP. the portion of trips that will use the bridge path is set equal to the relative saving. 1 form=LRD title='form=LRD' PRINTROW mw=1-21 form=6D base1=y maxperline=10 form=6D. the ENDPROCESS statement is not necessary. the occurrence of another Cube Voyager Reference Guide 239 . LIST INPUT LINKS LIST= A(5).. B(5). PHASE ENDPHASE A user process phase stack is defined by a PROCESS statement that names it and an ENDPROCESS statement that ends it. Example PRINTROW mw=1-2.B.Highway Program Control statements 6 See “PRINT” on page 62 for details.VC(5.A.2) ENDIF IF (ADJUST=1 && ITERATION >5 && VC >2. To simplify coding. NI. MW J TITLE FORM MAXPERLINE BASE1 See “PRINTROW” on page 69 for details. PHASE=name may be used directly.2) PRINTROW Formats and prints row(s) of matrices.DIST(6). T0(6. base1=y maxperline=10 PROCESS . ENDPROCESS Establishes phase blocks. And.0) LIST='BIGVC for: '.. Example IF (ITERATION = 0) . the PROCESS control word is not necessary. to further simplify coding. are not processed within the stack.ODTRIPS ENDPHASE PHASE=ADJUST LW.FLAGCODE ENDPHASE REPORT Requests reports and establishes tracing.1. CAPACITY PENI 240 Cube Voyager Reference Guide . Example PHASE=LINKREAD T0 = LI. FILEO. and LOOKUP. such as PARAMETERS. even if that is where they are coded. it may be coded as either ENDPROCESS or ENDPHASE.TIME = TIME * LW. VOL[1]=MI.DISTANCE*60 / SPEED ENDPHASE PHASE=ILOOP PATH=TIME. If ENDPROCESS is used. Exception: Static statements. PROCESS keywords Keyword PHASE |KS| Description Names the phase stack. The following names may be specified: • • • • ENDPHASE |K| SETUP LINKREAD ILOOP ADJUST Defines the end of the user control statements for a stack. until an ENDPROCESS statement or another PROCESS statement is encountered.6 Highway Program Control statements PROCESS statement acts as the ENDPROCESS statement. The control statements that follow it. will be executed when the phase is internally executed. FILEI. There may be any number of VDTSPD keywords. only the first five J values will be reported. Specifies which destination zones are to be included in this report.Highway Program Control statements 6 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. Controls the listing of the stack statements as they are processed (can be quite voluminous. If this keyword is not specified. thus controlling the amount of output as desired. If no subkeywords are appended to this keyword. the program will simulate: RANGE=0100-1. Trace can be turned on and off at any time. Switch that indicates if the vehicle distance traveled stratified by average trip speed is reported. all origin zones will be included. Switch that indicates if the speed portion on the SPDCAP tables is to be reported. If there are a larger number of junctions coded in the network then PENI=T could result in voluminous print file. Switch to turn off dynamic printing of the turn delays calculated by the junction model and reported every iteration. so be careful). SPEED TRACE |?| |K?| VDTSPD |?| VDTSPD I |IV| VDTSPD J |IV| Cube Voyager Reference Guide 241 . all destination zones will be included. Specifies which origin zones are to be included in this report. If this keyword is not specified. Note that this report requires considerably more computer resources (both process time and disk space). If a COMP is traced. 7. With multiple RANGE sets. it will also include any values less than the low value and any values greater than the highest value.5-100-5 specifies that two different schemes are to be obtained. RANGE=0-100-1 specifies that the report is to have 100 values reported. the output will be stacked onto the file.2 Interval includes speeds >= x and < 2. RANGE=0-7. an I-J value can be placed into more than one RANGE set.5. and possibly three for each sub report. If the same file is specified following different VDTSPD keywords.5 Interval includes speeds >= 4 and < 5 5 . For example: • • • RANGE=0-100 specifies that the report is to VDTSPD RANGE |IP| have only one number reported. If RANGE=2-5-1 is specified.3 Interval includes speeds >= 2 and < 3 3 . The values can have at most one decimal place. Specifies the speed stratification for this report. There must be at least two values.y Interval includes speeds >= 5.4 Interval includes speeds >= 3 and < 4 4 . x is the lowest speed found 2 .6 Highway Program Control statements REPORT keywords (continued) Keyword VDTSPD Subkeyword FILE |F| Description Specifies a file where the VDTSPD reports are to be written (exported) in a format that can be easily read by most spreadsheet software. Each subreport will not only contain values for the RANGE specified. the printed report will appear as: x . Specifying FILE will not preclude the reports from being printed. y is the highest speed found 242 Cube Voyager Reference Guide . If this keyword is not specified. VAL VARS Use SET to set any number of variables to some value.5. FILE=VDTSPD. A COMP statement is not as efficient as a SET statement. report the capacities by lane by CAPCLASS REPORT VDTSPD=T. the entire array will be set to VAL. All variables are set to zero when they are first allocated.5-100-5. Sets the maximum number of decimal places to be printed for any variable. 7. ZDAT ZDAT DEC |?| |I| Example TRACE=y . VARS |S| Cube Voyager Reference Guide 243 .TXT SET Sets multiple variables or arrays to the same value. It must be a numeric constant. RANGES=0-7. COMP statements produce most changes. This one value applies to all variables on all ZDATI statements. J=1-933. List of variables that are to be set to the more recent value of VAL obtained from this statement. turn stack tracing on REPORT CAPACITY=yes . I=1-933. VOL=1.Highway Program Control statements 6 REPORT keywords (continued) Keyword VDTSPD Subkeyword VOL |IP| Description Specifies which volume sets are to be included in this report. VAL is initialized to zero when the statement is encountered. Switch that indicates if all the internal arrays obtained from FILEI ZDATI files are to be reported. If a VARS is the name of an array established on an ARRAY statement. the program will report all volume sets. SET keywords Keyword VAL |R| Description Value that the VARS that follow will be set to. ADDTOGROUP REMOVEFROMGROUP Use SETGROUP to set group codes for a link. VY SETGROUP Sets group codes for a link. sets all to 123 SET VAL=0. Group codes can be quite helpful in project analysis or for determining specific interchange to interchange movements. This keyword normally should not be used.SPDCLASS==1-3.55) ADDTOGROUP=1 244 Cube Voyager Reference Guide . There are no preconceived definitions for the codes. is also the same (VAL is 0) SET VAL=123 VARS=C123. VARS=TOT1. The codes are numbered 1-32. TOT2. Specifies that the current link is to have the designated values removed from its codes. SETGROUP keywords Keyword ADDTOGROUP |KIP| Description Specifies that the current link is to be assigned the codes that are in the value list. Group codes are used primarily for designating links that are to be excluded in path-building.6 Highway Program Control statements Example SET VAL=0.TOT2. VARS=TOT1.VA2. is a COMP statement to do the same thing SET VARS=TOT1 TOT2 COUNTER . VARS=VX.COUNTER TOT1=0 TOT2=0 COUNTER=0 . it is applicable during only the LINKREAD phase. that is the user’s responsibility. Each link can have up to 32 different group codes assigned to it. REMOVEFROMGROUP |KIP| Example PHASE=LINKREAD IF (LI. VARS=VA1.6.9. VAL=100. and for inclusion in select link analysis. TOT3 .VA3. 2.). inclusive. LANES |IV| SPEED |RV*99| Cube Voyager Reference Guide 245 . Lane stratification that any following CAPACITY and/or SPEED values are to apply to. All values must be 03276... 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. ARRAY NUMRECS See “SORT” on page 72 for details.. The revised tables will be written to the NETO file. CAPACITY[2]=40.Highway Program Control statements 6 SORT Sorts user-defined arrays. Actual link capacity is obtained by multiplying the link capacity based upon its capacity classification (CAPCLASS) value by the number of LANES. The capacity array is initialized to 20 times the index number. The speed array is initialized to the index number. for all lane stratification (CAPACITY[1]=20. This capability allows you to test various scenarios without having to modify the network. Speed is maintained with one decimal place. If this statement is used in the control file for the Highway program.99]=1.. LANES may be interspersed with other keywords and values on the statement. inclusive. SPDCAP Revises speed and capacity tables. Speed to be applied to the link...7.. inclusive. for all lane stratification (SPEED[1. All values must be 1-9. All values must be 09999. SPDCAP keywords Keyword CAPACITY |RV*99| Description Capacity in vehicles per lane per hour. the values from the NETI are updated when NETI is opened.99). At the end of each iteration (in the Adjust phase). and contains 891 values. SPDCLASS) as the column index to obtain a value for a link. Usually.. The value of T for each movement will be computed in the Adjust phase.21.8. LANES=1. the program uses the number of lanes (LANES) as the row index. the T= expression should be parallel to the V= expression that is specified on a FUNCTION statement. then revise the values for 20.700 SPDCAP LANES=2.8 SPDCAP CAPACITY=99*50. NT Use TURNS to request that the volumes at specific interchanges (nodes) be accumulated. SPEED=20.3. If CAPACITY or SPEED is encountered prior to a LANES keyword on the statement.50. and the capacity and/or speed classification (CAPCLASS..Set entire table to 50. and then combined with other iteration values to form the “combined” volume..30..88.5. LANES will be preset to 1-9. CAPACITY and SPEED are entered as vector data. and may have null fields to skip the revision of certain columns. and may be indexed to set a specific loading place.. Inappropriate. 246 Cube Voyager Reference Guide . the LANES will not be used. the program will accumulate turns for every PATHLOAD VOL[]= statement that is present. the single volume is computed by adding all the individual turn volume sets together (T = TURN[1] + TURN [2] + TURN [. .. Each array is dimensioned with ninety-nine values for each of nine lane stratification. LANES=5. and 24 for lanes 1. If there is at least one TURNS statement.6.. Example . TURNS Requests turning movement volumes.SPEED[15]=15 SPDCAP SPEED=30. This default accumulation process can be overridden by using the T= capabilities on this statement. The SPEEDFOR and CAPACITYFOR functions can be used to obtain values for these tables. By default.6 Highway Program Control statements A network contains an array of capacity and speed data. CAPACITY[20]=300. When an array is accessed.4-9. a single total turn volume will be computed for each movement at the nodes where turns are requested.2.] .400.3.3. LANES=2-8.). trn. Example FILEO TURNVOLO=myfile.5000-6000. you must specify a FILEO TURNVOLO statement. FORMAT=BIN TURNS N=1000-2000.19000-32000. The turn volumes will be written to the file(s) specified on that statement.Highway Program Control statements 6 To accumulate turn volumes. Expression used to compute the total volume at each of the nodes. T=TURN[1] + TURN[3] Cube Voyager Reference Guide 247 . TURNS keywords Keyword N T |IP| |N| Description List of nodes at which turning volumes are to be accumulated.3000. normally this phase is not used .6 Highway Program Theory Theory This section discusses the theory used in the Highway program. PHASE=ADJUST . If you use a basic template.. optional for user specified convergence tests .. revise special LW. they can be placed properly... skim paths. then only the actual operations of each segment need be completed. PHASE=LINKREAD . Example of suggested basic application template RUN PGM=HIGHWAY FILEI FILEO FUNCTION . Topics include: • • Process overview User stacks Process overview It is important to have a basic understanding of the logic of the program. TC.values for next iteration . extract custom information from the input network.. PHASE=ILOOP . ... ENDRUN 248 Cube Voyager Reference Guide . build paths. PHASE=CONVERGE .. include V.. and COST functions here PHASE=SETUP . Although you can place phases in the script in any order. load trips to paths .. insert any statements required to: . Citilabs suggests that you use a basic template for all applications. so that when certain special operations are to be performed. This phase is not specified by most users. Write requested MATOs. etc.Highway Program Theory 6 The internal logic of the program is as follows: • PHASE = SETUP Establish user SET arrays. Cube Voyager Reference Guide 249 .MAXITERS PHASE = ILOOP Loop I=1. process it. perform the statements of the block. EndLoop ENDPHASE • PHASE = ADJUST Loop LINKNO=1. then set the required values that LINKREAD did not set properly Set the Time and Cost values • EndLoop ENDPHASE • • LOOP ITERATION=1.NUMLINKS • • • Read each link record.ZONES • • • Read required MATIs.NUMLINKS • • Read each link record. Obtain link values using most of the LINKREAD process Apply the appropriate Functions (V. If there is a user supplied LINKREAD block. TC. If there is a PHASE=SETUP block. Process the ILOOP stack. COST) for the link. ENDPHASE • PHASE = LINKREAD Loop LINKNO=1. FILEO. It is suggested that all non-operational statements be placed at the beginning of the input for reader clarification. IF and LOOP blocks must be 250 Cube Voyager Reference Guide . Stack and phase are sometimes used interchangeably. as used here. and stack refers to the user supplied statement for that phase. Apply Function Cost. but all the others are optional. Each stack begins with a PROCESS PHASE = StackName statement. may be specified one time only.6 Highway Program Theory • Process the user’s ADJUST stack to either list the results of the assignment.) The operational statements that are to be preformed in this stack follow the PHASE statement. Process the CONVERGE stack (user or default) If Convergence met. • EndLoop. or Time for the next iteration. Non-operational statements (FILEI. means all the user supplied statements for the phase.values. or to revise LW. The ILOOP stack is required. Each of the phases. PARAMETERS. or the end of input. Iteration loop User stacks These are stacks of control statements that you provide to perform certain operations at various times in the process. but they are ignored during stack processing. Phase refers to a phase the program automatically processes. an ENDPHASE statement. Combine MATO matrices. the other stacks will not be necessary. (PHASE is a trigger key. The stack is terminated by the presence of another PHASE = stackname statement. Most times. so most users will just code PHASE= without the leading control word. exit ITERATION Loop. but it does provide a mechanism for altering program variable values at crucial times. Depending upon the values for COMBINE and ITERATION: • • Combine link volumes. The term stack. FUNCTION and others) can be within a stack. ENDPHASE • ENDLOOP . EXIT and ABORT will cause termination of a stack. Primarily.Highway Program Theory 6 complete within a stack.values can be adjusted with ILOOP statements. but will have impact on the actual program process only from ILOOP. ADJUST stack This stack is processed as the last operation in the ADJUST phase link loop.values for the next iteration. Most users will not have any need for this stack. If LW.values are dependent upon Time and/or Cost. and GOTO and associated label statements must be within the same stack. Alternatively. and it is necessary to reflect the changes in those values to the LW. Its primary purpose is to set BALANCE to 1 if certain conditions are met. LINKREAD stack This stack is in the LINKREAD phase. ILOOP stack This stack is the entire ILOOP phase. and is described previously. and is used as explained above in that section. It also provides the capability to print certain link values during the process. CONVERGE stack This stack is processed during convergence testing in the ADJUST phase. it is used to obtain required link values (if they are not directly available from the input network). and to set link LW. Cube Voyager Reference Guide 251 . the adjustment can be made here.values and GROUP codes. the LW. It provides a place for computing and accumulating special values such as objective functions (currently undocumented). It MUST be present. no LINKCLASS defined.6 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.net FILEI MATI[1] = TRIPS. */ RUN PGM=HIGHWAY FILEI NETI = Network. No TC functions defined therefore congested travel times computed using . the standard BPR formula for all links.0001 PROCESS PHASE = LINKREAD C = LI. assumes DISTANCE and SPEED are available on the input network . . load trips from input matrix to volume set 1 ENDPROCESS .mat FILEO NETO = LOADED.NET PARAMETERS COMBINE=EQUI MAXITERS = 99 GAP=.1.CAR. DISTANCE AND SPEED on the link attributes. No COST function defined therefore COST defaults to TIME ENDRUN 252 Cube Voyager Reference Guide . set capacity equal to a link field . build path based on time VOL[1]=MI. therefore defaults to 1 for all links ENDPROCESS PROCESS PHASE=ILOOP . . main loop for program PATHLOAD PATH=TIME.CAPACITY . . MO=1-2. */ RUN PGM=HIGHWAY FILEI NETI = LOADED. skim TIME and DISTANCE for the min TIME paths into work matrices 1 and 2 PATHLOAD PATH=TIME.DISTANCE) . building paths on a generalized cost function with the cost functions differentiated by the facility type (LINKCLASS). For intrazonals. Intrazonal time .NET FILEI MATI[1] = TRIPS.NAME= 'HWY Time'. ‘HWY Distance’ PROCESS PHASE=LINKREAD T0=li.PEN FILEO NETO = LOADED.Highway Program Examples 6 Highway example 2 /* EXAMPLE 2 Simple example of using HIGHWAY to ”SKIM” level of service information from the loaded highway network from Example 1. MW[2]=PATHTRACE(LI. Final congested travel times on the input network ENDPROCESS PROCESS PHASE=ILOOP .MAT. Loop across all origin zones and build path using congested time.MAT FILEI TURNPENI = TURNPEN. 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.TIME_1 .5 . 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.NET FILEO MATO[1] = HWY_SKIMS. MW[1]=PATHTRACE(TIME). . make the intrazonal time equal to half the time to the nearest zone COMP MW[1][I] = rowmin(1) * 0.NET Cube Voyager Reference Guide 253 . Turn penalties are included in the path building process and the PATH file is saved for graphical analysis */ RUN PGM=HIGHWAY FILEI NETI = NETWORK. 1.SET CAPACITY and LINKCLASS PROCESS PHASE=LINKREAD CAPACITY = LI.0 . VOL[2]=MI.0+0.CLASS = 1-4) LINKCLASS = 1 . cost function for major roads cost[2]=time*time_cost2+li. EXCLUDEGROUP=1.distance*distance_cost2} . PENI=1-2.7 distance_cost1 = 0. congested time function for major roads tc[2]=t0*(1.CLASS = 12) ADDTOGROUP=1 ENDPROCESS PROCESS PHASE=ILOOP PATHLOAD PATH=COST. ----. congested time function for minor roads cost[1]=time*time_cost1+li.6 Highway Program Examples FILEO PATHO[1] = HWY_PATHS. .5 time_cost2 = 0.4 .PTH . save path file ENDPROCESS PROCESS PHASE=ADJUST . exclude rail links PATHO=1 NAME=COST_PATH INCLUDECOSTS=T ALLJ=T .distance*distance_cost1 . load truck trips.CAR. .005 time_cost1 = 0. final turn delays and the binary junction data file */ RUN PGM=HIGHWAY 254 Cube Voyager Reference Guide . include turn penalties. set parameters and values for time and distance costs PARAMETERS COMBINE = EQUI GAP = 0. group railway links for exclusion from assignment IF (li. load car trips. set link classes for major roads IF (li.CLASS = 5-10) LINKCLASS = 2 .0+0.15*((v/c)^4)) .15*((v/c)^8)) .CAPACITY * 1. set link classes for minor roads IF (li.2 distance_cost2 = 0. . . Define cost and delay functions function { tc[1]=t0*(1.CLASS = 11 | li.TRUCKS. VOL[1]=MI.1. cost function for minor roads ENDPROCESS ENDRUN Highway example 4 /* EXAMPLE 4 This example script runs a junction constrained equilibrium assignment dumping the path file. */ RUN PGM=HIGHWAY NETI=DEMO. The subarea network is created with CUBE/VIPER POLYGON tools with the default renumbering of the network.WTH.NHB.Highway Program Examples 6 FILEI NETI = NETWORK.NET .NET FILEI MATI[1] = VEHICLETRIPS.1.15*((v/c)^8)) .MAT FILEI JUNCTIONI = JUNC_BASE. period=60.15*((v/c)^4)) .ALLJ=T.1.HTO.FUNC_CLASS = 1-2) LINKCLASS=1 IF (LI. 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.IND. ----.MAT FILEO NETO=Loaded_DEMO.NET FILEO SUBAREAMATO=submat1.set=1 FILEO NETO = LOADED. subarea network created with POLYGON tools in CUBE/VIPER FILEI SUBAREANETI=subarea1.0+0.FUNC_CLASS = 3-10) LINKCLASS=2 ENDPROCESS PROCESS PHASE=ILOOP PATHLOAD PATH = TIME. set convergence method and criteria PARAMETERS COMBINE = EQUI.TOTAL Cube Voyager Reference Guide 255 .SET CAPACITY and group links PROCESS PHASE=LINKREAD C = LI. GAP = 0.INT .NET FILEO PATHO[1] = ROADPATHS.net MATI=TRIPSBYPURPOSE. maxiters=99 PARAMETERS EQUITURNCOSTFAC=1 . VOL[1]=MI.OTH.DAT FILEO JUNCTIONO = TURNS.CAP IF (LI. NAME='assignment'. INCLUDECOSTS=T.mat NAME=HTW. PATHO=1.PTH FILEO TURNPENO = TURNDELAYS.005.PENI=1 ENDPROCESS PROCESS PHASE=ADJUST function { tc[1]=t0*(1. congested time function for major roads tc[2]=t0*(1.0+0. 1.0.1.0.VOL[2]=mi.VOL[3]=mi. SUBAREAMAT[1]=mi.VOL[4]=mi.05. In step 1 several examples of select link assignment are shown. extracts a subarea matrix for each trip purpose and the total trips PATHLOAD PATH=TIME.0. this PATHLOAD statement builds paths on TIME.6.1. SUBAREAMAT[5]=mi.05 .0.1.6 ENDPHASE PHASE=ADJUST . set volume to use in congested travel time functions ENDPHASE ENDRUN Highway example 6 /* EXAMPLE 6 This script has two steps.0.FRACTIONS=0.SUBAREAMAT[4]=mi.4.1. and the total trips to separate volume sets.1.VOL[1]=mi.1.5.1.1.NET NETO=DEMOSelectLink. or volume averaging by specifying COMBINE=AVE if desired PHASE=LINKREAD 256 Cube Voyager Reference Guide .CLASS C=LI.3.0001 PHASE=LINKREAD LINKCLASS=LI. SUBAREAMAT[3]=mi.4 dec=2. at each iteration the listed fraction of the trip table is assigned COMBINE=SUM.1.1. this is an example of an incremental assignment procedure ..SUBAREAMAT[2]=mi. Equilibrium assignment could be performed specifying COMBINE=EQUI .05.0.0 5.5. VOL[5]=mi.0.3.NET MATO = MATVOUT.1. Step 1 Select Link Assignment RUN PGM=HIGHWAY MATI=TRIPS. the number of fractions defines the number of iterations .1.05.0.SUBAREAMAT[6]=mi. In step two a MATRIX job is run to build trip end reports for the select link trip matrices created in step 1 */ .1.1.1. volume function V sets the volume to use for V/C in the delay function .2. combine=Y .0.6 Highway Program Examples PARAMETERS COMBINE=EQUI GAP=.1.4.1. assigns each trip purpose .1.0. formula is used for all link classes FUNCTION V=VOL[6] .MAT.1.0. No delay functions (TC[#]=) are specified here so the default BPR .mo=1-2.1.05. .2.MAT NETI=DEMO.VOL[6]=mi.0.CAPACITY ENDPHASE PHASE=ILOOP . selectlink = (L=1494-1423).6 to these paths and put them in Volume set 1 (V1_1 on the output network). put trips from mi. and lastly put the total trips assigned from mi. This is why you need the function V=vol[1]. vol[2] = mw[1] mw[2]=mi.1.VOL[3]=mi. 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.6.6 into working matrix 1 if they are on paths that use the selected links (L=). Note that V=vol[3] would give the same result as these two sets are the same. mw[4] = mi.6.6 /* this step says “build paths based on time. assign the trips in working matrix 4 (the select link trips) back to the time based paths and put them into Volume set 4 (V4_1 on the output network).6 to these paths and put them in Volume set 3 (V3_1 on the output network).6 into working matrix 2. The V function is automatically executed during the adjust phase. V is set to the sum of all volume sets which double counts volume when you have a select link volume set */ ENDPHASE ENDRUN . vol[4]=mw[4] /* this step says “build paths based on time.1.6 into working matrix 4 if they are on paths that use the selected links (L=).Highway Program Examples 6 LINKCLASS=LI. 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).CLASS C=LI. Step 2 Extract and report select link trip ends RUN PGM=MATRIX .1. assign trips from mi.1. assign trips from mi. selectlink = (L=1449-1495).1.1.1.1.1. Note that on the MATO line mo=4 will output the selected trip matrix (4) for the links L=. but only want to calculate congested travel times based on the true total volumes on each link. put trips from mi. note this example was for a 25 zone network Cube Voyager Reference Guide 257 .6. Now you have 4 volume sets. */ ENDPHASE PHASE=ADJUST function { V=vol[1] } /* this function sets the volume for the capacity restraint to be the total volume.CAPACITY ENDPHASE PHASE=ILOOP PATH=TIME.6.1. mw[1] = mi. Without this statement.VOL[1]=mi. LINKIDCNTMW=2 LINKIDLASTUSE=3 LINKIDMW=4-8 ENDPHASE ENDRUN 258 Cube Voyager Reference Guide . LIST=INDEX.USE=2. they by pass tolls ENDPHASE PHASE=ILOOP PATHLOAD PATH = LW. LINKIDARRAY=li.TIM).1.NET FILEO MATO[1] = test. MW[1] = PATHTRACE(LW. 2nd.TOLL.6 Highway Program Examples FILEI MATI=matvout.TIM. #2 is the number of toll gates traversed on the path. mo=1-8 PHASE=LINKREAD LW.FFS * 60 If (li.TOLL.0.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. #3 is the number of the last toll gate traversed on the path and #4-#8.ROW_TOT[INDEX].SUM_MAT[INDEX]. This network data field contains a value of 1-8 corresponding to one of the 8 toll bridges in the San Francisco Bay Area network.TIM=LI. */ RUN PGM=HIGHWAY FILEI NETI = SF_BAY_AREA. file =SelectTripEnds. don't use HOV facilities. The output work matrices include: #1 is the travel time on the I-J path.mat mw[1]=mi. include the 1st.25 PRINT FORM=10.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. 3rd and 4th gate number traversed on the path if used.mat. In this example. the LINKIDARRAY uses li. EXCLUDEGROUP=1.DISTANCE/LI. .3) ADDTOGROUP=1 . TIME. Cube Voyager Reference Guide 259 .NET" FILEO PATHO[1] = "TOLLPATH.00 ELSE LW.DAT" FILEO MATO[1] = "TOLLSKIM.FUNC_CLASS = 1-2) LW. ENTRYGATE=ON_RAMP. the paths are built on COST and the COST function will include any gate to gate tolls traversed on a path.15 LW. NETITOLLROAD=TOLLROAD FILEI NETI = "BASE.EXPO=4.99 NAME=PATHCOST.CAP IF (LI.EXPO=8. VOL[1]=MW[99].1+MI.PTH" FILEO JUNCTIONO = "JUNCTION1. NETIENTRY=ONRAMP. MO=1-5.VEHTOLLS. NETIEXIT=OFFRAMP.PEN" FILEI MATI[1] = "PKHOURTRIPS.MAT" FILEO TURNVOLO[1] = "TURNS.PATHTOLL. In this example. */ RUN PGM=HIGHWAY FILEI TOLLMATI[1] = "TOLL.1.COEF=0. EXITGATE=OFF_RAMP.LOADS PAR MAXITERS=20 TURNS N=1-9999 PROCESS PHASE=LINKREAD C = LI.2 .DBF". ----------------------------------------------------------.MAT".1.NET" FILEI TURNPENI = "PROHIBIT1.Highway Program Examples 6 Highway example 8 /* Example 8 Example of using TOLLMATI to incorporate closed system tolls into the pathbuilding process. Assign WITH TOLL COST CONSIDERED PATHLOAD PATH=COST. trips to load MW[99]=MI.COST_TRUCK.COEF=0.DBF".15 LW. TOLLS=COST_CAR. FORMAT=DBF FILEO NETO = "TOLLLOAD.COST. ----------------------------------------------------------.00 ENDIF ENDPROCESS PROCESS PHASE=ILOOP . 1). MW[4]=PATHTRACE(TIME.6 Highway Program Examples PENI=1 TOLLMATI=1. . MW[2]=PATHTRACE(COST. TOLLFACTOR=2.1). cross trips with tolls ENDPROCESS PROCESS PHASE=ADJUST function { tc=t0*(1. toll factor is in min/toll units.0+LW.EXPO)) . .COEF*((v/c)^LW. here 2min/$ (implies VOT=$30/hr) MW[1]=PATHCOST.1. NOACCESS=0.NOACCESS=0. NOACCESS=0. congested time function for major roads } ENDPHASE ENDRUN 260 Cube Voyager Reference Guide . MW[5]=mw[3]*mw[99] .0. MW[3]=PATHTOLL. Cube Voyager Reference Guide 7 Intersection Modeling This chapter discusses intersection modeling. part of the Cube Voyager Highway program. Topics include: • • • • • • • • Introduction to intersection modeling Control statements Common keywords Signal-controlled intersections Two-way stop-controlled intersections All-way-stop-controlled intersections Roundabouts Priority junctions Cube Voyager Reference Guide 261 . provided both models have been run to an adequate level of convergence. it can easily be observed that most of the delay arises from the conflicts between streams at intersections. we have stable comparable results. This form of model has a unique Wardrop equilibrium solution.7 Intersection Modeling Introduction to intersection modeling Introduction to intersection modeling This section provides an overview to intersection modeling. the Frank-Wolff algorithm (invoked by default in Cube Voyager) gives us a reasonably good solution algorithm. we can be sure that. Furthermore. in congested urban environments. if the policy responses being evaluated include traffic management 262 Cube Voyager Reference Guide . 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. However. Models with separable costs and monotonic nondecreasing cost functions have been very successful in modelling interurban travel. Thus later in the planning process. Furthermore. 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. They have been applied to most kinds of geographic region and most kinds of planning decision. when we wish to compare schemes. 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 we can achieve good convergence in reasonable time. changing the form of control at key intersections) it must be possible to represent the proposals in the model. intersection modelling tends to make the overall network model less stable. using the default method of combination. the flow pattern is passed to the intersection model.Intersection Modeling Introduction to intersection modeling 7 measures (for example. When the costs arising from a flow pattern are required. Consequently the assignment may take many more iterations to converge. you can change to using COMBINE=AVE to guarantee eventual convergence. Indeed. a bus counts 2. Data from a file of “Junction Descriptions” is read to determine the exact model form for each modelled node. If necessary. the model may never reach adequate levels of convergence. Cube Voyager intersection modelling and other programs This chapter describes only those junction description keywords that are directly relevant to Cube Voyager intersection modelling. Some of these extra keywords are used by Cube Voyager Reference Guide 263 . How the intersection models work Cube Voyager intersection modelling occurs during the ADJUST phase of a capacity restrained assignment. A PCU is similar to a vehicle but it is adjusted for vehicle length. A delay function is applied to calculate the average delay per vehicle for vehicles in the lane group. Trucks vary between 1. NOTE: A global minimum capacity of 1 vehicle (or PCU) per hour is now enforced. These calculated delays are then applied as turn penalties in the next path build.5 (tractor-trailer). However there are several other keywords permitted in an intersection description. Limitations of intersection modeling As noted above. Note that the capacity of a lane group will be reduced by any conflicting flows through the intersection. so a car counts 1. with each lane group having a capacity. The model will allocate the turning movements into lane groups.5 (light van) and 2. 264 Cube Voyager Reference Guide . Some of these extra keywords are used to preserve data that is required or used by Cube Dynasim.7 Intersection Modeling Introduction to intersection modeling Cube graphics to assist in editing and display of intersections. Comments. also following the usual Cube Voyager script syntax. This section describes: • • JUNCTION UNITS JUNCTION Each JUNCTION statement describes the control of some particular intersection in the network. and the remainder are JUNCTION statements. of which at most one is a UNITS statement. 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 × × × × × Cube Voyager Reference Guide 265 .Intersection Modeling Control statements 7 Control statements A junction file contains a sequence of statements. It follows the usual syntax for Cube Voyager script statements. 7 Intersection Modeling Control statements 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| × v × × × × × × |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 × × 266 Cube Voyager Reference Guide . UNITS Defines units of measurement for junction geometry.Intersection Modeling Control statements 7 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 LENGTH Cube Voyager Reference Guide 267 . MajorRoadWidth and CentralReservationWidth. ApproachWidth.7 Intersection Modeling Control statements This statement defines whether the lengths used to define junction geometry are measured in feet or meters. Example UNITS LENGTH=FEET UNITS LENGTH=METERS 268 Cube Voyager Reference Guide . Visibility. EntryRadius. If no UNITS statement is found. that have units of length are: AverageLaneWidth. FlareLength. measurements will be taken to be in meters. InscribedDiameter. EntryWidth. The keywords. Width. At most one UNITS statement may appear in a junction file. in the Junction statement. The value of the Length may be either “feet” or “meters” (case insensitive). The grouping of neighboring nodes into a single approach may be necessary. Approach. It describes how neighbors of the modeled node are grouped into approaches. StorageSpace. for example. Approach1. This sequence continues until the next occurrence of Node. CentralReservationWidth. Phase. 2. It has two functions within the junction description: 1.Intersection Modeling Common keywords 7 Common keywords This section describes common keywords. The value of the keyword is a list of node numbers of nodes adjacent to the node being modeled. FourLaneMajor. Type. MajorRoadWidth. CentralBusinessDistrict. or the end of the JUNCTION statement. It begins a sequence of keywords which describe the specified approach. LaneAdjust. because Cube Voyager can only model Cube Voyager Reference Guide 269 . 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. CycleTime. zone centroid connectors). this restriction may be overcome by modeling the circulating section explicitly). Every node. For example.7 Intersection Modeling Common keywords three. in the diagram below. which is a neighbor of the modeled node. a is a modeled node. Any grouping of links into legs must not invalidate the ordering. at roundabouts. Any valid approach which includes both nodes b and d must also include node c. must appear in exactly one Approach clause. or because the two lanes of a road are represented by individual links. 270 Cube Voyager Reference Guide . because some of the neighbors are fictional (for example. Cube Voyager requires that the legs of a junction can be assigned a clockwise ordering by using the coordinates of the nodes involved.or four-legged intersections (although. the first and third approaches are major and the second and fourth (if any) approach are minor.Intersection Modeling Common keywords 7 APPROACH1 Every junction description must contain exactly one occurrence of the integer-valued keyword APPROACH1. Node. the value of APPROACH1 determines which movements are available from each approach: LeftDrive = n First Approach Second Approach Third Approach Through Right Right Left Left Through LeftDrive = y Through Left Left Right Right Through At other modeled intersections. At two-way stop-controlled and priority (two-way yield-controlled) intersections. no intersection modeling will occur at the node). ENABLE Every junction description may contain at most one occurrence of the logical-valued keyword ENABLE. but if LEFTDRIVE = y is in force. the choice of APPROACH1 is arbitrary with no modeling consequences. By default. Cube Voyager will ignore the entire junction description (that is. At three-legged intersections. the approaches are numbered in anti-clockwise order. Its value is the node number of a node adjacent to the modeled node. If it has the value false. is taken to be the first approach and the other approaches are numbered in relation to it. Cube Voyager Reference Guide 271 . the approaches are numbered in clockwise order. The approach containing the specified node. to be used during the first PATHLOAD command to be executed. a value of 0. no volumes exist yet to use for junction-delay calculations. may be coded for the approach. No other keywords. This real valued keyword specifies the delays. Capitalizing as ExitOnly might improve readability. By default. in urban areas. An approach’s ESTIMATEDDELAY value is analogous to a link’s initial travel time. For any “approach. in minutes per vehicle.” EXITONLY=y indicates that the leg is not an approach. This occurs prior to the first Adjust phase. it is an exit only.7 Intersection Modeling Common keywords ENABLE is a quick way of turning modeling on and off at a particular node from within the junction file during model development. EXITONLY NOTE: Keywords are case-insensitive. so no calculated values will be available yet. except EXITLANES. Once an Adjust phase has been executed. Modeling can also be turned on and off in the Cube Voyager Highway script file using the N clause of the FILEI JUNCTIONI command. However. this user-specified value provides an initial estimate of the movement delay during path building.0 minutes is used. ESTIMATEDDELAY NOTE: Keywords are case insensitive. Capitalizing as EstimatedDelay might improve readability. this is a very poor estimate and it is very desirable that better values be supplied. 272 Cube Voyager Reference Guide . On the assignment’s first iteration. calculated values will replace these initial estimates. During the first iteration. a default value of one vehicle per hour is applied. Capitalizing as InitialQueue might improve readability. If the calculated capacity for any stream from an approach is less than the minimum capacity value for that approach.Intersection Modeling Common keywords 7 The coding of EXITONLY must agree with the network (that is. just path building for skimming). Note that the initial queue’s discharge rate is not a constant. INITIALQUEUE has no effect. INITIALQUEUE NOTE: Keywords are case insensitive. Consequently. the delay to the vehicles in the initial queue is not part of the results. Rather than being additional time added to the delay at the end of the process. MINIMUMCAPACITY The MINIMUMCAPACITY keyword takes a positive value in vehicles per hour as its argument. INITIALQUEUE is more like additional demand added to the assigned demand prior to junction calculations. It defaults to zero. 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. The results only include the delay that these initially queueing vehicles cause to the vehicles that arrive during 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). If no value is coded. the discharge rate depends on the junction’s conflicting flows. However. This substitution occurs before any delay calculations are started. Cube Voyager Reference Guide 273 . the minimum capacity will be used instead of the calculated value. if there is no assignment (that is. INITIALQUEUE is the queue at the start of the modeled period. It is coded by approach. the exit only approach must correspond to a set of one-way links leading away from the modeled intersection). Eventually. 274 Cube Voyager Reference Guide . In this circumstance.7 Intersection Modeling Common keywords The minimum capacity is most likely to apply when a movement is very lightly trafficked but is very heavily opposed. 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. Driver behavior: If conditions are very congested. Modeling expediency: If a minimum capacity of one vehicle per hour results in a predicted delay of the order of an hour. This is especially true when the opposing stream is a slow moving queue. trips will be diverted away from that turn during subsequent iterations. AVERAGELANEWIDTH. they will just force their way into a smaller gap. CAPACITYINTERCEPT. 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). The sequence continues until the next occurrence of APPROACHWIDTH. the delay for the lightly trafficked movement will be close to 60/MinimumCapacity (that is. 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. BUSBLOCKAGE. drivers will no longer wait for an appropriate gap in the opposing stream. 2. the default value leads to delays being estimated as an hour). Thus a positive feedback may occur between having low traffic on the turn and having high delay on the turn. 0.55 for signalized intersections and 1. ENTRYWIDTH. When coding gap-acceptance roundabouts.0 . Its value must satisfy the inequality 0. these two keywords should appear within each approach.RANDOMNESS) By default. MINIMUMCAPACITY. At geometrically modeled signals. These values are appropriate for isolated junctions (that is. MOVEMENT.Intersection Modeling Common keywords 7 CAPACITYSLOPE. FREEFLOWCAP. Its value is the node number of the junction to be modeled. RANDOMNESS values of 0. The lower value for signals reflects that even if arrivals at a signal are random. SINGLELANE. However. in urban areas where there are signal linkage effects.0 < RANDOMNESS <= 1. EXITONLY.2 are appropriate for signals in advanced traffic Cube Voyager Reference Guide 275 . TURNCHANNELIZED. the service times depend on whether the arrival was at a green signal aspect or a red one. GRADE. but if they are coded they must be coded by movement. NUMBEROFLANES. the platoon ratio is estimated as 2(1. arrivals are random). When coding two-way stop-controlled intersections. Care should be taken when coding CRITICALGAP and FOLLOWUPTIME which can occur as keywords at both the approach and movement levels. it will not usually be necessary to code CRITICALGAP or FOLLOWUPTIME. before any movements for that approach are described. ENTRYRADIUS. ENTRYANGLE. NODE Every junction description must contain exactly one occurrence of the integer-valued keyword NODE. INSCRIBEDDIAMETER. RANDOMNESS is 0.1 or 0. or the end of the approach. RANDOMNESS RANDOMNESS is a real-valued keyword which specifies how random the service times are with respect to the arrival times. FLARELENGTH. the appropriate RANDOMNESS values are reduced.0 for unsignalized intersections. RANDOMNESS. PARKINGMANEUVERS. 01. Offline signal plans are generally not completely up to date so they are usually more random than ATMS. for the relevant approaches.6 to 0.7 Intersection Modeling Common keywords management systems (for example. SCOOT. When Cube Voyager offers more than one methodology for modeling a particular kind of junction control.4. SCATS. Unsignalized intersections in this region should have RANDOMNESS values of the order 0. Its value should be taken from the following list: • • • • • • Roundabout Priority FixedTimeSignal Adaptive Signal TwoWayStop AllWayStop The keywords are case insensitive.8 are appropriate for unsignalized intersections in these areas. TYPE Every junction description must contain exactly one occurrence of the keyword TYPE. Note that the type field only distinguishes between different types of intersection on the ground. the capitalization in the list above is merely to improve readability. values of 0. Therefore. Consequently. code very low values of randomness. such as 0. 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.3 or 0. It determines the type of junction to be modeled. in areas where offline signal plans operate RANDOMNESS values for signals should be 0. OPAC) or in offline signal plans at the time that they are installed.3 or 0. other keywords will be used to distinguish between them: 276 Cube Voyager Reference Guide .4. The issues of “adaptive settings” (that is. However. If you code DELAYEQUATION=Catling you can force the use of Catling’s delay formulation at an HCM signals. This facility is invoked using TYPE=AdaptiveSignal. a delay equation formulated by Ian Catling is used. adaptive modeling is always recommended. When HCM capacity calculations are executed. Giving the keyword UnitExtension to a positive value for some approach invokes this model. Chapter 16. Cube Voyager can optimize the settings for the forecast flows. However.) The next level of modeling methodology chooses between calculating capacities using supplied saturation flows or calculating them using the methodology described in HCM 2000. even if the signal controller is fixed time. future or base year) and “actuated controllers” (that is.Intersection Modeling Common keywords 7 • 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. use TYPE=FixedTimeSignal to perform delay calculations for those settings. Note that the HCM methodology can model semi-actuated signal controllers. hardware in the field) are independent of each other. by default Cube Voyager also applies the HCM delay calculations. given a feasible signal setting and a set of constraints. Cube Voyager Reference Guide 277 . The HCM methodology is invoked using the keyword LANEADJUST. for all other models. Both methodologies may be invoked either using supplied settings or adaptive green time calculations. (Note that when forecasting future years. some traffic engineer will reset the signals every few years. When observed baseyear signal settings are available. 7 Intersection Modeling Common keywords Note that the type of control called a “priority junction” in the U.S.K. (where they are very common) would be called a “two-way yieldcontrolled intersection” in the U. 278 Cube Voyager Reference Guide . (where stop-controlled intersections are the norm). The detailed model also imposes more constraints on the allowed signal phasing than the saturation flow only model. green. 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.Intersection Modeling Signal-controlled intersections 7 Signal-controlled intersections This section describes signal controls. Cube Voyager offers two ways of modeling the capacity of signals.. The difference is primarily due to two factors: lost time while the signals are changing phase and pedestrian phases. Cube Voyager Reference Guide 279 .S. At any given time.. and there is a model which requires saturation flows to be estimated or measured externally. flashing amber. amber. 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. yellow. Note that effective green begins and ends later than actual green (due to reaction times).S. which has been calibrated to traffic conditions in the U.K. green. green.. red amber. red. vehicles making a particular movement through the intersection will see a particular signal aspect: • • In the U.K. which has been calibrated to traffic conditions in the U. red. In the U. Modelers reclassify the aspect into effective green (when the traffic can go) and effective red (when the traffic stops). There is a detailed model of junction geometry. Capitalizing as CanShareLeft might improve readability. no opposing flow is running) or permitted (that is.7 Intersection Modeling Signal-controlled intersections A left turn (right turn when LEFTDRIVE=T) which sees a green phase will either be protected (that is.” is not permitted in the U. (The LEFTDRIVE=T equivalent. allowing the right-turners to bypass the signal control. “left turn on red. Both methodologies can model both permitted and protected phases.S. the vehicles must give way to some oncoming traffic). Cube Voyager does not offer any model of “right turn on red” although this is allowed in many areas of the U. This keyword specifies that there is a shared lane to the left of the exclusive lanes for this movement (that is. 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. and omitting some lane(s) from the definition of the approach. Note that this keyword does not 280 Cube Voyager Reference Guide . the movement can share with the movement to its left).K.) This is best handled by introducing a dummy link into the network. If SINGLELANE = T then CANSHARELEFT should not be coded. CANSHARERIGHT NOTE: Keywords are case insensitive. 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. Capitalizing as CycleTime might improve readability. Cube Voyager Reference Guide 281 . then there must be a movement to this movement’s left and the movement to this movement’s left must have CANSHARERIGHT = T coded. This keyword specifies that there is a shared lane to the right of the exclusive lanes for this movement (that is. Note that this keyword does not mean “can share with right turners” unless either the movement is THROUGH or the movement is on the minor leg of a three-arm junction. Capitalizing as CanShareRight might improve readability. CYCLETIME NOTE: Keywords are case insensitive. This real-valued keyword is required for all signals. then there must be a movement to this movement’s right. If SINGLELANE = T then CANSHARERIGHT should not be coded. If a movement has CANSHARERIGHT = T coded. and the movement to this movement’s right must have CANSHARELEFT = T coded. the movement can share with the movement to its right).Intersection Modeling Signal-controlled intersections 7 mean “can share with left turners” unless either the movement is THROUGH or the movement is on the minor leg of a three-arm junction. If a movement has CANSHARELEFT = T coded. 282 Cube Voyager Reference Guide . PHASE must be followed by a single occurrence of the real-valued keyword ACTUALGREEN. 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. There should be one such pair for each phase of the signals during which vehicles move (that is. PHASE and ACTUALGREEN These keywords occur in pairs. If no constraints are placed on the cycle time at an adaptively modeled signal. Set LANEADJUST to Y at a signal to invoke the HCM2000 capacity calculations. Minimum = 60. the constraints will be deduced from the constraints on the individual green times. Maximimum=180. which are reserved for the exclusive use of vehicles making the specified movement. This integer-valued keyword gives the number of lanes. then EXCLUSIVELANES should not be coded. on the specified approach. Set LANEADJUST to N at a signal if you are supplying saturation flows. For example: Actual Cycle = 120. all-red and/or pedestrian phases should not be coded). Capitalizing as ExclusiveLanes might improve readability. LANEADJUST NOTE: Keywords are case insensitive. Capitalizing as LaneAdjust might improve readability. every occurrence of the integervalued keyword. If SINGLELANE = T.7 Intersection Modeling Signal-controlled intersections At actuated signals. EXCLUSIVELANES NOTE: Keywords are case insensitive. set green-time to zero). Capitalizing as SatFlowPerLane might improve readability. conceptually. If the signal is being modeled adaptively. then any two-digit phase specifications must specify contiguous phases. in seconds. of the effective green-time associated with the phase.Intersection Modeling Signal-controlled intersections 7 The values of the PHASE keyword should form a continuous sequence. two digits). Cube Voyager Reference Guide 283 . until the number of phases is reached. and the coded value of ACTUALGREEN is taken to be part of the example feasible solution. it consist of either one phase number (that is. then the keywords maximum (required) and minimum (optional) may be used to specify constraints. Cube Voyager may remove the phase altogether (that is. SATFLOWPERLANE NOTE: Keywords are case insensitive. At geometrically specified signals. digit) or of two phase numbers (that is. No such restriction is required when saturation flows are coded. The value of the ACTUALGREEN keyword is the duration. Every phase must be mentioned in a PHASE keyword for some movement at the intersection. without gaps. 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. Note that the (node-level) keyword PHASE is used to define phases and the (movement-level) keyword PHASES associates movements with the defined phases. If no minimum is applied. The vehicles making the movement see a green signal aspect when the specified phase(s) is/are running and red otherwise. PHASES The keyword PHASES is integer-valued but. starting at one and increasing. The effective green time is the period during which vehicles move across the stop line. except that no signal aspects are involved. 284 Cube Voyager Reference Guide . 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. Saturation flows at signals are the flows that would be observed if the movement had a continuous green all other movements had no flow and no green. Capitalizing as SingleLane might improve readability. 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. The logical-valued keyword is used to indicate that an approach consists of a single lane.7 Intersection Modeling Signal-controlled intersections This real-valued keyword allows the specification of saturation flows in pcu (vehicles) per hour per lane. SINGLELANE NOTE: Keywords are case-insensitive. or CANSHARELEFT on that approach. CANSHARERIGHT. Saturation flow at a priority junction (two-way yield-controlled intersection) is defined similarly. 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. If the value falls outside this range. of an approach to a geometrically modeled signalized junction. This real-valued keyword describes the mean lane width.8m.Intersection Modeling Signal-controlled intersections 7 At two-way stop-controlled intersections and priority junctions. Cube Voyager Reference Guide 285 . has two lanes. a minor arm that does not have SINGLELANE = Y explicitly coded. Capitalizing as AverageLaneWidth might improve readability.6m is used. the approach should be recoded to have more or fewer lanes. in meters or feet. a default of 3.4m to 4. 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. The average lane width must be in the range from 2. as appropriate. If no value is provided. the second refers to the other side of the road (for example. The flow of bicycles in from the curb-side lane in units of bicycles per hour. In the diagram. The CONFLICTINGBIKE is the flow of bicycles through this region. Capitalizing as ConflictingBike might improve readability. The diagram below illustrates the relevant bicycle flow for right hand rule of the road. The first element refers to the normal curb side of the road. Bicycle traffic which weaves with turning traffic in advance of the stop line should be excluded from this value. BUSBLOCKAGE NOTE: Keywords are case insensitive. if there is a tram line in the center of the road or there is a 286 Cube Voyager Reference Guide . because these bicycles do not interact with the other vehicles while they are still within the intersection. Capitalizing as BusBlockage might improve readability.7 Intersection Modeling Signal-controlled intersections CONFLICTINGBIKE NOTE: Keywords are case insensitive. The real values supplied to this keyword are number of buses stopping per hour. the crossed box is the bicycle conflict zone where right turning traffic may be impeded by any bicycles crossing the intersection. You can also use the abbreviation. CBD. The keyword accepts the values “HCM” or “Catling” (case-insensitive).Intersection Modeling Signal-controlled intersections 7 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. CENTRALBUSINESSDISTRICT is a logical-valued keyword which may be applied at geometrically-modeled fixed-time signals. Cube Voyager only uses this value for pedestrian and bicycle modeling. Coding CENTRALBUSINESSDISTRICT=Y causes all calculated capacities to be 90% of the value that would be obtained otherwise. NOTE: If exit lanes are omitted from an arm that pedestrians cross. 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. Capitalizing as CentralBusinessDistrict might improve readability. EXITLANES The number of lanes traveling away from the modeled intersection. the capacity of movements entering the arm may be reduced significantly. Cube Voyager Reference Guide 287 . The HCM delay equations are invoked. DELAYEQUATION Selects the delay modeling methodology applied to the capacities calculated by the HCM2000 signal capacity modeling methodology. By default. This keyword is only applicable at geometrically modeled signals. CENTRALBUSINESSDISTRICT NOTE: Keywords are case insensitive. 7 Intersection Modeling Signal-controlled intersections GRADE The real-valued keyword GRADE describes the grade. Only parking within 80 meters of the stop line should be included By default. negative values indicate that the approach is downhill and positive values indicate that the approach is uphill. Coding PARKINGMANUEVERS = 0 means that parking is allowed. if there is parking in a central reservation or on the offside of a one way street). PEDESTRIANPHASE The keyword PEDESTRIANPHASE is integer-valued but. PARKINGMANEUVERS NOTE: Keywords are case insensitive. It is a signed value. it consist of either one phase number (that is. parking is not allowed. but more extreme grades do occur. The first element refers to the normal curb side of the road. For example the maximum grade in San Francisco is about 31%. expressed as a percentage. In this respect. PEDESTRIANFLOW The number of pedestrians crossing the approach per hour. it is like 288 Cube Voyager Reference Guide . digit) or of two phase numbers (that is. The real values supplied to this keyword are number of maneuvers per hour. two digits). conceptually. By default the approach is assumed to be flat (GRADE = 0). Note that this is a two-way flow. the second refers to the other side of the road (that is. Capitalizing as ParkingManeuvers might improve readability. but it is extremely rare. This keyword is only applicable at geometrically modeled signals. of an approach to a geometrically modeled signals or a two-way stop-controlled intersection. The models have been calibrated for grades the range -6% to +11%. an icon of a man walking is displayed in green. the two phases must be adjacent. any two-digit phase specifications must specify contiguous phases. Note that the (node-level) keyword PHASE is used to define phases and the (movement-level) keyword PHASES associates movements with the defined phases. Cube Voyager Reference Guide 289 . Node = 276. two digits). If using a two-digit number. between successive vehicles moving on a traffic-actuated approach to a signalized intersection that will cause the signal controller to terminate the green display. one digit) or of two phase numbers (that is.Intersection Modeling Signal-controlled intersections 7 the keyword PHASES. At geometrically specified signals. laneadjust=t. Junction. 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.K. in seconds. PHASES The keyword PHASES is integer-valued but. No such restriction is required when coding saturation flows. conceptually. The vehicles making the movement see a green signal aspect when the specified phase(s) is/are running and red otherwise. the word WALK or an icon of a man walking is displayed in white whereas in the U. for example in the U. Type = FixedTimeSignal. UNITEXTENSION The minimum gap.S. 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. it consist of either one phase number (that is. 1. ExclusiveLanes = 1. ExclusiveLanes = 1. Movement = Left. Movement = Right. EstimatedDelay = 0. ExclusiveLanes = 1. AverageLaneWidth = 3. Movement = Left. Phases = 12. Phases = 3. EstimatedDelay = 0. Movement = Right. EstimatedDelay = 0. Phases = 32. Phases = 1. minimumcapacity=50. Approach = 291.1. EstimatedDelay = 0.6.3.6. AverageLaneWidth = 3. CycleTime = 90. ExclusiveLanes = 1. ActualGreen = 59. Movement = Through. Phase = 1.1. Phases = 3. Movement = Left. Approach = 264. ExclusiveLanes = 1. ActualGreen = 11. EstimatedDelay = 0. ActualGreen = 5. minimumcapacity=50.1. 290 Cube Voyager Reference Guide . Phases = 1. Phases = 1. minimumcapacity=50. Phase = 3. Phase = 2.6. Approach = 267. EstimatedDelay = 0. ExclusiveLanes = 1. AverageLaneWidth = 3.3. EstimatedDelay = 0.3.7 Intersection Modeling Signal-controlled intersections Approach1 = 291. Movement = Through. ExclusiveLanes = 1. Movement = Through. EstimatedDelay = 0. Phases = 3. AverageLaneWidth = 3. Movement = Through. Movement = Right.2. EstimatedDelay = 0. Phases = 32 Saturation flow signals example This example illustrates the coding of fixed-time signals: Junction.2. ExclusiveLanes = 1. CanShareLeft=y. ExclusiveLanes = 1. Type = FixedTimeSignal. Phases = 3. ExclusiveLanes = 1.1. Phase = 3. Approach = 291. Movement = Through.1.1. Phase = 1. ExclusiveLanes = 1. ActualGreen = 11.2. Phases = 1. Phases = 12. CanShareRight=y. ExclusiveLanes = 1. Movement = Left. Movement = Right.Intersection Modeling Signal-controlled intersections 7 EstimatedDelay = 0. ActualGreen = 5. EstimatedDelay = 0. Node = 276. EstimatedDelay = 0. Cube Voyager Reference Guide 291 . EstimatedDelay = 0. Approach1 = 291. ActualGreen = 59. Phase = 2. Phases = 1. Approach = 306. CycleTime = 90. Movement = Left.6. EstimatedDelay = 0.2. Movement = Through. 292 Cube Voyager Reference Guide .3. CanShareRight=y. Phases = 23.3. ExclusiveLanes = 1. ExclusiveLanes = 1. CanShareRight=y.3. Movement = Left. Movement = Right. EstimatedDelay = 0. Movement = Left. EstimatedDelay = 0. EstimatedDelay = 0.2. ExclusiveLanes = 1. Phases = 3.1. Phases = 3.2. ExclusiveLanes = 1. CanShareLeft=y. EstimatedDelay = 0. EstimatedDelay = 0. Phases = 1. Phases = 2. ExclusiveLanes = 1. EstimatedDelay = 0. EstimatedDelay = 0. Movement = Right. Approach = 306. EstimatedDelay = 0. Approach = 267. Movement = Through.1. Movement = Through.2. Phases = 1. CanShareLeft=y. Movement = Right. Movement = Left. Approach = 264. Phases = 3. Phases = 2. CanShareLeft=y.1. CanShareRight=y. Movement = Right. Phases = 1.2. EstimatedDelay = 0. EstimatedDelay = 0. Phases = 3.7 Intersection Modeling Signal-controlled intersections ExclusiveLanes = 1. ExclusiveLanes = 1. Intersection Modeling Signal-controlled intersections 7 ExclusiveLanes = 1. Phases = 23 Cube Voyager Reference Guide 293 . or approaches (at a crossroads) have “stop” signs. before entering the intersection. even if there is no major road traffic visible.7 Intersection Modeling Two-way stop-controlled intersections Two-way stop-controlled intersections This section describes two-way stop-controlled intersections. Traffic on the minor road must stop. There is a hierarchy of flows. in which lower rank flows must give way to all higher rank streams. illustrated below. The minor road approach (at a “T”). 294 Cube Voyager Reference Guide . Topics include: • • • Overview Keywords Example Overview This control is an unsignalized intersection between a major road and a minor road. which has been implemented in Cube Voyager. This situation is enabled when a non-zero value of storage space is coded. Keywords This section describes the keywords for two-way stop-controlled intersections: • • • • • • • • • • • CRITICALGAP FLARESTORAGE FOLLOWUPTIME FOURLANEMAJOR FREEFLOWCAP GRADE PEDESTRIANFLOW PEDESTRIANSPEED SINGLELANE STORAGESPACE TURNCHANNELIZED Cube Voyager Reference Guide 295 .Intersection Modeling Two-way stop-controlled intersections 7 The capacity model. 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. First the vehicle crosses to the central reservation. may do so in two stages. minor road traffic. between the lanes of the major road. is a gap-acceptance model that has been calibrated against traffic conditions in the USA. The value is the number of vehicles which can wait in the center of the major road without obstructing major road flows. which crosses the major road. or there are islands. then it completes its movement through the intersection. By default this value is zero. Capitalizing as CriticalGap might improve readability. At two-way stop-controlled intersections. Note that the coded value is the base critical gap. 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.1 6.2 6. is one of the parameters of any gapacceptance capacity model. It is modified to allow for junction geometry. Capitalizing as FollowUpTime might improve readability.5 Normally this value is allowed to default.1 6.7 Intersection Modeling Two-way stop-controlled intersections CRITICALGAP NOTE: Keywords are case insensitive.9 6.5 7. It is defined as the minimum time interval in a higher priority stream that allows intersection entry for one vehicle. FOLLOWUPTIME NOTE: Keywords are case insensitive. 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. that is.5 7. it is applicable by movement.1 Four-Lane Major Street 4. The critical gap. 296 Cube Voyager Reference Guide . in seconds. no or negligible flare. If FourLaneMajor = y is coded. 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. otherwise the major road has one lane in each direction (total 2). By default. FREEFLOWCAP NOTE: Keywords are case insensitive. It is the capacity for the unmodelled movements from the arm. then the major road has two lanes in each direction (total four). in seconds. Capitalizing as FreeFlowCap might improve readability.Intersection Modeling Two-way stop-controlled intersections 7 The follow-up time.3 4. only code when there are observations indicating site-specific driver behavior at the intersection FOURLANEMAJOR NOTE: Keywords are case insensitive.2 3.5 Normally this value is allowed to default. At two-way stop-controlled intersections. This value is only relevant for major approaches where FOURLANEMAJOR is false. Capitalizing as FourLaneMajor might improve readability. these movements have Cube Voyager Reference Guide 297 . under a condition of continuous queuing on the entry. It is defined as the time between the departure of one vehicle the next using the same gap in a higher priority stream. is one of the parameters of any gapacceptance capacity model. it is applicable by movement.0 3. This logical-valued keyword determines the number of lanes on the major road of a two-way stop-controlled intersection. especially to Equation 18-18 and the surrounding text. SINGLELANE NOTE: Keywords are case insensitive. of an approach to a geometrically modeled signals or a two-way stop-controlled intersection. PEDESTRIANSPEED The average speed at which pedestrians cross the approach in feet or meters per second. which. gives strange large capacities in the results.2 meters or. The models have been calibrated for grades the range -6% to +11%. equivalently. GRADE The real-valued keyword GRADE describes the grade. when combined with the capacity of the modelled turn. 298 Cube Voyager Reference Guide . It is a signed value. two or three abreast. Capitalizing as SingleLane might improve readability. but there will be a corresponding increase in delays. 4 feet per second. Pedestrians may cross the road singly.7 Intersection Modeling Two-way stop-controlled intersections infinite capacity. If you code a sensible value (such as 1800 vph). Each such group counts as one pedestrian platoon. negative values indicate that the approach is downhill and positive values indicate that the approach is uphill. For example the maximum grade in San Francisco is about 31%. By default this value is 1. By default the approach is assumed to be flat (GRADE = 0). but more extreme grades do occur. PEDESTRIANFLOW The number of pedestrian platoons crossing the approach per hour. For more details of pedestrian platoons refer to Chapter 18 of HCM 2000. expressed as a percentage. or they may cross in groups. the resulting capacity will be reduced. 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. a minor arm. or CANSHARELEFT on that approach. At two-way stop-controlled intersections and priority junctions. has two lanes. 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. Capitalizing as StorageSpace might improve readability. CANSHARERIGHT.Intersection Modeling Two-way stop-controlled intersections 7 The logical-valued keyword is used to indicate that an approach consists of a single lane. 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. Cube Voyager Reference Guide 299 . which does not have SINGLELANE = Y explicitly coded. STORAGESPACE NOTE: Keywords are case insensitive. Capitalizing as TurnChannelized might improve readability. 300 Cube Voyager Reference Guide .7 Intersection Modeling Two-way stop-controlled intersections This integer-valued keyword applies to two-way stop-controlled intersections. It does not matter whether the central reservation is curbed or striped (ghost islands). TURNCHANNELIZED NOTE: Keywords are case insensitive. It is the number of vehicles (PCU) that can wait in the central reservation without impeding major road traffic. when LEFTDRIVE = T. TurnChannelized = y. the right turn.Intersection Modeling Two-way stop-controlled intersections 7 The turn referred to is the turn which follows the curb (by default. Approach = 6. The turn is said to be channelized if there is a triangular. the left turn). Setting TURNCHANNELIZED to T for an approach indicates that the unopposed turn from that approach is channelized. Approach = 7. Cube Voyager Reference Guide 301 . StorageSpace = 3. Approach = 5. 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. Example The example describes a two-way-stop-controlled intersection with two-lane majors. By default. no turns are channelized. Junction Node = 9 Type = TwoWayStop Approach1 = 8. Approach = 8. FourLaneMajor = y. curbed island separating the turners from the other movements on the approach. two-lane minors and a central reservation. Example The following example describes an all-way-stop-controlled intersection between a one-lane road and a two-lane road. The capacities reported by models of undersaturated all-way-stopcontrolled intersections can appear very large.7 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. as the flows are increased. Valid values are 1. or 3. Cube Voyager offers a capacity model of all-way-stop-controlled intersections which has been calibrated against traffic conditions in the US. NOTE: Keywords are case insensitive. The model’s only variable is the number of lanes for each arm. However. Capitalizing as NumberOfLanes might improve readability. Junction Node Approach = 6 Approach = 7 Approach = 8 Approach = 5 = 9 Type = AllWayStop Approach1 = 8. All-way-stop-controlled intersection keyword Keyword NUMBEROFLANES |I| Description Number of lanes at an approach to an all-waystop-controlled intersection. NumberOfLanes = 2 302 Cube Voyager Reference Guide . the capacities will decrease. the model is very nonlinear and. 2. NumberOfLanes = 2. NumberOfLanes = 1. NumberOfLanes = 1. Topics include: • • • • • Overview of roundabouts Empirical roundabouts: Keywords Empirical roundabouts: Example Gap acceptance roundabouts: Keywords Gap-acceptance roundabouts: Example Overview of roundabouts Roundabouts are a form of unsignalized intersection in which traffic circulates around a one-way closed lane to travel from an approach to an exit. The 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 Cube Voyager Reference Guide 303 . The model builder. without compromising the modeling of the intersection. therefore. There are no constraints on traffic leaving the roundabout. Traffic on an approach must give way to traffic which is already on the circulating section. can always represent the circulating lane explicitly in the network. Individual roundabout models are placed at each entry. The circulating flow past an entry is the only flow which influences the capacity of that entry.Intersection Modeling Roundabouts 7 Roundabouts This section describes roundabouts. it should be used in preference to a gap acceptance model However. on the other. This technique is particularly useful for modeling roundabouts with five or more legs. on one hand. it may be necessary to fine tune the slope and intercept for local conditions • • 304 Cube Voyager Reference Guide . 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. the calibration of relationships between geometry. and slope and intercept. You can calculate the slope and intercept outside of Cube Voyager. 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.7 Intersection Modeling Roundabouts that approach are not significantly constrained. 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. -calibrated empirical roundabout model. one of the geometric parameters for the U. Cube Voyager Reference Guide 305 . Capitalizing as ApproachWidth might improve readability. 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.K. 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. This real-valued keyword allows the specification of the approach half width (in meters or feet).Intersection Modeling Roundabouts 7 • When no general countrywide empirical relationships exist. In the diagram below. 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.7 Intersection Modeling Roundabouts To measure the approach half width. Capitalizing as CapacityIntercept might improve readability. 306 Cube Voyager Reference Guide . 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. the capacity slope and the capacity intercept. The CAPACITYINTERCEPT keyword may be used to supply the capacity intercept directly. The capacity intercept is the entry capacity when the circulating flow is zero.Intersection Modeling Roundabouts 7 At an empirically modeled roundabout. the capacity slope and the capacity intercept. The capacity slope is the marginal decrease in Cube Voyager Reference Guide 307 . At an empirically modeled roundabout. each approach is characterized by two real numbers. 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. each approach is characterized by two real numbers. Capitalizing as CapacitySlope might improve readability. If CAPACITYINTERCEPT is coded for a roundabout entry. If CAPACITYSLOPE is coded for a roundabout entry. The CAPACITYSLOPE keyword may be used to supply the capacity slope directly. At roundabouts and single lane minor approaches to priority junctions. separate values should be supplied for each of the two lanes. Its value is the number of vehicles that may queue at the junction without impeding pedestrians who wish to cross. 308 Cube Voyager Reference Guide . a single integer value should be supplied. on two-lane minor approaches to priority junctions. 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.7 Intersection Modeling Roundabouts entry capacity when the circulating flow is increased by one PCU per hour. However. This real-valued keyword allows the entry angle. 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. Capitalizing as EntryAngle might improve readability. There are three cases for the measurement of phi.Intersection Modeling Roundabouts 7 CROSSING2EXIT This integer-valued keyword specifies the position of a zebra crossing on an exit from a roundabout or priority junction. Case 1: A roundabout with straight weaving sections • Let A be the point where the entry line meets the inside edge of the lane Cube Voyager Reference Guide 309 . theta. ENTRYANGLE NOTE: Keywords are case insensitive. Its value is the number of vehicles that may queue at the crossing without impeding vehicles using other exits from the junction. If it is absent then no crossing will be modeled. of a roundabout to be coded. the line AD is replaced by a curve A’D’ which is always parallel to the weaving section. However. Case 3: A roundabout with short weaving sections • EF and BC are constructed as in case 1 310 Cube Voyager Reference Guide .7 Intersection Modeling Roundabouts • • • • Let D be the point on the median island (or line) of the following entry which is nearest to A EF is curve which is in the middle of the area of road for vehicles entering the junction BC is a tangent to EF at the point where EF intersects the stop line phi is the angle between BC and AD Case 2: A roundabout with long curved weaving sections The construction for case 2 is nearly identical to that for case 1. Cube Voyager Reference Guide 311 . whichever is greater ENTRYRADIUS NOTE: Keywords are case insensitive. This real-valued keyword allows the specification of the entry radius (in meters or feet). 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 .K.Intersection Modeling Roundabouts 7 • • • • JK is constructed in the same way as EF. one of the geometric parameters for the U. The entry radius is defined as the minimum radius of curvature of the curb line at the entry.-calibrated empirical roundabout model. Capitalizing as EntryRadius might improve readability.½(angle GLB)). K. one of the geometric parameters for the U. the double arrow marked “C” and “EWID” illustrates the measurement.calibrated empirical roundabout mode. This real-valued keyword allows the specification of the entry width (in meters or feet). 312 Cube Voyager Reference Guide .7 Intersection Modeling Roundabouts ENTRYWIDTH NOTE: Keywords are case insensitive. To measure the entry width: • • • Let A be the point where the stop-line meets the inside edge of the lane Let B be a point on the curb-line such that the line A-B is normal to the curb at B The entry width is the length of the line A-B In the diagram below. Capitalizing as EntryWidth might improve readability. (G is the point where the curve meets the curb). This is measured using the following procedure: • • • • • Let A be the point where the stop line meets the inside edge of the lane. Let D-G be a curve through D and parallel to the inside edge of the lane. Let D be a point on A-b such that the length of A-D is v. 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. e). 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.Intersection Modeling Roundabouts 7 FLARELENGTH NOTE: Keywords are case insensitive. Let v be the approach width. Cube Voyager Reference Guide 313 . Let C be the mid point of D-B. This real-valued keyword allows the specification of the inscribed circle diameter of the roundabout (in meters or feet). 314 Cube Voyager Reference Guide . Usually this is the largest circle that can be inscribed wholly within the outline of the junction (see figure below). Empirical roundabouts: Example The following example uses geometrical data to calculate slopes and intercepts: Junction. a local value in the region of the entry should be taken. Capitalizing as InscribedDiameter might improve readability. INSCRIBEDDIAMETER NOTE: Keywords are case insensitive.7 Intersection Modeling Roundabouts • • Let C-F’ be a curve parallel to the curb which intersects the curve D-G at F’. The modified flare length is the length of the curve C-F’. However. when the intersection is very asymmetrical. 0. FlareLength = 15.5. EntryWidth = 10.0.0. Approach = 321. InscribedDiameter = 25. Node = 213. EntryWidth = 12.0.0. EntryWidth = 10. CapacitySlope = 0. Cube Voyager Reference Guide 315 .Intersection Modeling Roundabouts 7 Node = 213.0.0. it was decided to recode approach 224 to give the slope and intercept directly: Junction. InscribedDiameter = 25. ApproachWidth = 6. FlareLength = 25. InscribedDiameter = 25. Approach = 223. Type = Roundabout. InscribedDiameter = 25.2.0.0. Type = Roundabout.0.0. InscribedDiameter = 25. After comparing the model results to the performance of the intersection on the ground.0. ApproachWidth = 6. CapacityIntercept = 3600.0. EntryWidth = 10. ApproachWidth = 6. Approach = 224.3. FlareLength = 15. EntryWidth = 10.0. Approach1 = 223. Approach = 321. Approach = 224. FlareLength = 15. Approach1 = 223. Approach = 223. ApproachWidth = 6. ApproachWidth = 7.0. FlareLength = 15.0.0.0. the follow-up time should be in the range 2. The U. for a singlelane roundabout entry in the America. The follow-up time.S.1 to 4. is one of the parameters of any gapacceptance capacity model.6 to 3. 316 Cube Voyager Reference Guide . under a condition of continuous queuing on the entry. for a singlelane roundabout entry in the US. is one of the parameters of any gapacceptance capacity model. 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.1 seconds. it is applicable by arm. the critical gap should be in the range 4.6 seconds. Highway Capacity Manual 2000 suggests that. Capitalizing as FollowUpTime might improve readability. It is defined as the minimum time interval in the circulating stream that allows intersection entry for one vehicle.7 Intersection Modeling Roundabouts Gap acceptance roundabouts: Keywords This section describes the keywords to model gap-acceptance roundabouts: • • CRITICALGAP FOLLOWUPTIME CRITICALGAP Keywords are case-insensitive but the recommended capitalization CriticalGap may improve readability. in seconds.S. The U. The critical gap. FOLLOWUPTIME NOTE: Keywords are case insensitive. Highway Capacity Manual 2000 suggests that. At roundabouts. it is applicable by arm. in seconds. At roundabouts. Intersection Modeling Roundabouts 7 Gap-acceptance roundabouts: Example The following illustrates a gap-acceptance roundabout model: Junction. FollowUpTime = 3. Approach1 = 32. Approach = 32. Type = Roundabout. FollowUpTime = 2. CriticalGap = 4.1. CriticalGap = 4. Approach = 256.6 Cube Voyager Reference Guide 317 .35. 208. CriticalGap = 4. Approach = 486. Node = 253.1. FollowUpTime = 2.6.85. the minor road approach (at a “T”).K. both of which are calibrated to U. 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. This occurs when a movement.S. It has different names in the U. shares a lane. 318 Cube Voyager Reference Guide . In the U. but must give way to any major road traffic.K.. Traffic on the minor need not stop before entering the intersection. the yield signs are optional. When a single-lane major road is being modeled. In the U. (where “twoway yield-controlled intersections” are rare). or approaches (at a crossroads) have “yield” signs. which is unconstrained. (where “priority junctions” are common) and the U. 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..K. Cube Voyager offers two model variants.S.7 Intersection Modeling Priority junctions Priority junctions This section describes priority junctions (two-way yield-controlled intersections). The capacity is chosen to give the correct ratio of volume to capacity (as calculated for the constrained movement). very large capacities may be reported. The default. invokes modeling of layout geometry at a priority junction. Capitalizing as SingleLane might improve readability. 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 Cube Voyager Reference Guide 319 . 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. at a priority junction is for the user to supply saturation flows directly. SINGLELANE NOTE: Keywords are case insensitive.Intersection Modeling Priority junctions 7 Keywords This section describes keywords for priority junctions: • • GEOMETRIC SINGLELANE GEOMETRIC The keyword “Geometric=y”. The logical-valued keyword is used to indicate that an approach consists of a single lane. “GapAcceptance=n”. a minor arm. CENTRALRESERVATIONWIDTH is a real-valued keyword (only) applicable to geometrically modeled priority junctions. At two-way stop-controlled intersections and priority junctions.2 to 5. If there is no central reservation. which does not have SINGLELANE = Y explicitly coded. road markings). has two lanes. of the curbed central reservation in the major road. or CANSHARELEFT on that approach. 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. Its value is the width.7 Intersection Modeling Priority junctions Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES. in meters or feet. Capitalizing as CentralReservationWidth might improve readability. then CENTRALRESERVATIONWIDTH should be zero (the default). or the central reservation is composed of ghost islands (that is. Otherwise its value should be in the range from 2. CANSHARERIGHT. 320 Cube Voyager Reference Guide . separate values should be supplied for each of the two lanes. Its value is the number of vehicles that may queue at the crossing without impeding vehicles using other exits from the junction. a single integer value should be supplied. CROSSING2EXIT This integer-valued keyword specifies the position of a zebra crossing on an exit from a roundabout or priority junction. CROSSING2ENTRY This keyword specifies the position of a zebra crossing on an approach to a roundabout or a minor approach priority junction. However. Its value is the number of vehicles that may queue at the junction without impeding pedestrians who wish to cross. Capitalizing as FreeFlowCap might improve readability. the CENTRALRESERVATIONWIDTH is given by ½(W5 + W6).Intersection Modeling Priority junctions 7 In the diagram below. CROSSINGLENGTH This real-valued keyword allows the specification of the length of a zebra crossing that crosses an approach to a roundabout or priority junction. on two-lane minor approaches to priority junctions. FREEFLOWCAP NOTE: Keywords are case insensitive. At roundabouts and single lane minor approaches to priority junctions. If it is absent then no crossing will be modeled. Cube Voyager Reference Guide 321 . In each case the major road width is given by the expression ½(W1 + W2 + W3 + W4). MAJORROADWIDTH is a real valued keyword whose value is the width. where it is required. in meters or feet.7 Intersection Modeling Priority junctions By default. Capitalizing as MajorRoadWidth might improve readability. the unmodelled movements from the major approaches of a priority junction have infinite capacity. It is illustrated in the four diagrams below. this may result in too large a capacity for the approach as a whole when it must share a lane with a modelled turn. However. You can supply a capacity for these movements by coding FreeFlowCap=value and SingleLane=t. The presence or absence of this keyword allows the two methodologies for priority junction modeling to be distinguished. MAJORROADWIDTH NOTE: Keywords are case insensitive. 322 Cube Voyager Reference Guide . MAJORROADWIDTH is only applicable to geometrically modeled priority junctions. of the major road lane (excluding any central reservation or ghost islands) near the intersection. Visibilities may be coded for the minor road left and right movements and for the opposed movement from the major road. in meters or feet. towards the road center line. at a geometrically coded priority junction (two-way yield-controlled intersection) to be entered.05 meters above the road surface. Cube Voyager Reference Guide 323 . The major road visibility is measured from the mid-point of the turning lane (again at height 1. along the major road.Intersection Modeling Priority junctions 7 VISIBILITY This real-valued keyword allows the visibilities. Minor road visibilities should be measured from a point ten meters before the give-way line and 1.05m). 7 Intersection Modeling Priority junctions WIDTH This real-valued keyword is used to specify the lane widths (in meters or feet) for a minor road at a priority junction (two-way yield-controlled intersection). 324 Cube Voyager Reference Guide . To describe a two-lane minor road: • • • Do not code SINGLELANE = T. Code widths for left and right movements on minor roads and for the opposed movement from the major road. Approach1 = 455.2. but not both. Node = 250. Coding techniques for minor roads vary with the number of lanes. or the right movement. The coded widths should be the lane’s average width during the final 25 meters of the approach before the give-way line. Code the width of the single lane in the left movement. The width for the major road’s opposed movement is the width of the lane from which vehicles on the major road turn. Code the width of the right-hand lane in the right movement. with input geometric data. Junction. To describe a one-lane minor road: • • Code SINGLELANE = T. Code the width of the left-hand lane in the left movement.9. Type = Priority.5. Geometric priority junctions: Example This example illustrates the coding of a three-arm priority junction. CentralReservation = 1. Movement = Right. Width = 2. Approach = 455. MajorRoadWidth = 10. SingleLane = y.Intersection Modeling Priority junctions 7 Visibility = 170.1. Capitalizing as CanShareLeft might improve readability.0. Approach = 251. This keyword specifies that there is a shared lane to the left of the exclusive lanes for this movement (that is.0. Movement = Right. Visibility = 100. Visibility = 130.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. Note that this keyword does not Cube Voyager Reference Guide 325 . Movement = Right. Approach = 255.0. Width = 2. Movement = Right. Movement = Left.9.05. Visibility = 127. Width = 3. Approach = 249. Width = 2. Visibility = 150.05. Visibility = 125. Width = 2.0.0. Movement = Left. the movement can share with the movement to its left). 326 Cube Voyager Reference Guide . then there must be a movement to this movement’s right. This integer-valued keyword gives the number of lanes. If SINGLELANE = T then CANSHARERIGHT should not be coded. If SINGLELANE = T then CANSHARELEFT should not be coded. Capitalizing as ExclusiveLanes might improve readability. CANSHARERIGHT NOTE: Keywords are case insensitive. If SingleLane = t then ExclusiveLanes should not be coded. 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). If a movement has CANSHARERIGHT = T coded. 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. EXCLUSIVELANES NOTE: Keywords are case insensitive. If a movement has CANSHARELEFT = T coded then there must be a movement to this movement’s left and the movement to this movement’s left must have CANSHARERIGHT = T coded. on the specified approach.7 Intersection Modeling Priority junctions mean “can share with left turners” unless either the movement is THROUGH or the movement is on the minor leg of a three-arm junction. and the movement to this movement’s right must have CANSHARELEFT = T coded. Capitalizing as CanShareRight might improve readability. which are reserved for the exclusive use of vehicles making the specified movement. Cube Voyager Reference Guide 327 . Movement = Left. CanShareLeft = y. Approach1 = 396. CanShareRight = y. Saturation flow at a priority junction (two-way yield-controlled intersection) is defined similarly. Movement = Right.Intersection Modeling Priority junctions 7 SATFLOWPERLANE NOTE: Keywords are case insensitive. Node = 229. ExclusiveLanes = 1. CanShareRight = y. except that no signal aspects are involved. CanShareLeft = y. Saturation flows at signals are the flows that would be observed if the movement had a continuous green all other movements had no flow and no green. Movement = Left. ExclusiveLanes = 1. This real-valued keyword allows the specification of saturation flows in pcu (vehicles) per hour per lane. Movement = Through. ExclusiveLanes = 1. ExclusiveLanes = 1. CanShareLeft = y. Approach = 396. Approach = 228. Movement = Through. Capitalizing as SatFlowPerLane might improve readability. ExclusiveLanes = 1. Junction. Type = Priority. CanShareRight = y. 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. CanShareRight = y. CanShareLeft = y. Approach = 315. CanShareRight = y. CanShareRight = y. ExclusiveLanes = 1. Movement = Through. Movement = Left.7 Intersection Modeling Priority junctions CanShareRight = y. Movement = Left. CanShareRight = y. ExclusiveLanes = 1. ExclusiveLanes = 1. Movement = Through. Movement = Right. Movement = Right. CanShareLeft = y 328 Cube Voyager Reference Guide . ExclusiveLanes = 1. Approach = 409. CanShareLeft = y. CanShareLeft = y. CanShareLeft = y. Movement = Right. ExclusiveLanes = 1. Topics include: • • • • Introduction to the Network program Control statements Theory Examples Cube Voyager Reference Guide 329 .Cube Voyager Reference Guide 8 Network Program This chapter discusses the Network program. (Note: Cube Voyager treats a FSUTMS network as a standard Tranplan network. In v3. and then use that file in place of the original file for subsequent processing. In v4.x and earlier. A data record is generated for each unique node and each link that is found in all the input files. and its data can be summarized and reported in various manners. Tranplan.8 Network Program Introduction to the Network program Introduction to the Network program Network is a utility program for processing highway networks. or TRIPS binary network format. node and link records in a given data file had to be unique.2. If a Tranplan network is detected as input.0. Only Cube deals with FSUTMS networks differently.0.0. the program will immediately write it in a Cube Voyager format onto a temporary file. TP+.) 330 Cube Voyager Reference Guide . Cube expects these coordinate variables to be named X and Y. 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 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. This limitation has been lifted starting with v4. The input network files can be of various formats: ASCII records. MINUTP. 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. No auxiliary files will be open. or any Cube Voyager. and one output network can be generated. Beginning with version 5. input highway networks may be a Cube geodatabase network. standard database in dBASE style (DBF). Up to ten input networks can be processed simultaneously. Each of these records can be processed through user controlled logic. 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. 0. 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. In a Cube Voyager or TP+ network. Optionally. In MINUTP networks. output networks may be a Cube Voyager custom network feature class. a file is written in a proprietary (Cube Voyager or MINUTP) binary format. there may be any number of items for nodes. a file of link records and/or a file of node records may be written in either ASCII or DBF format. Subsequent topics discuss: • • Built-in variables Built-in functions Cube Voyager Reference Guide 331 . stored in an ESRI custom geodatabase. the node information consists solely of coordinates for each node. node records. Beginning with version 5.Network Program Introduction to the Network program 8 If an output network is specified. It is a network database that contains speed/capacity information. and link records. These ten networks can be any of the supported binary formats. the value is taken from the first available value from all the input networks. Cube geodatabase networks. When specifying an output network to a Cube geodatabase network. for example). downtown use LINKI[3]. records that are merged from other LINKIs retain their GEOMETRYSOURCE value. Other input formats could also have a field called GEOMETRYSOURCE defined by the user. the output GEOMETRYSOURCE field will have a value of 2 (unless there is no record in LINKI[2] for a certain link). 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 332 Cube Voyager Reference Guide . Each input network coming from a geodatabase network will have a field called GEOMETRYSOURCE. you can specifically set the value in a script based on other attributes in the various input networks (for example. The Network program may take up to ten input networks. By default. or MDB formats. and other areas use LINKI[2]). In addition. DBF. If Merge Record=T. Therefore. This field’s value is the index of the input file (3 for LINKI[3]. the output network could have a mix of GEOMETRYSOURCE values. So if LINKI[1] is a binary network without a GEOMETRYSOURCE field and LINKI[2] is a geodatabase network.8 Network Program Introduction to the Network program Built-in variables Variable A B GEOMETRYSOURCE Description Node number of a link’s A node Node number of a link’s B node Defines the input file index number that controls the source of the geometry to be applied to the output NETO file when multiple input networks are specified. GEOMETRYSOURCE specifies which # from the FILEI LINKI[#]= specifications provides the geometry to be applied to the output geodatabase network. or combinations of link and node files in ASCII. The value of the GEOMETRYSOURCE field in the output network dictates the source of the link geometry. capclass) Description Returns the speed from the SPEED table for the designated number of lanes and spdclass.Network Program Introduction to the Network program 8 Built-in functions Function SPEEDFOR(lanes. Returns the capacity times the lanes for the designated number of lanes and capclass. Cube Voyager Reference Guide 333 .spdclass) CAPACITYFOR(lanes. Control word ABORT ARRAY BREAK COMP COMPARE CONTINUE CROSSTAB DELETE EXIT FILEI FILEO IF .... ENDLOOP MERGE PARAMETERS PLOT PLOTTER PRINT PROCESS ... ELSE ..8 Network Program Control statements Control statements This section describes the control words available in the Network program. “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 334 Cube Voyager Reference Guide ..... 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. ELSEIF . ENDIF LOOKUP LOOP . the most Cube Voyager Reference Guide 335 . Values stored in arrays must be numeric. When an array is referenced. Arrays cannot store string values. Use this statement if you can determine from the data that you desire no further processing. Arrays can be useful for different processes. MSG Use ABORT to quit the Network program at with a “fatal” return code. VAR=size Use ARRAY to allocate user arrays that are to be used in the process. ABORT keyword Keyword MSG |S| Description Optional message to be printed along with the ABORT message. and if the index exceeds the size.Network Program Control statements 8 ABORT Aborts the Network program and Cube Voyager. An array is different than a variable in that it represents vectored data. VAR=size. the program may fatally terminate. it should include an index []. Example IF (a > 1000) ABORT MSG='Must be the wrong Network' ARRAY Declares user single dimension arrays. VAR must be a unique name. VMT=LINKS . BREAK would be used in conjunction with an IF statement. Most likely. NODES and LINKS should not be used if links are to be added to the network. BN=LINKS. NETI must be a binary network BREAK Breaks out of stack processing for current data record. if (a. bypass the links that go from right to left BREAK endif 336 Cube Voyager Reference Guide .8 Network Program Control statements common use may be to store information for specific zones.x > b. and the operation is BREAK. Arrays are cleared when they are allocated. Example ARRAY abc=100. and LINKS if there is a binary input network. or a special name. Example 1 if (a=1-500 || b=1-500) BREAK . do not process centroid links. if BREAK is encountered within a LOOP. When a data record is being subjected to the operations in a phase block. xyz=100 ARRAY AN=LINKS. Special names are: ZONES. However. stack processing jumps to the statement after the associated ENDLOOP statement. the remainder of the block operations are bypassed and the next data record is processed. NODES. they are allocated prior to any stack operations. ARRAY statements are not dynamic (stack oriented).x) . The size following the keyword is the highest index possible for VAR. ARRAY variable Variable VAR |I| Description VAR is the name of the variable that is to be allocated according to the specified size. Size may be either a numeric constant. or misuse of variable modes. The program tries to detect any possible changes. If a variable is misused as to mode. The phase for which this COMP statement is coded will establish which variables may be included within the expression. If the expression results in a string. but it might not detect all inconsistencies.index . Cube Voyager Reference Guide 337 . A normal numerical expression is required._zones _total = _total + array1[index] if (_total>1000) BREAK endloop list=’INDEX =’. and where the results can be stored. 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. The statement need not begin with COMP. but there must be comma between an expression and the next variable=expression. The expression will be solved and the results stored in the named variable. There may be more than one variable computed on a statement. A variable’s mode should be consistent throughout the application. unless it is a working variable (begins with an underscore).Network Program Control statements 8 Example 2 /* this example finds the index where subtotal of ARRAY1 exceeds 1000 */ loop index=1. The maximum length of the name is 15 characters. any name that appears on the left side of the equals sign will be placed into the output network record. During any phase other than the SUMMARY. the mode of the target (named) variable will be set to string instead of numeric. This limit includes the “_” prefix of temporary variables. x-b. Example i = 0 j = a / i. if the second argument is less than 1.x)^2 + (a. If the lanes value is less than 1.y-b. Similarly. In the SPEEDFOR and CAPACITYFOR functions. or greater than 99.capclass) Description Returns the speed from the SPEED table for the designated number of lanes and spdclass. lanes would be reset to 9.y)^2) _LinkSpeed = SPEEDFOR(Lanes. or greater than 9. k=j*2+3*i newb = nodecode(b) sumab = newb+newa cdist = sqrt((a. the internal value will be reset to the appropriate limit. The expression may contain function names with their arguments. the function value of lanes will be reset accordingly.8 Network Program Control statements unpredictable results could occur. RECORD (LIST TITLE) 338 Cube Voyager Reference Guide . such as always beginning with the same letter. and the capacity extracted for that value would be multiplied by 9. Returns the capacity times the lanes for the designated number of lanes and capclass. They are coded as: Function SPEEDFOR(lanes.spdclass) CAPACITYFOR(lanes... It might be prudent to have a standard naming convention for string variables. the SPEEDFOR and CAPACITYFOR functions are utilized. the first argument is the number of lanes and the second argument is the class.) were specified. if CAPACITYFOR (88.Facility*10+Area) COMPARE Compares network records. Thus. To obtain speed and/or capacity values from the SPDCAP tables. COMPARE also returns a value indicating the result after the comparison of each record. if the record keys match. It is suggested that the value be embedded within quotes. the MERGE RECORD=T statement should be coded.Network Program Control statements 8 COMPARE statements are dynamic and are used to compare the records of either the link or node portion of two networks. Indicates how many of the links with differences are to be listed to the print file. a summary of the comparison is reported. But. then only the first 100 links with differences will be listed. If LIST=100. Record not in file one. The value is stored in a temporary variable: _COMPARE. LIST |I| Cube Voyager Reference Guide 339 . 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. There may be multiple COMPARE statements in a single application. The meaning of the returned value is as follows: Value of _COMPARE n 0 -1 -2 Meaning n attributes are different between two records. The default is 0. No differences between two records. At the end of the phase (NODEMERGE or LINKMERGE). Record not in file two. To make this statement function properly. must be coded. COMPARE keywords Keyword RECORD |IP| Description Indicates which LINKI or NODEI set of records is to be compared. a single line is generated. This keyword may occur only one time on a COMPARE statement. In addition to a summary report. If a link exists in one file but not in the other. Two numbers. The LIST parameter controls the listing of individual differences. separated by a dash. --7 -.-.--.-.321 1 1 -1 DISTANCE -. 340 Cube Voyager Reference Guide . Example 2 RUN PGM=NETWORK NETI=NET1. The CMPFLAG attribute can be used in selection expressions in Viper to post the comparison results.321 ------.23 1.--. using only records where there is a difference.-.--.23 -- The 1=2 column lists the number of records where the records are the same.-.321 1 1 -1 SPDCLASS -. 2: 1=2 ------.-.-.-. link in both but different ENDRUN Example 2 illustrates how to use _COMPARE to flag the links in the merged network.-.--. The final AVE column lists the average difference for the variable. LIST=20 . compare link record 1 with 2 IF (_COMPARE=-2) CMPFLAG=1 .321 2 2 -2 CAPCLASS -. not in NET1 IF (_COMPARE>0) CMPFLAG=3 .-.8 Network Program Control statements Example 1 LINKI[1] = current.-7 -. and the 1 > 2 set lists the summary where file 1 values are greater than file 2.--------A 321 ----B 321 ----LANES -.23 -1. not in NET2 IF (_COMPARE=-1) CMPFLAG=2 .1 > 2 ---Cnt Min Max Ave --.--.23 NAME -.-.321 1. NET2.--.-. The Min and Max differences show the range of differences for the variable. link in NET1.NET. 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.NET MERGE RECORD=T PHASE=LINKMERGE COMPARE RECORD=1-2.--.-.-- Ave -----1 -1 -2 -1.net COMPARE RECORD=1-2 The following is a sample output in the print file: COMPARE 1 vs. link in NET2.NET NETO=NET3.net LINKI[2] = future.--.1 < 2 ------Variable Cnt Cnt Min Max Ave -------. bypassing all stack statements until the associated end of loop.Network Program Control statements 8 CONTINUE Immediately jumps to the end of a loop. no more processing for this data record LOOP _L2=_K1. control passes to the appropriate ENDLOOP statement. stack processing for the record is terminated. Use the COMP keyword to generate additional reports after network generation using the values from the Cube Voyager Reference Guide 341 .3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE . Use the VAR keyword to specify the variables you want tabulated. the statement tabulates all the variables to the same specifications._K2. Although the CROSSTAB statement can include several instances of the VAR keyword._L2+5 IF (condition) CONTINUE . Use the ROW keyword along with the RANGE subkeyword and the COL keyword along with the RANGE subkeyword to specify the table’s dimensions. the report collapses into only one column or one row. VAR (FORM) ROW (RANGE) COL (RANGE) COMP (FORM) Use the CROSSTAB control statement to accumulate a tabular summary from the network. jump to ENDLOOP for _L3 ENDLOOP ENDLOOP CROSSTAB Cross tabulates variables. If it is within a loop. If you omit either ROW or COL. Example LOOP _L1=1._KINC LOOP _L3=_L2. Otherwise (not in a loop). The first format will be backfilled to apply to any prior COMP variables Name of the variable that will be used for the row definition of the report. If FORM is not coded for any COMP. VehTime.” The format applies to the COMP that it is coded with. 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. but applies to the COL variable. and to all subsequent COMP variables until a new value is encountered. then including COMP = VehDist / VehTime would produce a table of average speeds.8 Network Program Control statements tabulated variables. See below for a description of the process used in placing values in the appropriate range slots. Care should be taken to not cause the reported line to be too long (limit the number of column ranges). if the statement includes VAR = VehDist. Specifies the format for the COMP reports. The standard Cube Voyager FORM syntax is used. NOTE: The program does not automatically produce totals because your ranges may overlap. For example. There may be up to ten COMP expressions on a statement. The only variable names that may appear in the COMP expressions are the VAR variables that are on this statement. You can produce totals and subtotals with appropriate use of RANGE values. the program will supply “7cs. Expression that can be used to generate a report that is some combination of the reports generated by the VAR variables on this statement. COMP |NV| COMP FORM |S| ROW |S| 342 Cube Voyager Reference Guide . Same as for ROW (RANGE). Name(s) of the variable(s) that are to be tabulated.01 is a definite number in base 10. but it can only be approximated in base 2. Each range has a lower limit. and an increment. Single precision provides accuracy to about six. The three values are low. digits. and the actual variable values are computed and stored as double-precision floating-point numbers. the program makes the upper limit equal to the lower limit. the program generates a row for each increment. If FORM is not coded for any VAR. The value of each variable will be accumulated into the cells of the generated table(s). significant digits. the values are separated by dashes. Format to use when printing the accumulated values in the table. or seven. whereas double precision provides accuracy to up to fifteen. A separate report will be generated for each variable named. There may be up to ten VAR keywords on a statement. or three numbers. The standard Cube Voyager FORM syntax is used. numbers which seem to be easily described in base 10 cannot always be represented exactly in the computer. A range as either one. If the program compares a variable to a Cube Voyager Reference Guide 343 . and increment. For example: the number 0. The first format will be backfilled to apply to any prior VAR variables.Network Program Control statements 8 CROSSTAB keywords (continued) Keyword ROW Subkeyword RANGE |RV50| Description Series of ranges (and increments) for stratifying the row variable for use in the report. Because computers do arithmetic on a binary basis. two. and to all subsequent VAR variables until a new value is encountered. There are certain problems associated with stratifying non-integer data. If there is no upper limit. the program will supply “7cs. the program assumes one row. or sixteen. starting at the lower limit. an upper limit.” The format applies to the VAR that it is coded with. VAR |SV10| VAR FORM |S| Range classification strategy The ROW RANGE and COL RANGE values are stored as singleprecision numbers. and progressing until the upper limit is reached. high. The program establishes ranges for stratifying the ROW variable values. If there is no increment. If more than one number. If there is an increment. they are discussed below. 01 3. the lower RANGE. should a value of 0.00 1. depending upon the floating point capabilities of the computer. The level of precision is set by the maximum number of decimal places in any of the RANGE values (low-high-increment).45 3.8 Network Program Control statements range limit.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.5 1-3-0. the increment index is computed (in integer) as: ((value-lo) / inc) + 1.45 1. RANGE 1-10 1-10-1 1-10-1 1-10-1. If a single RANGE (no increment) is used.99 1. The comparison result may differ. the program checks the value against the limits as: if the value is greater than. If a RANGE with an increment is used. If the value fits with the range.9999999999 be included in it? If RANGE is 1-10-1.3 1-3-0. The RANGE values and the ROW and COL variable values are factored and integerized (rounded) according to the decimal digits. a similar initial check is made to determine if the value fits within the outer RANGE limits.3 1-3-0. the value satisfies the range. You can control the level of precision when specifying the RANGE values.0001 fall into? To address all these concerns.001 Value 1 2 1 15 15 30 13 30 30 Index -2 1 1 2 5 2 7 7 344 Cube Voyager Reference Guide .5 1-3-0.45 1. it might fail due to this limitation of the computer.50 1.0 1-10-0. should a value of 10. and less than. Another concern is the definition of limits.29 3. the higher value. the program is designed to check for RANGE satisfaction based upon an integer representation of both the RANGE limits and the data. If RANGE is 1-10.001 be included. or equal to. and which range should the value of 2. or equal to. Examples may best illustrate this process. 5-1. 1-7. Most likely. Example CrossTab VAR=DIST. and the operation is DELETE.VHT)). no reason to process beyond this link. When a data record is being subjected to the operations in a phase block. COMP=VMT / VHT. The remaining input records to the phase will not be read. RANGE=1-50-1. the remainder of the block operations are bypassed. COL=LANE. 1-100-5.5-9999.2. VAR=VMT FORM=6. DELETE would be used in conjunction with an IF statement.1c.2-0. Example If (a=2150-2199 || b=2150-2199) DELETE .5-0. RANGE=1-7-1.647. For this reason.5-1. COL=LANES. the program may adjust the number of decimal digits if either RANGE limit would exceed the maximum after revising. RANGE=1-10. 0. Example IF (a > 1000) EXIT. The maximum integer revised value for either RANGE or ROW is 2.3 . FORM = 6.147.1. 4-7. ROW=VC.remove all links connected to nodes 2150-2199 EXIT Exits current phase.2-2.Network Program Control statements 8 There is a caveat with this process. weird example & ave trip length CrossTab DELETE Deletes data record. FORM=8. VAR=VHT.5. ROW=CLASS.483. 2. RANGE=0.2c. 1-3. Use EXIT to exit the current phase. COMP=sqrt(VMT)+10*(min(1000. Cube Voyager Reference Guide 345 . _CNT. and the record is removed from the network. 1. 8 Network Program Control statements FILEI NOTE: See “FILEI” on page 44 for general information about FILEI and for important limitations when using Application Manager. MAX=). This allows the user to decide what to do with records that have invalid record keys. the record is rejected as an error and is not available for processing. Upon return from 346 Cube Voyager Reference Guide . If the limits are exceeded. If the LINKI and NODEI files are not binary. 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. However. the NODEI must precede the LINKI. the automatic corresponding NODEI file is the network’s node standalone feature class. This is not normally recommended. the records need not be in any sorted order. There may be up to ten NODEI and ten LINKI files designated. If the user codes value limits for a variable (MIN=. If a LINKI file is a recognized binary file. an automatic corresponding NODEI file is assumed. Cube geodatabase networks have associated link and node stand-alone feature classes. Inputs data files. 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. those limits are checked during the INPUT phase only. If a LINKI file is a Cube geodatabase network. but it is at the user’s discretion. 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. If a NODEI has the same index as a LINKI. Input record keys are not edited before being subjected to stack processing. and the LINKI file is a binary network. the record is then listed as an error. If it cannot identify the file as a DBF. NOTE: A valid network in Cube Voyager/TP+ need not have coordinate variables on the node records. SPDC. 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. and LANE will automatically be renamed to DISTANCE. or B) and DELETE the record. you can use the keyword NETI as an alias for LINKI. it will assume ASCII. or recode the key. FILEI keywords Keyword LINKI Subkeyword |KFV10| Description Name of a file that contains link based records. the variables DIST. If it is not. the LINKI file must have a field named A and a field named B and the NODEI file must have a field named N.CAPCLASS. If the input file contains many bogus records (not valid data records—possible if coming from a GIS DBF with extraneous 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. you can check the key (N. CAPC. MDB.Network Program Control statements 8 stack processing. SPDCLASS. Since most applications will input binary networks or Cube geodatabase networks. If it detects that the file is a MINUTP binary network. If these fields in the DBF or MDB do not use this naming convention. The program will try to detect what type of file it is. then the RENAME keyword below can be used to rename the variables on input. If the LINKI file and the NODEI file are DBF or MDB format then at a minimum. Cube Voyager Reference Guide 347 . respectively. A. the key is checked to see that is in the range of 1nodes. Cube geodatabase network. and LANES. or a binary network. v5. FIRST. The default for any variables not combined will be consistent with the value of PARAMETERS REPL_DUPL. both names must be specified.V2-V1. The following subkeywords can be used to specify how to combine attributes values across multiple link or node records. first=x. Names can be swapped on one statement. or if the input is defined as a series of variables (in delimited format -.temp1-V2 LINKI EXCLUDE |SV| LINKI RENAME |SP| 348 Cube Voyager Reference Guide .y. LAST. Example of usage: FILEI LINKI=linki.8 Network Program Control statements FILEI keywords (continued) Keyword LINKI Subkeyword COMBINE |?| Description Switch to indicate whether multiple link or node records exist on the input data file. to swap names for V1 and V2: RENAME=V1-temp1.x.v4. MAX. AVE.not with BEG/LEN). MIN. vars=n.dat. vars= v1. If REPL_DUPL is true.v2. May be used to rename a variable from the input file.v3. the unlisted vars will be set to LAST. variables during the run.v8 FILEI NODEI=node. otherwise to FIRST.v8 combine=t. and certain variables are not to be extracted from the input records. The format is RENAME=oldname-newname. 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. CNT.v7.v4 ave=v6. combine=t. It is relevant only if the file is a DBF or binary network file and certain variables from it are not wanted. Specifies name(s) of variable(s) to be excluded from the file.v3. AVEX0 The descriptions of these keywords are identical to those described for the MERGE statement. ave=v1.v6. SUM.dat. SELECT is processed after any STOP statement. STOP is processed immediately after a record is read. the default is 1. but it will not be written to the output network (the NETO will not contain a variable named REV). The expression should contain a SUBSTR function to extract the header. START is used to position the file before actual data records are read. an input record represents a single directional link from A to B. the value of the REV should be a 1 or a 2. Used only with ASCII input where the first valid data record follows some identifying header record. and before any field editing.Network Program Control statements 8 FILEI keywords (continued) Keyword LINKI Subkeyword REV [I| Description Parameter that can be used in conjunction with files that are ASCII or DBF to specify if an input record is to represent a single directional link or if it is to be considered as two links (A-B and BA. The syntax is the same as for START. Used in a manner similar to the START keyword. The primary purpose is to allow the user to specify that there is a header. with the B-A values being the same as the A-B values). Under normal conditions. which is the actual data record. The record variable defined as REV will be treated as any other link variable. There is a REV variable on the record. The REV parameter is used only if: • • There is no REV variable on the record. Name of a file that contains TRIPS X-Y data. This keyword is only required for TRIPS networks. If the value is not a 1 or a 2. and the only valid variable is RECORD. If there is a VAR=REV defined for the link data records. and before any editing. LINKI START [s] LINKI STOP [s] LINKI TRIPSXY [F] Cube Voyager Reference Guide 349 . the reversibility of the link is determined by the value assigned to this keyword. but its value is neither 1 nor 2. but is associated with a trailer record. The only valid values for this keyword are 1 and 2. LINKI SELECT [s] Used only with ASCII input when it is desired to select only certain records from the file. The expression value must be enclosed within parenthesis (). and how to identify it. If TYP=A is specified for free format input. The first column of the record is designated as 1. 2 3 1 .. May be used to specify a minimum allowable value for the field.. or it will default to 1.8 Network Program Control statements FILEI keywords (continued) Keyword LINKI Subkeyword VAR |SV| Description Name of a variable to be extracted from the file. Examples of free-form records: 1 2 3 1. To read character-string variables from free-format text files. if they contain special characters (other than alphanumeric characters: a-z. BEG. where n specifies the number of characters.. If the file is ASCII. To read character-string variables from fixed-format text files. Name lengths may not exceed 15 characters. and LEN subkeywords. use the subkeywords TYP and LEN. An “A” means that the variable is alphanumeric.2. TYP A variable values on free format input must be enclosed within quote or literal marks ('. BEG and LEN will have to be specified. 2. or append (C) or (Cn) to the variable name.2.3 All four of the above illustrated records contain three fields: 1.' or ". Subkeywords of VAR include: BEG |I| Designates the beginning of the field in the input records. use the BEG and LEN subkeywords."). or some combination of both. use the TYP. and 3.. the variable will be rejected as an error. To read variables from fixed-format text files. a comma. 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. LEN |I| TYP |S| MIN |R| 350 Cube Voyager Reference Guide . and the variable is to be extracted from specific positions on each file record. the LEN must also be specified. 0-9). The program assumes that ASCII files are free format and all fields are separated by white space. If the input value of the variable is less than this value.3 1 . case is ignored. var=rev.5.min.len=5.max.Network Program Control statements 8 FILEI keywords (continued) Keyword LINKI Subkeyword VAR (continued) Description VAR may also be specified with parameters directly (without the above subkeywords). LINKI[1]=\demo\demo20. Example This section contains some examples of FILEI LINKI and FILEI NODEI usage. For example: VAR=A.6-10 (A is in columns 1-5.len=4.section.5.fil.dat.B. the numbers indicate the actual columns of the data record where the field is located.typ. NODEI |KFV10| Name of a file or an MDB and element that contains node-based records.21.1.beg=6. and B is in columns 6-10).1-5.b. Example: VAR=A.X. If the first two numbers that follow the name are separated by a dash..section follows name in free form nodei[4]=c:\citya\nets\linka. var=b. If the field following the variable name is a number. You must index LOOKUPI.1.dbf Cube Voyager Reference Guide 351 .5 (A is in columns 1-5 and B is in 610). or null.tsin .dbf.len=1 LINKI[3]=freeform.B.. linki[4] = c:\citya\nets\nodea. file is binary network NODEI[1]=C:\DEMO\DEMOXY. A null field is specified by coding two commas with nothing between them. Equivalent to the FILE keyword of the LOOKUP control statement.dat exclude=dist. The parameter list is considered as exhausted when a non-numeric field is encountered.len=5. this format is automatically triggered. Typ must be coded as 1 to indicate that the variable is to be an alphanumeric field. If both forms may be used to specify variable (numeric format.beg=1.6. var=dist.0. 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.dat.beg=14. All these fields must be numeric.5 . followed by any of the sub-keywords). file is ASCII NODEI[2]=\demo\demo21.DAT VAR=N.len. See “LINKI” on page 347 for comments regarding file detection.Y .name. NODEI uses the same keywords as LINKI except REV and TRIPSXY. VAR=a.beg. The total format is name. var=a.beg=35. LINKI[2]=\demo\?07. lxy. May be any of the formats described by the FORMAT subkeyword or may be an MDB/element name.1. Used to set the format of all variables to be written to the file.lxy. var=a. or it can be specified by using its decimal equivalent (for example. Similar to EXCLUDE under NETO.2)=='XY'). . but there is no default value for TXT files. tab is code 9). FORM is usually specified as w.8 Network Program Control statements LINKI[8]=Mixed_Node_and_Link. stop=(substr(record. stop=(substr(record. LINKO DELIMITER |S| Specifies a character that is to be used as the delimiter in SDF and TXT files. LINKO LINKO EXCLUDE FORM |SV| |S| 352 Cube Voyager Reference Guide .b. 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.y.1.).2)=='LD') FILEO Outputs network file. The optional FORM characters (CTDLR) are usually not appropriate for use on this statement./ + * = .distance.1. See the PRINT FORM definition in “PRINT” on page 62 for details of this parameter.x. If the value is a special character (. var=n.2)=='XY') NODEI[8]=Mixed_Node_and_Link. start=(substr(record. start=(substr(record. it must be enclosed within quote marks.2)=='LD').1. The default value is a comma.d to indicate the maximum field width and number of decimal places to preserve. and a designated FORM does not provide adequate width and decimal space for a field value. The latest FORM will prevail for any variables not explicitly named in a VARFORM and/or INCLUDE list. the program first tries to determine an appropriate format. and there is no filename extension to the LINKO value. LINKO INCLUDE |SV| Similar to INCLUDE under NETO. and separated by a delimiter DBF — Industry-standard database file If there is a ? in the name. To obtain the form for each variable. • LINKO VARFORM |SV| Cube Voyager Reference Guide 353 . This keyword need only be specified for those variables for which specific forms are required. If the file format is SDF. the latest appearance will prevail. Then the forms are applied in the order they appear on the statement. Possible values are: • • TXT — File of ASCII records in which all the data fields are written in a fixed format SDF — File of ASCII records in which the data fields are written in variable length. Specifies the form for specific variables. B(4. VARFORM=A(4. the program will try to adjust the field form within typical database rules to fit the value into the field space. The same variable may be included multiple times. Each value is a variable name with its desired form in parenthesis appended to it. NETO |KF| Name of the standard output network that is to be written.Network Program Control statements 8 FILEO keywords (continued) Keyword LINKO Subkeyword FORMAT |S| Description Specifies the format of the LINKO file. an extension of this value will be appended to the filename. INCLUDE variables may have a form appended to their names in a manner similar to VARFORM. the leading spaces will be deleted.0). If the same variable appears on both a VARFORM list and an INCLUDE list. If a DBF is written.0) would cause A and B to be formatted as 4 characters wide with no decimal places. If the value specified on the NETO keyword is an MDB/element name. NETO FORMAT |S| 354 Cube Voyager Reference Guide . Specify FORMAT=MINUTP to write a MINUTP network. MINUTP string variables are truncated to 80 characters. Cube Voyager will ignore it and no warnings will be given. only the link variable will be excluded. If the specified variable does not exist in any of the input files.8 Network Program Control statements FILEO keywords (continued) Keyword NETO Subkeyword EXCLUDE |S| Description Designates that certain variables that would normally be included in the output network are to be excluded. the output will be written as a Cube geodatabase network in the MDB file. 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). Two stand-alone feature classes will also be created in the MDB file. The output Cube geodatabase network will contain the additional link and node attribute. Specifies the format for writing the output network. EXCLUDE and INCLUDE are mutually exclusive. element_Node and element_Link. If an excluded variables exists in both node and link records. Normally. the program will write the file as a standard Cube Voyager binary network. NETO INCLUDE |S| Designates the variables that are to be included in the output network. but. and will be given the element name. if it is. this keyword is not used. element_SPDCAP will also be created and will contain the indices and values from the internal speed and capacity table. Specify FORMAT=TRIPS TRIPSXY=fname to write a TRIPS network and its associated XY file. only the listed variables will be included. Normally. this is not specified. A table. It cannot be used with EXCLUDE. GEOMETRYSOURCE. subsets of it. See APPEND under “PRINT” on page 62. 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. The setting of the NETO value follows the rules: • • • • NODEO |KF| If PARAMETERS LEFTDRIVE is specified. Both LINKO and NODEO are derived from this output network. TEMP2 NODEO=TEXTNODE FORMAT=TXT. FORMAT=MINUTP.0 INCLUDE=A. This is primarily for use in JUNCTION modeling in the Network program.SPEED. FORM=8. or if PARAMETERS LEFTDRIVE was specified.NET NETO=DEMOMINU. it does not have any affect on any PLOT statements in Network. May be any of the formats described by the FORMAT subkeyword under the LINKO keyword. PRINTO |KF| Specifies the name of the file where the output from a PRINT statement is to be directed using PRINT PRINTO=#. PRINTO APPEND |?| When writing output files. or may be an MDB/element name. Its subkeywords are the same as those for LINKO. if NETO is specified and a link variable is excluded from it then that link variable will not be available for LINKO. Consequently.B. use that value Else if lowest LINKI contains a LEFTDRIVE value. hence.DAT. Example FILEO NETO=MY. an output network will be generated first even if NETO is not specified.Network Program Control statements 8 FILEO keywords (continued) 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.3) Cube Voyager Reference Guide 355 . EXCLUDE=TEMP1. This keyword is not necessary if the lowest numbered LINKI file had the LEFTDRIVE parameter set.SPDCAP(2) LINKO=LINK FORMAT=DBF VARFORM=VC(6. use that value Else if NETO LEFTDRIVE is specified.DIST. . LOOP LVAR=Lbeg. ENDIF” on page 48 for more details. ELSE .... Enclose the IF and ELSEIF selections within parenthesis. and optionally.Lend. ENDIF ENDPROCESS IF (I < (K*3/6 +J) ) DELETE LOOP .800-900) .. ELSE .8 Network Program Control statements IF . program.3. .Linc . Lbeg is a numeric expression that initializes LVAR. ELSE .1 IF (N==5) .. LVAR must be followed by Lbeg. LVAR is not protected during the loop. See “IF . • 356 Cube Voyager Reference Guide .. Example PHASE=INPUT. and other LOOP statements can alter its value. 8-42 && X<3000 || Y=1-500. by Lend and Linc. FILE=NI. ELSEIF (N=1.. the selections can reference any variables that are valid for the current phase. ELSEIF .... ENDLOOP Controls a general variable loop...... Code IF condition blocks like standard Cube Voyager specifications. ELSEIF . ENDLOOP where: • LVAR is the name of the loop control variable. computational. ENDIF Performs certain operations based on conditions. Use LOOP…ENDLOOP blocks to repeat of a series of statements. The logic is as follows: • At LOOP: Initialize LVAR to Lbeg. 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. If Linc is not specified. Cube Voyager Reference Guide 357 . Either jump back to statement following associated LOOP. • At ENDLOOP: If Lend not specified. Compute the value for Lend. a backwards loop). LVAR is incremented by Linc.Network Program Control statements 8 • Lend is a numeric expression that is computed and stored when the LOOP statement is first processed. Compare LVAR to Lend. LOOP blocks may be nested. Linc) must begin with the underscore character ‘_’ to prevent confusion with record variables. jump to next statement. ENDLOOP compares the contents of the variable to another value (Lend). or drop through. Compute the value for Linc (default to 1 if missing). and branches back to the statement following the LOOP statement if the comparison fails. Lend. • NOTE: All variables in a LOOP statement expression (Lbeg. The value is added to LVAR before the ENDLOOP comparison is made. they may not overlap IF blocks. Add Linc to LVAR. it will be set to 1 (-1 if Lbeg and Lend are both constants and Lbeg < Lend. If Lend is not specified. and compared with Lend when the ENDLOOP statement is processed. Proceed to next statement. LOOP initializes a variable(LVAR). _mno/_pqr LOOP _abc=_xyz. 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. Lend. it is suggested that it be enclosed in either parentheses or quote marks. they are computed at the LOOP statement and can not be modified by other statements.0 . This helps to protect against possible endless loops. RECORD AVE AVEX0 CNT FIRST LAST MAX MIN SUM Use MERGE to specify how records from different files are to be merged.. 7.2 . nested LOOP ..5... 358 Cube Voyager Reference Guide .-2. Example LOOP _pass=1._xyz+2. Lbeg. ENDLOOP LOOP _xyz=_abc*_def. 5. It is important to note that merging records and combining variables are independent processes. If an expression is used. perform 10 passes .. and Linc must be separated by commas (standard white-space delimiting cannot be interpreted properly). Because LVAR values can be expressions. ENDLOOP MERGE Specifies record and variable merging._ghi+_jkl.. and how variables of the merged record are to be combined.3.8 Network Program Control statements The Lend and Linc variables are processed somewhat differently than in the other programs. ENDLOOP ENDLOOP LOOP _jj=10.10. The loop will be processed at least one time regardless of Lend and Linc values.10 .5 . Most uses will involve constants. perform 3 passes -. If the value is false. Maximum value of all the records. MERGE keyword — selecting records Keyword RECORD |?| Description Specifies if duplicate records are to be merged. If two networks (NETI[1] and NETI[2]) are input.) Each resulting record will have a cell for every variable that is specified in any input file or any COMP statement. The following keywords indicate a process to use in obtaining the value for the variables that are listed following the keyword. Directly from the record from the FILEI with the lowest index[]. If the value is true. Minimum value from all the records. Sum of all the records.Network Program Control statements 8 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. 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. Cube Voyager Reference Guide 359 . The default is true. only the records that exist in the FILEI with the lowest index [] will be included. Average of all records. Count of the records that contain the variable. The values for the variables will be obtained only from file records that contain the variable. any unique record is included. A variable may appear in only one keyword list. where the value from the file records is not 0. (Duplicate records from the same file may not occur in the MERGE phase. only the links that are in NETI[1] will be processed. Directly from the record from the FILEI with the highest index []. any variables that are not in any list will be set to FIRST. and RECORD=FALSE. B.0 105 106 12.1 101 102 -101 103 11.0 Order as seen in LINKMERGE.DISTANCE. 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.LANES FILEI LINKI[2]=FILE2.1 106 12. after being processed in the INPUT phase.6 105 1.indicates variable not defined for file): FILEI LINKI[1]=FILE1.CAPCLASS.VAR=A.6 104 105 1. SUM=COUNT Illustration for sample input files (-.SPDCLASS.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. Resulting file: A 101 105 B 102 106 DISTANCE 10.5 102 103 -102 103 12.B.DISTANCE.1 12.VAR=A.SPDCLASS.VAR=A.5 102 -103 -102 11. LAST=LANES. AVE=DISTANCE.B.8 Network Program Control statements Example MERGE RECORD=TRUE FIRST=CAPCLASS.5 SPDCLASS 11 12 CAPCLASS 11 12 LANES 1 3 COUNT 1000 0 360 Cube Voyager Reference Guide .COUNT FILEI LINKI[3]=FILE3.5 MERGE RECORD=FALSE .5 103 12. 0 12. Default value is 20. unless the error is in the key (for example. LEFTDRIVE LIST_ERRS MAX_IP_ERRS NODES REPL_DUP ZONES PARAMETERS keywords Keyword LEFTDRIVE |?| Description Used to force a LeftDrive switch into the NETO. node number). See FILEO NETO LEFTDRIVE in “FILEO” on page 352 for more details. Specifies how many records with data errors are allowed. If this value is exceeded.Network Program Control statements 8 MERGE RECORD=TRUE FIRST=COUNT. Resulting file: A 101 102 104 105 B 102 103 105 106 DISTANCE 10.6 1. By default. this value is not set. LIST_ERRS |KI| MAX_IP_ERRS |KI| Cube Voyager Reference Guide 361 .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. the program will terminate with a fatal condition. Default value is 20. unless the error is a limits error. Specifies how many records with data errors will be listed before turning off the error listing. AVEX0=DISTANCE . The bad fields will be set to 0.8 12. Records with errors are not skipped. This need not be specified (by default. The value must be a greater than 0 and less than 999. If this parameter value is not supplied (or is not available from an input binary network). The value must be greater than 0 and less than 20000. specify REPORT DUPLICATES=T.8 Network Program Control statements PARAMETERS keywords (continued) Keyword NODES |KI| Description Specifies the highest node number to be allowed in the network. This keyword applies to each NODEI or LINKI file as it is read within any PHASE=INPUT. the program will set it to the highest node number in a monotonic string beginning at 1. any node numbers that exceed this value are considered errors. 362 Cube Voyager Reference Guide . Switch that indicates how to process records from an input file with matching node numbers. it will become a variable in the output network. Default value is false.999. the program detects the highest number). (Any nonbinary file will automatically be processed within an input phase. ZONES |KI| Specifies the number of zones in the network. If ZONES is used in a COMP statement. the later record will replace any previously read records. or it is desired to alter the number of zones. By default. This is required only if the number of zones cannot be determined from the LINKI and NODEI files. To obtain a listing of duplicate links.) The MERGE control statement is used to determine how duplicate links from different inputs are to be processed during the MERGE phases. the PARAMETERS control word need not be specified. binary files should not have duplicate records. If this switch is true. but if it is specified. REPL_DUP |K?| All the values on this statement are trigger keys. A temporary variable _ZONES is initially set equal to this value. and can be used in COMP and IF expressions. the program detects the value. Each keyword could begin a new statement. the node values are saved for post processing. the link is not processed for plotting. After the program completes the LINKMERGE stack for a link. The situation for nodes is different. it processes the final values for the PLOT keywords that may have been applied to the link. If there are no DRAWLINK values present. Cube Voyager Reference Guide 363 . DRAWA DRAWLINK LINKPOST NODEPOST PLOT statements in the LINKMERGE phase control plotting. they are saved until all the links from the current A-node are completed. If there is a LINKPOST value. If there are DRAWA and/or NODEPOST values. a node can be posted without a symbol. the LINKPOST value is ignored.Network Program Control statements 8 Example PARAMETERS repl_dup=n MAX_IP_ERRS=10 nodes=35000 zones=2203 PLOT Selects links/nodes for plotting. but there is no DRAWLINK value. so that node symbols will be prominent on the display. When the A-node is completed. 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) 364 Cube Voyager Reference Guide . Possible values are: • • • • DRAWLINK |KS4| Color — A value as described in “PLOTTER” on page 364. current Windows drivers do not allow both size and style at the same time (style is changed to solid if a width is specified). Size is the width of the line. If PLOTTER BANDWIDTH is specified and the bandwidth variable has a value. Specifies the color that this link is to be posted with. Rectangle. Size — Size of the symbol. and style. Possible styles are: Solid. Dash. below. Size and Style are ignored. DashDotDot. Specifies the color and size of the variables that are to be posted for this Anode. but it must begin with one of the keywords. or Triangle. size. (See NODEPOSTVARS under “PLOTTER” on page 364 for information about which variables are to be posted. can be Circle. PLOT keywords Keyword DRAWA |S4| Description Specifies the characteristics for drawing a symbol for the A-node of the link. Color is a value as shown in the PLOTTER description. DashDot.) LINKPOST NODEPOST |S| |S2| Example See “Examples” on page 387. It is recommended that Size usually be left null. Fill Specifies the characteristics for drawing this link: color. Symbol — Centered on the node. Dot.8 Network Program Control statements A PLOT statement may be specified on a short IF statement. The orientation (portrait or landscape) determines how the plot will be generated. In grid plots where Fill is not used. The possible values are: Solid and None. The default is None. the value must be enclosed within quotes so that the spaces can be considered as part of the name. The name must match the name of the printer as it appears in the Printers dialog box. PLOTTER keywords Keyword BANDWIDTH Subkeyword |S| Description Specifies the variable that is to be used to control the drawing of bandwidths along drawn links. The variable must be scaled appropriately. On raster plotters.Network Program Control statements 8 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. a taper of 45 might be more presentable. If the name has spaces in it. Usually. or the plot will be unreadable. otherwise the program will not know anything about the printer BANDWIDTH FILL |S| BANDWIDTH TAPER |I| DEVICE |S| Cube Voyager Reference Guide 365 . this value should be specified as solid. Specifies that the ends of the bands are to be tapered towards the nodes rather than being perpendicular to the link. solid could require excessive time for generating and actually drawing the plot. The printer driver properties are established by left-clicking the desired printer and then modifying the properties as desired. Name of the printer driver that is to be selected and written to. Case is not essential. Any integer value from 0 to 45 (degrees) may be specified. Specifies if the band is to be filled in or left empty. but on pen plotters. There must be a DEVICE specified. a temporary variable should be designated. and the size determines the plate size of the drawing. actual printing (or plotting) is performed by copying the file directly to the port that is connected to the device. The value can be: Left. size. If none of the footers has specified a date.8 Network Program Control statements PLOTTER keywords (continued) Keyword FILE Subkeyword |F| Description Used if it is desired to write the printer information to a file. Specifies lines of text that are to be printed at the bottom of the plot page. The values are (position). FOOTER FONT 366 Cube Voyager Reference Guide . If FILE is specified.MM. only the first three are used. rather than directly to the printer. Right. name. The program will add one additional footer to identify the software and the licensee after the user footers are printed.MM HH. Tokens may be specified in the footers. There may be up to nine values following FONT. color. There may be up to 16 footers. If FILE is not specified. The tokens and their replacements are: Token [date] [idate] [time] [times] [window] [scale] FOOTER ALIGN Replacement MM/DD/YY MMM DD YYYY HH. the date and time will be added included in the identification line. if more headers are to be specified after ALIGN.SS X=xxxxx-xxxxx Y=yyyyy-yyyyy Scale=xxxxx FOOTER |S16| Specifies how the footers should be aligned on the plot. ALIGN must be placed after a FOOTER or FONT value. or Center. the output will be written directly to the printer device. This is recommended for devices that are normally not connected directly to the processing computer. when they are present the token is replaced by a value. Specifies the font characteristics of the footers. but currently. the FOOTER[]= must be specified. Cube Voyager Reference Guide 367 . and their areas are not written into by network drawing. 3.. Specifies the position for additional user text is to be printed on the plot page. The value can be: Left.Network Program Control statements 8 PLOTTER keywords (continued) Keyword HEADER Subkeyword |S16| Description Specifies lines of text that are to be printed at the top of the plot page. Each LINE can have its own symbol. the HEADER[]= must be specified.. say HEADER[6]=". See “Examples” on page 387. 6 lines will be printed."). The values are (position). if more headers are to be specified after ALIGN. with the first 5 being blank. The legends are placed within the plot window area.". color. name. 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. 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. There may be up to nine values following FONT. only the first three are used. TR.. and 4. they will be used for the text for all lines in the legend.. Specifies how the headers should be aligned on the plot. ALIGN must be placed after a HEADER or FONT value. The coding rules are similar to those for HEADER and FOOTER. There may be up to 16 headers. 2. Since headers most likely have special characters in them. and BR. or Center. Example: if only one header is specified. Right. Each LEGEND may have its own font characteristics. but you can also enter symbols on each line. Legends are primarily for identifying the characteristics of the network drawing. size. or 1. Specifies the font characteristics of the headers. but currently. BL. Name See DRAWA under “PLOT” on page 363 for valid symbol names. see DRAWLINK under “PLOT” on page 363 for valid names. If a sample line style is to be drawn. MAPSCALE |R| 368 Cube Voyager Reference Guide . Specifies a scale factor to be used to convert coordinate units to inches. The value is expressed as coordinate units/inch. 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. The size of the symbol. the high-to-low node link will overwrite the low-tohigh link. Specifies the symbol that is to precede the LINE text. a scale factor will be computed from known information.8 Network Program Control statements PLOTTER keywords (continued) Keyword LEGEND Subkeyword FONT |S9| Description Specifies the font characteristics for the text in this legend. or the value is 0. or the length of the line. Note that when a factor is specified. size. If this keyword is not used. the MAPWINDOW will be used mainly to orient the center of the plot. Text to be printed at the specified line of the legend. Standard color designation. and fill color. This allows two-way links to be more visually presented. There should be four values specified for the symbol: name. See HEADER FONT on page 367 for details. If the value is not specified. color. Standard color designation if the symbol is to be filled with a color. If MAPSCALE is not specified. To make the top margin 1.25.1.1. If it were desired to leave more space around the plotted window (say 1 inch on the left and 1.25.Network Program Control statements 8 PLOTTER keywords (continued) Keyword MAPWINDOW Subkeyword |R4| Description Specifies two opposite corners of the map window to be selected. the program may adjust one of the dimensions if it is necessary.25 would be used.25 inches.25. the program uses the minimum and maximum coordinates from the network. The map window is specified in map coordinate units. MARGINS |R4| Cube Voyager Reference Guide 369 . The 4 required values are specified as X1.75. Any part of the network that exceeds the limits of the window will not be drawn.Y1.75.75 would be used.5 inches on the right). X2. If no window is specified. MARGINS[3]=1.1.5 inches and the bottom margin 2 inches. By judicial use. The center of the map window will be placed in the center of the plotting window. Specifies the margins that surround the plot window on the printed page. You can do this with one keyword: MARGINS = 0. the scale factor will be calculated to fit the window within the page. If the selected device is a printer that is selected with Letter size (8.75.1.5 x 11 inches). The plot will be scaled to fit within the map window.Y2. 1. MARGINS=0. MAPWINDOW will most likely not directly correlate with the plotting window. the plot window can be placed anywhere on the page that is desired. a normal margins would be 0. the output might be cropped. POSTLINKVAR |S4| POSTLINKVAR FONT |S4| 370 Cube Voyager Reference Guide . and the height (y dimension). it is not possible to vary the variables. Nothing will be printed outside the rectangle defined by this The MARGINS values can be used to position the printed window within the plate. This keyword is used primarily to make a plate that is smaller than the basic dimensions of the device. but it is possible for the user to cause this to happen by specifying variables that are modified as desired in the stack statements. the MARGINS values can be used to establish the dimensions of the plot window. Specifies the font characteristics for link posting. The standard font designations are specified. The same variables will be posted for all links. Two values must be entered: the width (x dimension). this need not be specified. POSTLINKVAR=VC(3) to post VC ratio with 3 decimal places. The number of desired decimal places for the posting of the variable can be appended to the variable name in parentheses.8 Network Program Control statements PLOTTER keywords (continued) Keyword PLATESIZE Subkeyword |R2| Description Specifies the maximum plot plate (page) size. PLATESIZE is not normally used. The plate will be oriented at the upper left corner of the printed page. It should not be greater than the dimensions specified in the device properties. Specifies the variables that are to be posted along links that are drawn and designated for posting by a PLOT LINKPOST value. In general. It is not recommended that different variables be posted on different links. They are expressed in inches. the PLOT DRAWLINK statements set color. but the color is ignored. for example. if it is. Up to four variables can be selected. Colors are processed in Windows by using a number that is a combination of the three colors (red green and blue). you can specify the name of the font. To use the mixing string. the size. You can create the internal number by specifying an integer number (not too likely).Network Program Control statements 8 PLOTTER keywords (continued) Keyword POSTLINKVAR Subkeyword POST |S| Description Specifies how link post text is to be printed when it is too long for the link. regardless if it overruns the link. the program will supply the name “ARIAL. The font name must be recognized (and available). The color can be specified in various ways: by a standard name. the string must begin with one of the letters (RGB) followed by a number in the range of 0-255. the PLOT NODEPOST statements set color. but the color is ignored.” The size is always specified as absolute. changing to a different size printer will not alter the size the text. the program will supply a value of 0. The standard font designations are specified. 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. and more Cube Voyager Reference Guide 371 . or is too small. Print it. it doesn’t fit. and the color. Three bytes are used to store the intensity of each of the colors. The possible selections are: Fit All AutoSize AutoSize(ss) Omit the text. If no font is specified. Same as AutoSize. or the printer driver will substitute a font of its choosing. a hexadecimal value (very common process). Decrease the font size until it fits. If no size is specified. The font size can be overwritten on a node-by-node basis. but the optional (ss) indicates the minimum size to allow. or a numeric value to index color mix.01. in inches. POSTNODEVAR FONT |S4| Font specifications You can control all text that is to be printed on the plot. Specifies the font characteristics for node posting. or by a string of digits preceded by a color indicator. the values can range from 0 to 255. In general. 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 -- 372 Cube Voyager Reference Guide . If there is no color for the font. The table below indicates the standard colors and their various representations. if desired. the string must begin with 0x and be followed by a string of hexadecimal values (0-f ).8 Network Program Control statements color strings. The pen color correlation is determined by the properties of the driver. The order of the strings is irrelevant. You may have to experiment to obtain which pen is selected for each color used. a color will be chosen by the printer driver. To enter the hexadecimal value. For pen plotters. the driver will translate the color number to a pen number. FORM=LRCD.B(5).Note: this line is a continuation Cube Voyager Reference Guide 373 . PRINT Formats and prints a line of information. Example PRINT LIST=A(4). LIST=SPEED. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) See “PRINT” on page 62 for more details.DISTANCE(6.3).2) ABCDE(6.Network Program Control statements 8 Example See “Examples” on page 387. TIME1 . PHASE FILEI |F| Normally.. only DBF and ASCII files are processed in the INPUT phase. NODEMERGE. Used only with PHASE=INPUT. or LINKI[#] that was previously specified on a FILEI statement. The ENDPROCESS statement can alternatively be specified as ENDPHASE. Citilabs recommends using PROCESS/ENDPROCESS blocks be used to contain all operational (stack) statements. the file will be processed in the INPUT phase.8 Network Program Control statements LIST= N(5). and the operations to be performed on the designated file during the phase follow on additional control statements. Even if there are PROCESS blocks surrounded by stack statements.. 374 Cube Voyager Reference Guide .0CDLR LIST=A. T0. to indicate a file from NODEI[#]. ENDPROCESS Specifies a PROCESS and ENDPROCESS block. but if a FILEI with a different mode is specified. Normally. The value for PHASE must be either INPUT. will be executed in the LINKMERGE phase. PHASE (FILEI (comp)) PROCESS keywords Keyword PHASE Subkeyword |KS| Description Indicates the phase to which the statements which follow it are to be applied. That way there is no confusion about what is intended. The program will skip over the PROCESS block. The end of the phase block is established when an ENDPROCESS or another PROCESS statement is encountered.#. all the stack statements will be executed during the LINKMERGE phase. or SUMMARY. Y PRINT FORM=6. SPDCLASS FILE=PRINTFIL.# or LI.002 PROCESS . a PROCESS statement contains only the above keywords and values. and indicates that the block statements are to be applied only when the specified FILEI file is being processed.B. any stack statements that are not explicitly within a PROCESS block. If there is no specific PHASE=LINKMERGE statement. LINKMERGE. The value must be NI. that is more consistent if the PROCESS control is triggered by PHASE=.DISTANCE. X. Example 1 . Re-code node numbers for LINKI[1] and NODEI[1] using a lookup function.DIST. The 2nd PROCESS statement also acts as an ENDPROCESS statement. PHASE=INPUT FILEI=NI.2.DIST ENDPHASE Cube Voyager Reference Guide 375 . once a LINKMERGE phase has been designated. .Network Program Control statements 8 There are some rules about PROCESS blocks: • • • There may be only one PHASE=NODEMERGE There may be only one PHASE=LINKMERGE If there is a PHASE=LINKMERGE statement. . LI. all stack statements must be with an explicitly stated PHASE. In other words. LIST=A(5) B(6).DIST) LIST='Distances Differ for link:'. FORM=6. B = NODECODE(B) ENDPROCESS Example 2 PHASE=LINKMERGE IF (LI.DIST != LI. .1.1. LI. but an ENDPROCESS is required after the 2nd PROCESS.2. PHASE=INPUT FILEI=LI. A = NODECODE(A).1.1 N = NODECODE(N).2. there may not be stack statements that are not explicitly within a PROCESS block. Internal specifications for the allocation of output variables use for debugging only). Additional file processing may be required. DUPLICATES FILEI FILEO INPUT MERGE SPEED UNCONNECTED |?| |?| |?| |?| |?| |?| |?| All reports must be specified with a logical value of true or false. Default value is F. Summary statistics following every phase. Speed tables. Default value is F. normally not specified. Default value is F. Duplicate links that are detected during PHASE=INPUT. REPORT SPEED=Y. UNCONNECTED=N REPORT ALL=true.8 Network Program Control statements REPORT Defines report specifications. Capacity tables. fileo=false. List of zones that do not have links into and out of them. The default value is true. Example REPORT FILEI=Y. FILEO=Y. Summary statistics following input phases. Default value is F. Default value is T. Default value is F. 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 T. Default value is F. filei=false 376 Cube Voyager Reference Guide . Links that are missing either an entry or exit link. Such links cannot be used by any path processing. Default value is F. Default value is F. Internal specifications for the input files (use for debugging only). Network Program Control statements 8 SORT Sorts user-defined arrays. NUMRECS=_L LOOP _K=1.2c) ENDLOOP ENDPHASE Cube Voyager Reference Guide 377 . BN=LINKS. VMT=LINKS .BN. Example ARRAY AN=LINKS. ARRAY NUMRECS See “SORT” on page 72 for more information about this standard Cube Voyager statement. AN. */ PHASE=SUMMARY SORT ARRAY=-VMT. only want to see the highest 30 LIST=AN[_K](6).VMT[_K](10.30 . the number of entries will be less than the original number number of links.BN[_K](6). 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. SPDCLASS) as the column index to obtain a value for a link. Inappropriate.99).700 SPDCAP LANES=2. . and may have null fields to skip the revision of certain columns. then revise the values for 20..8... LANES may be interspersed with other keywords and values on the statement. for all lane stratification (SPEED[1.Set entire table to 50.7. CAPACITY and SPEED are entered as vector data. and may be indexed to set a specific loading place..2. All values must be 1-9. and contains 891 values... Speed to be applied to the link.8 Network Program Control statements SPDCAP Revises speed and capacity tables. and 24 for lanes 1. When an array is accessed.8 SPDCAP CAPACITY=99*50.3. for all lane stratification (CAPACITY[1]=20.. All values must be 0-9999.88. SPEED=20... CAPACITY[2]=40. The speed array is initialized to the index number. the program uses the number of lanes (LANES) as the row index.400. LANES=5.2.4-9. CAPACITY LANES SPEED SPDCAP keywords Keyword CAPACITY |RV*99| Description Capacity in vehicles per lane per hour.6.. CAPACITY[20]=300. LANES |IV| SPEED |RV*99| A network contains an array of capacity and speed data. LANES=1. LANES will be preset to 1-9. 378 Cube Voyager Reference Guide .3. The SPEEDFOR and CAPACITYFOR functions can be used to obtain values for these tables.21.30.. Each array is dimensioned with ninety-nine values for each of nine lane stratification.). Speed is maintained with one decimal place. LANES=2-8.3. inclusive.99]=1. Actual link capacity is obtained by multiplying the link capacity based upon its capacity classification (CAPCLASS) value by the number of LANES. Example .50.5. inclusive. the LANES will not be used. inclusive.SPEED[15]=15 SPDCAP SPEED=30. The capacity array is initialized to 20 times the index number. All values must be 0-3276. and the capacity and/or speed classification (CAPCLASS. If CAPACITY or SPEED is encountered prior to a LANES keyword on the statement. Lane stratification that any following CAPACITY and/or SPEED values are to apply to. Network Program Theory 8 Theory This section describes the theory used by the Network program. they are used only when special processing is to be undertaken. In general. the user need not be concerned with process phases. the previous block is terminated. statements that are not dynamic operations. re-code values from any input files specifically designated. but that appear within a phase block will be recognized as such and will be processed properly. For most applications. the user must code operational statements within a PROCESS PHASE block defined for each phase. NODEMERGE phase — Read all node data and organize it LINKMERGE phase — Read all link data and process it (main phase) Cube Voyager Reference Guide 379 . which are listed below. The basic phases are: • • • INPUT phase — Read ASCII and DBF files. It is suggested that for readability and ease of editing. Only statements that specifically apply to the phase should be coded within the block. Topics include: • • • • Phase descriptions Variable referencing Output variables Plotting Phase descriptions The program processes the input files in separate phases. If another PROCESS PHASE statement is encountered before an ENDPROCESS statement. the phase blocks be defined in the normal process order. A block should be terminated with an ENDPROCESS statement. However. and the new block is begun. There may be only one block for each phase. and the order of the blocks in the input is not crucial. 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. The records are processed and edited for errors and duplication. but it is not mandatory. As in the INPUT phase. Any file (or file segment) that passes through this phase. the user may specify computations and/or selections to be applied to each node record as it is processed. but its data are used in subsequent phases in a revised internal format. and it is not within a PROCESS block. The file segment records are sorted in appropriate order (node or link) before being stored in the revised format. INPUT phase All ASCII and DBF files must pass through this phase. it is tagged as being in the LINKMERGE phase. As the program processes each file record. A PROCESS PHASE=LINKMERGE statement may be coded. 380 Cube Voyager Reference Guide . it determines the files that must be processed in that phase. it applies any phase operations that the user has designated for the phase. As it processes each phase. Internally. NODEMERGE phase The node based records from all the NODEI files must pass this phase. the program processes the phases in the order in which they are described below. If there are no relevant files for an INPUT phase. is no longer used in its original format after this phase is completed. and processes them. and saved for subsequent referencing in the LINKMERGE phase. the phase is bypassed. If an operational statement is encountered. It is possible to re-code node numbers in this phase. The user may specify selections and computations to be applied to each record as it is processed. because it is anticipated that most applications will be functioning in only this phase.8 Network Program Theory • SUMMARY phase — Report results of LINKMERGE phase There need not be a specific PROCESS PHASE for LINKMERGE. The resulting record for each unique node is written to the output network. It is not permissible to re-code node numbers in this phase. the variable is only a local working variable. and may consist of only letters. This is generally restricted to computations on working variables. the recoded link is included. Node based data can be accessed during the link processing. Variable referencing The main logic of the program involves processing variables. Variables are usually classified as either node or link based. passed onto the final phase. the record is processed against the operation statements designated by the user. in most cases. a link record is processed for each unique link found from the LINKI files. This is the phase that most users are mostly interested in. SUMMARY phase In this phase. certain post-processing operations can be performed.Network Program Theory 8 LINKMERGE phase The link based records from all the LINKI files must pass through this phase. and. etc. and the underscore character. If the first character of a name is an underscore (_). As in the above phases. summarized. These and other operations available to the user are described in “Control statements” on page 334. tabulated. The first character of the name may not be a digit. Records can be deleted. digits. In the LINKMERGE phase. If there are operations to be performed in the phase. Every record is processed according to the purpose of the current phase. usually to obtain averages. a node record is processed for each unique node from the NODEI files. If a link is recoded in the INPUT phase. and extracted to an external device or file. If a node is re-coded in the INPUT phase. the re-coded node number is included. In the NODEMERGE phase. Operation statements are generally expressed in the standard IF/ELSEIF/ELSE block and COMP statements. the user may specify selections and computations to each link record as it is processed. A variable name may be up to 15 characters in length. Tabulated and summarized data is reported at the end of the phase. and will not be included in the network. Classification Cube Voyager Reference Guide 381 . name L. Working 382 Cube Voyager Reference Guide .. the variables are node based.#. The program establishes a buffer for a record from each input file for every record in the phase. During the LINKMERGE phase. the variables will be associated with the type of file being processed. but node variables can be referenced. Working variables are set to zero at the beginning of the application. A node variable is referenced during LINKMERGE as either A.name N#. variables are link based.. For NODEMERGE the prefix is NI. They are distinguished by their first letter. If a variable from an input file is to be referenced during NODEMERGE or LINKMERGE. which must be an underscore. During any INPUT phases.name* NI#.name For link records: LI. and for LINKMERGE the prefix is LI. If there is a user SUMMARY phase.).ABC references the variable ABC from the LINKI[3] file. Working variables are variables that are to be used for intermediate storage. every variable referenced within the SUMMARY block is a working variable. Another type of variable is the working variable.name* LI#.#. but the program allows the following variations: For node records: NI. If a new variable is computed (NEWVAR=. The formal designation for the prefix is LI. and will not be part of an output network.name. If there is no input record for the current working record.name L#. and the prefix allows access to each of those buffers.#.8 Network Program Theory depends upon the process phase in which the variable is referenced.name or B.#. If it matches a link variable. unless it is the same as a link variable. the associated NODEI or LINKI file number must precede the variable name. For example: LI.. the variable from the last link will be processed.name N. the values are all zero. and are changed only by user statements.3.. it will be attached as either a node or link variable.#.#.#.name *The preferred method of designation. During the NODEMERGE phase. vol. RMSV endif Phase=LINKMERGE _ax = a.b. .x . If all the variables are not to be included in the output network. the variable list can be modified on the FILEO statement. and to then compute and print summaries at the end of processing. possibly (_vcnt-1) list = 'RMSV ='. NOTE: In some situations.Network Program Theory 8 variables allow the user to accumulate statistics during link processing. a PRINT LIST variable may not be recognized if it is cross-referenced.vol . (See “Examples” on page 387 for an illustration. Phase=SUMMARY if (_vcnt > 1) RMSV = sqrt(_sumsqdiff / _vcnt).B. 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).A. get assignment differences _vcnt = _vcnt + 1 if (_vdiff != 0) _sumsqdiff = _sumsqdiff + _vdiff*_vdiff ._ax. Cube Voyager Reference Guide 383 . The value that is stored for each variable is controlled by the MERGE control statement.X. 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. get the Node variable named X for Node A _ay = a.L2. To be sure. node based variables to be listed should be set into temporary variables and then listed with that name.) Example _vdiff = L1.y LIST=a.B.X may not be accepted. For example: LIST=A._ay EndPhase Output variables During the merge phases. 384 Cube Voyager Reference Guide . The Network program uses the Windows driver to perform the actual formatting of the network information. in particular.). so pen plotters are being left somewhat behind. 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. Windows operating systems are geared towards more recent technology. Plotting pens are selected by RGB (RedGreenBlue) standards. color correspondence is not guaranteed. raster plotters. green. There must be an appropriate printer device driver for the media where the network is to be plotted. perhaps later versions will internally rectify them. yellow. but deficiencies have been reported in these systems. the link posting will be oriented properly. Pen plotter problems: The standard Windows drivers for pen plotters do not seem to function properly. the program may not be able to properly scale the plot. Many default drivers come with Windows and provide considerable capabilities. It is possible to directly fax a network plot to a facsimile machine. as well. the user must specify the desired plate size. In those cases. There are thirdparty software drivers available that correct this problem. With one driver (WinPlus). They do cause some problems. This process provides for current and future flexibility. If standard colors are used (red. If roll size is selected in the device driver. so it becomes the responsibility of the user to ensure that the colors that are selected correspond with the pens on the plotter.8 Network Program Theory Plotting The network that is formed during the LINKMERGE phase can be plotted by sending information to a standard Windows printer device. This release of the program does not address these driver deficiencies. If esoteric colors are requested. etc. and pen plotters. if legends are used. blue. faxes. they do not always write text at the proper location and angle. but mis-positioned. there should be no problems. Typical types of drivers are available for printers. The logical layout of the plot plate on a sheet of the plotter device: the desired size. or to a file. The headers and footers to be printed on the plot. The user controls the color of link posts. • • • • • • In general. Bandwidths and type of fill and end tapers. The node variables that are to be posted.10. when a node is selected for posting. Node posting (writing text near a node) will always post the same variables. and optional scaling. The default values for each of these are: ARIAL. if different than the driver provided size. if a link is posted. If there are PLOT statements. the program will fatally terminate. Link posting (writing text along a link) can not be varied by link. its posting will contain the same type of information at the same size and font as any other link that is posted. the opposite is not an error. so that if a different driver is used. and whether the output is to be sent directly to the plotting device. and the margins to place the plate within the driver provided dimensions. Legends that can be displayed in the corners of the plotting window. but the size and color is controlled by PLOT statements. 0. PLOT statements processed during LINKMERGE determine what will be plotted from the network. The optional network window for selection. but no PLOTTER statement. Cube Voyager Reference Guide 385 . The link variables that are to be posted when a link is selected for posting. The PLOTTER statement contains information about: • • The plotting device name. individual variables can not be colored differently. black.Network Program Theory 8 A PLOTTER control statement is used to define the plotting system and the parameters for performing the plot. All sizes are specified in inches. color and size specified by the user. all text that is to be plotted can have its font. the text would still be readable. . If a PLOT statement is processed in LINKMERGE. Draw a specified symbol for the Anode of the link Post variables at the A node. The following processes are considered: Process DrawLink LinkPost DrawA NodePost Description Draw the link as specified. If a keyword specifies plotting. If a device is not attached directly to the computer. the values that are current following the last link outbound from a node are used. the driver should have the file option specified. and the PLOTTER DEVICE FILE value (filename) should be specified. PLOT statements control actual plotting. Example: IF (. LinkPost=red. it may be placed on a short IF statement. The orientation of the plot. In the Printers and Faxes window. the current link is flagged for processing by the plotting process. If the PLOT statement is invoked by the use of one of these trigger keywords. click Add a printer and follow standard installation processes. You can deal with these situations by specifying the fourth value for PLOTTER POSTLINKVAR FONT. For node processing. the device driver must be properly installed. landscape) is set in the device. Example: NodePost=-1.8 Network Program Theory Before performing a plot. Post variables for the link. but then later conditions determine that it should not really be plotted. 386 Cube Voyager Reference Guide .) DrawLink=red.. the values that are current at the end of the link are used for plotting. This is done by left clicking the Windows Start button and choosing Printers and Faxes. Many times a link posting may be too long for the link. the keyword can be nullified by setting its value to -1. Files are generally processed by copying them directly to the plotter port. These values can be specified multiple times for each link. (portrait. var=a. b. List the links in a network neti=demo20.2.4 linki[3]=demo07m. v1. write DBFs for nodes and links.4 nodei[1]=c:\demo\demoxy.b endrun Merging link records from multiple ASCII files run pgm=NETWORK .4.4.2. v2.2.var=n.7. rev. a.4.3.14.var=a.4.dat.x.b if (li.net list=a.1.4.b endphase endrun Dumping link and node records to DBF files excluding select fields run pgm=NETWORK . merge two ASCII files with different links linki[1]=demo07. dist.14.4. v2.a == 0) list=' LI[1] missing link:'.dat.2.a == 0) list=' LI[3] missing link:' a.1.2.2. dist2. AVE=dist report all=no zones=19 phase=LINKMERGE if (li.Network Program Examples 8 Examples This section contains examples of the Network program: • • • • • • Listing links to the print file Merging link records from multiple ASCII files Dumping link and node records to DBF files excluding select fields Building network from inline data records Simple link plot Complex plot Listing links to the print file run pgm=NETWORK .4. .7.y merge record=true. b.dat.rev=2. v1.35. but exclude many variables from input Cube Voyager Reference Guide 387 .4. EXCLUDE= FIELDOPT TCNUMBER COUNTY USER DATE OCOUNTA OCOUNTP.. stop=(substr(record. pagewidth=80 RUN PGM=NETWORK .lanes endrun Building network from inline data records copy file=3pth. EXCLUDE= SCENARIO STATUS NAME TPCAP1 TPCAP2 TIPRTP CNT.lxy. 388 Cube Voyager Reference Guide . EXCLUDE= OSPEEDX OSPEEDY ECOUNTA ECOUNTP ECOUNTD ECOUNTY.tsva1.now look at the results from the link DBF linki=testld.var=n1.var=n3.1.8 Network Program Examples neti=test.capc1.2)=='LD') linki[2]=3pth.a. start=(substr(record.typ=a.n. now build a network from the inline data merge record=y nodes=20 zones=2 nodei[3]=3pth.x.2)=='LD') .b. start=(substr(record.b.2)=='XY').1. 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.1.exclude=xcoor.string1. EXCLUDE= ATYPE nodeo=testxy linko=testld if (STATUS=='D' || ft==15) delete endrun run pgm=NETWORK .lane1.dist.tpn. EXCLUDE= OCOUNTD OSPEEDA OSPEEDP OSPEEDD..Hnt neto=test.spdc1.lxy .ycoor If (a>b && lanes > 4) list=a.dbf nodei=testxy.dbf.lxy. EXCLUDE= ESPEEDA ESPEEDP ESPEEDD ESPEEDY COMMENT6 COMMENT1.y. Sample Quickie plot with no parameters: draw links only RUN PGM=NETWORK .BOLD POST=AUTOSIZE(.10.italics.15.symbol=Dash.green LEGEND=TopLeft.TRne3. LINE[1]=TL...red LINE[5]=BL. "This is header 2". font='courier' . RUN PGM=NETWORK NETI = C:\DEMO\DEMO20._STR FONT='COURIER'. font='courier'. font='courier'. font='courier'..italics. LINE[1]=TR.This sample illustrates various capabilities of plotting.italics.red LEGEND=3.15.plt DRAWLINK=0xffff ENDRUN Complex plot . SETUP Plotter DEVICE="HP LASERJET 4" POSTLINKVAR=A.10 LINKOFFSET=0. FOOTER[7]='Shows window and scale tokens: [window] [scale]' align=right font='Courier'.2)=='XY') list=a. Cube Voyager Reference Guide 389 .red LEGEND=BottomRight font='courier'.YELLOW..b.1..red LINE[5]=tl. FILE=f:\sample.red LINE[3]=tr.08.B.10.5._AB.red LEGEND=TR.line5.line5..symbol=triangle. LINE[1]=BL.symbol=dashdot.Network Program Examples 8 stop=(substr(record.dist endrun Simple link plot .LINE1.LINE1.red..DAT PLOTTER { .15.blue.15.italics.green FOOTER="Footer 1" FOOTER[3]="Footer 3" FOOTER[5]='Shows various date tokens: [date] [idate]' FOOTER[7]='Shows various time tokens: [time] [times]'.symbol=rectangle.DAT PLOTTER DEVICE = "HP 7475A". sample quick link plot NETI = C:\DEMO\DEMO20.blue.0. align=center.05) POSTNODEVAR=A...10.10.01 BANDWIDTH=_BANDWIDTH FILL=SOLID TAPER=45 HEADER= "This is header 1".symbol=circle.. FONT='COURIER'.0.purple.15..LINE1.20.1.0.symbol=triangle. . set node postings and symbols IF (A<=5) DRAWA=RED.SOLID.CIRCLE.CIRCLE.WHITE NODEPOST=0XFF00FF IF (A>5 && A<=10) DRAWA=RED .Y) LINKPOST=BLUE.0.RECTANGLE.X || A.20.BLACK NODEPOST=R255 ENDRUN 390 Cube Voyager Reference Guide .LINE2. reset the color of these links .X == B.10..0.0.15.5.2) DRAWLINK=RED.Y == B.symbol=triangle.DASH .15. LINKPOST=GREEN IF (A. FLAT|VERTICAL LINES DRAWA=BLUE.0.1 IF (A>=30 && A <40) LINK=GREEN.40 CIRCLE NODEPOST=G255 IF (A>10 && A<20) DRAWA=R255..8 Network Program Examples LINE[2]=BR.red } .YELLOW NODEPOST=r123b220g100. Plotting Controls if (a<=19 || b<=19) _BANDWIDTH = lane/10 _AB = A*100 + B _STR = str(_ab/100.. Cube Voyager Reference Guide 9 Matrix Program This chapter describes the Matrix program. Topics include: • • • Using the Matrix program Control statements Examples Cube Voyager Reference Guide 391 . 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. 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. 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. Zonal data and matrices can be input. This program is also used when invoked as a special function via RUN PGM= FRATAR. or DISTRIBUTION. There are no default processes.) Frequency distributions User formatted files 392 Cube Voyager Reference Guide . and matrices and reports can be output. etc.9 Matrix Program Using the Matrix program Using the Matrix program This section provides information for using the Matrix program. Various file formats for both input and output are supported. it is the user’s responsibility to specify what is to be accomplished. GENERATION. It then starts the I loop. and are.Matrix Program Using the Matrix program 9 • • • Transposing matrices Generating matrices Renumbering. If any input matrices need to be transposed. and processes the control stack from the beginning. in most cases.” for details. When all control statements have been checked for basic syntax. the program builds a list of required variables. “Highway Program. (See Chapter 6. and other housekeeping is performed. and Generation programs). the program performs some end-of-zone summaries. When the I loop completes (or is terminated). The loop begins with I set to one and continues monotonically until the highest zone number is processed. When the end of the stack is reached. and disaggregrating matrices Almost any and all of the above processes can be performed in a single application. and flow control statements (illustrated below). and writes any matrices requested. and the program exits. processed outside of the I loop. The remainder of this document refers to this loop as the I loop. within the I loop. any requested reports are printed. computational. and have been stored in the control stack. they are transformed to a single file and made ready for subsequent retrieval. aggregating. reporting. Flow control statements provide the capability to iterate through portions and conditionally or unconditionally branch to a different place. The program processes within an overall origin zone loop controlled by the variable named I. When Matrix is called by Distribution.) The standard input is comprised of definition. zonal data files are read and stored. The input files are opened. Computational statements are those that cause data to be revised. reads the matrices for I. Definition statements are those that define the input and out files. I-loops are nested within iteration loops. There are some restrictions when used as a special function (Fratar. Distribution. Cube Voyager Reference Guide 393 . usually 1. Holds the number of records in the input record file. In addition to any variables explicitly specified by the users. see “COMP” on page 460 for more details. Holds the number of fields on the input record file. 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.9 Matrix Program Using the Matrix program All variables are initialized to zero (or blank) before the I loop. Result of LOWEST(). usually 1. The current row zone. I ITERATION J LASTZONE LOWCNT MW[] RECI. this is the highest zone number to be processed on the current Cube Cluster node.RECERR RECI. In a normal run this is 1. 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. and varies (1-Zones) for MW[] and LOOPs.NUMFIELD RECI. Stores the last zone number to be processed.NUMRECORDS RECI. and are thereafter altered only by computational statements or internal processing. The iteration number. The built-in variable are usually protected. the user is not allowed to alter their values. Under intrastep distributed processing with Cube Cluster. A column index. In a normal run this would be the same as ZONES. A work matrix. there are certain built-in variables that can be referenced.RECNO 394 Cube Voyager Reference Guide . Holds the record number of the current record being processed from the input record file. Cube Voyager Reference Guide 395 . See “COMP” on page 460 for details. Sum lowest valued cells in a row. Average cell value where value!=0 Number of cells whose values != 0 Divide one matrix by another. Factors the row by fac.nameT. Minimum value in the row. a transposed matrix is one that has had its rows and columns switched.n. Row total Transposed matrices A copy of a transposed input is obtained by referencing a variable with a name of MI. Z ZONES Built-in functions Described in more detail in “COMP” on page 460. Multiply one matrix by another. A copy of I. Integerize mw (start at column intrazonal + 1) Maximum value in the row. In Matrix program terminology. Matrix program built-in functions Function ARRAYSUM() LOWEST() MATVAL() ROWADD() ROWAVE() ROWCNT() ROWDIV() ROWFAC() ROWFIX() ROWMAX() ROWMIN() ROWMPY() ROWSUM() Description Returns the value of the sum of an array’s values. Number of zones. Allow random access to values from MATIs Add matrices.Matrix Program Using the Matrix program 9 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. ) LOOKUP PARAMETERS RENUMBER • Computational statements — Cause variable values to be updated. FREQUENCY PRINT PRINTROW REPORT • Flow control statements — Set which statement is to be performed next.9 Matrix Program Using the Matrix program Control statement types in Matrix program There are several types of control statements used in the Matrix program: • Definition statements — Define static processes. GOTO :label 396 Cube Voyager Reference Guide . BSEARCH CALL CHOICE COMP FREQUENCY SET XCHOICE • Reporting statements — Cause values to be accumulated and/or displayed dynamically. ARRAY FILEI and FILEO (which define the input and output data. whereas INTRAZONAL or INTRA fixes it to i. 99999) Cube Voyager Reference Guide 397 . or the row index). Neither can it be used with the INCLUDE or EXCLUDE subkeywords of the M[] statement. 0. Such commands may be used in conjunction with the LOWEST function set an intrazonal cost based on the cost to the nearest zone(s). 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 []. see “Control statements” on page 436. Special keywords INTRAZONAL or INTRA are provided to assist in this. 1. which are used to select destination zones. When such commands are executed. all elements of the matrix which lie off the diagonal are left unchanged. To set the intrazonal element of a matrix row.Matrix Program Using the Matrix program 9 BREAK CONTINUE LOOP ENDLOOP JLOOP ENDJLOOP IF ELSEIF ELSE ENDIF EXIT For more details about control statements. Note that it is invalid to use the above forms of calculation with a JLOOP (as JLOOP implies varying the j. or column.01. 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. As an example: INTRAZONAL mw[10] = 0 INTRAZONAL mw[10] = LOWEST(10. and similarly to movement types within matrices. 398 Cube Voyager Reference Guide . or zones corresponding to external cordon points. This keyword is coded in a similar manner to the j (or column) position when a matrix is referenced in an arithmetic expression. The INTRAZONAL or INTRA keywords may be used to access the diagonal element of a matrix during calculations. Examples of such zone groupings are the CBD (central business district). given a suitable descriptive name to identify them. Working with lists of zones When modeling travel demand. but their use is restricted to arithmetic computations. and then used wherever appropriate in the modeling. industrial zones. 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. Any of these areas comprises a list of zone numbers. and: var1 = MW[10][INTRAZONAL] which sets a scalar variable var1 to the intrazonal element of working matrix ten. the suburbs. but ignoring destinations with costs less than 0.9 Matrix Program Using the Matrix program sets the intrazonal cost to the cost from the origin to the nearest destination.01 or more than 99999. it is often necessary to apply different treatments to various types of zones. Examples are: MW[1] = MW[1][INTRA] which copies the intrazonal (or diagonal) element of the first working matrix into all column positions. taken from the current row of the matrix. such lists of zones may be set up once. lists which are lengthy and used on many occasions in processing could easily be a source of errors in typing or updating. it is simple to define lists. This section outlines two methods: • Working with lists of zones using the INLIST function — Uses the INLIST function to select required zones. To avoid such difficulties. The INLIST function gives a value of 1 when the particular zone (first parameter) is found in the specified list (the second parameter). Working with lists of zones using the INLIST function As an example.15-20' suburbs='23-30. origins in suburbs and destinations in CBD . The particular zone under consideration is often i (the origin zone) or j (the destination zone).50-57' .. but they may be used in a wider range of contexts. zones 1 to 12 and 15 to 20 form the CBD of a study area....Matrix Program Using the Matrix program 9 • Working with list of zones using the substitution method — Defines lists in the Pilot program.. ENDIF ENDJLOOP ENDIF Cube Voyager Reference Guide 399 ..suburbs) = 1) . then uses the substitution facility to work with them.suburbs) = 1) JLOOP IF(INLIST(j.. JLOOP IF (INLIST (j. ENDIF ENDJLOOP IF (INLIST(i.. The following example illustrates the use of this facility: CBD='1-12. using the COMP or computation control statement. A list called CBD may be defined.. The INLIST function is then used to construct a condition which determines whether its origin and/or destination are in the specified list..CBD)=1) . it is less easy to define the required lists.. ENDIF ... IF (INLIST(i. commands here will be processed for origins in the CBD .34-41.43. commands are processed for flows which have both . commands here processed for destinations in the suburbs .47.CBD) = 1) . The list of zones is specified as text data which is enclosed in quotes (').. it should be written with commas between items. . then adds a parking cost of 10 units into the skim (or level of service) matrix for destination zones in that area. MX[10]=mi. JLOOP INCLUDE = @CBD@ MX[10] = MX[10] + 10 ENDJLOOP .. zones 1 to 12 and 15 to 20 form the CBD of a study area. The list of zones is specified as text data which is enclosed in quotes ('). 400 Cube Voyager Reference Guide . This is done in the script before any RUN PGM statements for programs. The example: CBD='1-12. and so use of commas is recommended. using the COMP or computation control statement. its script contains the name of the list.9 Matrix Program Using the Matrix program Working with list of zones using the substitution method As an example. which is enclosed by @ symbols (denoting substitution of the list of zone numbers. in place of the list’s name).' (comma) between the start and end values....15-20' ...05: . the latter are specified in the form 1-10 with neither space or '... this form is not accepted by the conditional or IF statement which requires commas. To ensure that the list is generally acceptable.) A further example changes that part of a matrix which corresponds to origins in the suburbs and destinations in the CBD. The defined list may contain individual zone numbers and / or ranges of zone numbers. Wherever this list of zones is required by a program. ENDRUN defines the list of zones in the CBD.1.. dividing these matrix cells by 1. RUN PGM = MATRIX .LOSmatrix . and forms part of the script of the Pilot program... A list called CBD may be defined.. (Although Cube Voyager scripting allows spaces to be used as delimiters between items of a list. 27 ....05 endif endjloop endif .. .15-20' .227-341' CBD = '1-12. ENDRUN The calculation may be expressed more concisely as: if(i = @suburbs@) jloop include = @CBD@ mw[1]=mw[1]/1..05 include=@CBD@ The following illustrates the case where the calculation applies to all destination zones for selected origins: . if(i = @CordonZones@)mw[5]=mw[5] * 1.. CordonZones = '540-578' .Matrix Program Using the Matrix program 9 suburbs = '100-145.. RUN PGM = MATRIX ...148-191. ENDRUN Cube Voyager Reference Guide 401 .05 endjloop endif or even: if(i = @suburbs@) mw[1]=mw[1]/1..194-224...... if(i = @suburbs@) jloop if(j = @CBD@) mw[1]=mw[1]/1. RUN PGM = MATRIX .. New scripts developed after version 3. If a data field (FIELDS= or name=) is defined by a pair of numbers (lo-hi). If the data fields are being 402 Cube Voyager Reference Guide . There are two forms of text records that have to be dealt with: fixed format and delimited. the entire structure of RECI for text processing had to be completely rewritten. script references to RI. To incorporate these changes. If the data field is being defined via the name= format. All data fields MUST be defined in the same format.2. that sets the format as fixed. For backward compatibility. The way that the program distinguishes between the two is by the way the data fields are defined in the script.0 and beyond Substantial changes have been made in dealing with RECI text (non-DBF) files in versions later than 3.2. but necessary in this situation. These forms can not be intermixed in the same record processing step of the Matrix program. so FLD has been decommissioned and replaced with FIELDS.NFIELD[] were coded.0 can and later versions can deal with both numeric and character data fields. v4. If a data field is defined by a single number (field number on the records). with N being the default mode. a practice that we generally do not like to condone.NFIELD[]. The earlier versions could deal with only numeric data fields. All data fields can optionally be defined as character mode (C) or numeric mode (N).x should reference RECI. that sets the format as freeform.9 Matrix Program Using the Matrix program Working with RECI/RECO processing in v4. the mode can be appended to the name: ORGZONE(N)= STREET(C)=. There were several reasons for these changes: Earlier versions had used the keyword FLD to define data fields. This has rendered older setups unusable.x.FLD[] will act the same and be treated as if RECI. This was inconsistent with most other text file processing where FIELDS was used. 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. CFIELD[1-6] will be blank.FIELD9 to be obtained from data fields 1. FIELDS=6.FIELD1-7 with the values coming from columns 21-22. For fixed format.FIELD3 coming from data fields number 6.6(3). the parallel RECI.NFIELD[3].FIELD1… RI.9. FIELDS=21-22(7) would generate RI.2. the mode can be appended to the end of the field definition: FIELDS=1-3(C) for fixed format. FIELDS can specify multiple successive fields with a single specification (providing all are the same mode). FIELDS=1.FIELD1…RI. To define a number of data fields when the user does not wish to have uniquely specified names for all fields.FIELD1 through RI.22. but those fields would all be character values.CFIELD[1-9] will be defined. its parallel character RECI. there will be two values: a numeric value and a character value. In addition.25-26… If FIELDS= and name= are intermixed. 13 respectively.CFIELD[x]. However.23. RECI.24.2.FIELD10.NFIELD[] value will be zero. and RECI. FIELDS=6(C7) would be the same.FIELD1. 23-24.NFIELD[x] and RECI.7. var5=5. RI.CFIELD[1-10]. RI. the FIELDS= format is used. FIELDS=22(C3) will cause RI. or FIELDS=1(N). or without multiple definitions.NFIELD[1-9] and RECI.3.13 will define variables RI. and would cause population of RECI.NFIELD[7-9] will all be zero. RI.3. etc. for all character variables. Conversely.3. and RECI. Var6(C)=10. FIELDS= may be specified multiple times.FIELD2. Var4=4.CFIELD[] value will be blank. 9. These variables can also be referenced as: RECI. RECI.FIELD3 would be from 11-15.2.6. FIELDS=1-5(10).NFIELD[1-10].FIELD7 will be obtained from fields 6 through 13 of the data records. Cube Voyager Reference Guide 403 . FIELDS=1.FIELD8 (and RECI.8.Matrix Program Using the Matrix program 9 defined via the FIELDS= format. They are referenced as RECI. FIELDS=11(5) will generate RI. For every FIELD.FIELDs as character.NFIELD[3] RECI. Optionally. would define variables 10 variables: RI.xFIELD[1-8]).FIELD1…RI. RI.FIELD2 would be obtained from columns 6-10. FIELDS=15(C10) would establish the RI. with.NFIELD[2] RECI. If the field is defined as numeric. FIELDS=6(7) specifies that RI. the monotonic index for FIELDS continues with the next FIELDS value. or to RI.FLD[x] must be revised to RECI. If the highest field to be referenced is 15. then FIELDS=1(15) should be specified. several revisions are required.FLD[3] was obtained from column 3 of the data record and RI.FLD[x] should be revised to RECI. This will have to be revised to FIELDS=0-0.9 Matrix Program Using the Matrix program Application script running under earlier versions that did not have this capability will have to be revised.0-0. Any references to RI.10-10.FIELDx. for example: INCOME=3 will have to become INCOME=3-3 If FLD= was not specified (free format) and no name= was specified. FLD[10]=10. The basic revisions required are: If FLD= specification (which indicated fixed format records) was used.NFIELD.0-0. or to RI.0-0. Any references to RI.0-0.FLD should be changed to RECI.FLD[10] was obtained from column 10. This can not be duplicated in this version. 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 404 Cube Voyager Reference Guide .FLD[n]. the program estimated the number of variables (n) on the record and generated variables RI. the user must specify the maximum number of variables to be obtained from any data record (judicious over estimation should not cause any problems). RI. In general.0-0.0-0. and the definition was a single field (not lo-hi). If the old script had FLD[3]=3. This can usually be done quite easily with any editor with search and replace capabilities. all references to RI.FLD[1]…RI.NFIELD[x]. In addition.FIELDx. the definition will have to be changed to lo-lo.3-3. if name= was specified.NFIELD[x]. 1 of Cube Voyager. The XCHOICE (CHOICE prior to v4. Logit choice models have a number of distinct possible outcomes (for example mode of travel). Cube Voyager Reference Guide 405 . and the model estimates the probability of choosing each particular outcome. However. you must make additional changes at the keyword level.Matrix Program Using the Matrix program 9 • • Mode and destination choice General notes Introduction to choice modeling Beginning with version 4. whereas the cost has to be multiplied by an appropriate coefficient (or scale parameter) before use in choice models. A choice model implemented with XCHOICE should run significantly faster than the same model implemented with CHOICE. The alternatives are evaluated using either their costs or their utility values. Use the XCHOICE command statement whenever developing new choice models in the Matrix program. Existing choice models that use the CHOICE statement will continue to run as scripted. For detailed changes please refer to “XCHOICE” on page 451. Costs and utilities are related. Note that some of the keywords are different with the XCHOICE command statement. When converting a logit model that uses CHOICE to use XCHOICE. As the utility of an alternative increases the alternative becomes more attractive. Citilabs recommends modifying existing models to use the XCHOICE command statement and take advantage of the improvements in run time. but an increase in cost makes the alternative less attractive. XCHOICE implements the same logit model structures as the original CHOICE statement but improves choicemodel run times. The CHOICE command statement continues to function as in prior versions.1) command in Cube Voyager scripting provides powerful extensions to the core language designed to allow complex logit choice models to be specified easily. the other difference is that a utility directly measures the users benefit. Apart from sign. the XCHOICE control statement replaces the CHOICE control statement for implementing logit choice models. In practice when several alternatives exist. and may be used in absolute or incremental form. it is known as the binary choice model. They are: • • Absolute logit model Incremental logit model 406 Cube Voyager Reference Guide . The destination choice model is an extension to the logit choice concept where the alternatives are not modes of travel. These sub-nests are then brought together in the main (or toplevel) choice process. The section uses a number of examples to illustrate use of the CHOICE command and to explain the underlying theory. To overcome this hierarchic choice models are used which sub-divide the choice process into a sequence of decisions. the alternatives are not always independent of each other. An alternative form is the Incremental model (also known as the Pivot Point model) which has a different methodology. but destination zones which the traveler chooses between. The choice process may be viewed as initially choosing between sub-nests (representing types of travel). The simple choice and hierarchic models described above are forms of the “absolute” logit choice model.9 Matrix Program Using the Matrix program The simplest choice model splits total travel demand between two alternatives (or modes). It uses data for demand (by alternative) in the base situation together with changes in costs (or utilities) between the base and forecast scenario. and then choice at the sub-nest level which decides the mode used. This may be extended by adding further alternatives. The examples start at the simplest level and increase in complexity. 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). in order to re-allocate the demand between the alternatives in response to those cost changes. It may be combined with mode choice to form complex models. so forming a multinomial model. or car use (which includes through-trip by car and park-and-ride). any practical issues related to setting up such a model are discussed. Absolute logit model This section discusses the absolute logit model. Finally. Suppose that in a transport system there are just two discrete competing modes—car and public transport (PT)— Cube Voyager Reference Guide 407 . with example scripts. alternative strategies or more complex variations are also illustrated. Then the method for implementing a solution in the Matrix program is shown. For a detailed description of the demand modeling function syntax see “XCHOICE” on page 451. 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. For some models. supported with the relevant theory.Matrix Program Using the Matrix program 9 • • • Hierarchical logit model Destination choice Mode and destination choice Each model is described in the context of a typical problem. At the end of the section there are some general notes concerning coding of demand models. subscripts relating to the origin and destination zone have been omitted. because there are just two alternatives (car and PT). and by PT. for example the convenience of bus services. Let’s call the cost of travel by car. etc. A user of such a system is said to have a binary choice. There may also be an additive constant to approximate those elements of the cost that cannot be readily quantified. 408 Cube Voyager Reference Guide . Ccar. Cpt. Usually. wait. For the sake of clarity. this cost is a linear combination of the monetary cost (fare. Suppose that there is a total demand. Logit Choice model The process begins by calculating the generalized cost of travel between each origin and destination by either mode. Structure of absolute logit model The following paragraphs explain how the absolute logit model can be applied to the problem of estimating the probability of choosing each mode. in-vehicle-time. fuel. interchange. D. and in particular how this is implemented in Cube Voyager. or the quality of railway rolling stock.) and time (walk.9 Matrix Program Using the Matrix program between a given set of origins and destinations.). that make such a journey in a given period. etc. are given by the equations below. Using utilities. The forecast demand for car is given by Dcar and for PT. Ppt. as its effects have already been incorporated into the utility values.Matrix Program Using the Matrix program 9 The Absolute Logit Model states that the probabilities of choosing car. and Ppt. of which more later. The model also calculates a composite cost (C) that represents the cost of the combined choice (in this case. car and public transport). the probabilities of choosing car. where: Where utilities are used instead of costs. and PT. Pcar. Pcar. Dpt. this simple choice model does not require a distinct scale parameter. are: Cube Voyager Reference Guide 409 . Where λ is the scale parameter. called λ in the equations above. Finally.02 and 0. the sensitivity of the logit model increases. The graph below illustrates the model sensitivity with different values of λ. Scale parameter (cost-based models) The behavior of the model is determined by a positive constant known as the scale parameter. progressively allocating more demand to the choice with the lower cost. as λ approaches infinity.9 Matrix Program Using the Matrix program the composite utility (or logsum) is: and the equations for demand by alternative (Dcar.01. the model will allocate all the demand to the alternative with the lowest cost. and demand is shared equally between each of the available choices.04. 410 Cube Voyager Reference Guide . Notice that Pcar=½ and Ppt=½ when λ=0. As λ increases. If λ=0 the model is completely insensitive to cost. 0.) are as given above. The figure “Logit model sensitivity” on page 411 shows how the model becomes more responsive to the difference in cost for λ=0. etc. 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. the scale parameter is not required.Matrix Program Using the Matrix program 9 The value of the scale parameter will depend on the nature of the choice. . there is no cost coefficient as it has already been combined with the actual cost to form the utility values. characteristics of the demand and the units of cost. Thus for simple choice models. The examples used here are for illustrative purposes and should not be adopted as default values. but their specification and values are different from the style of use in cost-base models. Scale parameters are used in more complex (or hierarchic) models. Variable names have been chosen to match those used in the preceding equations. Absolute logit model Cube Voyager Reference Guide 411 . Logit model sensitivity Where choice models are based on utilities. as shown here using MW[10]. These specify what alternatives may be chosen. in which case the output “demand” will be the probabilities associated with each alternative. . These are forecast demand for each alternative. The block begins with the ALTERNATIVES clause listing of the names of the alternatives. These names will be used later to define the model structure. and the structure of the logit choice model. Forecast demand ODEMANDMW = 15.16. Forecast composite cost SPLITCOMP = 19. 412 Cube Voyager Reference Guide . Next. starting with the total demand which is coded in the DEMANDMW clause. These should be listed in the same order as the modes in the ALTERNATIVES clause. 4. as matrix MW[3]. Input total demand DEMANDMW = 10. and PT. the inputs to the calculations. . pt. . Input costs COSTSMW = 3. . again specified in the same order as the ALTERNATIVES clause. The model inputs are specified. List choices ALTERNATIVES = car. the generalized costs are specified for car. The specified input may represent a matrix of true demand (in trips). .02 car pt. .9 Matrix Program Using the Matrix program XCHOICE. . so MW[15] will contain car trips and MW[16] PT trips. or it may be set to 1. the resulting outputs. as matrix MW[4]. Model structure SPLIT = TOTAL 0. Now the output variables are specified. 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. In this case the choices are car and PT. List choices ALTERNATIVES = car. and either clause may be omitted from the script. Variable names match those used in the preceding equations.02 in the above equations) and the choice is between the car and PT alternatives. In this script. In this example the choice is between two modes. The STARTMW clause specifies a working matrix number which is higher than that of any other working matrix referenced in 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. car and PT. The forecast composite cost is output as MW[19] with the SPLITCOMP keyword.02 (or λ=0. the scale parameter is given as a numerical value but it is equally valid to use a variable instead. Absolute logit model XCHOICE. The word TOTAL indicates that the entire input demand is to be split between the alternatives listed in this specification. but this may be extended to three or more alternatives. pt. Matrix script for utility-based model This section describes how this example can be implemented using the XCHOICE command. The scale parameter has a value of 0.Matrix Program Using the Matrix program 9 Finally the structure of the choice model is defined. . . . Input utilities Cube Voyager Reference Guide 413 . Both the forecast demand and composite cost are optional outputs. and should not be used elsewhere in the script. the same STARTMW value may be used in all instances. Input total demand DEMANDMW = 10. The fragment of script below will run this model. The SPLIT clause defines the model’s structure in terms of the scale parameter (or coefficient of generalized costs) and the choices given in the ALTERNATIVES clause. Where a Matrix program script contains several XCHOICE commands. Working matrices from the STARTMW value upwards are used by the XCHOICE command. . starting with the total demand which is coded in the DEMANDMW clause. the resulting outputs. car and PT. These should be listed in the same order as the modes in the ALTERNATIVES clause. as matrix MW[5]. Next. Now the output variables are specified. In this case the choices are car and PT. . The block begins with the ALTERNATIVES clause listing of the names of the alternatives. These names will be used later to define the model structure. . as working matrix (MW) numbers. Model structure SPLIT = TOTAL car pt. or it may be set to 1. here the choice is between the car and PT alternatives.16. the utilities for car. Forecast composite utility SPLITCOMP = 18. as matrix MW[6]. Finally the structure of the choice model is defined. and PT. again specified in the same order as the ALTERNATIVES clause). 6. in which case the output “demand” will be the probabilities associated with each alternative. and the structure of the logit choice model. as shown here using MW[10]. but this may be extended to three or more alternatives. each of which defines some aspect of the logit choice model.9 Matrix Program Using the Matrix program UTILITIESMW = 5. . The SPLIT clause defines the model’s structure in terms of the choices given in the ALTERNATIVES clause. These are forecast demand for each alternative (MW[15] for car trips and MW[16] for PT. Working matrices STARTMW = 40 . These specify what alternatives may be chosen. the inputs to the calculations. The specified input may represent a matrix of true demand (in trips). The model inputs are specified. The XCHOICE command comprises a number of clauses of the form keyword = value(s). Forecast demand ODEMANDMW = 15. The word TOTAL indicates that this split divides the entire input demand between the specified 414 Cube Voyager Reference Guide . In this example the choice is between two modes. the same STARTMW value may be used in all instances.Matrix Program Using the Matrix program 9 alternatives. and should not be used elsewhere in the script. Working matrices from the STARTMW value upwards are used by the XCHOICE command. Where a Matrix script contains several XCHOICE commands. The STARTMW clause specifies a working matrix number which is higher than that of any other working matrix referenced in the script. Both the forecast demand and composite utility are optional outputs. The forecast composite utility is output as MW[18] with the SPLITCOMP keyword. The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the XCHOICE command. Incremental logit model This section discusses the incremental logit model. and either clause may be omitted from the script. Topics include: • • • • • • Introduction Incremental logit choice model Matrix script for cost-based model Alternative script using cost differences Matrix script for utility-based models Alternative script using differences in utilities Cube Voyager Reference Guide 415 . This is known as the incremental form of the logit model.9 Matrix Program Using the Matrix program Introduction This example returns to the structure of the absolute choice example. Incremental logit choice model The model inputs are base demand by mode (Dcar. both using costs and utilities below. base costs by mode (Ccar. The structure of the model shown below in Figure 1. Cpt) and forecast costs by mode (C’car. Structure of incremental logit model This model is developed. but now forecasts the change in demand based on the change in cost from a known base situation. Dpt). C’pt). The change in cost is denoted by DCcar and DCpt where: Base probabilities are denoted by Pcar and Ppt where: 416 Cube Voyager Reference Guide . So that the forecast demand by mode (D’car. D’pt) is: The incremental composite cost (DC) is given by: When working with utilities.Matrix Program Using the Matrix program 9 The choice model now takes the form of the equation below where P’ denotes the forecast choice probability and λ is the scale parameter. 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: Cube Voyager Reference Guide 417 . . Input forecast costs by mode COSTSMW = 30. Model Structure SPLIT = TOTAL 0. 21. Working matrices 418 Cube Voyager Reference Guide .3. pt. Forecast demand ODEMANDMW = 2. . . . . The utility-based form of the composite costs is given by: Matrix script for cost-based model Comparing the example code below with the first example (same structure. Incremental logit model XCHOICE. 31. Forecast incremental composite cost SPLITCOMP = 7.02 car pt. . . . The output composite cost is the incremental change in composite cost. Input base demand by mode BASEDEMANDMW = 10. The model requires base demand. List choices ALTERNATIVES = car. but an absolute logit model). one can see that only the model inputs change to construct an incremental model. base costs and forecast costs for both modes as input. Input base costs by mode BASECOSTSMW = 20.9 Matrix Program Using the Matrix program and the probabilities of using each alternative are: The equations for base and forecast demand by mode are the same as for cost-based models. . 11. Input CHANGE in cost (= ForecastCost . This variant is particularly useful when the costs do not change for all modes. suppose that the car cost is constant and that a series of tests are to be conducted for different PT scenarios. . Model Structure SPLIT = TOTAL lambda car pt. Incremental logit model Cube Voyager Reference Guide 419 . The example excludes the calculation of incremental composite costs. Where the cost difference is zero. . In this case. 25. Specify scale parameter (or cost coefficient) lambda = 0. . . Input base demand by mode BASEDEMANDMW = 10. DCcar.Matrix Program Using the Matrix program 9 STARTMW = 40 Alternative script using cost differences The XCHOICE command allows cost changes to be given instead of base and forecast costs. Forecast demand ODEMANDMW = 2. the numeric value may be specified as the cost difference for the alternative (rather than needing to construct a matrix of zero values). List choices ALTERNATIVES = car. The model requires base demand. . can be set to zero. one can see that only the model inputs change to construct an incremental model.3. base costs and forecast costs for both modes as input. . For example. the change in car cost. Incremental logit model (specifying cost differences) . Working matrices STARTMW = 30 Matrix script for utility-based models Comparing the example code below with the first example (same structure. pt. The output composite cost is the incremental change in composite cost. 11.02 XCHOICE . . Instead.BaseCost) DCOSTSMW = 24. but an absolute logit model). there is no need to calculate the car cost for each test. 11. For example. Incremental logit model (specifying cost differences) XCHOICE . DCcar. 31. pt. so are specified as '0' DUTILSMW = 24. . Forecast incremental SPLITCOMP = 7. . . can be set to zero. pt. 25. suppose that the car cost is constant and that a series of tests are to be conducted for different PT scenarios. List choices ALTERNATIVES = car.3.BaseCost) .9 Matrix Program Using the Matrix program XCHOICE. . . Model Structure SPLIT = TOTAL car pt. . Forecast demand ODEMANDMW = 2. This variant is particularly useful when the costs do not change for all modes. Input base demand by BASEDEMANDMW = 10. Input CHANGE in cost (= ForecastCost . . . Forecast demand ODEMANDMW = 2. 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. Input forecast costs UTILITIESMW = 30. The example excludes the calculation of incremental composite costs. the change in car utility. Car Utilities are unchanged. there is no need to calculate the car utility for each test. . List choices ALTERNATIVES = car. . . 420 Cube Voyager Reference Guide . 11. Model Structure SPLIT = TOTAL car pt. 21. Instead.3. . In this case. . Input base demand by mode BASEDEMANDMW = 10. Input base costs by BASEUTILSMW = 20. Cube Voyager Reference Guide 421 . bus and train. 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. In this model the process begins in the PT nest. Structure of hierarchical logit model Hierarchic models group related choices together in nests (or hierarchies). which can be implemented in Absolute or Incremental form. Working matrices STARTMW = 100 Hierarchical logit model This section describes the hierarchical logit 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 example. In an absolute model.Matrix Program Using the Matrix program 9 . This is an example of a Hierarchical Logit Model. bus and train are members of the public transport nest that is considered to be distinct from the (private) car mode. using the equations of the Incremental Logit Choice Model. A scale parameter must be associated each nest. the resulting probabilities are calculated. the calculations are again performed in two stages. the scale parameters are λ=0. 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.03 in the lower nest. bus and train). The first pass calculates conditional probabilities and composite costs working up the tree structure. the model’s sensitivity to cost increases down the hierarchy. 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.9 Matrix Program Using the Matrix program Firstly. That is to say. then in the second pass working down the tree. 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. Cost-based examples of hierarchic logit models As before the total demand is specified together with generalized costs for each choice (car. The composite PT cost will be used next to represent the cost associated with the combined PT choice. so that: For incremental models.02 in the upper nest (consistent with the previous example) and μ=0. In this example. Matrix script 422 Cube Voyager Reference Guide . Working matrices STARTMW =70 First the modes (car. . Input demand DEMANDMW = 1. Model Structure .16.03 XCHOICE. Forecast composite cost PT level SPLITCOMP = 20. The input total demand and costs for the three distinct modes are given first.02. . The hierarchical structure is specified by moving down the tree describing each nest. followed by the output forecast demand by mode. this is the name given to the combined choice of bus and train. . List choices ALTERNATIVES = car bus train. Absolute hierarchical logit model . Forecast composite cost top level SPLITCOMP = 19.02 mu = 0. PT nest SPLIT = PT mu bus train .15. 6. .Matrix Program Using the Matrix program 9 The example below shows how the earlier absolute-choice example can be extended to include the lower nest in the hierarchy: . bus and train) are declared with the ALTERNATIVES clause. 5. Forecast demand ODEMANDMW = 14. Notice that PT is not declared as an alternative. . Beginning at the top of the tree. Input costs COSTSMW = 4. . the first split command divides TOTAL (the total demand) into car and (all) PT with scale parameter λ=0. . . Specify scale parameters lambda = 0. Top level nest SPLIT = TOTAL lambda car pt. Notice that a scalar variable called lambda has been used to Cube Voyager Reference Guide 423 . Then the model inputs and outputs are specified. For example. with park and ride abbreviated as pandr. Another SPLITCOMP keyword for this SPLIT keyword computes the composite costs specific to the PT nest. Input demand DEMANDMW = 1. and heavy rail as hrail: . More complex absolute hierarchical models The hierarchy can be extended with additional nests on either side of the tree. but as a link with the lower nest. The second split command sub-divides PT trips between the bus and train alternatives using a scale parameter μ=0. List choices ALTERNATIVES = car pandr bus hrail lrt metro. in this case the top level. park and ride.9 Matrix Program Using the Matrix program represent the scale parameter in this case. PT is not considered as an individual mode now. The SPLITCOMP keyword computes the composite costs for the nest associated with this SPLIT. a large absolute hierarchical logit model structure might have six choices: car. Extract from a large absolute logit model XCHOICE. heavy rail. Structure of a large absolute hierarchical logit model Matrix script illustrating the complex example This example may be codes as an absolute model as below. . bus.03. and metro. 424 Cube Voyager Reference Guide . . and this acts as a link to the next level up the tree (where total demand was divided between car and PT). light rapid transit (LRT). The name pt is used as the first value in the SPLIT clause. Model Structure . and fare) and for scale parameters. and must not exceed 1.03 bus train. the scale parameter must be greater than 0.23. Input costs COSTSMW = 11. the scale parameters of utility-based models are viewed as part of the specification of the output of a split process. .02 allcar allpt. 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. and a number of sub-nests. Matrix script illustrating two-level hierarchy Cube Voyager Reference Guide 425 .26. 15. .22.0 there is no need to specify its value as this the assumed default.Matrix Program Using the Matrix program 9 . 14. there is a requirement that higher level nests are less sensitive to cost differences than any sub-nests which lie below them. Thus. Top level nest SPLIT = TOTAL 0. .0. All PT nest SPLIT = allpt 0. Train nest SPLIT = train 0. Forecast demand ODEMANDMW = 21. Where the scale parameter for a sub-nest is 1. Where a scale parameter applies to two or more sub-nests.25. and different values may apply to each sub-nest in a choice nest. so avoiding repetition of the parameter.04 hrail lrt metro.24. 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. 12. . 13. . In the estimation of the utility equations used in the choice model coefficients are estimated for individual cost-terms (such as travel time. . To meet the sensitivity requirements noted above. 16.05 car pandr. As with cost-based models. it may be specified once and brackets used to group the relevant sub-nests. All car nest SPLIT = allcar 0. Then the model inputs and outputs are specified. 5. . .6 is applied to the PT sub-nest when its composite (or logsum) utility is used in the calculations of the higher-level nest. List choices ALTERNATIVES = car bus train. Forecast demand ODEMANDMW = 14. . . PT nest SPLIT = PT bus train . Absolute hierarchical logit model XCHOICE. Working matrices STARTMW =70 First the modes (car. . PT sub-nest has scale parameter 0. 6.16. Forecast composite cost for the PT nest SPLITCOMP = 20.9 Matrix Program Using the Matrix program Using the tree structure shown in “Structure of hierarchical logit model” on page 421 as the basis of an absolute choice model.15.6 SPLIT = TOTAL 1. Input demand DEMANDMW = 1. followed by the output forecast demand by mode. Top level nest. A scale parameter of 0. The input total demand and utilities for the three distinct modes are given first. the total demand is specified together with the utility of each choice (car. Notice that PT is not declared as an alternative. bus and train) are declared with the ALTERNATIVES clause. Forecast composite cost for the top level SPLITCOMP = 19. .6 pt. . bus and train). this is the name given to the combined choice of bus and train. Input costs UTILITIESMW = 4. Model Structure . . 426 Cube Voyager Reference Guide . The hierarchical structure is specified by moving down the tree describing each nest. .0 car 0. Matrix Program Using the Matrix program 9 Beginning at the top of the tree. Model Structure . . PT is not considered as an individual mode now.25. 5.22. . . 2.6 which applies to the PT sub-nest. The composite cost for this SLIT are output with another SPLITCOMP keyword. . The example below is coded below in incremental form using utility differences: .0 bus 0. 4. but as a link with the lower nest. 15. The composite costs for this SPLIT are output with SLITCOMP. and this acts as a link to the next level up the tree (where total demand was divided between car and PT). Base demand BASEDEMANDMW = 1. .23. All car nest SPLIT = allcar car pandr.667 allpt. 13. the first split command divides TOTAL (the total demand) into car and (all) PT. The second split command sub-divides PT trips between the bus and train alternatives. Utility differences DUTILSMW = 11. Working matrices STARTMW = 45 Cube Voyager Reference Guide 427 . . 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.4 allcar 0. 16.75 train. but no scaling parameters are used.24. 3. and specifies a scale parameter of 0. Train nest SPLIT = train hrail lrt metro. . 12. . List choices ALTERNATIVES = car pandr bus hrail lrt metro. 14. All PT nest SPLIT = allpt 1. . The name pt is used as the first value in the SPLIT clause. Forecast demand ODEMANDMW = 21. Extract from a large absolute logit model XCHOICE. 6.26. Top level nest SPLIT = TOTAL 0. 9 Matrix Program Using the Matrix program In this example a scale parameter of 0. denote the choice of destination 1..667 to the all-PT sub-nest and 0. 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. destination 2 and so on. also 0. where d1. 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. 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: 428 Cube Voyager Reference Guide ..4 is applied to the all-car subnest. d2.75 to the train sub-nest. Destination choice This section describes the destination-choice model. and uses the incremental choice equations with alternative modes replaced by different destination zones. Cube Voyager Reference Guide 429 . . the base situation matrices of demand and cost (or cost differences) are also input rather than total travel demand.Specify choice parameter lambda = 0.Simple destination choice model . Matrix script The destination choice model described above is coded in the script below. the destination choice model takes the form: The incremental forms of logit choice model is also supported. In this model. For absolute utility-based models. Input cost matrix COSTSMW = 3. The clauses defining data input reflect the data required by the model. the choices are destination zones. Alternatives (only one. Its underlying theory is similar to the equations in the incremental logit model. 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. The incremental model is more widely used in studies than the absolute formulation. Input demand from each origin DEMAND = TripsFromI[i].Matrix Program Using the Matrix program 9 Where λ is the scale parameter. but with alternative modes replaced by destination zones.01 XCHOICE. as doing destination choice) ALTERNATIVES = all . In this case. The incremental logit model is also supported. . for examples UTILITIESMW (utilities) and DUTILSMW (differences in utilities). . Mode and destination choice This section discusses the mode-and-destination-choice model. . This section considers first mode followed by destination choice. Forecast demand from each origin to each destination ODEMANDMW = 7 . The output from the split clause is the alternative “all. The outputs are a forecast demand matrix. Topics include: • • • Introduction Mode followed by destination choice Destination followed by mode choice Introduction The XCHOICE command supports both mode and destination choice in the same structure. This is followed by the model inputs. Working matrices STARTMW = 20 The extract begins with the specification of alternatives. and no use of lambda. Model Structure DESTSPLIT = TOTAL lambda all. the scale parameter. The main differences for utility-based scripts are use of utility keywords (UTILITIESMW being used in place of COSTSMW ).” as listed on the ALTERNATIVES keyword. in this case the demand is an array of trips from each zone and the generalized cost is matrix MW[3]. so that the DESTSPLIT clause now becomes DESTSPLIT = TOTAL all. A scale parameter of λ=0. which comprises just one alternative as we have no choice between modes. 430 Cube Voyager Reference Guide . The structure of this model is defined by the DESTSPLIT clause which defines a destination choice process. then destination followed by mode choice. MW[7].01 has been chosen for this example.9 Matrix Program Using the Matrix program . car and PT. which reflect sensitivity to cost differences. d2. The figure illustrates a system with two modes..03 for car and PT respectively.01. Specify choice parameters lambda = 0. .Matrix Program Using the Matrix program 9 Which form of model is appropriate for a study is determined during model calibration. determine which form is used.. 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. Mode choice above destination choice model . The parameters for destination choice are μ=0. then across destinations for each mode individually. The model structure specification splits the total demand by mode first with scale parameter λ=0.03 XCHOICE. The values of scale parameter for the various choice nests.02 and θ=0.02 theta = 0. Mode followed by destination choice Consider first an example of mode followed by destination choice..01 mu = 0. and 100 destination zones (labelled d1. Cube Voyager Reference Guide 431 . 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).. Destination followed by mode choice The total input demand is first by destination (into a matrix). Model Structure Mode choice SPLIT = TOTAL lambda destcar destpt Car destination choice DESTSPLIT = destcar mu car.. Forecast demand matrices by mode ODEMANDMW = 31. .32. and 100 destination zones (labelled d1. d100). Base Costs BASECOSTSMW = 11. . d2. Forecast costs COSTSMW = 21. car and PT. Base Demand BASEDEMANDMW = 1. which is then split by mode (giving two matrices representing car and PT demand). . Working matrices STARTMW=110 Destination followed by mode choice Now consider the case of destination followed by mode choice.12. .. 432 Cube Voyager Reference Guide . List choices ALTERNATIVES = car pt.9 Matrix Program Using the Matrix program . PT destination choice DESTSPLIT = destpt theta pt.22. The figure illustrates such a system with two modes... . . . . .2. 5 distribution. DUTILSMW = 16. Forecast demand matrices by mode ODEMANDMW = 21.12. The mode-choice sub-nests has scale parameters of 0. .” This name. and the intermediate matrix is identified by the name “distribution. the model structure specification splits the total demand by destination. a rail mode might not be a practical alternative for travel between all zones in the study area. . Destination followed by mode choice model XCHOICE. .17. . . Model Structure .Matrix Program Using the Matrix program 9 Matrix script Starting from the top. Destination choice DESTSPLIT = TOTAL 0. Large in this context is Cube Voyager Reference Guide 433 . Mode choice SPLIT = distribution car pt.22. 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. Input base demand and utility-difference matrices BASEDEMANDMW = 11. List choices ALTERNATIVES = car pt. distribution. .5. For example. To make a choice unavailable you should give that choice a large positive generalized cost (or large negative utility). . is then used as the link (or input) to the lower choice nest. but the sensitivity (and so cost-coefficient) varies between segments.. In some instances the model structure is common to all segments. endif For simple choices between alternative modes. as needed . . 434 Cube Voyager Reference Guide . For example. the following provides guidance on techniques used. Under these conditions. rather than the entire matrix. When a XCHOICE control statement occurs in the Matrix program it will typically be applied to all cells (or origin-destination pairs). through trips etc. the cost coefficient may be specified as a matrix (such as MW[5]. . and different choice models apply to these different segments. or mi. then apply the model XCHOICE. if costs are up to 400 generalized minutes. or the user wishes to apply the choice model separately for each segment.apply the model to trips from zones 1-45 to zones 46-53 if (i < 45) JLOOP INCLUDE = 46-53 XCHOICE. to select particular rows and columns of the matrix where the choice model is applied: .. .1.coefficient) rather than a scalar value. subsequent clauses of XCHOICE statement... . try using a cost of 40000 minutes to make a particular choice unavailable. Where the model structure varies between segments. test to see if model applies to this origin zone if (i < 45) . by use of the JLOOP command. this may be extended. 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. The XCHOICE control statement may be coded inside a conditional test which selects the origin zones it is applied to: . as needed .9 Matrix Program Using the Matrix program 100 times greater than typical costs. if so. These typically arise when matrices can be broken down into distinct segments (such as trips entirely within study area.). subsequent clauses of XCHOICE statement. Practical considerations: Scale parameters For models calibrated in terms of generalized costs to give sensible results. test to see if O-D meets selection criteria for the segment if (mi. That is to say. . Where these conditions are not met. If this effect is a problem. but is determined by some other matrix attribute (such as distance from origin to destination). This is made clear if one examines the equation in the “Incremental logit model” on page 415.start a JLOOP to process each origin-destination pair in turn JLOOP . the forecast demand for that choice will always be zero. if so. Cube Voyager Reference Guide 435 .distance > 50) .. as needed . where. 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.Matrix Program Using the Matrix program 9 ENDJLOOP endif Where the choice model applies to a segment which is not a regular set of rows and columns. Practical considerations: Incremental models In an incremental model. 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.. if Pcar=0 then P’car=0 whatever costs are given.1. if the base demand for a choice is zero. then the modelling approach should be reviewed. a script may be coded as follows: . subsequent clauses of XCHOICE statement. then apply the model XCHOICE. an error message will be output. endif ENDJLOOP Where a model seeks to use destination choice. . the model’s sensitivity to cost increases down the hierarchy. ELSEIF . 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..1) Compute variables from expressions Continue at end of loop statement Terminate current program Input files Output files Set path for temporary files Fill work matrices Accumulate distributions of one matrix versus another Immediate jump to :label Define IF ENDIF block Define a loop for destination zones (J) Define lookup tables (see Chapter 3... ELSE ..” for details) Set zone renumber specifications Select standard reports Set multiple variables/arrays to same value 436 Cube Voyager Reference Guide ... “General Syntax”) Define user controlled loop Set static parameters Print variable values Print a row of a matrix (see Chapter 3... “General Syntax. or series of sorted arrays using a binary search. ENDIF JLOOP ...9 Matrix Program Control statements Control statements The following control words are available in the Matrix program. ENDJLOOP LOOKUP LOOP . Control word ABORT ARRAY BREAK BSEARCH CALL CHOICE COMP CONTINUE EXIT FILEI FILEO FILET FILLMW FREQUENCY GOTO IF . Call user’s dll (external process) Implement logit choice models (prior to v4. the program detects walk access and drive access between the same zone pair. but you know that this should not occur. Intrazonal present in MW[1] INTRA = MW[1][I] IF (! INTRA) LIST='No intrazonal value for MW[1] at Zone '. 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. I ABORT ENDIF ARRAY Programs: Distribution. you can use this statement to terminate processing due to some detectable conditions. Fratar. VAR=n. VAR=n-str Cube Voyager Reference Guide 437 . MSG Use ABORT to terminate the program and return a fatal code to Cube Voyager. Though not normally used. For example.1) ABORT Programs: Distribution. Generation. Matrix Aborts the entire run. Generation. suppose that during a mode-split process. Fratar.Matrix Program Control statements 9 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. Example IF (MW[1][I] != 0) ABORT . Matrix Declares user single-dimension arrays. The size n defines the dimension of the array. ARRAY statements are not dynamic (stack oriented).9 Matrix Program Control statements Use ARRAY to allocate user arrays. 438 Cube Voyager Reference Guide . The size following the keyword is the highest index possible for VAR. the most common use may be to store information for specific zones. Values stored to arrays in this program can be numeric or string. n. When an array is referenced. Designate an array as a string array by appending a dash followed by the string size. to the array size. n. defines a string array with size of 1000 and a character width of 5. Example ARRAY sum_mat=10. Arrays are cleared when they are allocated. and if the index exceeds the size. Size may be either a numeric constant. and an appended -str defines the array as a string array and sets the string length. str. they are allocated prior to any stack operations.51-58.96) cbd2ext[I] = cbd2ext[i] + MW[1] include=501-535 ARRAY row_total=zones . ARRAY keyword Keyword VAR |I| Description Name of the variable that is to be allocated according to the specified size. example of defining a string array ARRAY StrArray=1000-5 . all the cells in the array are set to the same value. the program will fatally terminate. When an array variable appears in a SET statement. VAR must be a unique name. or a special name—ZONES. it must include an index [ ]. An array is different than a variable in that it represents vectored data.63. either numeric or string. Arrays can be useful for different processes. cbd2ext=500 IF (M <= 10) sum_mat[M] = sum_mat[M] + rowsum(M) IF (I=1-10. Matrix Program Control statements 9 BREAK Programs: Distribution. stack processing for the I zone is terminated but output and zonal reporting statistics will not be bypassed. Example LOOP L1=1.88 IF (condition) BREAK . the search will begin at the first Cube Voyager Reference Guide 439 . ..L2+5 IF (condition) BREAK. ARRAY=value. If there are multiple arrays specified. The format is: BSEARCH ARRAY=value... .K2. 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). 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. Fratar. jump to LOOP L3= ENDJLOOP LOOP L3=L2. Generation. control immediately passes to the stack statement after the associated end of loop.KINC JLOOP EXCLUDE=25-50. The routine will do a binary search to expedite the search for the key. Otherwise. ARRAY |N| is the name of a user array that is in ascending sort. jump to IF statement ENDIF ENDLOOP IF (condition) BREAK . Matrix Use BREAK to break out of a loop. When encountered.3 IF (condition) statements ELSE BREAK .. no more processing for this origin zone LOOP L2=K1. 9 Matrix Program Control statements 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 Programs: Distribution, Fratar, Generation, Matrix Executes an external routine. DLL 440 Cube Voyager Reference Guide Matrix Program Control statements 9 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:*). Cube Voyager Reference Guide 441 9 Matrix Program Control statements 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. 442 Cube Voyager Reference Guide Matrix Program Control statements 9 • 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; } Cube Voyager Reference Guide 443 9 Matrix Program Control statements 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 444 Cube Voyager Reference Guide Matrix Program Control statements 9 • 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 Cube Voyager Reference Guide 445 9 Matrix Program Control statements 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 446 Cube Voyager Reference Guide Matrix Program Control statements 9 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. Cube Voyager Reference Guide 447 9 Matrix Program Control statements CHOICE keywords: Utility-based models Keyword ALTERNATIVES Description Lists the set of discrete choices in the forecast scenario. If the model is confined to destination choice, then the alternatives list comprises just one item (representing the demand matrix). The names used in the alternatives list are subsequently used in SPLIT or DESTSPLIT commands which define the structure of the logit-choice model, and also determine the order that input or output data are specified. Supplies the names of the base-demand variables. For incremental models only. For lists of two or more variables, the order must match that in the ALTERNATIVES clause. Supplies the names of the base utilities for the various alternatives. For lists of two or more variables, the order must match that given in the ALTERNATIVES clause. This clause is only used in incremental models which specify base and forecast utilities (as opposed to utility differences). The corresponding forecast costs are specified using the UTILITIES clause. DEMAND Specifies the total demand for an absolute model. Demand is typically a matrix, although numeric values may be specified. For example, a demand of 100.0 will give output demand corresponding to the percentages which choose each alternative. Use the DESTSPLIT clause when the nest in the hierarchy corresponds to a destination-choice model. It divides the travel demand between destination zones, rather than alternatives. The output list must comprise just one item, representing either a distinct choice from the ALTERNATIVES clause or an output which links to a subnest. This output item may be preceded by a scale parameter. The following example applies a scaling factor to the ModeSplit logsum utility, and performs a destination choice dividing the total trips across all destinations: DESTSPLIT = TOTAL 0.9 ModeSplit, BASEDEMAND BASEUTILS DESTSPLIT (INCLUDE, EXCLUDE) By default the destination-choice model works over all zones. By using the INCLUDE or EXCLUDE subkeyword clauses the choice process may be restricted to a sub-set of all zones. The following example restricts destination choice to zones 1 to 23: SPLIT = TOTAL, allTrips, INCLUDE = 1-23, NOTE: Certain restrictions apply to the use of destination-choice models. The composite utilities cannot be saved, and this form of logit model may not be used inside a JLOOP. 448 Cube Voyager Reference Guide Matrix Program Control statements 9 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 Cube Voyager Reference Guide 449 9 Matrix Program Control statements CHOICE keywords: Utility-based models (continued) Keyword SPLIT Description The structure of the logit choice model is specified by the SPLIT and DESTSPLIT clauses. One of these clauses is required for each nest (or subnest) in the model hierarchy. For a hierarchic model, these are typically specified starting at the top-level and working down the structure. Each SPLIT clause specifies an input, and one or more outputs which may have their own scale parameters. (A choice with only one output may be specified to apply a scaling factor to a sub-nest logsum utility, and so achieve consistent scaling at all equivalent levels in a complex hierarchic structure.) The input (or first item listed in a SPLIT clause) may either be TOTAL (representing the total demand at the top level of the choice hierarchy) or for subnests it is the name of an output from the appropriate higher level nest. The remainder of the SPLIT clause define the output list, and any scale parameters which apply to subnests. The main items in the output list represent either distinct choices (from the ALTERNATIVES clause), or links to sub-nests which are given unique meaningful names and used as inputs to lower splits. An example is: SPLIT = AllPT Bus Rail, Subnests in the output list may be preceded by a scale parameter, which is applied to the composite (or logsum) utility of the subnest before evaluating this choice nest. The scale parameter should be greater than 0, and must not exceed 1.0. The scale parameter may be omitted where its value is 1.0, as this is the assumed default. Examples are: SPLIT = TOTAL Car 0.5 PT 0.4 WalkCycle, where scale parameters are applied to the PT and walk/cycle subnests. Car either is a distinct alternative, or a subnest with a default scale parameter of 1.0. Where the same scale parameter applies to several subnests, the scale parameter may be specified once followed by the list of relevant subnests grouped together by use of brackets. An example is: SPLIT = TOTAL, 0.4 Car 0.5 (Bus Rail), where the bus and rail subnests share the same scale parameter, and a different value applies to the car subnest. 450 Cube Voyager Reference Guide Matrix Program Control statements 9 CHOICE keywords: Utility-based models (continued) Keyword STARTMW Description The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the CHOICE command. The STARTMW clause specifies a numeric value corresponding to a particular working matrix which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the CHOICE command, and should not be used elsewhere in the script. Where a Matrix script contains several CHOICE commands, the same STARTMW value may be used in all instances. Specifies forecast utilities. If there is more than one utility, their order must be the same as that used in the ALTERNATIVES clause. See also BASEUTILS and DUTILS (utility-differences) for incremental models; the UTILITIES clause is not used in conjunction with DUTILS. UTILITIES XCHOICE Program: Matrix XCHOICE implements a logit choice model. XCHOICE replaces the CHOICE command statement, resulting in improved run times. Though you can continue to use CHOICE, Citilabs recommends using the XCHOICE command statement for logit choice models. Usage is similar with XCHOICE, but there are some differences in keyword usage and in value formats for keywords. See “Summary of syntax usage differences between XCHOICE and CHOICE” on page 458. ALTERNATIVES COSTSMW BASECOSTSMW DCOSTSMW UTILITIESMW BASEUTILSMW DUTILSMW Cube Voyager Reference Guide 451 9 Matrix Program Control statements DEMANDMW DEMAND BASEDEMANDMW ODEMANDMW SPLITCOMP SPLIT (COEFF, SPLITINTO SPLITCOMP) DESTSPLIT (COEFF, SPLITINTO, INCLUDE, EXCLUDE) STARTMW Use the XCHOICE command to implement logit choice models, based on either generalized costs or utilities. The actual keywords supported depend on whether you use cost-based or utility-based models: • • XCHOICE keywords: Cost-based models XCHOICE keywords: Utility-based models XCHOICE keywords: Cost-based models Keyword ALTERNATIVES Description Lists the set of discrete choices in the forecast scenario. If the model is confined to destination choice, then the alternatives list comprises just one item (representing the demand matrix). The names used in the alternatives list are subsequently used in SPLIT or DESTSPLIT keywords which define the structure of the logit choice model, and also determine the order that input or output data are specified. Supplies the names of the base cost matrices. For lists of two or more matrices, the order must match the list of choices given in the ALTERNATIVES keyword. This keyword is only used in incremental models which specify base and forecast costs (as opposed to cost differences). The corresponding forecast costs are specified using the COSTSMW keyword. BASEDEMANDMW Supplies the names of the base demand matrices. For incremental models only. For lists of two or more matrices, the order must match that in the ALTERNATIVES keyword. BASECOSTSMW 452 Cube Voyager Reference Guide Matrix Program Control statements 9 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. Cube Voyager Reference Guide 453 9 Matrix Program Control statements XCHOICE keywords: Cost-based models (continued) Keyword SPLIT (COEFF, SPLITINTO, SPLITCOMP) Description The structure of the logit choice model is specified by the SPLIT and DESTSPLIT keywords. One of these keywords is required for each nest (or subnest) in the model hierarchy. For a hierarchic model, these are typically specified starting at the top level and working down the structure. Each SPLIT keyword specifies an input, a scale parameter (or coefficient of cost), and one or more outputs. The coefficient and outputs may both be specified in the SPLIT keyword or specified using the COEFF and SPLITINTO subkeyword clauses. The input (or first item listed in a SPLIT keyword) may either be TOTAL (representing the total demand at the top level of the choice hierarchy) or for subnests it is the name of an output from the appropriate higher level nest. The coefficient is specified as the second item in the SPLIT keyword, or using the COEFF subkeyword. It may be specified as a numeric value, a variable, or even a matrix with differing values between origin-destination pairs. The latter is appropriate when the demand matrix comprises distinct segments (such as travel within study area, trips from cordon into study area, and through traffic) and these segments respond differently to cost differences. The remainder of the SPLIT keyword, or the SPLITINTO subkeyword define the output list. The items represent either distinct choices (from the ALTERNATIVES keyword), or links to sub-nests which are given unique meaningful names and used as inputs to lower splits. The following examples shows a subnest taking AllPT as an input and using a scale parameter of 0.3 to divide between bus and rail alternatives. Specified as a SPLIT keyword it takes the form: SPLIT = AllPT, 0.3, Bus, Rail, and using subkeywords it is: SPLIT = AllPT, COEFF = 0.3, SPLITINTO = Bus, Rail, The SPLITCOMP subkeyword specifies the working matrix to store the composite costs or composite utilities for the nest defined by its parent SPLIT keyword. 454 Cube Voyager Reference Guide Matrix Program Control statements 9 XCHOICE keywords: Cost-based models (continued) Keyword SPLIT (continued) Description Example: XCHOICE ALTERNATIVES = A,b,c, baseCOSTSmw = 2,3,4, COSTSmw = 2,3,5, basedemandmw=1,1,1, ODEMANDmw=6,7,8, SPLIT= Total 0.1 desta, destpt, SPLITCOMP=20, destSPLIT= desta 0.15 a, destSPLIT= destpt 0.15 pt, SPLIT= pt 0.2 B C, SPLITCOMP=21, startmw=30 MW 20 is composite cost of alternative "Total" MW 21 is composite cost of alternative "pt" STARTMW The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the XCHOICE command. The STARTMW keyword specifies a numeric value corresponding to a particular working matrix which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the XCHOICE command, and should not be used elsewhere in the script. Where a Matrix script contains several XCHOICE commands, the same STARTMW value may be used in all instances. XCHOICE keywords: Utility-based models Keyword ALTERNATIVES Description Lists the set of discrete choices in the forecast scenario. If the model is confined to destination choice, then the alternatives list comprises just one item (representing the demand matrix). The names used in the alternatives list are subsequently used in SPLIT or DESTSPLIT commands which define the structure of the logit choice model, and also determine the order that input or output data are specified. Supplies the names of the base demand matrices. For incremental models only. For lists of two or more matrices, the order must match that in the ALTERNATIVES keyword. BASEDEMANDMW Cube Voyager Reference Guide 455 9 Matrix Program Control statements XCHOICE keywords: Utility-based models (continued) Keyword BASEUTILSMW Description Supplies the names of the base utility matrices for the various alternatives. For lists of two or more matrices, the order must match that given in the ALTERNATIVES keyword. This keyword is only used in incremental models which specify base and forecast utilities (as opposed to utility differences). The corresponding forecast costs are specified using the UTILITIESMW keyword. DEMAND DEMANDMW DESTSPLIT (INCLUDE, EXCLUDE) The demand value for a destination-choice or mode- and destination-choice model. The demand matrix for a pure mode-choice model. Use when the nest in the hierarchy corresponds to a destination-choice model. It divides the travel demand between destination zones, rather than alternatives. The output list must comprise just one item, representing either a distinct choice from the ALTERNATIVES keyword or an output which links to a subnest. This output item may be preceded by a scale parameter. The following example applies a scaling factor to the ModeSplit logsum utility, and performs a destination choice dividing the total trips across all destinations: DESTSPLIT = TOTAL 0.9 ModeSplit, By default the destination choice model works over all zones. By using the INCLUDE or EXCLUDE subkeywords the choice process may be restricted to a subset of all zones. The following example restricts destination choice to zones 1 to 23: SPLIT = TOTAL, allTrips, INCLUDE = 1-23, NOTE: Certain restrictions apply to the use of destination choice models. The composite utilities cannot be saved, and this form of logit model may not be used inside a JLOOP. DUTILSMW Gives the change in utility for each choice rather than the base and forecast utilities. For incremental models only. These utility-differences may be specified as matrices, or numeric values such as 0.0. Specifies working matrices (MWs) used to store the forecast demand; the list comprises a list of working matrix numbers. If there is more than one cost matrix, then the list must be in the same order as used in the ALTERNATIVES keyword. This command is optional, and may be omitted if only the composite costs are required. ODEMANDMW 456 Cube Voyager Reference Guide Matrix Program Control statements 9 XCHOICE keywords: Utility-based models (continued) Keyword SPLIT Description The structure of the logit choice model is specified by the SPLIT and DESTSPLIT keywords. One of these keywords is required for each nest (or subnest) in the model hierarchy. For a hierarchic model, these are typically specified starting at the top level and working down the structure. Each SPLIT keyword specifies an input, and one or more outputs which may have their own scale parameters. (A choice with only one output may be specified to apply a scaling factor to a subnest logsum utility, and so achieve consistent scaling at all equivalent levels in a complex hierarchic structure.) The input (or first item listed in a SPLIT keyword) may either be TOTAL (representing the total demand at the top level of the choice hierarchy) or for subnests it is the name of an output from the appropriate higher level nest. The remainder of the SPLIT keyword define the output list, and any scale parameters which apply to subnests. The main items in the output list represent either distinct choices (from the ALTERNATIVES keyword), or links to subnests which are given unique meaningful names and used as inputs to lower splits. An example is: SPLIT = AllPT Bus Rail, Subnests in the output list may be preceded by a scale parameter, which is applied to the composite (or logsum) utility of the subnest before evaluating this choice nest. The scale parameter should be greater than 0, and must not exceed 1.0. For utility-based models, if one alternative has a scalar, all others must also have scalars. For example: split=total,0.5,auto,1.0,pt, Scalars of 1.0 cannot be omitted in XCHOICE. Examples are: SPLIT = TOTAL 1.0 Car 0.5 PT 0.4 WalkCycle, where scale parameters are applied to the PT and walk/cycle subnests. Car either is a distinct alternative, or a subnest with a scale parameter of 1.0. Where the same scale parameter applies to several sub-nests, the scale parameter may be specified once followed by the list of relevant subnests grouped together by use of brackets. An example is: SPLIT = TOTAL, 0.4 Car 0.5 (Bus Rail), where the bus and rail subnests share the same scale parameter, and a different value applies to the car subnest. Cube Voyager Reference Guide 457 9 Matrix Program Control statements XCHOICE keywords: Utility-based models (continued) Keyword STARTMW Description The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the XCHOICE command. The STARTMW keyword specifies a numeric value corresponding to a particular working matrix which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the XCHOICE command, and should not be used elsewhere in the script. Where a Matrix script contains several XCHOICE commands, the same STARTMW value may be used in all instances. Specifies forecast utilities. If there is more than one utility, their order must be the same as that used in the ALTERNATIVES keyword. See also BASEUTILSMW and DUTILSMW (utility-differences) for incremental models; the UTILITIESMW keyword is not used in conjunction with DUTILSMW. UTILITIESMW Summary of syntax usage differences between XCHOICE and CHOICE In each XCHOICE, there must be one and only one case-insensitive “Total” in a SPLIT clause. “Total” is the starting node for mode split. All matrix valued keywords must end with MW. For example: • • UTILITIES is now UTILITIESMW COSTS is now COSTSMW DEMANDMW is only available to pure mode choice models where input demand is a matrix. In destination-choice or mixed modeand destination-choice models, use DEMAND instead. DEMAND in XCHOICE can be any of these values: • • • • • Constant Variable Array without index Array with constant index Array with variable index 458 Cube Voyager Reference Guide Matrix Program Control statements 9 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: Cube Voyager Reference Guide 459 The index n may be either a constant or a variable name. must be between one and Zones. It is used to compute variable and work matrix values. the program only solves the expression one time only. if not. OCOMPCOST and OCOMPUTIL in CHOICE are replaced by a new keyword SPLITCOMP in XCHOICE.1. COMP Programs: Distribution. 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. or 1. COMP keywords Keyword MW Subkeyword |KN| Description Value for a working matrix. Generation. VAR=expression MW[]=expression (INCLUDE EXCLUDE) The COMP statement is probably the most important of all the statements in the program. Matrix Computes a variable. 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. which can be used only on the upper most level of a nested mode choice structure. with J being the value of the loop’s current J.0.9 Matrix Program Control statements split=total. as indexed by n.5. matrix. or matrix element. Unlike OCOMPCOST and OCOMPUTIL. o. Fratar. The second index.pt. Scalar 1. with J being the loop’s J if within a JLOOP. Within a JLOOP statement.auto. • MW[n][o] — Defines the value for column o in row n. SPLITCOMP can be used on any level to get nest specific composite costs or composite utilities. but it cannot be omitted in XCHOICE.0. 460 Cube Voyager Reference Guide . The program solves the expression one time only.0 can be omitted in CHOICE. If the current J is on the list.. Always processed after INCLUDE subkeyword. the program does not evaluate or store the expression for that J. MW INCLUDE |IP| Optional. As the program internally loops on J. By default all zones are included. Specified values can range from 1 to the highest zone number. Filter applies to all MW[n] values on the COMP statement.. the program compares J to the values in the INCLUDE list..Matrix Program Control statements 9 COMP keywords (continued) Keyword MW Subkeyword EXCLUDE |IP| Description Optional. the program does not evaluate or store the expression for that J. If the current J is not on the list. ENDJLOOP block. Not permitted if COMP statement within JLOOP . ENDJLOOP block.. Cube Voyager Reference Guide 461 . By default no zones are excluded. Values of J included when computing the MW[n] expression. Specified values can range from 1 to the highest zone number. Not permitted if COMP statement within JLOOP . Filter applies to all MW[n] values on the COMP statement. As the program internally loops on J. Values of J excluded when computing the MW[n] expression. the program compares J to the values in the EXCLUDE list. because jkl is never used. INCLUDE and EXCLUDE may not be specified within a JLOOP block. no matter where they appear on the statement. The expression is solved one time for each encounter.name MI. 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 . xyz is declared a string The program does not always bother computing expressions for variables that are not used as input to some process. the filters apply to all MW[]= values. the variable must be a character string variable. messy -.T 462 Cube Voyager Reference Guide . the statements with jkl= might never be executed. In the above examples.n. invalid: xyz is declared a string (later) xyz = 'xyz' . Supported expressions Special Matrix variables: MW[] MI. with J being either one (not in JLOOP). or the value of the JLOOP J.matnum. and special matrix functions on the statement. EXCLUDE is processed after INCLUDE.9 Matrix Program Control statements COMP keywords (continued) Keyword VAR Subkeyword |KN| Description VAR is the name of a variable where the result of expression is to be stored.n.name.T MI.matnum MI.don’t mix types jkl = 1 . If a COMP statement includes any INCLUDE or EXCLUDE filters. If expression results in a character string. valid abc = abc+def . invalid: abc has been declared a string abc = abc+'456' . The name may be as long as desired (within reason).n. jkl is declared numeric jkl = xyz . All variables are assumed to be numeric variables.n. the retrieved cell will represent the value of the cell for the index to I. ZI. Value from the MATI[n]. the column index is computed. instead of the I-J value. Special cases for the above two MI formats. be careful! MW[Rexpression][Cexpression] is the value from any work matrix for zone Cexpression. For example: MW[1]="MI.name matrix.n. the column index is computed. If a column index is used. MI. Variable MW[Rexpression] Description Value from any work matrix.matnum matrix. spaces.T MI. This triggers a preprocessor program that will transpose the matrix. Transpose operation can only be applied to binary data.n. the zone index (not explicitly expressed) will be supplied as I.n. Thus.Matrix Program Control statements 9 The expression is a standard Cube Voyager numeric expression. then you must include the entire MI matrix reference in double quotes to recognize the name. and underscores (_). the column index (not explicitly expressed) will be supplied as J.n. Rexpression may contain nested MW[]. but there are also certain special variables names that may be used within it. The appended “. the column index (not explicitly expressed) will be supplied as J. If matrix names have spaces.1HBW TRIPS" MI. must be a constant.name matrix.n. MI.T ZI. MI.name.n.name Cube Voyager Reference Guide 463 .matnum.name[Cexpression] is a variation.n. The row index [n].T” indicates to use the transposed values for the matrix. The row index [n] and the matnum must be constants. the column index (not explicitly expressed) will be supplied as J.name[Cexpression] is a variation. the retrieved cell represents the J-I value.matnum Value from the MI[n].name MI.matnum[Cexpression] is a variation. the zone index is computed.n. Value from the ZDATI[n]. Valid matrix names contain only alphanumeric characters. exp. will cause a program error message. The function format has two advantages: coding is much easier. hi will be set to lo.01. Matrix function descriptions Function1 ARRAYSUM(array_name) LOWCNT Description Returns sum of an array (see “Examples” on page 534). Example: DUMMY = ROWFAC(3. For example: W[mw][I] = LOWEST(mw. In the following matrix function descriptions.5. sqrt—see “Expressions” on page 30 for more details). Lo and hi are inclusive values. max. you can use the max function to prevent this. and must be specified. and hi is not. Warning: Dividing by LOWCNT.9 Matrix Program Control statements The expression may contain the following special matrix row processing functions: ROWSUM() ROWCNT() ROWMIN() ROWMAX() ROWAVE() ROWFIX() ROWFAC() LOWEST() ROWADD() ROWMPY() ROWDIV() ROWREAD() In addition to the standard numeric expression functions (abs. and lo is supplied. some special purpose functions are available. the first argument (mw) indicates the work matrix to process.. ln. and should not be used within JLOOP blocks and MW[]= expressions. the function will return a zero.5) + ROWFIX(3) will factor matrix 3 and then integerize it. The matrix oriented functions process all cells in a matrix (subject to the restrictions of any INCLUDE and EXCLUDE lists). If “lo. Stores actual number of cells used in LOWEST. int. In some cases. Combining functions on a single statement is permissible. and processing is more efficient. If an invalid argument is detected by a function.LOWCNT)/ 2 464 Cube Voyager Reference Guide . without any diagnostics.1. Most of these functions could be duplicated with a combination of MW[]= statements. min. they will be processed in appropriate order. log.4. round.hi” is allowed.I) /max(1. if it is 0. Cube Voyager Reference Guide 465 . The cache size is specified by the PARAMETERS MATVALCACHE.lo. Because the arguments are dynamically set. However.) 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. F = MATI[#] M = Matrix # I=I J=J E = the value to return if the request for the cell is invalid. Use z to exclude specific zones. For example: K = matval(3. M.J.hi.1..-1) indicates to get the value from I to J from matrix 1 on MATI[3].hi) LOWEST(mw. The Matrix program maintains a cache of the matrix rows to try to help speed up the process. the more efficient the access will be. some types of processing will not be helped much by the use of the cache. or constant. Since all MWs are initialized to zeros.z. variable.. I. the program can not pre-edit the values. In general the larger the cache.#) LOWEST(mw.#.Matrix Program Control statements 9 Matrix function descriptions (continued) Function1 LOWEST (mw. Use lo and hi to exclude possible dummy zones that appear as zero in the row. E]) Returns random access values from MATIs (see “Examples” on page 534). the function can be slow in some cases and quite efficient in others.. Since this is direct access. the intrazonal cell (I) would be excluded. MATVAL (F.#. J [. normally. This exclusion is in addition to any on an EXCLUDE list. The range of arguments accommodates most situations. Each of the arguments can be an expression. use caution when applying LOWEST with no range specified.I.z. NOTE: LOWEST treats zeros as regular numbers.lo. sn) Description Add matrix mw[1] + … mw[sn] into mw[d] Same as: MW[d] = MW[s1] + MW[s2] + MW[sn] ROWAVE(mw) ROWAVE(mw. Integerize mw (start at column n.lo.s) ROWFAC (mw.n) Integerize mw (start at column intrazonal + 1.9 Matrix Program Control statements Matrix function descriptions (continued) Function1 ROWADD(d.lo.hi) ROWCNT(mw) ROWCNT(mw.hi) Average cell value for nonzero values Average cell value for nonzero values.. w/ rounding factor = 0) 466 Cube Voyager Reference Guide .fac) Factors the row by fac. Same as: MW[mw] = MW[mw] * fac ROWFIX(mw) ROWFIX(mw. with rounding factor = 0). 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.s1.. including only cells where: lo>=value<=hi Number of cells with nonzero values Number of cells with nonzero values. With a rounding factor of 0. It integerizes each cell after adding the rounding factor and the accumulated fractional portions from the previously treated cells.rnd) Description Integerize mw (start at column n. the lowest numbered zones never gets their fair share of the fractions. each cell is truncated and its fractional remainder is carried to the next cell. drops all fractional portions of the number). ROWFIX ensures the integer total is consistent with the original total. using specified rounding factor. With a rounding factor of 0. ROWMAX(mw) ROWMIN(mw) ROWMPY(d. The optional second argument specifies which cell the process is to end with.n. To eliminate this bias.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] Cube Voyager Reference Guide 467 . the default condition starts at the cell after the intrazonal cell and wraps around until the intrazonal cell is the last cell processed. rnd) ROWFIX integerizes the values in each cell of the matrix (that is. each cell is rounded to the nearest integer and the difference (original – rounded) is carried to the next cell.5.Matrix Program Control statements 9 Matrix function descriptions (continued) Function1 ROWFIX(mw. If the process always begins at zone 1. loop over the 20 matrices . external user program FILEO MATO[1]=Fixed_trips00. with random I zone order from . from I=1 to I=ZONES loop m=1. Allows for processing input matrix data not in I zone ascending sort order. in the input file x=ROWREAD(m.20 .mo=1-20.mat .lo. but include only cells where: lo>=value<=hi 1. read row for the . in the work matrix endloop endrun ROWSUM(mw) ROWSUM(mw.1. input matrix . I. mw is a working matrix number (that is. 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. MATI#.m) .I.hi) Row total Row total. Matrix automatically runs an ILOOP . dec=20*8 . M) Description Reads a random row from the input matrix and places it in the current row of the referenced working matrix. MW[1]) lo is the lo end of a range hi is the hi end of a range. current value of I and places it . defaults to lo if not specified 468 Cube Voyager Reference Guide .9 Matrix Program Control statements Matrix function descriptions (continued) Function1 ROWREAD(MW#. MW[22]=MI.8.K2.attr[j] * f1(mi. Use CONTINUE to immediately jump to the end of a loop. Matrix Jumps to end of loop. Otherwise. EXCLUDE=90.2. Example LOOP L1=1. bypassing all stack statements between it and its associated end of loop. Generation.3 MW[21]=MI. control passes to the appropriate ENDLOOP or ENDJLOOP statement. B=2.2. MW[13]=MI.1) .3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE . get total for mw[1] mw[2] = zi.Matrix Program Control statements 9 Example MW[2]=J MW[K]=MW[2] * MW[5] / SQRT(A*MW[3][MW[22]]) A=1. If it is within a LOOP or JLOOP block. no more processing for this origin zone LOOP L2=K1. will apply to all MW[]s= ABC=LOOKUP(DEF)*3 . MW[K][I%10+1]=ODD. sum A*F endjloop .KINC Cube Voyager Reference Guide 469 .452.47-93 MW[3]=5*A.1. MW[12]=MI.1. clear variables lookup name=f1.attr[j]*f1(MI.rowsum1 . stack processing for the I zone is terminated but output and zonal reporting statistics will not be bypassed.1.93. move input matrices to work areas MW[11]=MI.2.12.1. MW[4]=MW[3]*2. A * F's sumaf1 = sumaf1 + mw[2] . MW[23]=MI.1.12. INCLUDE=1-100.1. file=f1. Fratar.1. Next line is same process done with functions: rowsum1=ROWSUM(1) mw[2]=zi.3 JLOOP J=I MW[6]=J .1) sumaf1=ROWSUM(2) CONTINUE Programs: Distribution.401-500. store only at intrazonal column ENDJLOOP set var=sumaf1. MW[A]=A+B INCLUDE=1-5.2.1.txt JLOOP rowsum1 = rowsum1 + mw[1] . Matrix Exit the program before the end of zone processing Upon encountering EXIT. Example IF (expression) EXIT FILEI NOTE: See “FILEI” on page 44 for general information about FILEI and for important limitations when using Application Manager. jump to ENDLOOP for L3 . Generation. Matrix Selects input data files. Fratar. and goes to the end of I loop processing. Programs: Distribution. Generation. DBI (FIELDS name SORT DELIMITER AUTOARRAY MAXRECS JOINTODBI(JOINTOFIELDS)) LOOKUPI MATI (PATTERN FIELDS) RECI (FIELDS name SORT DELIMITER MAXERRS LISTERRS MAXRECS MAXSCAN) 470 Cube Voyager Reference Guide .9 Matrix Program Control statements JLOOP EXCLUDE=25-50.88 IF (condition) CONTINUE . ENDLOOP ENDLOOP EXIT Programs: Distribution.L2+5 IF (condition) CONTINUE . the program immediately terminates stack processing. Fratar. jump to ENDJLOOP . ENDJLOOP LOOP L3=L2. and zonal data files have names only.x or earlier and using the RECI/RECO keywords you may need to make some slight modification to your scripts for proper processing. it references the nth item in the vector. whereas zonal data is read prior to the initiation of the I loop. and MATI[5].n.name. file2. then you must include the entire MI matrix reference in double quotes to recognize the name. and must be in origin zone (I) order. ZI.3 indicates matrix number 3 on the MATI[1] file.. specified. MATI=.) will be treated as an error. it may have an additional subscript appended to it to specify a zone number.x series.name and ZI. the subscript references the column within a row. Data from these files is accessed via COMP statements. and for zonal data. If running scripts developed under v3.2. and need not be in any specified order. MATI[4]. For matrices.2.. and are identified as MI.Matrix Program Control statements 9 ZDATI (Z SELECT name (DEFAULT) AVE AVEX0 CNT FIRST LAST MAX MIN SUM) Note for v4.POP indicates the POP variable from ZDATI[6] file.6. and MATI[3]=name3. Zonal data can be viewed as having zones rows with one column per zone. Since it is required that ZDATI files have variables explicitly defined for them.n. other matrices have only numbers. the vector form of ZDATI (ZDATI=file1. Valid matrix names contain only alphanumeric characters. defaults to MATI[1].0 and later: Significant changes in RECI/RECO processing have been made from v3. Example: MI. or as Cube Voyager Reference Guide 471 . and underscores (_).name4. Cube Voyager matrices can have names and/or numbers.1. Refer to the descriptions below for the updated coding and comments on the processing.. For example: MW[1]="MI.name5 sets up MATI[3].. 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).1HBW TRIPS" On the FILEI statement the subscript is either explicitly. spaces. or implicitly. If matrix names have spaces. The n designates subscript of the file. name designates the matrix name or number. When an input file is used in an expression. each record containing all the variables in the element. or as data on ASCII or DBF type records. The Matrix program will not recognize any other file name as an EMME/2 data bank file. 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. those definitions are ignored.1. and DBI can point to elements in a multidatabase (MDB) file by designating the filename followed by a backslash and the element name.1. respectively. On the other hand. In the latter case.6. the file name must be emme2ban with no file extension. or in some cases. the Matrix program can read the scalar and vector matrices stored in the EMME/2 data bank file as zonal data records. If there is no subscript specified. if the field contains non-numeric data. ASCII type records are more subject to variation (empty fields.TRMTIME[I] and ZI. invalid values.3[I] accesses the intrazonal cell. ZI. If MATI specifies an EMME/2 data bank file. it doesn’t matter). In this case. 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). and the program is a bit more tolerant with them. Example: MI. it is treated as an error. Matrices can be input as either binary matrices. J will always be in the range 1-zones.9 Matrix Program Control statements one row having zones columns (user’s choice. 472 Cube Voyager Reference Guide . If the FILEI file keyword value is followed by variable definitions. RECI. The program will generate a temporary file of records.). and further processing of the record is terminated. To specify an EMME/2 data bank file. The Matrix program will not recognize any other file name as an EMME/2 data bank file. the values for the field are ignored. etc. then the file name must be emme2ban with no file extension. EMME/2 matrices stored in an EMME/2 data bank file. On a ZDATI file name. If ZDATI specifies an EMME/2 data bank file. cause a fatal termination. The FILEI file keywords ZDATI. PATTERN and FIELDS must be specified. If a J or M is out of range. the current value of J is used.TRMTIME[J] reference the origin and destination terminal times. #.fieldname. using the appropriate keywords.Matrix Program Control statements 9 FILEI keywords Keyword DBI Subkeyword |KF9| Description Name of a DBF file. If you specify an ASCII record file. (Indicate a single-column character with the hi column number the same as the lo column number. TITLE(C)=1 would define the variable named DI. If you specify a DBF file. Do not explicitly define the variables in the DBI statement.fieldname. Cube Voyager Reference Guide 473 . 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.) Define a field as a character variable by appending “(C)” to the name. Do not explicitly define the variables in the DBI statement.#. MDB data element. Indicate fixed format fields by using name=lo[-hi] or field=lo[-hi] syntax. Reference the field names in the MDB data element directly in the script as DI. or free format.name) in the DBI statement. For example. where lo is the first column number of the field and hi is the last column. Reference the field names in the DBF header directly in the script as DI.#. the program recognizes the file and the fields. ASCII record files are either a fixed format text file (fixed field locations and lengths). define all variables that you want the program to recognize (DBI. Indicate free format with field definitions containing a single number. the program recognizes the file and the fields.#.TITLE as a character variable. If you specify an MDB\element file and name. You must indicate which format is used in the definition of each field. 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. [0] will be revised during the SORT.name[0] is used.9 Matrix Program Control statements FILEI keywords (continued) Keyword DBI (continued) Subkeyword Description The following special variables are available for all file formats: DBI. Note that if the name is included in a SORT. such as DBA. where Index may be 0-DBI. 474 Cube Voyager Reference Guide .FIELDERRCNT — Cumulative count of errors for this field. DBI AUTOARRAY |S| Designates the name(s) of the field(s) that are to be stored in arrays with the specified name.#.TYPE=’C’) DBI.#. If you enter a value of “ALLFIELDS.#. See “More on DBI” on page 489.#. All the values (except Name and Type) are updated each time the record is processed.#.#.TYPE — Type of field (either ‘N’ for numeric or ‘C’ for character DBI. Each array is dimensioned as [DBI. You can provide a substitute value for invalid Index processes.#.name[Index].Name[0]=999999.#. the value at ARRAY[0] will be 0 for numeric fields and NULL for character fields.NFIELD — Numeric value for the field (0 if DBI.RECNO — Number of the currently processed record Different arrays are available. because the SORT routine uses that cell for temporary storage.” all the fields will be placed into arrays (no other names need be supplied).1.#.NUMRECORDS. You can reference each array as DBA.#.#.CFIELD — String value for the field (Null if DBI.NUMRECORDS — Number of data records in file DBI.#.FIELDERR — 1 if the field had a format conversion error DBI.NAME — Name of the field DBI.#.Name[0] = 'ERROR' or DBA.NUMFIELDS — Number of defined data fields DBI.#. If Index is less than 0 or greater than NUMRECORDS.#.TYPE=’N’) DBI. The arrays are: DBI. By default.# — String variable containing the full data record DBI. the value in DBA. An array for each named field will be generated and populated with values from the DBI records.1.NUMFIELDS]. Example Suppose you set a comma as field-separator and double quotes as an escape sequence: DELIMITER='. where t is used to designate a tab: DELIMITER[1]=" . USA Cube Voyager reads three fields: “ John Smith.” and “USA. Cube Voyager automatically removes leading spaces from all fields. brackets. The default value specifies single quotes. CA. 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 treats all subsequent data as part of the same record until it encounters the ending escape-sequence character. DELIMITER[1] specifies the field-separator characters. double quotes. Upon encountering the starting escape-sequence character. even if it encounters a field-separator character.” Cube Voyager Reference Guide 475 . CA". The default values are “ .” “Oakland. If you include a single space as the last character in DELIMITER[2].' '""' When reading the following input data: John Smith. "Oakland.t" DELIMITER[2] specifies escape-character sequences that permit field-separator characters in free-format records. parenthesis. the character that marks the start of an escape sequence along with the character that marks the end of an escape sequence.Matrix Program Control statements 9 FILEI keywords (continued) Keyword DBI Subkeyword DELIMITER |S2| Description Use to specify two different controls for free-format records. Cube Voyager will remove the leading and trailing character from any string it reads. and braces as escape character sequences: DELIMITER[2]="""''()[]{}" NOTE: You must enclose the entire value in double quotes or single quotes. The starting escape-sequence character in DELIMITER[2] cannot be a field-separator character in DELIMITER[1]. unless the field is enclosed in an escape-character sequence and DELIMITER[2] does not contain a space as its last character. Specify characters in pairs.t”. NFIELD[#]. then the SORT keyword must also be specified. All data fields must be defined in the same format. For example: FIELDS=1-5. If a data field (FIELDS= or name=) is defined by a pair of numbers (lo-hi). 476 Cube Voyager Reference Guide . You must also specify the JOINTOFIELDS subkeyword. The field names referenced by the SORT keyword define the join key. DBI.#.#.#. FIELDS=6. that sets the format as fixed. Optionally.NFIELD[7] will be obtained from fields 6 through 13 of the data records. FIELDS=6(C7) Specifies the same. FIELDS can specify multiple successive fields with a single specification (providing all fields are the same type.NFIELD[3] comes from field number 13.NFIELD[1] is in columns 1-5. N or C).#.NFIELD[3] is in 21-25.CFIELD[#] or as DI.13 Specifies that the data is in free format and defines DBI. If this keyword is present.FIELD# in script statements. For example: FIELDS=6(7) Specifies that DBI. You can reference these field values as DBI.21-25 Specifies that the data is fixed format and DBI.NFIELD[2] is in columns 6-10. If JOINTODBI is specified for a DBI file. only the fields specified will be extracted.#.6-10. and DBI.NFIELD[1]…DBI.NFIELD[2] comes from field number 9.#.NFIELD[1] comes from field number 6. but those fields would all be character values.#. Used only when the DBI records are fixed or free format. DBI. that sets the format as freeform.#. DBI JOINTODBI |I| Specifies the number of the input DBI file to join this DBI file to.9 Matrix Program Control statements FILEI keywords (continued) Keyword DBI Subkeyword FIELDS |IPV| Description An optional method for defining data fields in the input file.#. If a data field is defined by a single number (field number on the records).#. DBI. The values specify the columns or fields of the DBI file records where a desired field is located. and DBI.9. If the file is a DBF file. SORT=HHNO. along with other trip-related data fields. and TRIPNO. Cube Voyager Reference Guide 477 . which uniquely identify each person-trip record.Matrix Program Control statements 9 FILEI keywords (continued) Keyword DBI Subkeyword JOINTOFIELDS |SV8| Description Specifies the fields on the file referenced by JOINTODBI that corresponds to the join key fields identified by the SORT keyword. along with other household and person-level demographic data fields.DBF".DBF". the program treats both zero length and blank records as legitimate records. script statements that process a trip record are linked to the corresponding person-level data file. which uniquely identify the person record.PERSNO In this example. For example: FILEI DBI[1] = "TRIPRECORDS. DBI file 1 contains the person-level trip records from a travel survey. This file contains the fields HHID and PERSID. deleted records (flagged with a “*”) are not counted as records. PERNO. This keyword can have fewer referenced field names than the SORT keyword but cannot have more than the number of sort keys.PERSID JOINTODBI=1 JOINTOFIELDS=HHNO. If the DBI is not a DBF file.PERSNO TRIPNO FILEI DBI[2] = "PERSON. This file contains the fields HHNO. SORT=HHID. With the files joined. DBI MAXRECS |I| Limits the number of records read from the DBI file. Note that the key field name on which the join is performed does not need to match in the two files. DBI file 2 is a person-level survey record file. enabling trip-based computations to directly reference the household and person-level characteristics in the joined file. it is assumed to be an ASCII text file. that field is to be sorted in ascending order.1. If there is no leading sign. If the name has “(C)” appended to it. or there is a preceding plus (+) sign. If the records are in free format. There may be up to nine sort keys. that field is to be sorted in descending order. MINUTP. or Tranplan binary matrix file. MATI |KFV20| Specifies the input files with matrix data. PATTERN and FIELDS must be associated with the MATI. You can reference the variable in other parts of the script as DI. the variable type is numeric. See “Example of FILEI statements” on page 494 for an example of MATI usage when accessing an EMME/2 data bank file. or a pair of integers (separated by a dash). or a standard data base (DBF) file.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. You can reference input matrices from an EMME/2 data bank file in the script by matrix number.. DBI SORT |S9| Designates that the input records are to be processed in a specified sorted order. then the Matrix program will recognize the file as an EMME/2 data bank file. If the file specifies a Cube Voyager. If a sort name is preceded by a minus (-) sign. the variable type is character. the value will be lo-hi. For example if FILEI MATI[1]=’emme2ban’. where lo=hi=the column number of the data field. If the input file name is specified as emme2ban with no file extension. The value must be either a single integer.name. If the name has nothing—or “(N)”— appended. it must be designated as lo-hi. The values are the names of the variables that the sort is based upon. If it is not detected as one of those. the values must be single integers indicating the field number in the data record. if the field is a single column.9 Matrix Program Control statements FILEI keywords (continued) Keyword DBI Subkeyword NAME |IP| Description Name of a variable to extract from a text format record. the program will automatically detect it. then MW[1]=mi. TP+. If the input records in fixed format. You must index LOOKUPI. Name of file containing records for a lookup function implemented with the LOOKUP control statement. If it is not a binary matrix file. The value contains the location of that variable on the data record. LOOKUPI |FKV999| 478 Cube Voyager Reference Guide .#. Equivalent to the FILE keyword of the LOOKUP control statement. Ranges of variable format fields may be specified. For example: #4-6. The specification of FIELDS with implied matrix number will be shown in the example in the next section. A range of names (namename) may be used to specify a string of consecutive fields. Example: FIELDS=13.11-20-8. or as a group of three (beg-end-numflds) to indicate a series of equal length fields. For a PATTERN=IJM:V. for a record longer than 2047 bytes. If the first field value is a number. the format will be fixed. FIELDS=1-10-204 is OK. M is in column 10. the highest begin column number may not exceed 2047. pairs of numbers (beg-end). 21-30. For example.2. it indicates that the starting matrix number is not included in the input data. every field value must end with a number (only the first field value is required to have a leading non-digit).Matrix Program Control statements 9 FILEI keywords (continued) Keyword MATI Subkeyword FIELDS |S| Description Specifies the data fields to be read from an input record. A leading # is recommended for variable format. while FIELDS=1-10-205 will get a warning because the program is unable to read in the last field. J is in columns 6-8. If the MATI file is a database file. This limit is not applicable to variable format files. and the matrix number always starts at one for each record. the values in FIELDS must be names found in the dbf dictionary. the first field definition establishes the format. If the file is not a DBF. and eight data fields (each 10 characters wide) are in columns 11-20. the field values define the positions on the record where a data field is located. hence. Any one (and only one) format may be used to specify the fields.etc. 10.10. the format will be variable. (Note: When reading with fixed format. although any character string is acceptable. 6-8. The field values may be entered as single values (single column).13. implied. Cube Voyager Reference Guide 479 . if it begins with a letter (not a digit).) When the field value of M is set to zero. its format may be either fixed or variable. this example would indicate that I is in columns 1-3. With variable format. leading non-digits are ignored. The program extracts the number from the right end of the definition. With fixed format. J+2.J+1. and M I:JMV — I sets of J. There may be one M to specify the starting matrix number. and V I:MVJ — I sets of M.J+1. J. the last character in the base portion indicates which variable is incremented for each repeating set. The highest M that the program recognizes is 255. M. In the pattern definition: • There must be a single I. and V must be in the repeating portion.J+2.. The pattern has two portions separated by a colon: a base portion and a repeating portion... IMJ:V — I M J values for J. If there are multiple characters in the base portion. and J 480 Cube Voyager Reference Guide . matrix 1 is assumed. and V. and J I:VJM — I sets of V.. and M I:VMJ — I sets of V. • • Valid combinations are: IJ:V — I J values for J.M+1... M.9 Matrix Program Control statements FILEI keywords (continued) Keyword MATI Subkeyword PATTERN |S| Description Sequence of letters that specifies how the program processes the associated text or DBF MATI file. I must be the first letter in the base portion. J.M+2. V. If there is no M. IJM:V — I J M values for M. I:JV — I sets of J and V I:VJ — I sets of V and J IJ:VM — I J sets of V and M IJ:MV — I J sets of M and V IM:JV — I M sets of V and J IM:VJ — I M sets of J and V I:JVM — I sets of J. and V I:MJV — I sets of M. J. V. the reading continues from the beginning of the repeating portion of the PATTERN. If the values specified in FIELDS do not align correctly with the PATTERN. When the PATTERN is exhausted. Note that the data values need not be read in sequential order from the input records. If the FIELDS list is exhausted before the end of the PATTERN. See “More on MATI PATTERN” on page 490.Matrix Program Control statements 9 FILEI keywords (continued) Keyword MATI Subkeyword PATTERN (continued) Description This method allows Cube Voyager to read any commonly encountered input format. When reading a data record. reading is terminated without storing the last repeat value. This continues until the FIELDS list is exhausted. a warning message is issued. the program aligns the next FIELDS value with the next letter in the PATTERN. and extracts the data. It is necessary to have FIELDS specified in conjunction with PATTERN. The FIELDS values can be used to specify any order. The above examples assumed that the FIELDS values implied variable format and that there was an appropriate number of FIELDS values specified. Cube Voyager Reference Guide 481 . To define a variable as a character variable.9 Matrix Program Control statements FILEI keywords (continued) Keyword RECI Subkeyword |KF| Description Name of a DBF file. where lo is the first column number of the field and hi is the last column. The RI. If there are any RECO statements. 482 Cube Voyager Reference Guide . Only variables with the RO. or free format. When RECI is not a DBF or MDB file.prefix can be written to the RECO file.fieldname. an element in a multidatabase file. it is considered a text file (fixed field locations and lengths). this is accomplished by the definition of the first variable. The user can also specify the delimiters for free format records using the DELIMITER keyword.variables. If the file records are delimited (separated by a space or a comma or combination of both space and comma).variable attributes are ported to the corresponding RO. the program will recognize it and the field names in the DBF or MDB header can be referenced directly in the script as RI. the records will be considered free format.name) on the input file are automatically copied into equivalent RO. If that field definition is a single number. or if the file records are fixed format all variables that are to be recognized (RI. A single column character does need to have the hi column designated as the same as the lo column number. the variables should not be explicitly defined on the statement. the name has “(C)” appended to it. 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.name variables immediately when a record is read.name) must be defined in the FILEI RECI statement using the appropriate keywords described below. For example. If the file format is DBF or MDB. or an ASCII record file with either delimited or fixed format records. It is the user responsibility to indicate which format is to be used. For a DBF or MDB file. Fixed format variables are defined by use of the name=lo[-hi] or field=lo[-hi] syntax. all RECI variables (RI. NUMRECORDS — Number of data records on the RECI file RECI. RECI DELIMITER |S2| Use to specify two different controls for free-format records.NAME — Name of the field RECI. The PRINT statement allows the user to write out any portion of the input record plus any computed variables. As each RECI record is read. Thus.Matrix Program Control statements 9 FILEI keywords (continued) Keyword RECI (continued) Subkeyword Description The following special variables are available to the user for all file formats: RECI — String variable containing full data record RECI.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. the program enters a record processing loop instead of the traditional I Loop. Cube Voyager Reference Guide 483 . and FILEO MATO keywords should not be used. MATIs are not read unless a MATVAL function is used. See “More on RECI” on page 492 for some examples. Usage of DELIMITER is the same under both keywords.TYPE — Type of field (either ‘N’ for numeric or ‘C’ for character RECI. Each array is dimensioned as [RECI. it is processed against the script statement stack. The record processing loop sets I=1 and reads records until the end of file is found where it sets I=0.NUMFIELDS — Number of defined data fields RECI.TYPE=’C’) RECI.NUMFIELDS]. The arrays are: RECI. If a RECI statement is present.RECNO — Number of the current record being processed The program also makes four different arrays available to the user.NFIELD — Numeric value for the field (0 if RECI. To test on end of file the IF (I=0) condition can be used. For details. see DELIMITER description under DBI keyword on page 475. 0 and beyond.NFIELD[7] will be obtained from fields 6 through 13 of the data records. FIELDS can specify multiple successive fields with a single specification (providing all are the same TYPE. For example: FIELDS=15. If this keyword is present. Places a limit on the number of records to be read in from the RECI file.NFIELD[1] RECI.CFIELD[#] or as RI. RECI LISTERRS |?| RECI MAXERRS |I| RECI MAXRECS |I| 484 Cube Voyager Reference Guide . Default value is no limit.NFIELD[#]. These fields can either be reference as RECI. All data fields must be defined in the same format.NFIELD[1] is in columns 1-5.9 Matrix Program Control statements FILEI keywords (continued) Keyword RECI Subkeyword FIELDS |IPV| Description Only available in v4. FIELDS=6. RECI.NFIELD[3] coming from data fields number 6.NFIELD[2] RECI. If a data field is defined by a single number (field number on the records). 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 the user wishes to see more than 1000 error messages in the run print file then he must explicitly code the MAXERRS value desired. that sets the format as freeform.9. 13 respectively. FIELDS=6(7) specifies that RECI. The default setting will not return a fatal error message no matter how many errors are detected. that sets the format as fixed. Default value is F.FIELD# in stack statements. FIELDS=6(C7) would be the same.21-25 specifies that the data is fixed format and RECI. only the fields specified will be extracted. If LISTERRS=T then MAXERRS automatically defaults to MAXERRS=1000. Maximum number of errors allowed in reading the RECI records before a fatal error message is returned. Flag that indicates if errors should be listed to the run print file. 9. and RECI. Default value is no limit.NFIELD[3] is in 21-25. This is to prevent excessive listing of error messages to the run print file.6-10. RECI. N or C). If a data field (FIELDS= or name=) is defined by a pair of numbers (lo-hi).NFIELD[1]…RECI.NFIELD[2] is in columns 6-10. Optionally. The values specify the columns or fields of the RECI file where a field is located. but those fields would all be character values.13 specifies that the data is in free format and will define RECI. If there is no leading sign. Specifies the input files containing zonal data. appended. the variable will be considered numeric. 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. RECI NAME |IP| RECI SORT |S5| ZDATI |KFV10| Cube Voyager Reference Guide 485 . the number of records. the values must be single integers indicating the field number on the data record. There may be up to five sort keys. it must be designated as lo-hi. to designate where the variable will be obtained from each record. that field is to be sorted in ascending order. This control should not generally be used and was added primarily for internal Citilabs use. any fields from the record can be extracted and used by the program. if the field is a single column. If the input records are read in fixed format. I maybe save time if processing very large data files. and not really productive for very large files such as the census files. If a sort name is preceded by a minus (-) sign.Matrix Program Control statements 9 FILEI keywords (continued) Keyword RECI Subkeyword MAXSCAN |I| Description Allows the user to limit the file sampling for text records in order to reduce front end time on very large files. and there is no SORT specified. The value must be >= 10. the maximum length of each field. The values are the names of the variables that the sort is based upon. That could be quite time consuming. Aside from the zone number. etc. If it has nothing. or “(N)”. It can be referenced in all other parts of the script as RI.name. This value will be used only if the format is fixed. that field is to be sorted in descending order. Every zonal record must include a field that identifies the zone to which the record data applies. or a pair of integers (separated by a dash). the variable will be considered as character. or there is a preceding plus (+) sign. The program normally scans the entire file to obtain the longest record. Zonal data is data which is specific for each zone. If the name has “(C)” appended to it. the value will be lo-hi. if specified. There can be up to 10 zonal data files. Designates that the input records are to be processed in a specified sorted order. If the user is certain that all the records are the same length. If the records are read in free format. The value must be either a single integer. the use of this keyword can reduce front end time. where lo=hi=the column number of the data field. The program will not recognize any other file name as an EMME/2 data bank file. (Note: For files with more than one possible zone field from the list above. the program will try to determine the zone number field based on file type. DBF. The program will try to detect what type of file it is. All fields will be extracted and can be referenced. MDB. The field that contains zone number must be specified using 'Z=' keyword. If the file is an EMME/2 data bank file. by existing field names from the input file. where name is the EMME/2 bank matrix name for the origin. When the program detects a Cube Voyager network file.9 Matrix Program Control statements FILEI keywords (continued) Keyword ZDATI (continued) Subkeyword Description The file format can be: ASCII. MDB.) For Cube Voyager network files. it will assume ASCII. or a Cube Voyager network. EMME/2 data bank. 486 Cube Voyager Reference Guide . it is not necessary to name the fields to be extracted. or a Cube Voyager binary network. J. TAZ}. or scalar matrix. or by exact column positions on the records. To reference zonal data from an input Emme2 data bank file in the script. or a Cube Voyager network. the specified field will be used to extract zone number. it opens the node database portion of the file as zonal data.#. I. EMME/2 data bank. referred to as either an origin-based matrix (MO#) or a destination-based matrix (MD#) where # is the reference matrix number. MDB. node numbers (N) will be used as zone numbers by default. If 'Z=' is present. 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. The first matched name will be used to extract zone number. The specification of zone number field is optional for those two file formats. If the file is a DBF. use the standard zi. ZONE. Otherwise. then the file name must be emme2ban with no file extension. in the script. ZONA. destination. the fields to be extracted must be named and identified on the ZDATI statement by either relative field number. it is recommended to specify zone number field explicitly to ensure the correct field is used. referenced as MS#.name convention. For DBF or MDB files. EMME/2 data bank files store zonal data as a vector matrix. If the file is of ASCII format. If it cannot identify the file as a DBF. Bank files store scalar data (or constants) as a scalar matrix. See “Example of FILEI statements” on page 494 for an example of ZDATI usage when accessing an EMME/2 data bank file. Average of all records. 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. Maximum value of all the records. Count of the records that contain the variable. AVE AVEX0 CNT DEFAULT |SV| |SV| |SV| |R| Average of all records. Directly from the record from the FILEI with the highest index []. any variables that are not in any list will be set to LAST. Then. string valued arrays are not supported at this time. if there are no records for a zone.Matrix Program Control statements 9 FILEI keywords (continued) Keyword ZDATI (continued) Subkeyword Description In general. The values for the variables will be obtained only from file records that contain the variable. Minimum value from all the records. ZDATI ZDATI ZDATI ZDATI Cube Voyager Reference Guide 487 . 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. or the field is blank on a record. A variable may appear in only one keyword list. where the value from the file records is not 0. this value will be used. Value with which to initialize the array for the named variable. ZDATI ZDATI ZDATI ZDATI FIRST LAST MAX MIN |SV| |SV| |SV| |SV| Directly from the record from the FILEI with the lowest index []. the record is bypassed. If the first value is a number. These are all be valid. Alternatively. each name value MUST end in a number. SELECT[2] and [3] must both be numeric and should be separated by a dash. In most DBF cases. it designates the beginning column of the comparison field on the input record. Used to cause selective reading of zonal data records from ASCII files. otherwise. If the file is a dbf. or the columns (fixed format) where the variable is located on the record. SALES=xxx4. This selection is not used if SELECT is not specified. AREA=3.6-8 select only if columns 6-8=abc SELECT=1.9 Matrix Program Control statements FILEI keywords (continued) Keyword ZDATI Subkeyword name |S| Description Identifies a data variables that is to be extracted from each record. ZDATI SELECT |S3| 488 Cube Voyager Reference Guide . fixed format is assumed. but it is not necessary to keep the same names. SELECT=abc. That field is the comparison string. but ends with a number (first example). SELECT[2] specifies the input record field whose value is to be compared with the value of SELECT[1].#2 select only if a 1 in field no. if`SELECT[2] is not numeric. If SELECT[2] is a number. Example: Z=#1. it is assumed that the value indicates a relative field number on the data record. delimited format is assumed. It doesn’t matter what string precedes the number (the value need not be prefixed with a string). All names must be specified with the same format. the first name value (including Z) establishes the format. For text files. 2 ZDATI ZDATI SUM Z |SV| |S| Sum of all the records. Z is required only for ASCII files. because Z specified triggered delimited format.POP=#2 would be invalid because Z specifies fixed format. and if the comparison fails. If delimited format is specified. Only the variables named will be extracted. The program will compare a field from each record with the string specified in SELECT[1]. 'Z=' is a special case for 'name='. the value for each name is the name from the DBF dictionary.POP=#2. and SELECT[3] can be optionally specified to designate the ending column. the value assigned to name is either a field number (delimited format). Identifies where the zone number identifier is found on each data record. SELECT[3] is ignored if SELECT[2] is a free field definition. Z=15. name=name would be the standard. • • Cube Voyager Reference Guide 489 . any other value indicates the read was not 100% successful. You must check the return code. All the functions return a value to indicate the success of the operation. Several functions are available to read the records. DBISeek(#. or the return code will be 1.) where R is a value to search for in the field specified as SORT[1].#. The return values are: 0 — A match was found... but not more. specified relative to the current record. This function searches for the record that matches all the specified R values. R<1. For delimited files. You must write scripts to read the records. the required length is known.NUMRECORDS. R. DBIReadRecord(#.#. though DBIReadNext(#) is also allowed. The functions are: • DBIReadNext(#. and a positive R means after the current record. or R>DBI. there must be at least as many SORT values as there are R arguments. R must be 1 – DBI.1).. Write sequential reads as DBIReadNext(#. Use these functions in a COMP statement with the form: N=DBIfunc(DBI#..NUMRECORDS. More on DBI DBI files are not automatically processed. DBI# must always be the first argument. 1 — An error in setup occurred. A return value of 0 indicates a successful operation..Matrix Program Control statements 9 Caveat: The program establishes a buffer to read file records into. A negative R means prior to the current record. It has to know how long a buffer is required. the required length can not be estimated exactly. In order to use this function.R) where R indicates the record to read.. With DBFs and fixed format records. a dummy variable with a high field number can be specified to generate a larger record length.). but with delimited format. A return code of 1 indicates any of the following errors: bad #. If the estimated length is inadequate. the record length is estimated by multiplying the highest field number by 10.R) where R indicates the record to read. There may be fewer R values than there are SORT fields. 22.1.RECNO.105 I:JMV 5 12 1 8 14 2 90 I=5 MI.RECNO is set to the record that is above the R selections.1.23. See “Example 5” on page 538 and “Example 6” on page 539 for examples of DBI processing.1. the PATTERN IJM:V.3[12] 8 I=5 MI.1.24 IMJ:V 1 6 18 100 101 105 I=1 MI. 3… In this case.9 Matrix Program Control statements 2 — A match was not found. 3 — The R values are greater than the last record and DBI.RECNO is set to the last record.#. 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. then multiple values to represent matrix 1.1[12] 8 I=5 MI.#.6[12] 90 The above PATTERNS do not provide for the situation where the record contains I.1. In all cases.1[15-18] 21.6[18-20] 100. The matrix number is implied and always starts with 1 on each record. the DI.5[12] 2 I=5 MI. with the FIELD value of M set to zero.1.1.#.field values are extracted from the record indicated by DBI. 2. 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) 490 Cube Voyager Reference Guide . NOTE: You can create and populate arrays with just a FILEI DBI statement.1. J. and the record pointer points to that record. you do not need DBIRead functions. can be used to describe the input data.4[12] 14 I=5 MI.2[14] 90 IJM:V 5 12 3 8 14 2 90 I=5 MI. and DBI.101. MI.DAT FILEO MATO=temp1..mat PAR ZONES=4 MW[1]=mi.0. 2. The script example below will build a binary matrix using the implied J values. MI. The input dbf in this example would have the named .1215 10.1.. DBF format .3912 167.3-6 .V3. RUN PGM=MATRIX FILEI MATI=temp1.V4 (results) I=1.2.0612 31.6512 54.2914 14. can be used to describe the input data. fields I.1612 13. The J value is implied and always starts with 1 on each record.3-4. 3.8414 35. fixed format or MATI[1]=input. FIELDS=#1.dbf.2=22. pattern=IJM:V. for a single matrix (implied matrix number M=1). J=15. with the FIELDS value of J set to zero.6815 31.1 ENDRUN PATTERN=IJ:V MO=1 FIELDS=#1.1.V2.1.0.5-7-4 . the PATTERN IJ:V. In this case. then multiple values to represent J values 1. 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.5314 4.V3.Matrix Program Control statements 9 MATI[1]=input.txt.J.5015 75. PATTERN=IJM:V.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.V1.8514 12.1=21.2-5 Cube Voyager Reference Guide 491 . PATTERN=IJM:V.1213 54.5413 269. MI.0.3=23.J.V1.1.0. MI.2513 22. variable format or MATI[1]=input.txt.V2.V4.2813 6.4=24 The above PATTERNs also do not provide for the situation where the record contains I. FIELDS=I. FIELDS=1-2.1. TYPE[K] = 'N' && substr(RECI.VAR1TOTAL. SORT=nvar2.dbf PARAMETERS MAXSTRING=100 if (RI.NAME[k].RECI. cvar3(C)=3. cvar2(C)=2. cvar3(c)=3.t' . cvar3 FILEI RECI=myfree.9 Matrix Program Control statements More on RECI Example RECI statements: FILEI RECI=myfile.dbf. cvar3(c)=1010.mdb\mytable. +key6 FILEI RECI=myfile.A>25 & RI. -key1. SORT=key2. cvar2(C)=2. -key1.. DELIMITER[2]='//' FILEI RECI=myfree. nvar1=1.NUMFIELDS If (RECI. but we do know that all units fields are named xxUNITS): TotUnits=0 Loop k=1.NUMRECORDS PRINT LIST=RECI.txt. cvar3(C)=3.NUMRECORDS. DELIMITER=' .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. nvar1=1.txt. DELIMITER[2]='""'' ' FILEI RECI=myfree.+cvar3 Example of usage: to sum all the housing units in a record (even if the exact names are not known.NFIELD[K] EndLoop Example: In a record processing run of matrix VAR1TOTAL=VAR1TOTAL+VAR1 IF (I=0) VAR1AVG=VAR1TOTAL/RECI. the total of VAR1 and the average of VAR1 Example: RUN PGM=MATRIX FILEI RECI=network_link.3.B>25) 492 Cube Voyager Reference Guide . '//() ' SORT=-nvar1. cvar2(C)=2.txt.txt. nvar1=1-3. SORT=key2. nvar1=1.5) = 'UNITS') TotUnits = TotUnits + RECI. +key6 FILEI RECI=myfile. nvar2=5-8. nfield[10]. ri..'.\nri.'.'..10='.field6.'.'.'\ncfield[1-5] ='.'.. ri..A.recno. ' highest field='.field4.reci.field6.ri.'.allfields FILEO PRINTO[1]=junkprn.reci.IMPORTANCE.'. ri.ri.'.prn write reco=1 print printo=1 form=5lr.ri.'..'. list=ri.'. reci.reci. RECI.1(n5) FILEO RECO[1]=junkout.'.ri.' lng='.'.'.field7.ROAD_NAME.'..'.'.'.numfields..Fields=1(c5).cfield[4]..'. reci.'..'.csv endif if (I=0) print list='Number of link records='.'.'. ri.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 .'.SPEED.'.'.reci.field9.'. ri.ROAD_TYPE.CLASS.field1.txt.cfield[1].'.ri.'.dat endif ENDRUN Example: copy file = junk..'.lng print printo=1 form=5lr.'.B. ri.'.list=reci. reci.cfield[3].field1.\nnfield[6-9] ='.reci.field8.ri..'. reci.cfield[2].\nri.reci.'.field2.'.' endrun Results of the PRINTO file from the above example: Cube Voyager Reference Guide 493 .'.NUMRECORDS file=tmp2.'.reci.'..ri.fields....'..field3.reci.reci.'.'..field5..'.dbf FIELDS=reci.nfield[7].PICTUREFIL file=tmp1.nfield[9].' NumFields='.Matrix Program Control statements 9 print.ri.'.nfield[6].'.'..'.nfield[8]. ri.ri.cfield[5].reci.ri..field10.'.5 ='.'.get 1st 5 data fields as numeric fields and also as character fields FILEI RECI = junk..list='\nRecno='..'. ' '..33.. PATTERN=I:JMV FIELDS=ORG.txt.txt..DU1=#2.B .56.0.44.DEST..txt. print=y .11..TRIPS ZDATI[1]=housing.55. file=out_reci.0. each data record is stored in a string variable ”reci” s2=substr(reci.MAT.txt ..MULTI_FAMILY=4.56.. nfield[6-9] =0...1)..55.22..56..44... TPP or MINUT matrix file MATI[5]=external..44. 1..Z=1-5.dd. s2...5 =aa.0.0.10=11. '.test12.DUPLEX=3.5 =11..poptotal=6-15.dd.txt.popsr=56-65 These statements show an example of simple record processing: copy file=reci_in. switch to record processing mode .. Example of FILEI statements These statements show various examples of FILEI usage: FILEI MATI=test11.field6.33.22.0 A 1 2 3 4 5 6 7 8 9 10.dat. Recno=2 NumFields=10 highest field=5 lng=23 aa bb cc dd 56 78 90 12 cfield[1-5] =aa..22.. FIELDS=1-3 ..dat . I is the end-of-file indicator print list=i(3.1. FIELDS=1-4. s3.bb.pop19-65=46-55. LAST=DUPLEX ZDATI[4]=pop.. reci(10).cc..popfemale=26-35.55.0.11-10-20 MATI[6]=external.6-8...55. ri.'. nfield[6-9] =11.12) s3='Z' if (substr(reci. PATTERN=IJ:V.. Z=#1..33.popmale=16-25.0 B 1 2 3 4 5 6 7 8 9 10. ri.33.mat .1)=='A') s3='B' .field6.0. ri.. 0. CONDO=5.56.cc.field1.txt.. PATTERN=IJM:V FIELDS=#1-30 MATI[7]=external.9 Matrix Program Control statements 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.. will result in .var....22.field1. popyouth=36-45...bb..10=0...Z 494 Cube Voyager Reference Guide .44.RETIREMENT=6 SELECT=abc-1-3 FIRST=DU1. 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. MINUTP binary matrix files MATI[4]=tppltrips.... ri..dbf. md81(6).DEST>0) Time = matval(1.mat" mo=1-8 DEC=8*9 .3).mo21(6.2LR) .RI.1.3).dbf" FIELDS=ms10(5.108 MW[6]=MI.RI.0) Else Time=0. mo22(6. contains time and distance matrices in 1 and 2 If (RI.3).RI.1. dest=2 MATI[1] = mymat.mo25(6.2).3). get matrices mf104 to mf111 from emme2ban .2LR).1. dist=0 Endif print file=outfile.md80(6). list=reci.ORG.3).0) Dist = matval(1.Matrix Program Control statements 9 endrun These statements show an example of getting I-J values from a delimited file: RUN PGM=MATRIX RECI = myfile.RI.3). time(6.DEST.107 MW[5]=MI.3). org=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.mo23(6.ORG.109 MW[7]=MI.1. dist(8.ORG > 0 && RI. 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.md23(6).1.1.1.mo20(6.2.110 MW[8]=MI.105 MW[3]=MI.md25(6.md82(6) report zdat=t Cube Voyager Reference Guide 495 .1.106 MW[4]=MI.1.DEST. and put into work matrices 1 to 8 MW[1]=MI.104 MW[2]=MI.md22(6. 496 Cube Voyager Reference Guide .mo21 ro.1.md82 write reco=1 ENDRUN FILEO Programs: Distribution.ms10=zi.1.md22=zi.1.1.md23=zi.mo25 ro.md23 ro.mo21=zi.1.md80 ro.mo22 ro.mo23=zi.md22 ro.1.1.ms10 ro. Matrix Outputs data files.mo20 ro.md25 ro.md80=zi.1.1. 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.mo20=zi. Cube Voyager writes matrix type output files at the end of each I zone.1.1.mo23 ro.1.mo25=zi.md81 ro.md81=zi.md25=zi.md81=zi. Fratar.9 Matrix Program Control statements zones=900 ro.mo22=zi. If it does not exist. The data bank file must exist already.Matrix Program Control statements 9 PRINT statements write formatted print files to the PRINTO file. The program can write output matrices in various formats. the program will not create the data bank file. EMME/2 data bank files must be named emme2ban. May have an index [x] appended. FILEO keywords Keyword MATO Subkeyword |KFV20| Description Name of an output matrix file. MATO may reference an existing EMME/2 data bank file in order to store matrix data into the existing data bank. Cube Voyager Reference Guide 497 . the program assumes the index is 1. which you can use with other software. 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. If you do not specify an index. The program will overwrite an EMME/2 data bank file in the format specified by FORMAT if the name is not emme2ban. Indices need not be monotonic or sequential. Cube Voyager stores 1. However. In most cases. If the cell value exceeds the maximum integer value (2. the result is 3.147. NOTE: Cube Voyager stores fixed-point format as a decimal-coded integer. For example. which translates to 1. If stored as fixed-point with DEC=2. If stored as fixed-point with DEC=0. If stored as single precision with DEC=S. Valid values vary by file format: • Cube Voyager files Valid values include: 0 through 9 — Writes output matrix cells in fixedpoint format.33.33333333.258.258. For example.483. 498 Cube Voyager Reference Guide . Cube Voyager processes all matrices in double-precision floating-point format to accommodate a wider range of values and to maintain accuracy and precision. the result is 3.258. and requires two bytes to store. preserving the indicated number of digits following the decimal. This format provides 15 to 16 significant digits. Additional digits may change from their original value when a program reads them. However. and requires four bytes to store. this result might not be precise enough for the subsequent uses. a few decimal places for each cell value are adequate. then Cube Voyager reduces the number of digits stored after the decimal. If you do not specify DEC. with DEC=5.756..337. S — Writes output matrix cells in single-precision floating-point format (4 bytes). This is the traditional format for transportation planning matrices. Certain matrices might require more precision.756. writing double-precision numbers to the matrix files might produce very large files. to sixteen digits. the default value is 2.. the result requires eight bytes to store. If stored as double precision with DEC=D.647). This format provides seven to eight significant digits. the result is 3. Specify a separate DEC for each MO. for a cell computed as 10/3. the result is accurate to about seven digits.337.33715 as the integer 1.756.9 Matrix Program Control statements FILEO keywords (continued) Keyword MATO Subkeyword DEC |SV*| Description Specifies numeric format of values in the output matrix. D — Writes output matrix cells in double-precision floating-point format (8 bytes). and requires one byte to store. • DBF files Set DEC as for Cub Voyager files. If a number’s integer value with implied decimal exceeds the maximum integer value (2.483. If you set PATTERN such that M varies in a record’s matrix data values. LOS rounding COMP MW[2]=MW[2]*100. the program writes variable-length values and truncates trailing zeros. Storing numbers larger than the maximum integer value (2. distance. However. • Text files Set DEC to the number of decimal places to format in text records. However. If you specify DELIMITER.647) will result in erroneous values. the program uses the DEC[1] value for all the matrix data fields unless “M” immediately precedes the colon in PATTERN (for example. cost.147. Cube Voyager Reference Guide 499 . and “bucket round” matrices that represent trips to ensure row totals. bucket rounding Optionally. and so on). the program uses DEC[#] appropriately.Matrix Program Control statements 9 FILEO keywords (continued) Keyword MATO Subkeyword DEC (continued) Description • MINUTP or Tranplan files Do not set DEC. you round matrices that represent levelof-service (time. The program stores numbers as integers with implied decimal. the program uses the default value of 2. PATTERN=IJM:V ). The program ignores the DEC setting and automatically writes 4-byte values.147. the program substitutes the maximum integer value for that number. usually integer numbers. the program treats as DEC=0. COMP MW[1]=INT(MW[1]*100+. you cannot use such a matrix as input to Cube Voyager. set DEC=S to write a single-precision matrix. You must set the included work matrices to the desired external format before the program writes the matrices.5) . • TRIPS files Set DEC to the number of digits after the decimal point (0 to 9). Total=ROWFIX(2) .483. otherwise the program writes fixed field lengths. NOTE: Normally. If you set DEC to S or D. If you do not code DEC. based on the values of FIELDS.647). To use a comma or space.25-32 .4.. the program omits the corresponding data. M will be in 15-16. PATTERN=I:JVM FIELDS=4..0..4.9 Matrix Program Control statements FILEO keywords (continued) Keyword MATO Subkeyword DEC (continued) Description • EMME/2 data bank files Do not set DEC. If you do not specify DELIMITER. Character that separates data values. The number of values specified with FIELDS must match the number of letters in PATTERN (the “base” portion precedes the colon.. 39-40 . MATO DELIMITER |S| For text files only (FORMAT=TXT ).. After exhausting the list of FIELDS values.. 27-29. 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. When you code this subkeyword. based on the values of FIELDS.15-20. V will be in 9-14.. the program reverts to the FIELDS value that corresponds to the repeating portion of PATTERN.. 33-38 . I will always be in columns 1-4 J will be in 5-8. enclose with quotes.6 MATO FIELDS |IV4| • • • • • • • • • • • I will always be in 1-4 J will always be in 5-8 V will be in 9-14..6. and the “repeating” portion follows the colon). Field width for data values when DELIMITER is not specified. The first FIELDS value always sets the length for I. the program writes fixed field lengths. If the FIELDS value that corresponds to a base portion of PATTERN is set to 0..4. ' '. The program stores values in singleprecision floating-point format in the data bank file. you delimit data with a comma or space.8 500 Cube Voyager Reference Guide . 29-32 . 17-20.21-26 .17-24. the program writes data values in variable length and separates values with this character.2 PATTERN=IJM:V FIELDS=4. Examples: PATTERN=IJ:V FIELDS=4. Usually. 21-26. In that case. Ignored if MATO is set to emme2ban. the program updates an EMME/2 data bank file. unless you set PATTERN. Cube Voyager Reference Guide 501 .Matrix Program Control statements 9 FILEO keywords (continued) 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. With PATTERN set. the default value is TXT. If MAXFIELDS is less than the number of matrices specified with MO.4.3. PATTERN=IJ:MV.5-7. MO=1-8.' MATO[15]=TEST15. with IJ:V.6.HBOTHER. MAXFIELDS=1000. For example. the program will start a new record if starting a new record requires less space. If the repeating portion of PATTERN is more than V (contains a J or M. MAXFIELDS=10. DEC[3]=2 502 Cube Voyager Reference Guide . and V is zero. DEC=6*0. The program tests MAXFIELDS before writing a value set. MAXFIELDS=10.DAT. the program does not write the value set. MO=1. MO=3-7. the program will split a logical data record into multiple records. If not set. NAME[3]=PURP_5 MATO[4]=TEST4.MAT.9 Matrix Program Control statements FILEO keywords (continued) Keyword MATO Subkeyword MAXFIELDS |I| Description Maximum number of value sets written on a single record.NHB. or both).TXT. the program would write at most 10 sets of VM values on a record. The results might be confusing. Citilabs recommends that you always set MAXFIELDS.42. The new record will begin with the next J containing a value. FIELDS=4. If the repeating portion of PATTERN (the “repeating” portion follows the colon) is only V and the program encounters a string of zero values. Example FILEO MATO=TPPTEST. With IJ:VM. A “value set” is the group of values that follow the colon in PATTERN. PATTERN=I:JMV. DELIMITER='. FORMAT=MINUTP.2.TXT.IXI. MO=1-5. for a maximum of 20 fields. the program does not limit the size of a data record (there is a limit of 255 fields in a DBF record). the program writes at most 10 V values on a record. NAME=HBWORK.XX MATO[3]=DEMO12. Use care with DBF files. Valid matrix names contain only alphanumeric characters. the program only writes the specified matrices. NAMES[1-3] refers to those fields. For other formats. If there are three characters prior to the colon in PATTERN. Each output matrix (specified by MO) does not require a name. Cube Voyager programs reading the file can reference the matrices by name and/or number.11-15. For EMME/2 data bank output files. spaces. which you can use for internal documentation. For such files. MO[6]=31 the program will write 20. NAME[n+1] refers to the first actual data field that corresponds with the first character following the ”:” in PATTERN. Cube Voyager. specifies user names for the record variables. the program stores the first four characters of NAME into the bank short name and the entire name into the bank long description. the program ignores NAME.n] will refer to the beginning n record fields. NAME[1. with MO=1-5. For MINUTP and text output files. For DBF output files. The highest implicit or explicit index determines the number of matrices included in the output file. but including a name helps document the file. You may index MO. MO[20]=1. For example. Nine of the matrices (11-19) will be empty because no data was entered for them. specifying matrix numbers and names. specifies names of output matrices. If writing to an EMME/2 data bank output file. Note that missing MO index values are acceptable when writing binary files but not when writing text files.Matrix Program Control statements 9 FILEO keywords (continued) Keyword MATO Subkeyword MO |IVP| Description List of working matrices that the program writes in the output file. MO[200]=7. the program will write MF1.8. The program numbers output matrices monotonically beginning with 1. and underscores (_). See “Example: FILEO MATO for EMME/2 file” on page 507 for an example of writing matrices to an EMME/2 data bank file. most set to 0. which will align with PATTERN. For example. and TRIPS output files. Cube Voyager Reference Guide 503 . Tranplan. the program starts output matrices at 1 and writes through the highest MO index.. MATO NAME |SV| For TP+. You may write the same working matrix more than one time. MF2. When writing output matrices to an EMME/2 data bank file. and MF200. with MO=1. specifies the names for the matrices. the program will write 200 matrices. Each RECO must have an index [x] appended to it. DBF. the program will not create the bank file. The bank file must exist already.ALLFIELDS include macro described under FIELDS above. 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. If there is no index. RECO CFORM |I| Length of field for all character variables that follow it on the statement. RECO EXCLUDERECI |S| 504 Cube Voyager Reference Guide .9 Matrix Program Control statements FILEO keywords (continued) Keyword MATO Subkeyword PATTERN |S| Description Sequence of characters that indicates the order the program writes values to the output records. Currently. File name for the RECO specified. If it does not exist. The program will write any other file name to binary PRINTO PRINTO RECO APPEND |KF| |?| |KF20| format and not in bank-file format. Valid values of PATTERN are listed and described under FILEI MATI PATTERN on page 480. the index is assumed to be 1. 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). You can use RECO to write scalar or vector matrices into an EMME/2 data bank file. the file name must be emme2ban. See APPEND under “PRINT” on page 62. See “WRITE” on page 532. The allowed range is 1-255. the default is 15. Specifies the name of the file where the output from a PRINT statement is to be directed using PRINT PRINTO=#. and do not have a specific format associated with it. MDB and EMME/2 data bank files are the only file formats supported for this record file. The indices need not be monotonic or sequential. A later occurrence of CFORM will reset the value for character variables following it. Used to exclude selected fields when using the RECI. If specifying an EMME/2 data bank file. If specifying an EMME/2 data bank file with RECO. The include macro RECI. 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. 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. prefix anywhere in the script (a 3. the RO. Cube Voyager usually refers to these as constants and zonal arrays. For RECO fields that are not assigned a value in the script or do not have a matching RI. If using RECO in conjunction with matrix processing.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.name variable each time a new RECI record is read. origin matrices as MO#.2 script would never have an RO. Prefix in the first place). it is strongly recommended that the RO. Cube Voyager Reference Guide 505 . and destination matrices as MD#. a logical variable for Z would be I (Z=I) if there is one RECO per zone. or D. O. variable. However. they will be left empty in the output record. where x=S.2. you must also specify a Z=variable to indicate for which zone to store the data. When the output file is an EMME/2 data bank. EMME/2 references scalar matrices as MS#. the program ignores any FIELDS not named with this format (Mx#). Care should be taken to ensure that the other names in the FIELDS list do not conflict with the names on the RECI file. the RO.Matrix Program Control statements 9 FILEO keywords (continued) Keyword RECO Subkeyword FIELDS |S| Description Defines the variable names to be written to the output RECO file. For backward compatibility to version 3. The RECI fields will be inserted on the RECO file at the location where this macro is found. variables (with or without matching RI.name variables in the script. specifying fields and field names. the field values are NOT initialized when a new RECI record is read. If you specify MO or MD. prefix be used at all times to avoid confusion. If a RECO variable name matches a variable in the RECI record. All RO. variables) can be modified in the script. the format is: RECO=emme2ban FIELDS=Mx#. 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.name variable will take on the same value as the matching RI. These variables are referenced as RO. and # is a valid number for the data bank. PrescreenType and PRESCREEN value set in SM with KEYS IF ({PrescreenType}=1) .SORT = -VULNERABIL FILEO RECO[1] = "PRESCEENED_LINKS. decimals) as they will appear in the DBF. Used in conjunction with the FIELDS subkeyword. For output to EMME/2 data bank files. specifies zone for which the program stores the data.2. and do not have a specific format associated with it. and RO.. length.DBF". writes the number of links to CNT. Used in conjunction with the FIELDS subkeyword..\emme2\emme2ban Z=I.MD2. (i. number of records (links) in the input file LOG PREFIX=CNT VAR=NUMLINKS . Default value is F. screen based on a percentage of number of links .9 Matrix Program Control statements FILEO keywords (continued) Keyword RECO Subkeyword FORM |R| Description Format specification (w. The allowed range is 1-31. Upon encountering each WRITE RECO=1 statement in the script. fields=MS1 MO1 MD1 name=ms1 mo1 'md1 term time' RECO NAME |S| For this example.MD1. in the input network (i. the script must set the variables . For output to EMME/2 data bank files. top N based on Vulnerability) PRESCREEN={PRESCREEN} ELSE . in the *.. the default is 10.5.e.DBF". mode. Example: reco[1] =.e.B. specifies name in the data bank for scalar and vector matrices. Optional. FIELDS=A. RUN PGM=MATRIX FILEI RECI = " LINK_DATA. RO. top N% of links based . the program would update the data bank. RECO REPORT |?| Can be specified to have the program print a listing of the fields (name. on Vulnerability) PRESCREEN=ROUND(NUMLINKS*{PRESCREEN}/100) 506 Cube Voyager Reference Guide .NUMLINKS . screen based on a fixed number of links .NUMRECORDS .MS1.rank_bas NUMLINKS=RECI. Optional. Required when writing MO or MD matrices. A later occurrence of FORM will reset the value for numeric variables following it.d) for all numeric variables that follow it on the statement. changing the names as defined.var file . RECO Z |S| Example: FILEO These statements demonstrate FILEO. B If (RO. NAME=mf01.mf27.mf24.A Bnode=RI.rank_bas<=PRESCREEN) If (Anode <={Zones} | Bnode <= {Zones}) .mf40.mf21.NAME[206]=mf206 .mf09.mf12.15.mf11.mf05-mf13 FILLMW MW[1]=mi.201-220.mf192.mf25.1.mf37.2.MO[17]=101-106.mf04. mf30.mf38.22.mf32. NAME=mf17.MO[171]=221-240.mf31. NAME[191]=mf191.MO[206]=8.mf05.1(9) MW[10]=mi.mf42.Matrix Program Control statements 9 ENDIF LOG PREFIX=CNT VAR=PRESCREEN RO.RANK_BAS=RO.mf13.mf26.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.mf35.25.rank_bas+1 Anode=RI.mf39.mf06.mf193.mf29. MO=1-4.1.mf191-mf193.mf18.mf23.MAT" FILEI MATI[2] = "HWY_SKIMS.mf206.MAT" FILEI MATI[3] = "PT_SKIMS.mf36.mf33.mf34.rank_bas=RO.MAT" FILEO MATO[1] = " EMME2BAN".19. mf171-mf190 FILLMW MW[201]=mi.MO[191]=5-7.mf41.mf22.mf18.mf02.21.mf20.9-17.mf28.23.mf10.mf07. of links to be analyzed RO.get mf23-mf42.27 . prevents any centroid links .mf08. get mf01-mf04.mf03.4(6) . from being included in set .11.3. get mf17-mf22 FILLMW MW[101]=mi. RUN PGM=MATRIX FILEI MATI[1] = "Purpose_Trips.1(40) ENDRUN Cube Voyager Reference Guide 507 . 1(3) JLOOP IF (I=J) ro.MO25 ro.md23.ms02=8 .7 .1.MO22 ro.MD81 ro.md80=zi.md82 FILEI ZDATI[1] = "VECTORDATA.scalar ro.mo25.md23=zi.1.1.1.mo20.mo21.MD25 ro.1.md81=zi.md82=zi.MD82 ro.mo20=MW[1][I] ro.mo22.md22.1.1.MD22 ro.scalar WRITE RECO=1 ENDIF ENDJLOOP ENDRUN 508 Cube Voyager Reference Guide .z=I ro. md25.mo22=zi.9 Matrix Program Control statements Example: FILEO RECO for EMME/2 file These statements demonstrate FILEO RECO to an EMME/2 data bank file.ms10.MD80 ro.get mo20.md25=zi. Z=I FIELDS=ms02.DBF" FILEI MATI[1] = "HWY_SKIMS.MD23 ro. mo21.mo23.mo25=zi. RUN PGM=MATRIX FILEO RECO[1] = " EMME2BAN".mo21=MW[2][I] ro.mo23=MW[3][I] ro.md80.1.md22=zi.1.ms10=34.MAT" . mo23 FILLMW MW[1]=mi.md81. If there is a ram disk installed. and TMP is specified in the Operating System environment. If not specified. use the PATH.Matrix Program Control statements 9 FILET Programs: Distribution. and 2 Mb of RAM available. The first file is the actual transposed data. the compressed data would require about 30 Mb. If PATH[1] is specified. The amount required for the data would be something less than 80 Mb. FILET keyword Keyword PATH |KS| Description Specifies the path(s) to the disk area where any temporary files are to be written. Fatal. or TEMP. the non-specified path is set equal to the specified one. Fratar. It may speed retrieval somewhat if the two files are on different physical drives. The index file size will be zones * chunks * transposes * 4 bytes. When transposing is required. The number of chunks would be 40 (80 Mb / 2 Mb). 20 matrices to be transposed. or 80 Mb. The actual RAM requirement would be 1000 * 1000 * 20 * 4. and the second file is an index to the data file. then the index file might fit on it. In most cases. and PATH[2] is not. Matrix Sets temporary file paths. Chunks depends upon the amount of RAM that is available for the transposing processing. Assume a 1000 zone system. use current directory. (Same logic for TEMP. use the TMP. The values for PATH are entered as standard operating system paths. The logic for determining the appropriate path. The index file may not be necessary. PATH FILET is used to specify where various temporary files are to be written.000 bytes of RAM. they both will default to the path in the environment variable named TMP. and if it is. If neither is specified. Up to two files are required for this process. or vice-versa. If the PATH is specified. it will be relatively small. it could be none.setting. and opening the files is: • • • • If the PATH=' '. The index file would require 800.) If the open fails. the transposed matrices are written to a temporary file and then recalled during stack processing. Cube Voyager Reference Guide 509 . depending upon how well it compresses. 1(3) FILLMW MW[1]=mi.1. 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.2. Because of its structure.R: . The beginning MW target is the keyword and the values are the matrices that are to be moved into the target matrices.cost 510 Cube Voyager Reference Guide .. the following values may be unqualified (they do not have to have MI. This is also true for MW sources. Fratar.cost FILLMW MW[1]=mi.9 Matrix Program Control statements Example PATH=' ' .mi.1.1.1.1.\. matrices can be very easily moved from input matrices to work matrices or from work matrices to other work matrices.2. Multiple matrices can be easily filled on one specification.1. After the first value.1.1.distance.3 FILLMW MW[1]=mi. root of c: for data.3 FILLMW MW[1]=mi. but FILLMW sets up very fast moves in contrast to internal computational solutions performed by COMP statements. Matrix Fill work matrices MW This statement is used to speed up the process of filling matrices with values from other matrices.mi.time. drive R: for index PATH=c:\ d . Everything that can be done on a FILLMW statement can be accomplished by COMP statements.mi.1.mi. up a directory for data.time. current directory on d: for index FILLMW Programs: Distribution. use current directory for both PATH=. Example .distance. The following five statements all do the same thing FILLMW MW[1]=mi.1. prefixed to their names/numbers).#.1. The next two statements illustrate the simplicity of FILLMW vs.2. MW[4]=mi. mw[14]=mw[9]. BASEMW RANGE REPORT SAVE TITLE VALUEMW Use FREQUENCY to obtain a frequency of occurrence of the values of a work matrix. MW[1](3) . FREQUENCY keywords Keyword BASEMW |I| Description Work matrix number ( MW[ ] ) whose values will be used for the stratification (the time matrix for a trip length distribution).1. where the number of trips in a matrix is stratified according to the times from a time or distance matrix.MW[1.1-5.1(5). A typical use is for a trip length distribution.6 COMP MW[11]=mw[1].1.2.3.2.4 FILLMW MW[101]=mi. Cube Voyager Reference Guide 511 .1. mw[15]=mw[6] .2. COMP FILLMW MW[11]=mw[1]. The final results are reported at the end of all zone processing.3.1. mw[13]=mw[3]. An example of multiple keywords FILLMW MW[1]=mi. mw[12]=mw[2]. Matrix Stratifies one matrix’s values based upon the values of another.9. Fratar.3] FREQUENCY Program: Distribution.3.Matrix Program Control statements 9 .2.will fill MW[101-108] with MI. Matrix Use GOTO to jump to statement named :label. Generation. Work matrix number ( MW[ ] ) whose values will be accumulated according to the values of BASEMW (the trip matrix for a trip length distribution). optional. REPORT IP| SAVE TITLE VALUEMW |?| |S| |I| Example FREQUENCY BASEMW=1. Minutes' FREQUENCY BASEMW=1.9 Matrix Program Control statements FREQUENCY keywords (continued) Keyword RANGE |RP| Description Set of two.RANGE=1-100. the report will be printed for the last iteration. The first number (RANGE[1]) is the lowest value for which there is to be a stratification. the default will be 1.VALUEMW=2. If this keyword is not specified. REPORT=99 GOTO Program: Distribution. The numbers are separated by a dash. Not yet in use.5. Title for identifying the final report at the end of the application. if the value from BASEMW is less than RANGE[1]. The third. If there is no increment. number (RANGE[3]) is an increment for stratification. or three. Label can be within IF and LOOP blocks. 512 Cube Voyager Reference Guide . Fratar. The second number (RANGE[2]) is the highest value for stratification. Iterations for which the report will be printed. but care should be taken if this is to be done. the value from VALUEMW is accumulated into an out-of-range bucket.RANGE=0-100-0. flow immediately branches to the statement named label. or if any of the values exceed the last iteration.VALUEMW=2. TITLE='Work Trips vs. numbers that establishes the valid values for stratification. REPORT is used primarily only when the Matrix program is invoked as a process that runs in a multiple iteration mode (Distribution program). or higher than RANGE[2]. During accumulation. When GOTO is processed. . Matrix IF (expression) ELSEIF (expression) ELSE (expression) ENDIF IF/ENDIF blocks are used to determine if certain operations are to be performed. If a variable in the expression is MI.. ZI. NOTE: The placement of a :label inside a JLOOP is not allowed..n. IF blocks may be nested. It is permissible to go backwards. . it is suggested that they be used judiciously.. that has meaning with only GOTO statements. JLOOP. :buildhwy IF (expression) GOTO :buildhwy . IF .. Example GOTO buildhwy . or other IF blocks.name. Fratar.n.name or MW[] should realistically only be used within a JLOOP. care should be taken if this is done. ENDIF Program: Distribution. Example GOTO buildhwy GOTO :buildhwy A statement that begins with : is a label statement..name.n. 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. Although IF expressions can be quite powerful for Cube Voyager Reference Guide 513 . Lengthy IF expression solutions could be time consuming. but they may not overlap LOOP. The leading ”:” is ignored.Matrix Program Control statements 9 label is a character string that must have a matching LABEL statement. the same rules for indexing in a COMP statement are applied. Generation. or MW[]. The leading colon ”:” is removed from label when determining the qualified name of the statement to branch to. MI. A label statement can be within IF and LOOP blocks. ELSEIF . This prevents using GOTO from jumping into a JLOOP. ELSE . 57 & k=(2*j-4) ) || ((J*k) = 14-20. and probably can not be aided by a filter. ENDJLOOP Programs: Distribution. ... The following illustrates a more efficient process for using IF for . 514 Cube Voyager Reference Guide . but that might have caused . ***** Inefficient ***** JLOOP IF (I=i_ranges. . && J=j_ranges. sometimes INCLUDE and EXCLUDE filters may provide a much more efficient selection process (see the examples in this section)..) statement ENDJLOOP .time < 32) . lengthy zonal selections within JLOOPs .. statement ENDJLOOP ENDIF JLOOP ..) JLOOP INCLUDE=j_ranges.. ELSEIF (loop_cntr > 5 && diff. The above IF example is rather esoteric.. Matrix Control a J loop for processing matrices. Fratar.. conflicts with the use of J in other parts of the expression. Generation. ELSEIF (loop_cntr > 10) . The J selection could have been filtered.. ***** More efficient ***** IF (I=i_ranges.9 Matrix Program Control statements zonal selection. 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 .6-30.single IF with process IF (expression) EXIT IF ( ( j=3-5.56) ) . ELSE . . ENDIF .. and J meets EXCLUDE) go to ENDJLOOP. Only the following statements are valid within a JLOOP block: BREAK CALL COMP CONTINUE EXIT GOTO IF ELSEIF ELSE ENDIF Cube Voyager Reference Guide 515 . and J fails INCLUDE) go to ENDJLOOP. COMP MW[]= statements are processed only for the current value of J. JLOOP blocks may not be nested. Jinc=1. If (J < 1 or J > Zones or Jend <1 or Jend > Zones) fatal termination. and may not overlap other JLOOP. and J fails INCLUDE) go to ENDJLOOP. Jend=Zones. 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. If (EXCLUDE. and Jinc. Else set J=1. If (Jinc < 0 and J >= Jend) go to statement following JLOOP. All statements between the JLOOP and ENDJLOOP statements are processed with the current value of J. The logic for JLOOP and ENDJLOOP processing is: • at JLOOP: If J is specified. Jend. and J meets EXCLUDE) go to ENDLOOP. LOOP or IF blocks. Next statement. establish values for J.Matrix Program Control statements 9 J INCLUDE EXCLUDE JLOOP ENDJLOOP blocks are used primarily to control computations on matrices that a single COMP MW[]= can not properly control. If (EXCLUDE. • at ENDJLOOP: Add Jinc to J. If (INCLUDE. If (INCLUDE. If (Jinc > 0 and J <= Jend) go to statement following JLOOP. If Jinc is not specified.1 are used. Jend and Jinc. Jinc If Jbeg is not specified.process only intra zonal values . get rowsums for matrices ROWSUM1 = ROWSUM1 + MW[1] ROWSUM3 = ROWSUM3 + MW[3] ENDJLOOP 516 Cube Voyager Reference Guide . Because all these values can be expressions. If there is no Jend. If Jend is not specified. the value may not be less than 1. This prevents using GOTO from jumping into a JLOOP. and the values Jbeg and 1 are used.9 Matrix Program Control statements PRINT REPORT SET NOTE: The placement of a :label inside a JLOOP is not allowed. 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. the value may not be less than 1 nor greater than Zones. JLOOP and ENDJLOOP keywords Keyword J Jbeg Jend |I| Description Sets Jbeg. Expression that establishes the Jend for the loop. Expression to initialize J. nor greater than Zones. it must be enclosed within (). and Jinc is set to 1. if Jbeg > Jend). Example JLOOP J=I EXCLUDE=500-535 . depending upon the direction from Jbeg to Jend.Zones. if an expression contains any commas. but exclude externals ENDJLOOP ROWSUM1 = 0 ROWSUM3=0 JLOOP . Expression that establishes the Jinc for the loop. If Jinc is not specified. and the values 1. Jinc is set to 1 or -1. Jend and Jinc can not be. it is set to 1 ( -1. Jinc can not be. . they must be separated by commas. Jend is set to Jbeg. Matrix Control a general variable loop. they may not overlap IF blocks. 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 Cube Voyager Reference Guide 517 . Proceed to next statement. LOOP blocks may be nested. If Linc not specified: Set Linc to 1 or -1 (if Lbeg and Lend are constants.Matrix Program Control statements 9 LOOP .. The process differs considerably from JLOOP. and branches back to the statement following the LOOP statement if the comparison fails. Add Linc to LVAR. and Lbeg > Lend) Else compute Linc. Fratar. Compare LVAR to Lend. • at ENDLOOP: If Lend not specified. Lend. jump to next statement. ENDLOOP compares the contents of the variable to another value. Linc LOOP ENDLOOP blocks are used to repeat of a series of statements. LVAR = Lbeg. Compute Lend. ENDLOOP Programs: Distribution.. Generation. The logic is as follows: • at LOOP: Initialize LVAR to Lbeg. LOOP initializes a variable. mno/pqr LOOP abc=xyz. and Linc must be separated by commas (standard white space delimiting can not be interpreted properly).5. Lend. Because LVAR values can be expressions. This would only happen if the Lend and/or Linc values are expressions that contain variables which could be altered during the loop. 10. it will be set to 1 (-1 if Lbeg and Lend are both constants and Lbeg < Lend. The loop will be processed at least one time regardless of Lend and Linc values. a backwards loop).9 Matrix Program Control statements Because of the flexibility of this logic. Lbeg.xyz+2.3.5 . Most uses will involve constants. and other LOOP statements can alter its value. If it is not specified.2 . Numeric expression that LVAR is to be compared with when the ENDLOOP statement is processed. LOOP and ENDLOOP keywords Keyword LVAR Description Name of the loop control variable. If Linc is not specified. 7. nested LOOP ENDLOOP ENDLOOP LOOP jj=10. it is assumed no comparison is to be made (rather meaningless loop). LVAR must be followed by Lbeg. Numeric expression to initialize LVAR. and optionally. program. Lend and Linc. perform 10 iterations .0 ENDLOOP PARAMETERS Program: Matrix 518 Cube Voyager Reference Guide .ghi+jkl. unpredictable results and/or endless loops can occur if care is not taken. 5. On the other hand. computational. LVAR is not protected during the loop. Numeric expression that is to be added to LVAR before the ENDLOOP comparison is made. ENDLOOP LOOP xyz=abc*def.10 .-2. Lbeg Lend Linc Example LOOP iter=1. the flexibility provides for powerful control. Valid values range from 1 to 999. Establishes the maximum length for a string variable’s value. The default is 100. the value must be defined. Normally. MAXMW |KI| MAXSTRING |KI| Cube Voyager Reference Guide 519 . Maximum index for work matrices (MWs). If too large a value is used. Each value requires (zones*8 + 4) bytes of RAM. which could possibly hinder performance.Matrix Program Control statements 9 Sets general parameters. Each read of a row for matval results in a matrix row being read and stored for possible later use. but if it is desired to compute longer strings. the larger the number. Default value is 999. the more efficient matval is. MATVALCACHE MAXMW MAXSTRING TRAM ZONEMSG ZONES PARAMETERS keywords Keyword MATVALCACHE |KI| Description Number of matrix rows to cache when dealing with the MATVAL function. All string variables will have this possible length. The user might have to experiment to determine the best number of his application. Optional. you do not specify this keyword and override default value. Each matval call requires a direct access lookup on the designated MATI. Default value is 50. the RAM for cache might come from disk. In general. the program writes a message for every zone. If ZONES is not specified. the default value for ZONES will be determined by the highest value from any of the MATIs.exe.exe. the program writes a message for every 10 zones.9 Matrix Program Control statements PARAMETERS keywords (continued) Keyword TRAM |KI| Description Establishes the maximum amount of memory that is to be used for temporary storage when transposing matrices. Valid values are greater than or equal to zero. with a value of 1. With a value of 10. If there are any input MATIs being processed. However. 4MB (4000000) should be adequate for most applications. The program writes to the console when initiated through runtpp. ZONEMSG |IK| 520 Cube Voyager Reference Guide . if Windows is controlling the computer. ZONES |KI| Establishes the number of zones to process. Specify a larger value to reduce run times. Frequency with which the program writes zonal timing messages to the run monitor or console. With a value of 0. The program can not detect if the ram is real or virtual. the program writes no zonal messages. The most efficient amount would be (Zones * Zones * 8 * NumberTransposes). but that would probably be more than the computer has available in real memory. 4000000 is the default. and the program has no other way to identify the appropriate number of zones. Optional. For example. Program writes to the run monitor when initiated through Application Manager or voyager. therefore. The program will request the amount that it thinks will provide the most efficient processing. Default value is 1. it will be set to 100. and should not normally be reset. The use of virtual memory is disastrous in terms of efficiency for the transposing process. but a portion of it might be virtual memory (temporary work space on disk). Value corresponds to number of zones. it will provide that much memory. care should be taken to not specify a value that is too large. In general. Fratar.31-60.Matrix Program Control statements 9 Example ZONES=3000 PRINT Programs: Distribution. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) See “PRINT” on page 62 for details about the standard Cube Voyager statement.JLOOP_J .2CS) 'ABCDE'(6. Example Examples of output with various parameters follow: pagewidth=80 mw[1]=j mw[2]=j include=1-5. LIST=N. Matrix Prints row of matrices.90-100 exclude=35. Generation.001 PRINT FORM=6. MW J TITLE FORM MAXPERLINE BASE1 See “PRINTROW” on page 69 for details about the standard Cube Voyager statement.TOTAL2 FILE=PRINTFIL.1 form=LRD title='form=LRD' printrow mw=1-21 form=6D base1=y maxperline=10. title='form=6D base1=y.Note this line is a continuation LIST= I(6) J(6) TOTAL1. Matrix Format and print a line of information.83 printrow mw=1-2. TOTAL2. TOTAL3 FILE=PRINTFIL. Example PRINT FORM=0 LIST=I. Fratar. FORM=LRCD.0CDLR LIST=I.002 PRINTROW Program: Distribution.3). maxperline=10' Cube Voyager Reference Guide 521 .TOTAL1.J.TOTAL(6.J. .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......91 92 93 94 95 96 97 98 99 100 PRINTROW MW[1] form=6D base1= Tot=5...-32 33 34 -.. Matrix Renumbers (aggregate..-.-... and then retrieved and combined after all normal processing is completed..-...36 37 38 39 40 42 43 44 45 46 47 48 49 50 52 53 54 55 56 57 58 59 60 -..-.. 522 Cube Voyager Reference Guide ..9 Matrix Program Control statements Resulting Output: J: I=1 1: 1 2 27: 27 50: 50 73: 73 96: 96 J: I=1 1: 1 2 33: 33 57: 57 90: 90 J: I=1 1: 1 2 11: 11 21: 21 31: 31 41: 41 51: 51 61: 61 71: 71 81: 81 91: 91 J: I=1 1: 1 2 31: 31 41: 41 51: 51 81: -91: 91 PRINTROW MW[1] form=LRD Tot=5...-.-.. This causes an extra layer of processing......-.... 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.....90 92 93 94 95 96 97 98 99 100 RENUMBER Programs: Fratar..-.-.-.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.31 32 34 . because the matrices must be saved..390 3 4 5 .-..-.36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 58 59 60 -.-...390 3 4 5 -........-. The records may have from one to four fields to specify the renumbering. is a comment.Matrix Program Control statements 9 Each input zone must be assigned a new output zone number. Two fields may be separated by a dash (”-”) if the two are to form a range. If there are three fields. If there are less than three fields. COLPCT is set to ROWPCT. A semi-colon (. 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). Cube Voyager Reference Guide 523 . anything following the . These equivalencies are obtained from records in the designated FILE.) terminates data on a record. The word may be any length. but the first character must be D. Output zone number. ROWPCT and COLPCT are set to 100. OPZONE is set to 0. The standard fields are: Field IPZONE OPZONE ROWPCT COLPCT Description Input zone number Output zone number Percentage of IPZONE’s values to be assigned to OPZONE when renumbering the IPZONE row Percentage of IPZONE’s values to be assigned to OPZONE when renumbering the IPZONE columns If there is only one field. and a pair of percentages (ROWPCT and COLPCT ) to indicate how the outgoing matrix zonal values are to be allocated to the renumbered zones. it MUST be followed by ”=”. Remaining fields are the input zones that are allocated 100% (ROWPCT and COLPCT) into OPZONE. RENUMBER keywords Keyword FILE |F| Description File that contains the zonal equivalencies. An OPZONE of 0 means there is intentionally no OPZONE for the IPZONE. When all zones have been processed. The sum of all ROWPCTs and COLPCTs for each IPZONE should each be 100. the saved matrices are retrieved in appropriate order. Every IPZONE (1-IPzones) should be fully allocated. if not. combined when necessary. at the normal output phase. the record must be broken into several records. and may not terminate with a dash. If saved on disk. Only one of those two keywords can be used at one time. An OPZONE may appear more than one time. The intermediate matrices are saved either in RAM (normal format). or on disk files (compressed format). usually the case when aggregating zones. and the length of the record would exceed 250 characters. Example D 1=1-10. renumbered. the normal output matrices are trapped. The process is optimized to the extent possible.9 Matrix Program Control statements If the list of IPZONEs is large. 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. there must be sufficient disk space for both the intermediate rows. FILE and ZONEO are mutually exclusive. if not. 524 Cube Voyager Reference Guide . Each record must begin with the District string. usually the case when a zone is to be split into several new zones. the use of the FILES and INRAM keywords could help considerably in reducing running times. and saved. To accommodate this process. a message is issued. and the final output files. An IPZONE may appear more than one time.48. There should be an OPZONE for every zone (1-OPZONES). An IPZONE of 0 means there is intentionally no IPZONE for the OPZONE.20-30 45. and written to the MATO files. a message is issued. MO=1 Cube Voyager Reference Guide 525 . more files generally speeds up the final stage. If the keyword is not specified. MISSINGZI |S| ZONES |I| Example[1] FILEI MATI=IN. no edit is performed. Ten files will normally reduce the application time by a factor of about 20-35 per cent as compared to one file. or MISSINGZI is not specified. the IPZONE is the current zone number and the OPZONE is the specified input zonal attribute. or M. but never less than 1. until they can be sorted and combined in the final stages of the application.Matrix Program Control statements 9 RENUMBER keywords (continued) Keyword FILES |I| Description Number of temporary files to use to store intermediate factored matrix rows. if there are any gaps. it defaults to F. a message is issued. The character may be F. ZONEO and FILE are mutually exclusive.**. It indicates the level of error associated with gaps in the OPZONE structure. Designates the highest new zone number and serves as an editor as the file records are read. inclusive. The value must be in the range 1-10. nor greater than 10. Alternate method of specifying zonal equivalencies using an input zonal data file. and ZONES is set to the highest OPZONE. the program will set the value to ZONES/100. Only one of those two keywords can be used at one time. If ZONES is not designated. Single character (if a longer string is specified. In this convention. A typical value of ZONEO is an input zonal attribute: ZI. to ensure that each OPZONE doesn’t exceed this value. W.MAT. district or TAZ number. The number of files affects the running time when the final matrices are being formed. The meanings are: F — Fatal W — Warning M — Message only (no penalty associated) MISSINGZO ZONEO |S| |S| Indicator similar to MISSINGZI.MAT FILEO MATO=OUT. for example.***. A check is made to ensure that there is an OPZONE for all values: 1-ZONES. and if it is none of these. only the first character is processed) to indicate how to treat input zones that are not fully allocated (ROWPCT and COLPCT totals of 100). A typical process might be to split zones into fully nested sub zones in ArcView. must load values into MW[1].44 3.MAT will be all zeros . MISSINGZI=M. writes the split factors to the PRN file PRINT LIST=SPLIT1. Z=#1.EQ.STEP 1 RUN PGM=MATRIX FILEI ZDATI[1] = TAZDATA1.EQ RENUMBER FILE=2005ZON.5 9 10 6. MO=1 MW[1]=MI.18 3.SPLIT2 526 Cube Voyager Reference Guide .1 .MAT. .DAT RENUMBER ZONEO=ZI.2 3 4 6.MAT will be all zeros . */ .1.DBF is: .MAT according to ZDATIN. SPLIT1=100*(ZI.88 .42 3.DAT. PARAMETERS ZONES=2999 .75 2. establishes a split factor based on the new zone geography .3 5 6 6. DIST=2 FILEO MATO=OUT.46 2. 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.22 4. 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.78 2. and that the total area of the new zones is equal to the area of the parent zone.66 . . of its parent.1. else OUT.9 Matrix Program Control statements MW[1]=MI.MAT according to 2005ZON. Data structure of TAZDATA1.48 3.24 .1.1 1 2 6.73 .Z_AREA) SPLIT2=100-SPLIT1 .1. ZDATI=ZDATIN. renumber OUT.58 3. must load values into MW[1]. the split factor is the ratio of the area of the new zone to the area . This set up assumes all input zones are split into two output zones .MAT. else OUT.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. renumber OUT.1 .Z NEW_Z1 NEW_Z2 Z_AREA Z1_AREA Z2_AREA . MISSINGZO=W Example[2] FILEI MATI=IN.18 .4 7 8 6.40 2.DBF .Z1_AREA/ZI.1. . 30 .ZI.00 57. 4.1.00 8. the zonal equivalency file has the fields IPZONE.2 .31 . 4.MAT mw[1]=mi.00 6. .94 . write the zonal equivalency file PRINT LIST=I. OPZONE and ROWPCT .NEW_Z2.00 7.00 1. the default when no COLPCT is specified is to set the COLPCT=ROWPCT.00 34. fourth column of the file.00 4.69 .06 .13 .87 . if different COLPCT factors are desired they would need to be specified in the . MO=1-2. .1 . ENDRUN REPORT Program: Matrix Request reports and establish tracing MARGINS TRACE MARGINREC (CFORM FORM LIST FILE (PRINT)) Cube Voyager Reference Guide 527 .00 9.DAT .53 . NAME=AUTO.00 60. 5.47 . 2.1. FILE = EQUIV_1.00 41.00 3.00 42.00 58.00 49.DAT" .70 . TRANSIT FILEI MATI[1] = TRIPS1.MAT.00 39. FILE = EQUIV_1. ENDRUN .ZI. . 2.DAT" PRINT LIST=I.STEP 2 – split input trip table to new zonal system RUN PGM=MATRIX FILEO MATO[1] = TRIPS2.00 50. fill work matrix 1 with AUTO trips from input matrix 1 mw[2]=mi. fill work matrix 2 with TRANSIT trips from input matrix 2 RENUMBER.SPLIT2.Matrix Program Control statements 9 . FILE = EQUIV_1. data structure of EQUIV_1. 1.00 10. 1.00 2. 5.1. .SPLIT1.00 65. 3. 3.DAT is : .NEW_Z1.00 5.1. Only one FILE value is allowed per each MARGINREC switch. Variable values are formatted to the zonal record.9 Matrix Program Control statements ZDAT (DEC) MATSTAT REPORT keywords Keyword MARGINREC Subkeyword |K?| Description Switch that indicates that MARGIN summary records for each zone are to be written to the standard output and/or a designated file. If names conflict. normally. The keywords that are subordinate to MARGINREC are a subset of those available on a standard Cube Voyager PRINT control statement as shown below. the variables are row and column values obtained from the accumulation of margin values for work matrices. A separate file is written for each MARGINREC FILE value. 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. It differs from the function of the MARGINS keyword. Format to use for any numeric data items that appear after this keyword. the earlier files will be overwritten. MARGINREC MARGINREC CFORM FILE |S| |F| MARGINREC FORM |S| 528 Cube Voyager Reference Guide . I1_I2_I3 is the sum of the intrazonal values for matrices one. the format applies to only that item. there may be a format appended to the it. the program will delete (and notify) some. If there is insufficient RAM. and J is the zone variable that is used. and I4 is the intrazonal value for work matrix four. R1 indicates the row total for work matrix one. MARGINREC MARGINS PRINT |?| |KIP| Switch that indicates that the FILE record is to also be written to the standard printed output. If. and three. Valid values are: MI. C. margin accumulation could be canceled for certain matrices. Other variables can be inserted into the record. MO. If it is desired to have an explicit format for any item in the list. Example: J ITEM1(6) ITEM2(8C) 'abcde' 'i='(8R) K(L) The variables are normally a character (R. output matrices and working matrices.Zones).Matrix Program Control statements 9 REPORT keywords (continued) Keyword MARGINREC Subkeyword LIST |KSV| Description Specifies the items (variables and/or strings) that are to be formatted to the print line. and MW to generate reports for input matrices. Requests that row and column totals be accumulated and reported for the specified MWs (work matrices). two. there is insufficient RAM to accumulate all the totals. for some reason. C. Such a format is surrounded by (). or I) followed by a number. or all. C2 indicates the column total for work matrix two. and I names with an underscore '_' acting as the concatenating character. Each MW report is listed in telephone book style with empty zones being omitted. MATSTAT |S3| Specifies desired matrices for which statistical summaries will be formatted and reported in the run print file. Example: R1_C1 is the sum of the row value and the column value for the zone. Variables can be formed by concatenating R. but the most meaningful one would be J. Cube Voyager Reference Guide 529 . of the requests as required. NOTE: MARGINS and MARGINREC cause the program to accumulate margin values for each zone for each of the included matrices. A record is written for each zone (J=1. Ave ---------- 530 Cube Voyager Reference Guide .007.Matrix Min/Max (625 cells) ---------.C1.82418 -MW[4] 27.Cnt --.R3_R4_C3_C4.---. turn stack tracing on REPORT TRACE=n .370.1.26.Minimum -------------. only the first five J values will be reported.C2.923. request margins summaries REPORT TRACE=y .64 13-13 -. Sets the maximum number of decimal places to be printed for any variable.97 13-13 -.99 978.Matrix Intrazonal Summary (625 cells) ---------.256 -.--.Cnt --.9 Matrix Program Control statements REPORT keywords (continued) Keyword TRACE Subkeyword |K?| Description Controls the listing of the stack statements as they are processed (can be quite voluminous.Matrix Summary (625 cells) ----------.56638 3.--Table 3 .04 -.04 9.5450 3-16 -.76187 -MW[3] 978. FILE=r:\intras.Sum ---------.Maximum ------------->0 @I-J <0 @I-J >0 @I-J <0 @I-J MW[1] 2.65 1-1 -.17 27. If a COMP is traced.256 -.1. thus controlling the amount of output as desired.32822 64.--MW[4] 6. ZDAT |?| ZDAT DEC |I| Example These statements illustrate REPORT.71 13-13 -.--MW[2] 3.923. Trace can be turned on and off at any time.---. Switch that indicates that the zonal data arrays generated by any FILEI ZDATI keywords are to be formatted and reported.1050 3-16 -.357.R1.357.14 -. turn stack tracing off MARGINREC=y LIST=J.256 -.256 -. REPORT MARGINS=1-3.Sum ----------.43. I1_I2_I3.14 16.' sum intras for 1-3='.77147 106.99 -.----------.Ave ---------ALL >0 <0 >0 <0 ALL >0 <0 MW[1] 16. request statistical summaries for working matrices Example MATSTAT REPORT: Table 1 .0145 3-16 -.378.R5_C5 MARGINREC=y LIST=J.R2.1.455.--.15.--MW[3] 0.-----------.print=y REPORT MATSTAT=MW .455.39.87686 38.8 .1015 13-12 -.--.17 -. This one value applies to all variables on all ZDATI statements.--.----------.86395 -Table 2 .27789 -MW[2] 9. so be careful). COUNTER COMP TOT1=0 TOT2=0 COUNTER=0 .--MW[3] 0.629.85625 -MW[3] 178.--- SET Programs: Distribution.007.--.378.70 -. All variables are set to zero at the beginning of the I loop.27 -.1.16 -. SET keywords Keyword VAL |R| Description Numeric value that the VARS that follow will be set to. Fratar.--.--.Matrix Intrazonal Min/Max (625 cells) ---------. Most changes are the result of COMP statements.70 1.629.96 -.-----------.12 5-5 -. or more. Generation.2. and then reset as this keyword is encountered. is the same as previous statement SET VARS=TOT1 TOT2 COUNTER .Matrix Program Control statements 9 ALL >0 <0 >0 <0 ALL >0 <0 MW[1] 3. is also the same (VAL defaults to 0) Cube Voyager Reference Guide 531 .99 -. VAL is initialized to zero when the statement is started.16 -.24750 -Table 4 . List of variables that are to be set to the more recent value of VAL obtained from this statement.7.TOT2.059.64 13-13 -.16 -. A COMP statement can accomplish all that SET does. VAL VARS Use SET to set any number of variables to some value. variables. VARS=TOT1.96 4.Maximum ------------->0 @I-J <0 @I-J >0 @I-J <0 @I-J MW[1] 4.09 12-12 -.99 3.27 178.867.788736 304.97 13-13 -.607520 101.4.285232 11.16 -.1. VARS |S| Example SET VAL=0. If a named VARS is an array allocated by an ARRAY statement.24937 -MW[2] 1.--MW[4] 18.74 7-7 -. but it is not as efficient.71 13-13 -.65 1-1 -. and are then changed only by the user.Minimum ------------.--. and is somewhat wordier.0.059.39.895984 191. Matrix Stores numeric values into one.14187 -MW[4] 4.867.370.82 3-3 -. the entire array is set to the value of VAL. If there is no VAL.--MW[2] 6. the coded VARS are all set to zero. Fratar.-HH. VARS=TOT1. HH[J] ENDJLOOP WRITE Programs: Distribution. sets all to 123 ARRAY SUMS=50 SET VAL=100. Generation. Generation.1.1. INCOME=ZONES . TOT3 .INCOME[I] . HH=ZONES. SORT ARRAY=-INCOME. ZONENO[I] = I HH[I] = ZI. sets all 50 cells of SUMS to 100 SET VARS=SUMS . . TOT2. VARS=SUMS . ARRAY NUMRECS See “SORT” on page 72 for details about the standard Cube Voyager statement. LIST=ZONENO[J].ZONENO. Example ARRAY ZONENO=ZONES. Matrix Sort user-defined arrays.HH[I] INCOME[I] = ZI. .9 Matrix Program Control statements SET VAL=123 VARS=C123. Fratar. sets all 50 cells of SUMS to 0 SORT Programs: Distribution. Matrix Output record data files to DBF format RECO 532 Cube Voyager Reference Guide . INCOME[J]. NUMRECS=ZONES LIST=’ Zone Income HHs’ JLOOP PRINT FORM=8. WRITE keyword Keyword RECO |I| Description Number of the FILEO RECO[#] DBF file where you want to direct this print output.Matrix Program Control statements 9 Use WRITE to specify the record files that are to be written at the end of each I zone. Cube Voyager Reference Guide 533 . mat zdati[1]=socoecon.2.1. 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 . hh2=#6.hh3 jloop include=1-5. this is a 10 zone problem area[i]=zi.38. gov=#2. Get I-J values for records with trip tours on them. /*Sample setup to use the MATRIX program to process the tours. tothh=10 .dat.2.dat. at last zone jloop .retail + zi. z=#1. retail=#3.1.1.1.145-150 .cbd zones cbdtrips[j] = cbdtrips[j] + mi.tottrips[j] endjloop if (i==zones) .other tothh[i]=zi.1.hh2 + zi. area=#3.hh1 + zi. other=#4 ARRAY pop=10.dat file 534 Cube Voyager Reference Guide .area totemp[i]=zi.z=#1. income=#4. hh3=#7 zdati[2]=employ.2.gov + zi.56-100.9 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. pop=#2. area=10 totemp=10. hh1=#5. mat. if main mode org-dst is hwy . but has not been thoroughly tested for logical content.42. The format is: MatVal( filenumber. vars=hwyt trnt .42 if (reci. initialize output variables . if main mode org-dst is hwy if (reci.mat reci=tours. or j) This script has been tested for validity. from file 1 table 1 hwyt[leg]=MatVal(1. look up highway or transit time based on the major mode for that journey. trips from org to dst from=ri. trips from dst to org Cube Voyager Reference Guide 535 .nfield[#]. flds 32.37.nfield[stops]. tablenumber.dst.nfield[76] = 1) . j. i.org leg=1 loop stops=32.org. from file 2 table 1 trnt[leg]=MatVal(2.0) endif leg=leg+1 from=reci.trntime. and field 26 as ri.5 . from file 2 table 1 trnt[leg]=MatVal(2.reci. failvalue) The failvalue is returned if lookup fails (invalid filenumber.1.Matrix Program Examples 9 For each leg of the tour. Field 23 can also be referenced as ri.nfield[76] = 1) . org=23.0) endif . assuming 1 is highway otherwise transit The program will read each input record from the RECI file and do calculations as specified. can be referenced by reci. there are 80 fields on the record.from.nfield[stops] > 0) .nfield[stops] endif endloop .dst .1.nfield[stops].0) else .1.1.from.0) else . The MatVal function is used to random access any i-j value from any input matrix.from. from last stop to dst if (reci. */ RUN PGM=MATRIX mati=hwytime.dst.from. . i. setup array to store time values with max of 8 legs on each tour array hwyt=8 trnt=8 set val=0.reci.ri. from file 1 table 1 hwyt[leg]=MatVal(1.dat. dst=26 .ri. tablenumber. 536 Cube Voyager Reference Guide .1. from file 2 table 1 trnt[leg]=MatVal(2. from file 2 table 1 trnt[leg]=MatVal(2.nfield[stops].dst leg=5 loop stops=47.ALLFIELDS. write out I/P record(RECI) and append highway and transit time values print file=tourtime.ri. hwyt[1]. from file 1 table 1 hwyt[leg]=MatVal(1. compute totals of highway and transit time arrays hwyt_tot=arraysum(hwyt) trnt_tot=arraysum(trnt) ENDRUN Example 3 /* This is an example of using RECI/RECO processing of DBF data files */ RUN PGM=MATRIX FILEI RECI = ZONES_2002.trnt[6]. from last stop to org if (reci.reci. from file 1 table 1 hwyt[leg]=MatVal(1. HH_2002(8.hwyt[6].hwyt[8]. FIELDS=RECI.1. HHsiz_2010(4.0).1. trnt[1].org.hwyt[5].nfield[stops] endif endloop . Pden_2002(6.ri.9 Matrix Program Examples from=ri.DBF FILEO RECO[1] = ZONES_2002_NEW.trnt[3].2).0). EXCLUDERECI=HOUSEHOLDS FILEO RECO[2] = ZONES_2010.0) else .from.nfield[77] = 1) .0).trnt[8] .dat. HH_2010(8. form=5 list=reci.trnt[7].1. HH_2002(8. HHsiz_2002(4.2). if main mode dst-org is hwy . Pden_2002(6.hwyt[7].hwyt[4].0) else .2). FIELDS=RECI.from.nfield[stops]. POP_2010(8.hwyt[3].2).trnt[2].2).5 if (reci. if main mode dst-org is hwy .0) endif leg=leg+1 from=reci.org.trnt[4].hwyt[2].nfield[stops] > 0) if (reci.trnt[5].2).reci.from.ALLFIELDS.0) endif .57.DBF.DBF. HHsiz_2002(4.0).nfield[77] = 1) . Pden_2010(4.from. POP_2002/HH_2002 .AREA/43560) . HHsiz_2002(4.2.NFIELD[6]*1.HH_2002=ri.POP_2010=RECI.NFIELD[6]*1.5 RO. rename RECI field RO.HHsiz_2002=ri.MAT" MO=1 NAME=HBW Cube Voyager Reference Guide 537 . HHsiz_2010(4.HHsiz_2020=POP_2020/HH_2020 RO. check for end of file PRINT LIST='Total Households = '.2). print regional base year statistics if (I=0) .AREA/43560) .DBF.8 RO.AREA/43560) .0). HHsiz_2020(4. compute regional base year statistics TotalHH=TotalHH+RECI.Pden_2010=POP_2010/(ri. POP_2010(8.HHsiz_2010=POP_2010/HH_2010 RO.HOUSEHOLDS . FIELDS=RECI. Pden_2020(6. Pden_2002(6.0).2).4 RO. factor base year data for 2020 RO.avgHHsize endif .3 ENDRUN Example 4 /* Example of using the CHOICE command in MATRIX to estimate a singly constrained gravity model constrained on Production trip ends */ RUN PGM=MATRIX FILEO MATO[1] = "C:\CUBETOWN\MODEL\MODELS\SINGLEPRODDIST.Pden_2002=ri.0).POP_2002/(ri.2). factor base year data for 2010 RO. write data to defined output files WRITE RECO=1.HH_2020=HH_2002*1. calculate zonal average household size for base year RO. calculate zonal population density per/acre for base year RO.Pden_2020=POP_2020/(ri. EXCLUDERECI=HOUSEHOLDS .TotalPop PRINT LIST='Average Household size = '. POP_2020(8.2). HH_2002(8.Matrix Program Examples 9 EXCLUDERECI=HOUSEHOLDS FILEO RECO[3] = ZONES_2020.2).TotalHH PRINT LIST='Total Population = '.0).HH_2010=HH_2002*1.2 RO. Pden_2010(6.POP_2020=RECI.ALLFIELDS.2).NFIELD[5] TotalPop=TotalPop+RECI.NFIELD[6] avgHHsize=TotalPop/TotalHH .0). HH_2020(8. HH_2010(8. 1. TOTAL=ZI. COSTS=mi. reading the transposed costs.1.e. to implement a destination choice. STARTMW=99. DESTSPLIT = TOTAL 0.run MATRIX. .ZONE_=DI.If you require a gamma curve deterrence function rather than the negative exponential. .mdb\BETA". production and attraction data (i.A[1] etc) . DEMAND=ZI. ODEMAND=1.1.BETA WRITE RECO=1 538 Cube Voyager Reference Guide . SORT=ZONE_ JOINTODBI=1 JOINTOFIELDS=ZONE_ FILEI DBI[1] = "DBI_Examples.NUMRECORDS x=DBIReadRecord(1..you need to specify the appropriate calculations yourself. . CHOICE ALTERNATIVES=all1.ALFA RO.P1.The general approach for a singly constrained in Voyager is to use the MATRIX . ENDRUN Example 5 /* Example of DBI processing to combined two fields from different tables stored in a MDB file to a new table in the MDB file using the JOINTTODBI functionality.mdb\AlfaBeta2".program and the CHOICE command to implement a destination choice model.This example gives a ”destination choice” model constrained on production trip ends.ALFA=DI. saving it to output file .1.1. . reversing your use of the . ..ZONE_ RO.9 Matrix Program Examples FILEI ZDATI[1] = "{SCENARIO_DIR}\TRIPENDS.k) RO.2 all1 .1. */ RUN PGM=MATRIX FILEO RECO[1] = "DBI_Examples.mdb\ALFA" ZONES=1 LOOP k=1.transpose the cost matrix.transpose the resulting matrix to correct orientation..To apply singly constrained on attractions.DBI.BETA=DI.2.MAT" .1. FIELDS=ZONE_ ALFA BETA FILEI DBI[2] = "DBI_Examples.DBF" FILEI MATI[1] = "{SCENARIO_DIR}\CURRENTCOSTS. with attraction totals as the single constraint.. 1.ZONE_ = L3 RO.Matrix Program Examples 9 ENDLOOP ENDRUN Example 6 /* The same process as Example 5 but using AUTOARRAY functionality to accomplish the same task.ALFA[L3] RO. AUTOARRAY=BETA FILEI DBI[1] = "DBI_Examples.mdb\BETA".DBI.mdb\AlfaBeta3".4) FILEI DBI[2] = "DBI_Examples.BETA[L3] WRITE RECO = 1 ENDLOOP ENDRUN Cube Voyager Reference Guide 539 .NUMRECORDS.BETA = DBA.mdb\ALFA".4) BETA(10. */ RUN PGM=MATRIX FILEO RECO[1] = "DBI_Examples.1.1 RO.2. AUTOARRAY=ALFA ZONES = 1 LOOP L3=1. FIELDS = ZONE_ ALFA(10.ALFA = DBA. 9 Matrix Program Examples 540 Cube Voyager Reference Guide . Cube Voyager Reference Guide 10 Distribution Program This chapter discusses the trip distribution process. Topics include: • • • Introduction to the Distribution program Control statements Examples Cube Voyager Reference Guide 541 . additional information about some measure of travel between each zone pair should be included in the process. trip distribution process. A gravity model distribution can be easily implemented within Matrix. The Matrix program provides a framework that allows the user to perform distribution in a variety of ways. 542 Cube Voyager Reference Guide .n (A * func(T)). The most commonly used distribution process is the “gravity” model. Cube Voyager does not have any automatic. where: P = the number of trip productions for a zone. and the user has to follow certain guidelines for proper implementation. These margin totals are distributed to the rows and column of a generated matrix. the Matrix program does have some built-in functions that aid in the implementation of the more popular distribution processes. A brief illustration of a typical gravity distribution follows.. but other processes are also employed. In some cases.10 Distribution Program Introduction to the Distribution program Introduction to the Distribution program This section introduces you to the Distribution program. or default. Usually. The gravity model equation is: TRIPi-j = Pi * Aj * func(Ti-j) / Sz=1. but it does need some help. Usually the process uses the number of trip ends in each zone as the starting point. 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. j = the attraction zone. several guidelines must be followed: • There must be a set of Ps and As for each purpose to be estimated. Many agencies share the same curves when their regions are similar in nature. To facilitate application. n = the number of zones. z = any zone. The function of spatial separation (func(T)) is the indefinite portion of the equation. Experience has shown that often a single curve does not suffice. 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. where b is the curve factor. It is believed to be best described by an expression of the form of e^bT. Each J will then be given a prorata share of the productions for I based upon its attractiveness relative to the accessibility index for I. and T is the travel time. They are established by the presence of a SETPA control statement. 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. most gravity model processes use a lookup function to obtain empirical values for the function based upon the impedance. To implement the gravity model in Matrix. T = the travel impedance factor between zones. and it difficult to estimate what b should be used. Each J’s attractiveness is determined by the product of its attractions and some function of the spatial separation between I and J.Distribution Program Introduction to the Distribution program 10 A = the number of trip attractions for a zone. i = the production zone. The sum of the these products for all Js (relative to I) is obtained and often referred to as the accessibility index for I. Cube Voyager Reference Guide 543 . A singly constrained gravity model can be formulated as a destinationchoice model with the CHOICE control statement in Matrix. MO=1 LOOKUP NAME=FF.Z=#1. Usually. a level-of-service matrix is used to obtain the zone-tozone impedance for I-J. FFACTORS=FF .P1=#2.MAT The productions and attractions are in file: PA. FILE=FF. faster process 544 Cube Voyager Reference Guide . A[1]=ZI.1.A1 MW[1] = A[1] * FF(1. and one to distribute the productions based upon the values and the accessibility index. LOS=MI.1. ZDATI[1] = PA. and the travel function value (friction factor) is obtained by finding the impedance in a LOOKUP table.A1=#3 FILEO MATO[1] = OUT. one to sum them to form the accessibility index for I. INTERPOLATE=Y SETPA P[1]=ZI. these expressions must be executed in the proper order.MI. Example 1 /* given: The impedances are in the first matrix of file: IMP.10 Distribution Program Introduction to the Distribution program • A mechanism must be established to obtain the travel function. See “Examples” on page 534 under the Matrix program for an example of a singly constrained gravity model. At least three expressions are required. The gravity model equations must be executed in a specific order.RESULT=#1.LOOKUP[1]=#2.1). • As an alternative to complete user definition of the gravity formulation.1. PAF=P[1]/ROWSUM(1). Obviously. MW[1]=PAF * MW[1] GRAVITY PURPOSE=1.1. This process is more efficient than complete formulation. the GRAVITY control statements can be used to perform a built in process for a doubly constrained GRAVITY model.1.DAT */ FILEI MATI[1] = IMP. One to compute attractiveness for each J.P1.ZDA The friction factors are in file: FF.MAT.DAT.MAT.ZDA. -. This problem is alleviated by iterating the model.-. A set of A values internally named Used are set equal to the Desired values. and. The row totals shown are the Desired Ps for each zone. the estimated column totals are compared to the input As.-. The model goal is to fill in the matrix with values so that the totals will match the totals shown. or that a maximum number of iterations have been performed.100 2 -. the row (production zone) totals for each will always match the number Ps for the zone. An iteration is a complete pass for all I zones. At the end of each iteration.-. the process is repeated with an adjustment in the data. In all likelihood.-. 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 Cube Voyager Reference Guide 545 .Distribution Program Introduction to the Distribution program 10 Convergence: Iteration control The gravity model equation ensures that the correct number of trips will be distributed for each I zone. The adjustment is based upon the closeness for each zone. Following is small example of this process: Prior to the first iteration the desired totals are: Zone 1 2 3 Total 1 -. and the column totals are the Desired As. based upon the comparison.300 Total 240 200 160 600 There really is no matrix yet. the estimated column values will not match the desired number of As input for each zone. The totals are the values as obtained from the SETPA control statements. There is no method to guarantee that the correct column totals (number of attractions) will be obtained for each J zone.-.200 3 -. The iteration process is repeated until it is decided that the results are close enough. The As for each zone are adjusted by a factor that is computed as: Desired * Used / Estimated. Another iteration is performed. The model is completed. In the real world. But. in this simple three zone problem. it is not likely that all the Estimated totals would match exactly with the Desired totals. 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.10 Distribution Program Introduction to the Distribution program As dictated by the formulation. The default is MAXITERS=3. 546 Cube Voyager Reference Guide . so adjustments are made to the used As. 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. with many zones. nothing would change. How does the program decide when it should stop? There are two parameters that can be used for controlling cutoff: MAXITERS and MAXRMSE. the totals did not match exactly (there were some slight differences in the decimal places). this is usually sufficient for most gravity model applications. As a matter of fact. But. the Estimated column totals do not quite match the Desired. and another iteration is performed. the floating point values were close enough to be accepted as having matched. Further iterations would be useless. Additionally. MAXITERS specifies that no more than a specified number of iterations are to be performed. the row totals are correct. the program knows when the last iteration is being processed. and some prefer to do them all at once.26. some analysts prefer to estimate them in a separate application. Home Based Other (HBO). friction factors. expressions. With the Cube Voyager process. and MAXITERS has not been reached. another iteration will be processed with adjusted As for all purposes. If the computed RMSE is less than MAXRMSE. they were insignificant. but this time writing Cube Voyager Reference Guide 547 . 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. and 0. The default is MAXRMSE=10. In the sample three zone problem the RMSEs for each iteration were computed as: 22. etc. and Non Home Based (NHB). That is no concern. If the default MAXRMSE value had been used. similar to the one just completed. There is one caveat: If convergence has not been reached for any purpose. The Ps and As and lookup functions can be obtained from different sources. a completion flag is set. the results will not get worse. The MAXRMSE parameter applies to the highest RMSE of all purposes. Each purpose can have its own impedance matrix and different formulation (functions. convergence could be obtained at some lower iteration. But.). In that case the program will perform another iteration. There are other popular purpose stratification. the process would have cutoff after two iterations. If the iteration number is equal to the PARAMETERS MAXITERS value. Desired attractions (sqrt (Sum(diff^2) / (n-1)). The final value of 0. MATO files are written only on the last iteration. Traditionally. 2.26 indicates that there were still some slight differences in the Estimated and Desired. but as noted above. at least three internal purposes are estimated. but that may not always be a good choice for certain applications. Often Internal-External and External-Internal and truck and taxi purposes are also estimated. Multiple purposes Usually a given application will consist of more than one purpose. but these are the most commonly used.78.Distribution Program Introduction to the Distribution program 10 the program computes the root mean square error of the differences in Estimated vs. with the most commonly used purposes being: Home Based Work (HBW).08. 1. but they will not be involved in any internal purpose editing. and two internal-external purposes (with entirely different formulation) are to also be included. The program assumes that there will be purposes from one. NAME=FF.1. and purpose 5 uses a simple lookup curve.1. FAIL=12000. above.RESULT=4 548 Cube Voyager Reference Guide . The use of PARAMETERS MATOEVERY will preclude an additional iteration. P[2]=ZI. LOOKUP[1]=1.RESULT=4 SETPA P[1]=ZI.1) PAF=P[PURP]/ROWSUM(PURP) MW[PURP]=PAF*MW[PURP] ENDLOOP In Example 3. Example 3 LOOKUP FILE=FF. LOOKUP[3]=1. A[3]=ZI. LOOKUP[1]=1. an additional iteration will be performed in order to obtain the matrices. Purpose 4 uses an equation for distribution.same P/A and FF file for all purposes LOOKUP FILE=FF.A2.P2.P1. INTERPOLATE=Y. but at the cost of additional time to write matrices during each iteration. Other COMP MW[]= statements may be specified. NAME=FF.DAT. LOOKUP[2]=1.RESULT=3.RESULT=2.3 MW[PURP] = A[PURP] * FF(PURP.0.A3 LOOP PURP=1. LOOKUP[3]=1. A[1]=ZI.1. the set up is only slightly different from what is depicted. INTERPOLATE=Y.A1.RESULT=2. if convergence is reached before MAXITERS.10 Distribution Program Introduction to the Distribution program the MATO files.1.1. with only three points in it. purposes 1-3 are the same as in Example 2. The number of purposes is determined by the highest P[] or A[] index established via the SETPA control statement. A[2]=ZI.RESULT=3. Example 2: Three purpose . In other words. If the estimates follow the same formulation. P[3]=ZI.1.MI.DAT. monotonically. Example 2 illustrates a typical setup for a three purpose application.P3. through that highest index.1. LOOKUP[2]=1. where the first index references the purpose number.P1.100.STACNT_IB LOOP PURP=1.1. read the data directly '400 20-30'. FAIL=500. Referencing productions and attractions Productions and attractions are referenced by using array notation for P and A.PI.2.A1.3.MI.1. it will be automatically provided. A[3]=ZI.IMPEDNACE IF (MI.3 IF (PURP <= 3) MW[PURP] = A[PURP] * FF(PURP.1. A[5]=ZI. MW[PURP]=PAF*MW[PURP] ENDLOOP Of course. However.AI.P3.2.Distribution Program Introduction to the Distribution program 10 LOOKUP NAME=XIFF. Differences in the totals would preclude convergence via RMSE calculations because there would always be differences. the purpose 4 and 5 Ps and As would not sum to the same total because they were derived from separate sources.1) ELSEIF (PURP==4) JLOOP INCLUDE=1-500 IMP = MI. '200 40-50' SETPA P[1]=ZI.2. P[5]=ZI. '300 30-40'. there are different ways that this distribution could have been written.2. If there is a difference in the totals for a purpose. Since most users may not wish to always code a zone index (it is more intuitive to reference the arrays with just purpose number).STACNT_OB. P[2]=ZI. the program issues a message and adjusts the As to match the P total.1. P and A are doubly dimensioned arrays.1.IMPEDANCE) INCLUDE=501-535 ENDIF PAF=P[PURP] / ROWSUM(PURP).P2. .DISTANCE < 3) IMP = MI. the zone index need not be supplied. A[1]=ZI. A[2]=ZI. and the second index references the zone number.1.2. the zone index has Cube Voyager Reference Guide 549 .SHORTIMP MW[4] = A[4]*EXP(-B * IMP) ENDJLOOP ELSE MW[5] = A[5] * XIFF(MI.3.1. P[3]=ZI. A[4]=ZI.A2. Most likely. R= '500 1-20'.A3 SETPA P[4]=ZI.2. 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. Zone 0 should always contain the total for the purpose. respectively. they are normally input to the program from an external lookup file. Purpose 0 and Zone 0 are valid.5 could be either 9000 or 8500. and the friction factor for purpose 2 would be 8000. the default zone index is I and for A. RESULT=2. except on SETPA statements. 2. and 4 are the values for purpose 1. The friction factor for purpose 1 for 1 minute would be 9000. For P. LOOKUP[2]=1. LOOKUP[3]=1. RESULT=3. NAME=FF. RESULT=4 This statement indicates that the first four values from each record will be used. and 3. but may not always be predictable. LOOKUP[1]=1. and the upper bounds are “number of purposes” and zones. If a different index is required. The curves are organized vertically on the records of the file. Travel function values: Friction factors If friction factors are to be used in the distribution process. If 550 Cube Voyager Reference Guide . respectively. depending upon the options specified on the LOOKUP statement. it is J. they may not be the result of COMP expressions.10 Distribution Program Introduction to the Distribution program different meanings for P and A. P and A are protected variables. The friction factor for purpose 1 for a time value of 1. The lower bounds for both indices are zero. 3. Field 1 will be the travel time value. it may be explicitly provided. The lookup file is usually formatted as a series of curves – one curve for each trip purpose. and fields 2. Most times an invalid index will cause a fatal termination. any time greater than 50 would be 0. a time value of 0. This can also be controlled by use of the LOSRANGE keyword on the GRAVITY statement. If the record for 51 were not in the file. if FAIL[2]=0 were used. However. The friction for any value greater than 51 will be 0. In this example. and if SETUPPER=F and INTERPOLATE=T. the friction factor for any time greater than 50 would be 1. the friction will be 8500. the friction factor will be 9000. 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.5 will result in the value 9000. because there is no explicit FAIL[1] specified.Distribution Program Introduction to the Distribution program 10 SETUPPER=T is specified. no distribution. This capability allows for compatibility with other model systems. Cube Voyager Reference Guide 551 . Since the Distribution program is a subset of the Matrix program. and a few additional ones are available. For descriptions of other control statements see “Control statements” on page 436 under the Matrix program. PURPOSE LOS FFACTORS KFACTORS LOSRANGE 552 Cube Voyager Reference Guide . Only the differences between the Matrix and Distribution control statements are included in this section. 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. it is assumed that the user is familiar with the Matrix-program control statement set.10 Distribution Program Control statements Control statements Most of the standard Matrix program statements are valid in the Distribution program. It is more efficient than using multiple COMP statements to formulate the same process. The value MUST be either a MW[#] or an MI. The lookup arguments will be automatically set to the value from the LOS matrix and the PURPOSE number. and FFACTORS must be specified.name/#. 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.Distribution Program Control statements 10 This statement is used to have the program compute a distribution based upon traditional gravity model formulation for a single purpose. no arguments should be used with the lookup name.result=4. file=tstff1. Cube Voyager Reference Guide 553 .0. The value MUST be either a MW[#] or an MI.1. Default range is 0 . Specifies which purpose this is calculation to: the results will be stored in MW[PURPOSE]. In this statement.#.name/#. GRAVITY keywords Keyword FFACTORS |SN| Description Specifies the expression that results in the friction factor that a gravity equation expects.result=2. LOS. Specifies the matrix that contains the level-of-service values for each I-J distribution. Normally. Specifies the matrix that contains the K-factor values for each I-J distribution. lookup[1]=1. The first number must be 0.result=3. The lookup table is expected to be in the form shown in the Examples. and the second value must be greater than the first. Example lookup fail=12000. This keyword must be followed by a pair of numbers separated by a dash. name=ff. there will be no distribution between for I-J. or greater. KFACTORS |S| LOS |S| LOSRANGE [R] PURPOSE |I| PURPOSE. list=n.999999. Optional. lookup[3]=1.#. Specifies the range of LOS values that are valid for use in the distribution process. lookup[2]=1. If an I-J values is less than the first value or greater than the second value. See “LOOKUP” on page 51 for hints about using Lookups to obtain friction factors. result=5. gravity purpose=5. los=mw[11]. instead of waiting until the last iteration. Since the program does not know that a particular iteration will be the final one until after it completes the iteration. This saves a considerable amount of computer time for larger systems.K5 PARAMETERS Sets general parameters. If it is anticipated that there will be many iterations to reach convergence. But. lookup[5]=1.10 Distribution Program Control statements lookup[4]=1. losrange=11-48 ffactors=ff ffactors=ff ffactors=ff. gravity purpose=4.1.result=6. gravity purpose=3.setupper=n gravity purpose=1. los=mw[11]. This causes the program to run somewhat longer for each iteration. interpolate=y. but may preclude the program from having to run another iteration to obtain the output matrices once convergence is reached. ffactors=ff ffactors=ff. PARAMETERS keyword Keyword MATOEVERY |K?| Description Switch that can be used to force the program to write output matrices for every iteration. it does force another processing iteration to write the matrices once it has determined that this is the last iteration. los=mw[11]. 554 Cube Voyager Reference Guide . the parameters described here may also be specified. it normally does not write matrices for the iteration. los=mw[11]. gravity purpose=2. Kfactors=MI. los=mw[11]. If it is anticipated that the process will involve only a few iterations. it is probably better to set this switch false. it is probably better to set this switch true. MATOEVERY MAXITERS MAXRMSE ZONES In addition to the standard Matrix-program parameters. 0001. Normally.Distribution Program Control statements 10 PARAMETERS keyword (continued) Keyword MAXITERS |KI| Description Specifies the maximum number of iterations to perform. Specifies the highest zone number to process. MAXRMSE |KR| ZONES |KI| REPORT Specifies Matrix program reports. ZONES must be provided. the number of iterations actually performed could be less than this value. If the highest RMSE (for any purpose) exceeds this value. if all the purpose RMSEs are less than this value. automatic cutoff is triggered. The default is 3. or the value will default to 100. and the minimum is 0. If the number of zones can not be ascertained from the project file or from any binary input matrices. so this keyword should not be required. Cube Voyager Reference Guide 555 . automatic cutoff is not triggered. there will be an input matrix file. Specifies the cutoff criteria. If present. one more iteration will be run (with the same values as the converging iteration) so that the MATO matrices will be written. If the MAXRMSE criterion is met. If the model converges in fewer iterations. Conversely. this value controls the application. and the max is 99. The default is 10. Only the purposes specified by the keyword are reported.10. The report is in a format that is similar the MARGINS report. There should be a P[]= and A[]= expression for every 556 Cube Voyager Reference Guide . If the values for ACOMP are followed by ITERATIONS.99 . In ACOMP reports. and how many purposes are to be processed. if it is not included. then those ACOMP purposes will be printed only during the iterations specified. the reports will be printed for the last iteration (no matter how it is determined: parameter or convergence). the program will fatally terminate. the report will be printed for every iteration (could be quite voluminous). 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). If no ITERATIONS follow ACOMP values. specified purposes and iterations REPORT ACOMP=6 .5 ITERATIONS=5. The values are reported as nearest integers (without decimal places).10 Distribution Program Control statements ACOMP (ITERATIONS) REPORT keywords Keyword ACOMP |KIP| Description Requests that the comparison of Estimated vs. ITERATIONS |IP| Example REPORT ACOMP=1-3. If at least one value is equal to. for all iterations SETPA Establishes base productions and attractions. Desired attractions be reported for the specified purposes. The statement defines to the program how the desired productions and attractions are to be obtained. If there are no ITERATIONS specified. the reports will be printed for all iterations. P A INCLUDE EXCLUDE The SETPA statement is required. Specifies the iterations for which the prior ACOMP purposes reports are to be printed. or exceeds. the PARAMETERS MAXITERS. If it is used. In most cases. If the same purpose is referenced more than one time (this is acceptable). The total of the As should match the total of the Ps for each purpose. Duplication of purposes might be helpful if values for different zones for a purpose are to be obtained from different sources. The SETPA expressions are computed in the order in which they appear in the control stream. the As are scaled so that the A total will match the P total. until all purposes are defined. INCLUDE |IP| Cube Voyager Reference Guide 557 . or if different INCLUDE/EXCLUDE filters are to be used (separate SETPA statements must be used for different filters).Distribution Program Control statements 10 purpose beginning with 1 and continuing. Processed the same as INCLUDE on COMP statements. SETPA keywords Keyword A EXCLUDE |NV| |IP| Description Expression that is solved to set the attractions for the indexed purpose. but the use of any variables in the expression could cause unpredictable results. If the totals differ by any amount. the subsequent values will replace the prior values. The Ps and As are computed from the expressions that are supplied. Complex expressions are allowed. and they are computed only one time -. Processed the same as EXCLUDE on COMP statements. the expression is solved in a loop of J=1-Zones. For each array. a message is issued. it is acceptable to set the Ps. The highest index encountered establishes the number of purposes. and then set the As equal to the Ps. the expression will simply point to a ZDATI file variable.prior to the first iteration. In a purpose where the Ps and As are the same for each zone. monotonically. If there are any holes in the purpose scheme. INCLUDE filtering precedes any EXCLUDE zones. the program will issue a warning statement. If it is used. the loop will not be processed for any zones in the list. If the totals differ by more than five percent of the P total. and the results are stored in the A[n][J] or P[n][J] cells. EXCLUDE filtering follows any INCLUDE filtering. (NonHomeBased is a typical example). A and P may not have a zone index in the SETPA statement. the loop will not be processed for any zones not in the list. 10 Distribution Program Control statements SETPA keywords (continued) Keyword P |NV| Description Expression that is solved to set the productions for the indexed purpose.a2. .1. Example SETPA INCLUDE=1-500.1. P[3]=zi. weird. merges with prior SETPA P[5]=sqrt(A[3]). A[1]=zi. A[5]=A[1]+A[2]+A[3] .p1.1. A[4]=10 . P[4]=zi.2. get only external data P[1]=zi.cnt.p1.cnt.p2.nhb.1. A[2]=zi. . .1. internal zone data only P[1]=zi. A[3]=P[3]. equal attraction for all zones SETPA EXCLUDE=1-500.2. but will work 558 Cube Voyager Reference Guide . P[2]=zi.a1.1. A[1]=zi. P1=2.MI. RESULT=5. P4=5. FILE=TSTFF1. LOOKUP[3]=1.1.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.1. A2=8. RESULT=3.1.MAT MATO = GMTRIPS.1.A4=10. RESULT=4. A5=11 MATI[1]=C:\DEMO\DEMO11. P5=6. NHB.A2=8. A1=7. SETUPPER=Y MAXITERS=3 MAXRMSE=10 SETPA P[1]=ZI.P5=6.1) SUMAF = ROWSUM(PURP) IF (SUMAF > 0) MW[PURP] = P[PURP]/SUMAF * MW[PURP] ENDLOOP ENDRUN Distribution example 2 /* Gravity Application illustrating several ways to do gravity model */ RUN PGM=DISTRIBUTION REPORT ZDAT=Y ZDATI[1]=TSTPA1.P5 SETPA A[1]=ZI. INTERPOLATE=N.1.Z=#1. LOOKUP[1]=1.1. RESULT=6. RESULT=2.P1 P[2]=ZI.A5=11 MATI = IMPEDE.A5 LOOP PURP=1.A1=7. LOOKUP[4]=1. A3=9.P4 P[5]=ZI.1. LOOKUP[5]=1. NAME=HBW.1. P2=3. LIST=N.A4 A[5]=ZI.1. NAME=FF.1.P2 P[3]=ZI.P3=4. HBO.0.1.A1 A[2]=ZI. A4=10. P1=2. P3=4. IX.P4=5.5 .A3 A[4]=ZI.1.P2=3. LOOKUP[2]=1.DO PURPOSES 1-5 MW[PURP] = A[PURP][J] * FF(PURP.A3=9. MO=1-5.A2 A[3]=ZI. XI LOOKUP FAIL=12000.DAT Cube Voyager Reference Guide 559 .P3 P[4]=ZI.Z=#1. p2=3.a3=8. FFACTORS=FF GRAVITY PURPOSE=4.z=#1. distribute with user equation (Results in MW[6-10]) PP = PURP+5 MW[PP] = A[PURP][J]*FF(PURP.a2=7. LIST=N. LOS=MW[11]. . LOS=MW[11]. RESULT=5. . in order to generate a trip table. FFACTORS=FF GRAVITY PURPOSE=3. NAME=FF. LOS=MW[11]. RESULT=4.Income4 PAR maxiters=20 maxrmse=10 560 Cube Voyager Reference Guide .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.1 LOOP PURP=1.1.-----------------------------------------------------. Finally. This script reads the composite time skim table created . .Income3.0. LOS=MW[11]. mo=1-4. run pgm=tripdist zdati[1]=hbwpa. new trip table. FFACTORS=FF ENDRUN Distribution example 3 /* Gravity Application illustrating use of GAMMA Impedance function */ . . RESULT=3. LOOKUP[4]=1. FILE=TSTFF1.10 Distribution Program Examples 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.p1=2.5 .-----------------------------------------------------. FFACTORS=FF GRAVITY PURPOSE=2. RESULT=6. LOOKUP[3]=1.Income2.txt. from the AM peak period highway and transit skims. This script then performs the gravity model using the .MAT mato=hbwgm. RESULT=2.a1=6. INTERPOLATE=Y. LOOKUP[2]=1. HBW GRAVITY MODEL USING GAMMA IMPEDANCES .p4=5. LOS=MW[11]. SETUPPER=N MAXITERS=20 MAXRMSE=35 MW[11]=MI.p3=4. name=Income1. a trip length frequency is performed for the . FFACTORS=FF GRAVITY PURPOSE=5. estimated friction factors along with the P's & A's .a4=9 mati=SKIM. LOOKUP[1]=1.mat.1. LOOKUP[5]=1. RANGE=1-140. Beta ' 3 -0. .1.1. .123'. . Gamma Function Parameters LOOKUP[1]=1. ======================LOOKUP FUNCTION===================== LOOKUP NAME=_FFParms.020 -0. Output Gamma Skim .p1 p[2]=zi.. RANGE=1-140.123'.4 .Distribution Program Examples 10 setpa p[1]=zi. Income Class 3. 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 .1.a2.p2.4 . ======CREATE GAMMA VALUE MATRICES FOR EACH INCOME CLASS===== LOOP Inc=1. Beta ' 2 -0. Income Class 4. time for income class 3 mw[14]=mi.1. a[3]=zi.020 -0.1.Inc) TSKIM=INC+10 . Alpha. time for income class 2 mw[13]=mi. RANGE=1-140. Alpha. Income Class 2. TITLE='** HBW Income Class 1 Travel Time Frequency **' FREQUENCY VALUEMW=2 BASEMW=12. p[3]=zi.p3 p[4]=zi.a1 a[2]=zi. Input Time Skim to MW[11] to MW[14] GSKIM=INC+20 . time for income class 1 mw[12]=mi. PUT GAMMA MATRICES IN MW[21]-MW[24] mw[GSKIM]=(mw[TSKIM]^_b)*exp(_c*mw[TSKIM]) ENDLOOP . Beta .1. TITLE='** HBW Income Class 3 Travel Time Frequency **' FREQUENCY VALUEMW=4 BASEMW=14.1.123'.020 -0. Beta ' 4 -0. TITLE='** HBW Income Class 2 Travel Time Frequency **' FREQUENCY VALUEMW=3 BASEMW=13. Set P and A Fields .020 -0.a4 .2 . TITLE='** HBW Income Class 4 Travel Time Frequency **' endrun Cube Voyager Reference Guide 561 .1.1.1. time for income class 4 . Income Class 1.1. BETA VALUE INTERPOLATE=N.a3 a[4]=zi.3 . . RESULT=2.p4. ALPHA VALUE LOOKUP[2]=1.Inc) _c=_FFParms(2. =================PERFORM TRIP DISTRIBUTION================= LOOP PURP=1. Alpha. Alpha. ==============Put TIME VALUES IN WORKING MATRICES=========== mw[11]=mi.1 . .1. ========GENERATE FREQUENCY REPORTS BASED ON TIME============ FREQUENCY VALUEMW=1 BASEMW=11. No Interpolation needed on income class R=' 1 -0. a[1]=zi. . RANGE=1-140.123' .4 _b=_FFParms(1. RESULT=3. 10 Distribution Program Examples 562 Cube Voyager Reference Guide . Cube Voyager Reference Guide 11 Generation Program This chapter discusses the Generation program. Topics include: • • • Introduction to Generation program Control statements Examples Cube Voyager Reference Guide 563 . Generation is a direct application of Matrix. To make things a little more meaningful to some users. The computed Ps and As are stored into arrays and must be referenced with array notation. Productions and attractions are to be computed for each zone. Its purpose is to provide capabilities to adjust and/or balance final production and attraction totals. The Generation program has two processing phases and stacks: the normal stack (ILOOP) that begins with the first stack statement. The arrays are doubly dimensioned. There are a few control statements and keywords in the Matrix control set that are not valid in a Generation application. but if one is used. There may be up to twenty trip purposes estimated in a single application.after the I loop is completed. Usually. The I loop processes only the normal stack statements. very little is assumed by the program. The program processes within an overall origin zone loop controlled by the variable named I. computations. There is very little need to use a JLOOP. and output. However. you use the Generation program to produce trip end data files (productions and attractions) for use in a trip distribution model. the capability is nearly open-ended. I and Z can not be revised by the user).11 Generation Program Introduction to Generation program Introduction to Generation program The Generation program processes zonal data according to specified expressions. they are referred to as P and A. which begins with the statements following the PHASE=ADJUST statement. it is your responsibility to specify what is to be accomplished. It is the user’s responsibility to program the logic. There may be up to twenty Ps and twenty As for each zone. There are no default processes. and generates arrays of productions and attractions for up to twenty purposes. (A companion variable Z is set to I every time I is changed internally. respectively. I may alternatively be referenced as Z. The ADJUST stack is processed one time only -. Only the first index (purpose) is required. it does not proceed beyond the PHASE=ADJUST statement. and an optional ADJUST stack. the second index (zone) is optional. it is suggested that P and A references within the JLOOP 564 Cube Voyager Reference Guide . The zonal index will be set to I if it is not specified. 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. sets only 1 cell P[1] = A[1] . A more detailed expression would be P[1][I] = ZI. It should be noted that IF/ENDIF. The lower limit for each index is 0. COMP P and A is processed for a single zone index (I). In ILOOP.1.Generation Program Introduction to Generation program 11 contain both indices. The program will treat such conditions as errors. P[1]=ZI. The statements in the ADJUST stack can reference index [0] to obtain row and/or column totals. Example A[1] = 1 . row and column 0 cells are set to the marginal values. a COMP P and A causes processing for all zones in that P or A. LOOP/ENDLOOP. Any attempt to use an invalid index will result in a fatal message. When the ILOOP phase is completed.POP indicates that the productions for purpose 1 for the current I zone are to be obtained from the ZDATI[1] array named POP. the program fills in the [0] row and [0] columns for the P and A arrays. double indexing on the right side of the equal sign can set the process to compute for only that specific zone. There is a significant difference when referencing P and A in COMP statements in the ADJUST stack. The COMP functions. 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] . Cube Voyager Reference Guide 565 . This is to simplify the final adjusting process. in ADJUST.POP[I]. PTOT(#) and ATOT(#) can also be used at any time to compute the totals for purpose #.1. but such detail is not necessary. However. the upper limits are MAXPURPS and ZONES. and JLOOP/ENDJOOP blocks and any GOTOs may not span a PHASE. . Only the differences between the Matrix and Generation control statements are included in this section. and a few additional ones are available. it is assumed that the user is familiar with the Matrix control statement set. ENDPROCESS PHASE= BALANCE A2P= P2A= NHB= Generation keywords not in Matrix: • • • • FILEO PAO= COMP A= P= PARAMETERS MAXPURPS= REPORT PC= AC= P= A= 566 Cube Voyager Reference Guide . For descriptions of other control statements see “Control statements” on page 436.11 Generation Program Control statements Control statements Most of the standard Matrix program statements are valid in the Generation program.. Since the Generation program is a subset of the Matrix program. 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 . P2A=list A2P=list NHB=list This statement makes the adjustment process much simpler. 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. P/A row.2. Typically. Example BALANCE A2P=1. most users adjust the Attraction totals to match the Production Totals. First Cube Voyager Reference Guide 567 .Generation Program Control statements 11 BALANCE This statement is used to specify how the trip ends are to be adjusted in the Phase=Adjust process. and then the productions are set equal to the attractions for each zone.4-7 NHB=3 COMP Computes a variable. It is used to compute variable and P and A array values. or P/A row element VAR=expression P/A[]=expression INCLUDE EXCLUDE The COMP statement is probably the most important of all the statements in the program. Specifies the purposes whose production totals are to be set to the attraction totals for that purpose. 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. The major difference between the Generation and Matrix programs for COMP statements is in the use of P/A[] and MW[]. Specifies the purposes whose attraction totals are to be set to the production totals for that purpose. While in the Generation program. See “COMP” on page 460 for details of COMP statements. the J loops from I to I (a single iteration). Example COMP P[1]= ZI.SPECIAL FILEO Generates trip-end records. Secondly.1. the J loops from 1 to zones. The result is stored in A[n][I]. each one should reference a different file. If the second [] is not specified. The flexibility of the statement can allow records to be written in almost any format that other software systems might 568 Cube Voyager Reference Guide . which return the attraction and production totals for purpose #.11 Generation Program Control statements of all. COMP keywords Keyword A[n][I] |N| Description Causes the program to solve the expression for each value of J. it will default to I. The result is stored in P[n][I]. There may be multiple PAO specifications. it will default to I. Within the ADJUST phase.90*ahbo IF (I=38-49) P[1]=ZI.4. The COMP statement may contain INCLUDE and EXCLUDE to cause selective processing. They will be processed in the order in which they appear in the input stream. when P[]= or A[]= is specified in the ILOOP phase. P[n][I] |N| Expressions may contain the functions ATOT(#) and PTOT(#).P1 COMP A[2]=0. A[]=. COMP P[]=. and MW[]= expressions automatically imply a loop based upon J from 1 to zones in the Matrix program. Causes the program to solve the expression for each value of J. MW[] is not valid in the Generation program. If the second [] is not specified. 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. PAO DBF |?| Cube Voyager Reference Guide 569 . etc. the user may optionally name the variables to be written to the DBF records with the NAMES subkeyword. If the PAO keyword specifies an MDB file for the output.Generation Program Control statements 11 require. The PRINT processor is called one time for each zone in a loop where Z=1-Zones. FILEO keywords Keyword PAO PAO CFORM Subkeyword |KF10| |S| Description Name of a file where the formatted records are to be written. normally. the most likely place where this data would be read would be in any program that accepts ZDATI files. Within Cube Voyager. The major difference between PAO and PRINT statement is that PAO specifies the output file by definition. the PAO processing uses the Cube Voyager General PRINT control statement processor. Although other data can be placed on these records. and the various trip ends such as P[1]. the records should contain only the zone number (I). If DBF=F and PAO specifies an MDB file the program will fail. Indicates if the output records are to written as a DBF file. A maximum of 100 variables may be designated for single DBF. usually it should be written in a format such that the Distribution process can read it as the distribution trip ends. This is off. Format for following string list items. Full documentation about the sub-keywords can be found in “PRINT” on page 62. a[1]. text variables will not be written to a PAO file. Normally. and the FILE keyword is not allowed. For consistency. If DBF=T is specified. 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. then DBF subkeyword should either not be specified or set to T. unless turned on. ignoring other characters. the only variables in the list will be Z. OTHERATTR. For example: LIST=z. If any expressions are used.NAMES=TAZ.a1. For example (VAR1+VAR2+VAR3) will be named VAR1VAR2VA. In most cases. FORM=20. OTHERPROD. the program will use the first 10 alphanumeric digits. P and A must be indexed. are ignored. List of items to be formatted into the output buffer.2SLR is recommended if the Distribution program is going to read the file. NHBATTR would set the names for a1.p1.a2. WORKPROD. DBF=T.a3. If there is no name specified for a variable. the zone index is automatically supplied as Z.NHBPROD PAO LIST |S| PAO NAMES |S| would set the names in the DBF for z. and should not contain any spaces or commas. A name may not exceed 10 characters.a2. the program will use the variable name directly. if designated as longer than 10. it will be truncated. If the LIST field is an expression. and expressions of P[n] and A[n] values. 570 Cube Voyager Reference Guide .p2. NAMES[11] in this example). respectively.p3.11 Generation Program Control statements FILEO keywords (continued) Keyword PAO Subkeyword FORM |S| Description Format for following numerical list items.p3. The routine does not check for duplicate names. they should be enclosed within parenthesis. The names are positional (their indices refer to the positional location of the variables in the LIST). Names to be assigned to the DBF variables.p2.p1.a3. Likewise: NAMES[5]=WORKATTR. Extraneous NAMES (that is. and the program has no other way to identify the appropriate number of zones. This is off. unless turned on. PHASE ENDPHASE Cube Voyager Reference Guide 571 . Z P[1] A[1] P[2] A[2] (P[3]+P[4]) (A[3]+A[4]) PARAMETERS Set general parameters.. which the program defaults to.Generation Program Control statements 11 FILEO keywords (continued) Keyword PAO Subkeyword PRINT |?| Description Indicates if the output records are to also be listed to the standard output. The maximum value is 20. Sets the number of P and A arrays to be allocated. if the keyword is not specified. Example PAO = OUTPUT. FORM=SL. If ZONES is not specified. FORM=8.. and establishes an index boundary for P and A in COMP statements.DAT.0.DAT. it will be set to 100. ENDPROCESS Establishes phase blocks. MAXPURPS |I| Example ZONES=3000 MAXPURPS=5 PROCESS . Setting this to a more realistic value will cause a less drain on computer memory. 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. ZONES MAXPURPS PARAMETERS keywords Keyword ZONES |I| Description Establishes the number of zones to process. PHASE=ADJUST . To simplify coding. . until an ENDPROCESS statement or another PROCESS statement is encountered. Exception: Static statements. PHASE=ADJUST . the ENDPROCESS statement is not necessary. In the Generation program. only the PHASE=ADJUST statement is all that is needed to differentiate between the normal ILOOP statements and the ADJUST statements that are used to balance the final Ps and As. PHASE=ILOOP P[1]=…. are not processed as stack statements. such as PARAMETERS.11 Generation Program Control statements A user process phase stack is defined by a PROCESS statement that designates its beginning and an ENDPROCESS statement that designates its ending. to further simplify coding. the following statements are used to balance Ps and As RUN PGM=GENERATION . If ENDPROCESS is used. . PHASE=name may be used directly. FILEI. the following statements are used to balance Ps and As 572 Cube Voyager Reference Guide . LOOKUP. FILEO. the PROCESS control word is not necessary. even if they are located within a phase block. Example RUN PGM=GENERATION . P[1]=…. PROCESS keywords Keyword PHASE |KS| Description Names the phase stack. And. normally. The control statements that follow it. will be executed when the phase is internally executed. it may be coded as either ENDPROCESS or ENDPHASE. the occurrence of another PROCESS statement acts as the ENDPROCESS statement. The following PHASE names may be specified: • • ENDPHASE |K| ILOOP ADJUST Defines the end of the user control statements for a stack. . This report follows any ADJUST processing. Requests that the final productions be reported. Requests that the final attractions be reported. This report precedes ADJUST processing.Generation Program Control statements 11 REPORT Requests reports and establishes tracing. Controls the listing of the stack statements as they are processed. This report follows any ADJUST processing. A P AC PC TRACE REPORT keywords Keyword AC A PC P TRACE |?| |?| |?| |?| |K?| Description Requests that the computed attractions be reported. Requests that the computed productions be reported. Example REPORT AC=y A=y P=y Cube Voyager Reference Guide 573 . This report precedes ADJUST processing. 18 * 8.1.z=#2.2 * zi.2 * zi.z=#2.59 * 10.21 * 4.61 * 13.62 * 17.hh7 + .1.hh1 + .15 * 16.hh3 + .23 * 11.hh3 + zi.hh4 + .4 * zi.hh1 + zi.1.1.hh9=11.select=3-1.1.4 * zi.1.9 * zi.22 * 8.hh7 + .1.16 * 15.4 * zi.1.1.hh2 + .1.1.57 * 6.23 * 15.1.1.1.hh6 + .2 * zi.1.hh11=#13.59 * 11.hh3 + .hh12 + .8 * zi.1.1.1. p3a=21-25.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.62 * 18.hh11 + .1.1 * zi.1.1.4 * zi.1.hh7=#9.2.1.hh9 + zi.62 * 19.0 * zi.hh1 + .5 * zi.2 * zi.emp2 phbw = .hh13=#15 zdati[2]=c:\demo\demo08.18 * 10.1.1.hh2 + zi.dat.hh1 + .8 * zi. select=2-1.1.1.1.0 * zi.hh13 phbo = .1.1.7 * zi.8 * zi.23 * 10.1.hh2 + .hh7 + zi.7 * zi.24 * 17.1.1 * zi.4 * zi.1.57 * 8.5 * zi.1.16 * 13.4 * zi.emp2=4 zdati[3]=c:\demo\demo08.13 * 19.2 * zi.hh4 + .23 * 16.emp1 + zi.21 * 6.select=1-1.2 * zi.hh10=12.1.hh11 + . xicnt=6-10.hh11 + zi.hh10 + .z=2-4.23 * 13.13 * 18.select=4-1.hh6 + zi.hh5=#7.hh9 + .1.16 * 14.1.2.ixcnt=11-15 report zdat=y tothh = zi.hh5 + .hh7 + . hh8=10.4 * zi.1.7 * zi. emp1=3.hh10 + .hh6 + .hh5 + .1.1.1.57 * 4.4 * zi.hh12 + zi.hh13 pnhb = .hh5 + .4 * zi.22 * 6.23 * 14.62 * 16.dat.hh4 + .hh8 + .0 * zi.hh12=#14.hh12 + .hh4 + zi.hh2 + .13 * 19.dat.1.hh6=#8.hh4=#6.14 * 17.61 * 14.hh5 + zi.hh2=#4.hh9 + .hh6 + .p4a=31-35 zdati[4]=c:\demo\demo08.hh8 + .hh8 + .68 * 15.5 * zi.22 * 4.hh10 + 574 Cube Voyager Reference Guide .hh9 + .1.dat.1.1.hh3 + .1.hh10 + zi.hh13 totemp = zi.1.hh3=#5.0 * zi.hh8 + zi.9 * zi.2 * zi.1 * zi.1.18 * 11.2 * zi. hh1=#3.1.z=2-4.9 * zi.62 * 19. V2.1. These fields could also be fields on your zone data file .dat..p[1].90*ahbo a[3]=0.DBF".hh12 + . LIST=Z.7 * totemp) ahbo = 1. dbf data structure is Z.p[2].2.a[3].5 .90 * (10.1. p[2]=phbo.6 . Xprod1. V254 FILEI ZDATI[2]=zonedata.92*ahbw a[2]=0.Xattr1.Xattr3 for example .a[5] ENDRUN Generation example 2 RUN PGM=GENERATION FILEI ZDATI[1]=zonedata.03 * (phbw+phbo+pnhb) pxi = zi.p[5].hh11 + .0 list=z(2).5 * zi..Xprod3.0 * zi.0 * zi.Xprod2.. p[5]=pxi a[1]=0.4. V1.0.08*ahbw + 0.25 * 19. P[1] P[2] P[3] A[1] A[2] A[3] .97*anhb a[4]=aix.10*ahbo + 0. External PA file.a[1].emp2 + tothh) anhb = 1. FILEO PAO[1] = "TRIPENDS.49 * ( 2.0 * zi.2. ZDATI[1] as well. FORM=6.a[2].dbf .81 * ( 1.25 * 19. production trip rate per industry/agricultural worker per day hbp_s = 0.1.dbf . DBF=T.xicnt ahbw = 1.emp1 + 2.Xattr2.2..p[4].2 * zi.5 * zi. . purpose = home based hbp_p = 0. define trip rates by purposes .a[4]. production trip rate per person (population) per day hbp_ia = 0.hh13 pix = 0. lets say system has 1000 zones with 901-1000 being the externals .5*tothh) axi = 0.ixcnt p[1]=phbw. p[3]=pnhb. dbf data structure is Z.emp2 + 0.25 * 18.Generation Program Examples 11 . 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.03 * 1.2 . production trip rate per service worker per day Cube Voyager Reference Guide 575 .2. p[4]=pix.p[3].0 * zi.form=8. and we have 3 trip purposes PARAMETERS ZONES=1000 PROCESS PHASE=ILOOP .4..03*anhb aix = zi.emp1 + 0. 005 .ret_2002 + hbp_sc*zi.3 . production trip rate per retail worker per day (incl shoppers) hbp_sc = 0. attraction trip rate per pupil/student per day .25 .sch_2002) P[2] = (nhbp_p*zi. attraction trip rate per retail worker per day scha_sc = 0.pop_2002 + hbp_ia*zi. attraction trip rate per person (population) per day hba_ia = 0. define P/A functions for internal zones .6 .95 .calculate productions per day by purpose .serv_2002+ per per per per per 576 Cube Voyager Reference Guide .3 .15 .1.1.005 .pop_2002+ nhbp_ia*zi.005 .11 Generation Program Examples hbp_r = 40. attraction trip rate per pupil/student per day IF (I<=900) .1. production trip rate per industry/agricultural worker day schp_s = 0.005 . attraction trip rate per industry/agricultural worker day hba_s = 0.95 .1.1 . production trip rate per person (population) per day nhbp_ia = 0.vnames are just the filed names in the dbf file P[1] = (hbp_p*zi. production trip rate per service worker per day nhbp_r = 12 . production trip rate per retail worker per day schp_sc = 0.5 . production trip rate per pupil/student per day scha_p = 0. attraction trip rate per industry/agricultural worker day scha_s = 0. attraction trip rate per person (population) per day nhba_ia = 0.serv_2002 + hbp_r*zi.1. attraction trip rate per service worker per day scha_r = 0. purpose = school schp_p = 0. production trip rate per industry/agricultural worker day nhbp_s = 0. zi. production trip rate per retail worker per day (incl shoppers) nhbp_sc = 0.0 .inag_2002 + hbp_s*zi. attraction trip rate per retail worker per day (incl shoppers) nhba_sc = 0.3 .1. attraction trip rate per retail worker per day (incl shoppers) hba_sc = 0.1. production trip rate per service worker per day schp_r = 0. attraction trip rate per service worker per day nhba_r = 14.1 . purpose = non-home based nhbp_p = 1.15 .1 .0 . attraction trip rate per person (population) per day scha_ia = 0 . production trip rate per pupil/student per day hba_p = 1.1.inag_2002+ nhbp_s*zi.0 . production trip rate per pupil/student per day nhba_p = 1.1 . attraction trip rate per service worker per day hba_r = 45. production trip rate per person (population) per day schp_ia = 0 . attraction trip rate per pupil/student per day . attraction trip rate per industry/agricultural worker day nhba_s = 0.3 .8 .6 .1. ----. sch_2002) .2.2.2.1.ret_2002+ schp_sc*zi.pop_2002+ scha_ia*zi. zi.3 NHB=2 .pop_2002+ schp_ia*zi.1. balance attrs to prods for purposes 1.pop_2002+ nhba_ia*zi.serv_2002+ nhba_r*zi.1. 3 .Xprod1 P[2]=zi.Xattr2 A[3]=zi.ret_2002+ nhbp_sc*zi.vnames are just the filed names in the dbf file A[1] = (hba_p*zi.inag_2002 + hba_s*zi.inag_2002+ scha_s*zi.serv_2002+ schp_r*zi.Generation Program Examples 11 nhbp_r*zi.1.inag_2002+ nhba_s*zi.ret_2002 + hba_sc*zi.1.1.1.1.sch_2002) P[3] = (schp_p*zi.serv_2002+ scha_r*zi.inag_2002+ schp_s*zi.Xprod2 P[3]=zi.Xattr3 ENDIF PROCESS PHASE=ADJUST . define P/A for external zones P[1]=zi.1.1.1.sch_2002) A[3] = (scha_p*zi.1.ret_2002+ nhba_sc*zi.1.1.pop_2002 + hba_ia*zi.2.1.1.1.calculate attractions per day by purpose .Xprod3 A[1]=zi.1.sch_2002) ELSE .2.1.1. prods set to attrs for purpose 2 ENDPHASE ENDRUN Cube Voyager Reference Guide 577 . ----.Xattr1 A[2]=zi.serv_2002 + hba_r*zi. adjust zonal attractions so total attractions match total productions BALANCE A2P=1.ret_2002+ scha_sc*zi.sch_2002) A[2] = (nhba_p*zi.2.1.1.1. 11 Generation Program Examples 578 Cube Voyager Reference Guide . Cube Voyager Reference Guide 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 Cube Voyager Reference Guide 579 . listing the program’s primary capabilities.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. composite and average travel costs. and components of costs 580 Cube Voyager Reference Guide . or alternatively single best-path routes may be used Demand stratification by user class with variations in the behavior of classes represented by different cost functions Comprehensive fares modeling Preparation of a public transport network for Public Transport’s modeling functionality Generation of the nontransit element of the public transport network (that is. access. 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. egress. network-wide and mode specific. This section also discusses terminology used within this document. This section provides an overview of the Public Transport program. and discussing how you can use the program to prepare data and model public transport systems. transfer and park and ride legs) Skimming. required inputs and generated outputs. lines. secondary analyses • The Public Transport program requires as input: • • • • • • • A highway or public transport network Public transport system data Line data Fare data Nontransit legs (developed externally or by Public Transport) Generalized cost information Demand The Public Transport program produces: • • • • • • • Nontransit legs Enumerated routes Skim and select-link matrices Loaded lines and nontransit legs Transfer matrices—results of loading analyses A variety of reports of input data and model results A public transport network that can be displayed by Cube and used as an input network for further modeling Cube Voyager Reference Guide 581 .Public Transport Program Overview 12 • • Two methods (service-frequency and service-frequency-andcost) for loading demand on to transit choices at stops Analyses of loaded trips—transfers between modes. multiple routes with probability of use. operators. model infrastructure. line and link loads. select-link/line outputs Reporting of input data. a variety of stop-to-stop movements. 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. considering: 582 Cube Voyager Reference Guide . distance. over which the public transport system operates. operators and wait curves. and so forth). Nontransit legs. Control information for route enumeration and evaluation. node coordinates. nodes and links (that is. Nontransit legs may be determined externally and/or generated by Public Transport under user control. defining the characteristics of the lines and nodes traversed. • • • • Modeling You can use the Public Transport program to model public transport. produced by Network or Public Transport. System information used to describe the characteristics of the public transport system such as modes.12 Public Transport Program Overview Preparing data You can use the Public Transport program to prepare data that supports public transport modeling. You can prepare: • A network. the Public Transport model finds “reasonable” or “attractive” multiple discrete routes between zones. Service or line data. presenting opportunities to access the public transport system. containing characteristics of zones. walk and transit link times. egress from it and transfer between services during the course of a trip. Where walk and transit choices are available.Public Transport Program Overview 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. Cube Voyager Reference Guide 583 . fares) Best trip cost • The model can extract network-wide trip costs. perceived. hours and revenue. The model can extract the following skims: • • • Composite costs Value of choice Average. where appropriate. the Public Transport model loads demand. by modes. derived from the combined frequency of services at stop nodes Fares (considered only for evaluation) Skimming (levels of service matrices) During skimming. boarding and transfer penalties. egress. nontransit. or the model can stratify them. the Public Transport model skims (extracts) the costs—and the components of costs—of journeys between zones. and transfer points. These costs are suitable for model validation. in-vehicle and wait times. it also determines the transit share. Loading (assignment) During loading. demand modeling. 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. and actual trip costs and components (that is. in the form of trips between zone pairs. scheme evaluation. loading demand on the network and producing operational statistics like passenger miles. namely “transit link” as opposed to “nontransit link. multirouting and best-path. The best-path method does not use walk or alighting choice models. The alternative-alighting model apportions the share of a service to the attractive alternative alighting points of that service. and loads demand using the service-frequency model. these models determine the probability of use of the alternative routes.) Two forms of loading are supported. trips are then loaded on the routes based upon these probabilities.12 Public Transport Program Overview • 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. “transit” is used in this document to describe a type of link over which a public transport service can run.” In particular.” ”lines” and “services” ”transfers” and “interchanges” ”skims” and “levels of service” • • • 584 Cube Voyager Reference Guide . the Public Transport model produces reports you can use to analyze different aspects of passenger loadings: • • • • Passenger transfers between all modes Passenger transfers between public transport modes Passenger transfers between operators A variety of stop-to-stop movements Terminology This document uses the following sets of terms interchangeably: • ”transit” and “public transport. Reporting During reporting. • (Strictly. ” and “IJ pairs” ”nontransit time” and “walk time” ”loading” and “assignment” ”volume.” and “passenger flow” Cube Voyager Reference Guide 585 .Public Transport Program Overview 12 • • • • • ”generalized cost” and “generalized time” ”origin-destination pairs.” “zone pairs.” “OD pairs.” “flow.” “load. 586 Cube Voyager Reference Guide .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. ) See “Phases” on page 620 for a description of the phases in the Public Transport program.Public Transport Program Processes 12 You control the main processes and their associated phases. Cube Voyager Reference Guide 587 . during the execution of the phases. the program evaluates them once. Control statements are either static or dynamic. Dynamic statements may be present only within phases. within a prescribed hierarchy. Public Transport program processes and associated phases (With multiple user classes. Static statements may be present anywhere in the job stream. the program evaluates them as encountered. processes in the blue boxes are performed separately for each class. You configure the Public Transport program to run through a specific combination of control statements and phases. The DATAPREP phase is mandatory for public transport network development. lines. line. the description of each phase lists valid control statements (see “Phases” on page 620). 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. you must provide public transport system. This includes stringent validation and consistency checks to ensure that the different components of the public transport network are compatible. and control information.12 Public Transport Program Processes Only context-sensitive dynamic control statements are available to the phases. However. and control data. do not code empty phases. The phase provides the control statements for nontransit leg generation and/or input. 588 Cube Voyager Reference Guide . only zone. public transport system data. Either the Network program or the Public Transport program can produce the input network. and link information are taken from networks produce by the Network program. nontransit leg. Only code phases that contain control statements. node. Network development During network development. A text version of the lines in the public transport system. route evaluation. which may be saved with LINKO. in DBF format. It contains all Cube Voyager Reference Guide 589 . which may be saved with LINEO. which may be provided separately for each class. The Public Transport network is made available to any other processes in the job stream that require it. A table of links and their attributes.Public Transport Program Processes 12 The components of the public transport network are common to all user classes. except for route-enumeration and route-evaluation control information. input with LINEI[#] Control information for route enumeration and route evaluation. The legs are in the format specified by the NT control statement. input with SYSTEMI One or more lines files. produced by Network or Public Transport. See “Public transport network development” on page 849 for examples of this task. nontransit legs input with NTLEGI[#] • • Outputs produced by Public Transport network development • • • • A public transport network. which may be saved with NTLEGO. 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. If trips are loaded in the run creating the public transport network. skimming. input with NETI Public transport system data. which may be saved with NETO. The lines are in the format specified by the LINE control statement. optionally. all output files can optionally contain the results of the loading. Nontransit legs (generated and input). Inputs required for Public Transport network development • • • • A network. The saved Public Transport network may be used in subsequent runs of the Public Transport program for route enumeration. loading and loading analyses. You can save an enumerated routes file and input the file to a subsequent run with ROUTEI. the Public Transport program identifies sets of discrete routes between zone pairs. Associated phases • DATAPREP (mandatory) Route enumeration During route enumeration. provide separate FACTORS statements for each class to produce enumerated route files for each class. When modeling multiple user classes. Public Transport enumerates routes for all zone pairs. A ROUTEO file in the job stream invokes route enumeration. However. in compliance with further user specified controls. You can use Cube to display but not edit the Public Transport network. Route enumeration is a heuristic process. which have some probability of being used by passengers to travel between the zones. you can use ROUTEI and ROUTEO statements to select zone pairs separately for route enumeration and reporting. which you control with the FACTORS statement.12 Public Transport Program Processes information required for these processes apart from fares data which may optionally be read later. This set of discrete routes may be pruned at the route-evaluation stage. so allowing it to vary between program runs. 590 Cube Voyager Reference Guide . By default. at the minimum. can be examined through a series of reports specified on the REREPORT statement. which is described in “Network simplification” on page 782. The line data is converted into transit legs and the network data into nontransit legs. at every decision point along the route Cube Voyager Reference Guide 591 . produced either by the current run of the Public Transport program. Outputs produced by Public Transport route enumeration • An enumerated routes file.Public Transport Program Processes 12 See “Route-enumeration process” on page 793 for theory about route enumeration. or produced previously and input with NETI. the data is organized in a highly compressed form for processing and storing routes. a user specified probability of use or more. the Public Transport program: • • • • Examines enumerated routes Eliminates any illogical ones that have crept in due to network simplification Disaggregates bundled routes. Inputs required for Public Transport route enumeration • A public transport network file. ROUTEO[#]. ROUTEO. For multiple user classes. To improve performance of the main algorithms and minimize memory and temporary disk storage. where appropriate Identifies routes that have. Associated phases • None Route evaluation During route evaluation. The simplified network. NOTE: Vast quantities of data can be required to define a public transport system. enumerated routes files. loading. and loading-analyses processes. Indeed.) Evaluated routes may be reported with ROUTEI and ROUTEO. 592 Cube Voyager Reference Guide . they are evaluated as required. Can be reported by zone pair. enumerated routes files input with ROUTEI[#]). or produced previously and input with NETI. 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. Inputs required for Public Transport route evaluation • • A public transport network file. (For multiple user classes. produced either by the current run of the Public Transport program. The skimming. Produced for each zone pair. but not saved. Selecting one or more of these processes automatically invokes the routeevaluation process. select-link. and loading-analyses processes are performed on the fly. these are by-products of the route-evaluation process. as they report on different aspects of the Public Transport model. but described separately. (Enumerated routes produced by an earlier run may be input with ROUTEI for evaluation or generated by specifying a filename with ROUTEO. This is because only enumerated routes are saved. produced either by the current run of the Public Transport program. loading. select-link.12 Public Transport Program Processes The route-evaluation process is a prerequisite for the skimming. or produced previously and 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. See “Route-evaluation process” on page 799 for the theory supporting route evaluation. A route file. Public Transport Program Processes 12 Associated phases • • MATI SELECTIJ Skimming (level of service) This section describes skimming in detail. Skimming is also described in “Skimming process” on page 812. either in the MATO phase or outside the Public Transport program. Topics in this section include: • • • • • • Overview Wait-time skim functions Travel-time skim functions Penalty skim functions Fare skim functions Other skim functions Cube Voyager Reference Guide 593 . see “Skimming — Quick reference” on page 604 for a quick reference to the skimming functions. When modeling multiple user classes. set to zero. you can produce skims for each class from the individual enumerated route files. See “Public transport skimming” on page 854 for examples of this process. These can be reset to large values. NOTE: All skim matrices have their intrazonal cells on the diagonal. for modeling demand. The skimming process produces skim (level of service) matrices of total trip costs and their components. from the information generated by route evaluation. and the cells for unconnected IJ pairs. enumerated routes files input with ROUTEI[#]).12 Public Transport Program Processes Overview Inputs required for Public Transport skimming • • A public transport network file. in DBF format. either produced by the current run of the Public Transport program. produced either by the current run of the Public Transport program. which may be saved in the file designated by LINKO. or produced previously and input with ROUTEI (for multiple user classes. MATO[#]). A table of links and their attributes. the files must be compatible. MATO (for multiple user classes. matrix files. and is specified as follows: • • • SkimName(Arg1) SkimName(Arg1. NOTE: If previously built files are input with NETI and ROUTEI. Arg2) SkimName where: 594 Cube Voyager Reference Guide . A route file. 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. Outputs produced by Public Transport skimming • • A matrix file. or produced previously and input with NETI. Each skim function has a name and one. two or no arguments. 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. So.-5. MW[8] will contain a TIMEA skim for Cube Voyager Reference Guide 595 . Combinations such as 1.9. If Arg1=0.4. the attribute skimmed is the total for the zone pair. the extracted skim is for the specified route set. or a default. setting Arg1 to zero or one will produce the same result.3.2. Example 1: Shows how skims requiring one argument are invoked. Therefore. the standard way of specifying ranges. Arg2= 3 would provide a skim for mode 3 while Arg2=1. if Arg1>0. the skim for the route set which is also the overall skim for the OD pair (route set). The arguments in skim functions are evaluated as expressions.-5. MW[7] will contain a DIST skim for mode 1.-12 are valid. Arg2=1-5 would result in Arg2=-4. MW[2]=COMPCOST(0) MW[3]=ValOfChoice(0) MW[4]=IWAITA(0) Currently only one route set is produced. For example. This could also be written as 1. that denotes its type: COMP for composite skims CWD for crowded skims BEST for best skims All other skims are average skims • Arg1 is the route set number and can range from 0 to the number of route sets.5 would produce one skim for modes 1 through 5. Note that range specification for skim functions is different from the standard specification for Cube Voyager.3.7. Example 2: Shows how skim functions requiring two arguments are invoked. • Arg2 is a list of modes for which the skim is required.Public Transport Program Processes 12 • SkimName includes an explicit prefix. The second argument is a single number or a list of single numbers and pairs specifying ranges. an alternative way to specify Arg2 is ALLMODES. Arg2 is text rather than a list.ALLMODES) MW[12] = TIMEP(0.31. Example 4: Shows how a skim function requiring no arguments is invoked.7.7. TMODES or NTMODES (case insensitive). MW[11] = TIMEP(0.7.and 33.31.-33) MW[9] = TIMEA(0.33 which are nontransit modes.NTMODES) • Where a skim requires no arguments.TMODES) MW[13] = TIMEP(0.-9. MW[9] for modes 1. MW[14] = BESTJRNY Subsequent sections describe the types of skims that can be extracted and their contents.1.11 which happen to be the transit modes in the system and MW[10] for modes 31.32.9. transit or nontransit modes. MW[7] = DIST(0.8.32. MW[9] for transit modes and MW[10] for nontransit modes. the parenthesis () should not be coded.-33) If skims are required for all. Example 3: Shows an alternative method for invoking skim functions requiring two arguments.9. 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 596 Cube Voyager Reference Guide .7. Here.8.1) MW[8] = TIMEA(0.-9.11.31.11.11) MW[10] = TIMEA(0.12 Public Transport Program Processes modes 1. MW[8] will contain a TIMEA skim for all modes.1. 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 transfer wait time XWAITA(RouteSet) Computes the average actual wait time incurred at the transfer points of all “attractive” routes between zones. from a default wait curve. or. from a default wait curve. Cube Voyager Reference Guide 597 . 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. weighted by the WAITFACTOR keyword. assigned to nodes by the XWAITCURVE keyword. Perceived crowding wait time CWDWAITP(RouteSet) Computes the average additional wait time due to crowding effects incurred at the transfer points of all “attractive” routes between zones. for nodes that have not been assigned one. for nodes that have not been assigned one. assigned to nodes by IWAITCURVE keyword.Public Transport Program Processes 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. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement. or. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement. Perceived initial wait time IWAITP(RouteSet) Computes the average actual 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. for nodes that have not been assigned one. weighted by WAITFACTOR. Mode) For transit modes. or. from a default wait curve. from a default wait curve. this skim computes the average in-vehicle run time for all “attractive” routes between zones. factored by any line specific factors. or. assigned to nodes by IWAITCURVE. for nodes that have not been assigned one. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement. Perceived transfer wait time XWAITP(RouteSet) Computes the average actual time incurred at the transfer points of all “attractive” routes between zones.12 Public Transport Program Processes 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). assigned to nodes by XWAITCURVE. It is taken from the network link data. 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. 598 Cube Voyager Reference Guide . weighted by WAITFACTOR. TIMEP. For nontransit modes. egress and transfer) for all “attractive” routes between zones. 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. Penalty skim functions This section describes penalty skim functions: • • • Actual transfer penalty Perceived boarding penalty Perceived transfer penalty Cube Voyager Reference Guide 599 . It is taken from the nontransit legs generated or read in by the GENERATE statements. Mode) For transit modes. This is the run time that is above the basic calculated in-vehicle time and arises due to crowding effects and crowd factors greater than 1. this skim computes the average nontransit time (access. and RUNFACTOR.0. this skim extracts the average additional invehicle run time for all “attractive” routes between zones. RUNFACTOR and crowding factor. so care should be taken to avoid double-counting.Public Transport Program Processes 12 For nontransit modes. egress and transfer) for all “attractive” routes between zones. Perceived travel time TIMEP(RouteSet. It is taken from the network link data and factored by any line specific factors. As a perceived data skim. this skim extracts the average nontransit time (access. Mode) For transit modes. This component of cost is included in the perceived travel time skim. It is taken from the nontransit legs generated or read in by the GENERATE statements and factored by RUNFACTOR. Perceived crowded link travel time CWDCOSTP(RouteSet. weighted by XFERFACTOR with XFERCONST added. Mode) Counts the boarding penalties associated with transit legs of the trip. Mode) Extracts the average fare.” Fares are calculated either by transit leg or for a sequence of legs. It is calculated from the fare systems used by the “attractive routes. Fare skim functions This section describes fare skim functions: • • Monetary units Generalized cost units Monetary units FAREA(RouteSet.12 Public Transport Program Processes Actual transfer penalty XFERPENA(RouteSet. It is the actual penalty as coded in XFERPEN. for all “attractive” routes between zones. Mode) 600 Cube Voyager Reference Guide . It is taken from XFERPEN. in monetary units. Perceived transfer penalty XFERPENP(RouteSet. Mode) Extracts the average actual transfer penalty for all “attractive” routes between zones. Perceived boarding penalty BRDPEN(RouteSet. Generalized cost units FAREP(RouteSet. Mode) This skim is the average perceived transfer penalty for all “attractive” routes between zones. in the latter case the fare is apportioned to the legs in proportion to leg distance. in generalized cost units. Fares are calculated either by transit leg or for a sequence of legs. from the fare systems used by the “attractive routes. the best choice is taken). for all “attractive” routes between zones. at each decision point. 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.Public Transport Program Processes 12 Extracts is the average fare.” and converted into generalized cost units with mode specific VALUEOFTIME. The trip time comprises: • • • • Walk time — taken from input or generated nontransit legs Average wait time — actual In-vehicle time — actual Boarding penalties Cube Voyager Reference Guide 601 . The fare is calculated as for skim FAREA. in the latter case the fare is apportioned to the legs in proportion to leg distance. Boardings BRDINGS(RouteSet. Mode) Extracts the average number of boardings used by the “attractive” routes between zone pairs. It is taken directly from the network link data. Mode) Extracts the average distance travelled by the “attractive” routes between zone pairs. 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. 602 Cube Voyager Reference Guide .12 Public Transport Program Processes • 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. walk or alighting). 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. and no viable alternative route is available. and no viable alternative route is available. Cube Voyager Reference Guide 603 . 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. These trips would need to wait till beyond the modeled period before being able to board their next transit leg. It is only available when crowd modeling is performed. The EXCESSDEMAND skim only gives cell values where demand exists and bottlenecks prevent it reaching the destination. and wait time adjustments are used. Value of choice ValOfChoice(RouteSet) Indicates level of choice available in the public transport system by computing average travel cost skim minus the composite travel cost skim. It highlights where the public transport system is unable to satisfy the demand flows which are being loaded. This skim is only available when crowd modeling is performed. 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). and wait time adjustments are used.Public Transport Program Processes 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. 12 Public Transport Program Processes 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) 604 Cube Voyager Reference Guide Public Transport Program Processes 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. Cube Voyager Reference Guide 605 12 Public Transport Program Processes 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 606 Cube Voyager Reference Guide Public Transport Program Processes 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 Cube Voyager Reference Guide 607 12 Public Transport Program Processes 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: 608 Cube Voyager Reference Guide Public Transport Program Processes 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 Cube Voyager Reference Guide 609 12 Public Transport Program Processes 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. 610 Cube Voyager Reference Guide Public Transport Program Processes 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). Cube Voyager Reference Guide 611 12 Public Transport Program Processes 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: 612 Cube Voyager Reference Guide Public Transport Program Processes 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. Cube Voyager Reference Guide 613 12 Public Transport Program Processes 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. 614 Cube Voyager Reference Guide Public Transport Program Processes 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: Cube Voyager Reference Guide 615 12 Public Transport Program Processes • 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. 616 Cube Voyager Reference Guide Public Transport Program Processes 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 Cube Voyager Reference Guide 617 12 Public Transport Program Processes 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 618 Cube Voyager Reference Guide Public Transport Program Processes 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. Cube Voyager Reference Guide 619 12 Public Transport Program Phases Phases The Public Transport program executes its main processes—data processing and modeling—within a series of phases. You control all the phases and can initiate additional, context-sensitive computations within them. The phases, presented in the order they would normally be implemented, are: • • • • • • • NODEREAD — Computes node based variables. LINKREAD — Computes link based variables. DATAPREP — Prepares the public transport network for modeling. MATI — Computes trips for loading. SELECTIJ SKIMIJ — Extracts skims and select link results, saving them, generally in working matrices. MATO — Manipulates and reports skim, select-link, and loading-analyses matrices. The NODEREAD, LINKREAD, MATI, and MATO phases provide data manipulation facilities, and are secondary to the main functions of the Public Transport program. They are optional. You specify the exact configuration for the Public Transport program to run through a combination of phases and control statements. Control statements provide information and instructions to the program. In the Public Transport program, control statements are either static or dynamic. Static statements may be present anywhere in the job stream; the program evaluates them once. Dynamic statements may be present only within phases; the program evaluates them as encountered, during the execution of the phases. 620 Cube Voyager Reference Guide Public Transport Program 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. Cube Voyager Reference Guide 621 12 Public Transport Program Phases A diagram showing how the phases would be used in a typical public transport model follows: Processing phases in a public transport model 622 Cube Voyager Reference Guide Public Transport Program Phases 12 NODEREAD In the NODEREAD phase, you can compute node-based information from the input network’s node attributes with NETI. This information is for use primarily in the DATAPREP phase but is available in later phases if the DATAPREP phase is active. The control statements within the NODEREAD phase are executed once per node. Only one NODEREAD phase is permitted per run. The computed variables may be scalars or vectored by node. The use of a vectored variable produces an array containing a computed value for each node. Vectored variables have the case insensitive prefix “nw.” The evaluated expression may contain any valid variables, numeric or string, and node based variables from the input network. Input node variable names must have the case insensitive prefix “ni.” An example of a computed node variable is: NW.XplusY = NI.X + NI.Y Computed variables are available for the duration of the run but not saved back to the network. See “Example 2: Preparing a public transport network from TRIPS link data” on page 851 for an example of this phase. Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO Cube Voyager Reference Guide 623 ” An example of a computed link variable is: LW. This information is for use primarily in the DATAPREP phase but is available in later phases if the DATAPREP phase is active.Time * 1. ENDIF LOOP . Input link variable names must have the case insensitive prefix “li..” The evaluated expression may contain any valid variables. ELSEIF .. Control statements available in this phase ABORT 624 Cube Voyager Reference Guide .. Vectored variables have the case insensitive prefix “lw. The control statements within the LINKREAD phase are executed once per link. See “Example 2: Preparing a public transport network from TRIPS link data” on page 851 for an example of this phase. you can compute link-based information from the input network’s link attributes with NETI. Only one LINKREAD phase is permitted per run..12 Public Transport Program Phases IF... ELSE . The computed variables may be scalars or vectored by link. and node based variables from the input network. ENDLOOP PRINT Public Transport variables available in this phase ZONES LINKREAD In the LINKREAD phase.GCTime = LI.. numeric or string.5 Computed variables are available for the duration of the run but not saved back to the network. The use of a vectored variable produces an array containing a computed value for each link.. .. 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. You can develop nontransit legs with one or more GENERATE control statements.. See “Public transport network development” on page 849 for examples of this phase.... ENDLOOP PRINT Public Transport variables available in this phase ZONES LINKNO DATAPREP The DATAPREP phase invokes the Public Transport network development process and provides the mechanism for generating and/or reading nontransit legs.. ELSEIF . Control statements available in this phase ABORT BREAK Cube Voyager Reference Guide 625 . ELSE . ENDIF LOOP ..Public Transport Program Phases 12 BREAK COMP CONTINUE EXIT GOTO IF. . ELSE . (MW[#]). if MATI points to a highway network matrix.. and loading analyses processes are done for each zone pair.#. from FILEI MATI matrices (MI. This phase provides a flexible mechanism for generating and manipulating one row of a matrix at a time. ELSEIF . I-J. and the matrix indicates that there is no highway access for zone I... ENDLINKLOOP LOOP . skimming. I. The MATI phase is executed for each origin zone..name). You might use this phase to: • Examine the matrix input with FILEI MATI.. ENDLOOP PRINT Public Transport variables available in this phase ZONES MATI The MATI phase produces working matrices. For example. and determine if there is anything specific about zone I that could affect further processing for that zone. one row at a time..12 Public Transport Program Phases COMP CONTINUE EXIT GENERATE GOTO IF. before the route evaluation. although COMP statements can also compute working matrices.. 626 Cube Voyager Reference Guide .. you might set a variable for zone I and test in the SELECTIJ phase.. loading. ENDIF LINKLOOP . With the BREAK statement. and save those matrices with FILEO MATO. The working matrix may be reported with the PRINTROW statement.. for subsequent loading. and then manipulate. you can use the MATI phase to select zones for processing. and save the trips in a working matrix. but for a zone pair at a time. ELSEIF . using the COMP statement and the built-in ROW functions. You can also do this in the SELECTIJ phase.. You can merge highway skims with • skims extracted in the Public Transport program run. Input matrices external to the Public Transport program with FILEI MATI.. from an origin zone (I) to all zones (J).... See “Public transport loading” on page 856 for an example of this phase.. ENDIF JLOOP .. ENDLOOP PRINT PRINTROW Cube Voyager Reference Guide 627 . ELSE ..Public Transport Program Phases 12 • Compute a row of trips. Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF. report. ENDJLOOP LOOP . The working matrix is designated for loading with PARAMETERS TRIPSIJ[userclass].. MW[#]. 628 Cube Voyager Reference Guide . The ROUTEI and ROUTEO subkeywords I. the I-J pairs loaded range from I=10-ZONES to J=1-9. loading.1 * 0. For example: PHASE=SELECTIJ if(I < 10) CONTINUE if(J > 10) BREAK TRIPSIJ=MI.12 Public Transport Program Phases Public Transport variables available in this phase ZONES USERCLASS I J SELECTIJ The SELECTIJ phase selects pairs of zones. I-J. (Route evaluation is a time consuming process. and SELECTBYMAT provide the first line of selection but they do not control specific I-J combinations. The Public Transport program executes the SELECTIJ phase prior to the route-evaluation process for the I-J pair. and loading analyses processes. The SELECTIJ phase allows a finer selection of specific I-J combinations. for bypassing the route-evaluation process.) Only zone pairs for evaluated routes are available for the skimming.TRIPSIJ ENDPHASE In this fragment of code. This phase can compute the trips to be loaded for each I-J pair. therefore judicious use of this phase can have a significant impact on overall processing time. although if the I-J combination is precluded by the values on the ROUTEI and ROUTEO.1.J. The trips to be loaded are computed from the input trip matrix and reported.75 PRINT LIST=I. J. that I-J pair is not available to this phase. I-J... 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.. generally in working matrices with the COMP MW[#] statement.. then saves them...Public Transport Program Phases 12 Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF. ELSE . ELSEIF . See “Public transport skimming” on page 854 for an example of this phase. Cube Voyager Reference Guide 629 . The Public Transport program invokes SKIMIJ for each zone pair. immediately after route evaluation. ENDIF JLOOP . you use the MATO phase with the matrices produced by the skimming and loading analyses phases.. ENDJLOOP LOOP . skimming... Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF.. With the BREAK statement.12 Public Transport Program Phases MATO In the MATO phase... ELSE .. combines. The program executes this phase once for each origin zone. the Public Transport program revises. and loading analyses processes for all destination zones of that origin zone. loading. but you can also process other working matrices similarly. reports and writes work matrices to the FILEO MATO files. Generally. you can use the MATO phase to select zones for processing. and create a report with the PRINTROW statement. You can manipulate matrices with the COMP statement and a set of built-in ROW functions. ELSEIF .. after completing the route evaluation. I. ENDLOOP PRINT PRINTROW 630 Cube Voyager Reference Guide .. See “Public transport skimming” on page 854 for an example of this phase.. Public Transport Program Phases 12 Public Transport variables available in this phase ZONES USERCLASS I J Cube Voyager Reference Guide 631 . ENDJLOOP. Examples of dynamic control statements include LINKLOOP .12 Public Transport Program Control statements Control statements Control statements provide instructions and information to the Public Transport program.. FACTORS). Some are specific to this program while others are available throughout Cube Voyager. These may only be present in the processing phases.. JLOOP . Some static statements are provided in files. regardless of their location in the script. • The control statements available in the Public Transport program are listed below. The Public Transport program has two types of control statements: • Static — Evaluated only once. Phases only permit contextsensitive control statements. Citilabs recommends keeping static control statements together at the beginning of the script file.. and REREPORT.. GENERATE. FILEO. PARAMETERS. not in the job script (that is. PRINT. 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 632 Cube Voyager Reference Guide . ENDLINKLOOP. LINE. at the start of each run. Examples of static control statements include FILEI. MODE. Dynamic — Evaluated as encountered. see each phase’s description in “Phases” on page 620 for a list of valid statements. . ABORT MSG = text ABORT keyword Keyword MSG |S| Description Optional. Message printed when the program terminates. ELSEIF ........ 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. ELSE .. Cube Voyager Reference Guide 633 . ENDIF JLOOP ..Public Transport Program Control statements 12 Control statement GENERATE GOTO IF.. ENDLINKLOOP LOOP .. ENDJLOOP LINE LINKLOOP . ..b....a. If BREAK is within a LOOP . the script terminates processing for the I zone but does not bypass output and zonal reporting statistics. the script reports the links and aborts the run with an appropriate message.12 Public Transport Program Control statements Example Before generating access and egress legs in the DATAPREP phase.WalkSpeed <= 0 || lw.b <=24) && (lw... ENDPHASE BREAK Breaks out of a loop.a <=24 || li.0 )) LnkCnt=LnkCnt+1 print list=li.Generate access legs only if walk costs coded on links GENERATE. LnkCnt if(LnkCnt>0) abort msg = Access/Egress Links with invalid walk speeds . the script immediately passes control to the statement after the associated loop. PHASE=DATAPREP LnkCnt = 0 LINKLOOP if((li. ENDJLOOP block. control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J is reset to 1). lw... this script checks that the speed of links that may be used for walking is between 0 and 5 km/h. Upon encountering BREAK. If the script finds links outside this range. ENDLOOP or JLOOP . If BREAK is not within a LOOP or JLOOP block. li.WalkSpeed > 5.WalkSpeed endif ENDLINKLOOP print list= 'Number of access/egress links with invalid walk speeds = '. 634 Cube Voyager Reference Guide . the route-evaluation. and saving matrices to file. regardless of the value of L1. loading.) PHASE=MATO Cube Voyager Reference Guide 635 . LOOP L1=1. BREAK terminates the loop at the 20th zone.Public Transport Program Control statements 12 When used within the Public Transport program’s MATI or MATO phases. manipulating matrices. skimming. and bypasses end-of-zone processing for zone I. BREAK bypasses any more processing for the relevant I zone. they would be done only for zones 1-19. When “condition 2” is met. and loading-analyses processes effectively stop after the 19th zone for each user class. Therefore. (Because MATO follows the processes. skimming.1 ENDPHASE Example 3 MATO selects zones 1 to 19 for reporting. and loading-analyses processes are completed for loop J within loop I. ignoring all other zones. BREAK terminates the I-loop at zone 20 for each user class. Example 1 Loop terminates if “condition 1” is not met.3 IF (condition 1) statements ELSE BREAK ENDIF ENDLOOP IF (condition 2) BREAK Example 2 MATI selects zones 1 to 19 for processing. breaks out of the I-loop. control passes to the following IF statement and processing for zone I ceases. Therefore.1. PHASE=MATI IF(I==20) BREAK MW[1] = MI. enabling no further processing. loading. The route-evaluation. the processes will run for zone 20 but will not save any matrices produced. or more. EXCLUDE=list of J zones Expressions are either numeric formulas or selection criteria.2 ENDPHASE COMP Computes a variable. See “Expressions” on page 30 for more details. Built-in functions must be followed by one. Built-in functions include: • • • Numeric functions (see “Numeric functions” on page 32) String functions (see “Character functions” on page 34) Row-based functions.12 Public Transport Program Control statements IF(I==20) BREAK MW[1] = MW[1] * 1. or row data and return a value. 636 Cube Voyager Reference Guide . Numeric expressions can use built-in functions that operate on numeric. 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. INCLUDE=list of J zones. The number of arguments must match the requirements of the function. matrix. VAR=expression MW[n]=expression. arguments enclosed within parentheses (). or matrix element from an expression. string. 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. You can specify this keyword in two formats: • MW[n] — Defines the value for row n of a working matrix. Not permitted if COMP statement within JLOOP . MW EXCLUDE |I| Optional. The index n may be either a constant or a variable name. Value for a working matrix. as indexed by n.. Values of J excluded when computing the MW[n] expression. Within a JLOOP statement. with J being the loop’s J if within a JLOOP. Always processed after INCLUDE subkeyword.. The program solves the expression one time only. ENDJLOOP block. By default no zones are excluded. As the program internally loops on J. Filter applies to all MW[n] values on the COMP statement. the program does not evaluate or store the expression for that J. if not. o. Matrices can contain up to MAXMW rows. The second index.Public Transport Program Control statements 12 • Skimming functions. must be between one and Zones. or 1. • MW[n][o] — Defines the value for column o in row n. filtering values indicated by any INCLUDE or EXCLUDE lists on this statement. with J being the value of the loop’s current J. Specified values can range from 1 to the highest zone number. If the current J is on the list. the program only solves the expression one time only. Cube Voyager Reference Guide 637 . the program compares J to the values in the EXCLUDE list. The program solves the expression for all values of J (1 through Zones). xyz is declared a string The program does not always compute expressions for variables that are not used as input to some process.messy -. the program does not evaluate or store the expression for that J. VAR |K| Optional. Variable that stores result of an expression. 638 Cube Voyager Reference Guide . Not permitted if COMP statement within JLOOP . the program compares J to the values in the INCLUDE list.. Values of J included when computing the MW[n] expression.. each node in the NODEREAD phase or each link in the LINKREAD phase). The COMP statement sets a variable type to the result of the variable’s first evaluated expression.valid abc = abc+def . Specified values can range from 1 to the highest zone number.invalid: xyz is declared a string (later) xyz = 'xyz' .invalid: abc has been declared a string abc = abc+'456' . In the above examples. Examples of variables are: abc = '123' def = 123 abc = def . As the program internally loops on J.jkl is declared numeric jkl = xyz .12 Public Transport Program Control statements COMP keywords (continued) Keyword MW Subkeyword INCLUDE |I| Description Optional. If the result is a character string.do not mix types jkl = 1 . because jkl is never used. Filter applies to all MW[n] values on the COMP statement. the statements with jkl= might never be executed. the variable must be a character string variable. If the current J is not on the list. ENDJLOOP block. By default all zones are included. The program evaluates each encountered expression (for example. using standard function MAX.5) PRINTROW MW=6 TITLE='AVJRNYCOST'.3. FORM=10. bypassing all intermediate statements. Cube Voyager Reference Guide 639 .2 Endphase Determine the highest node number in the public transport system.2 if (ROWSUM(5) > 0) PRINTROW MW=5 TITLE='XWAITA'.2 if (ROWSUM(6) > 0) PRINTROW MW=6 TITLE='IWAITP'.ALLMODES) MW[4]= BRDPEN(0.4. BASE1=T. Anode.1. Bnode) CONTINUE Jumps to the end of a loop. BASE1=T. BASE1=T.2 if (ROWSUM(4) > 0) PRINTROW MW=4 TITLE='IWAITA'.ALLMODES) MW[5]= XFERPENA(0. FORM=10.Public Transport Program Control statements 12 Examples of computation statements in Public Transport This example reports the nonzero rows of a selection of skim matrices. FORM=10. FORM=10. BASE1=T. FORM=10.2 Endphase Compute average perceived trip cost skim from its components.2. BASE1=T. ALLMODES) Endphase Phase=MATO x=ROWADD(6. FORM=10.2 if (ROWSUM(3) > 0) PRINTROW MW=3 TITLE='ValOfChoice'. Phase=SKIMIJ MW[1]= IWAITP(0) MW[2]= XWAITP(0) MW[3]= TIMEP(0. HighestNodeNum = MAX(HighestNodeNum. BASE1=T. Phase=MATO if (ROWSUM(2) > 0) PRINTROW MW=2 TITLE='Compcost'. .KINC JLOOP EXCLUDE=25-50. Example 3 LOOP L2=K1. Example 2 IF (condition) CONTINUE This statement is used in an explicit or implicit loop over I.3 IF (!(condition 1)) CONTINUE ENDLOOP In this user-controlled loop. processing for the I zone is terminated. Otherwise. Example 1 LOOP L1=1. from K1 to K2. LOOP processing is bypassed for the L3s for which “condition 2” is met. ENDJLOOP block... except output and zonal summaries. The outermost LOOP operates over the full range of L2... ENDLOOP or JLOOP .... ENDJLOOP LOOP L3=L2.. incrementing in steps of KINC.. ENDLOOP ENDLOOP JLOOP processing is bypassed for the Js for which “condition 1” is met. control is passed to the ENDLOOP when “condition 1” is not met. control passes to the appropriate ENDLOOP or ENDJLOOP statement. If the condition is met..12 Public Transport Program Control statements If CONTINUE is within a LOOP . but output and zonal reporting statistics will not be bypassed.L2+5 IF (condition 2) CONTINUE . for that value of L1. bypassing any statements between the IF and ENDLOOP.K2. Example 4 PHASE=SELECTIJ 640 Cube Voyager Reference Guide . similarly.88 IF (condition 1) CONTINUE . no more Js will be processed for the I zone. Crowded travel times are behavioral measures which increase the in-vehicle time to reflect the discomfort of standing or travelling in crowded conditions. The first BREAK stops the I-loop after zone 455 and the second stops each Jloop after zone 455. If crowding is not applied.Public Transport Program Control statements 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. Cube Voyager Reference Guide 641 .0 at both x=0 and x=100). No default curves are provided. CROWDCRVDEF Defines crowding curves. used to compute crowded travel time for particular combinations of transit lines and user-class. then either do not code line capacities. You can define up to 255 wait curves. 403-455 for processing. or use a flat curve (with y-value set to 1. The first CONTINUE bypasses origin (I) zones 1-402 and the second one bypasses destination (J) zones 1-403. the corresponding crowding factor values must increase. Each pair of X and Y values may be separated by a comma or a dash. CURVE= 0. The values for utilization vary from 0.1. When the first coded X-value is greater than 0% utilization. It is in addition to NAME.1. or remain the same. 100. the curve runs from the point (0-1. When the last coded X-value is less than 100%.0) to 100.0. 20. LONGNAME NAME NUMBER |S| |S| |I| Optional. Crowding factor (Y-axis) may not decrease as utilization (X-axis) increases. There is a linear interpolation between coded points. while the pairs themselves must be separated by a comma. For example: CROWDCRVDEF NUMBER=1 LONGNAME="Suburban Rail" NAME="S-Rail" .12 Public Transport Program Control statements Input CROWDCRVDEF statements must be input in the public transport system data file with SYSTEMI.000. Utilization (measured as a percentage) is the curve’s X-axis and the crowding factor is the curve’s Y-axis. the curve is extrapolated beyond that point at the same gradient as applies immediately below the point. Optional. Must be the first keyword coded on the CROWDCRVDEF control statement. 642 Cube Voyager Reference Guide . Specifies a unique numeric identifier for a crowding curve.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. Valid values range from 1 to 255. Specifies a text-string identifier for a crowding curve. when progressing from one point to the next. CROWDCRVDEF keywords Keyword CURVE |R| Description Defines X-Y pairs for the crowding curves used to compute link travel times under crowded conditions. Maximum value: 10.0 (where the crowding factor is at least 1.0.0) to the first coded point.1. Specify the utilization values in ascending order.1. Specifies a second text-string identifier for a crowding curve. runs the crowding model.Public Transport Program Control statements 12 Example Defining crowd curve number 1 for rail services. APPLY |?| Optional.9 CROWDMODEL Specifies the crowding model used in the run of the Public Transport program. NAME="Medium distance Rail". Default value is false. ITERATIONS PERIOD |I| |I| Specifies the number of iterations performed during a crowd-modeling run. Default value is false. Valid values are 1 to 1440. Example CROWDMODEL. Default value is false.0. Valid values are 1 to 99. the crowding model is disabled. CURVE= 0-1. Uses the available capacity of a service (at a particular boarding point) along with demand data to establish whether travellers may board this service. Length of the modeled period in minutes. Default value is 60. CROWDMODEL keywords Keyword ADJUSTLINK |?| Description Optional. 100-1. When set to true. APPLY = T. ADJUSTWAIT |?| Optional. CROWDCRVDEF NUMBER=1. ITERATIONS = 10 Cube Voyager Reference Guide 643 . When set to true. invokes link travel-time adjustment. or must wait for a later service. which reflects higher behavioral costs associated with travelling in crowded conditions. 37-1. When set to false. ADJUSTWAIT = T. Any demand matrix loaded during assignment should be calculated for the model period. When set to true.1. invokes the calculation of additional wait time. Each user class that the program references must have FACTORI keywords defined on a FILEI control statement. EXIT Terminates loops (implied or explicit). 644 Cube Voyager Reference Guide .12 Public Transport Program Control statements Specifies a run with 10 iterations of crowd modeling. including a wait-time adjustment. The index of the FACTORI keyword. You define user classes with the USERCLASSES keyword in the PARAMETERS control statement. the program passes control to the end of the loop. Some FACTORS keywords are used for both the route enumeration and evaluation processes. is the number of the user class. If there is no index. IF (expression) EXIT .10 . as noted in the keyword description. When the program encounters an EXIT statement within a loop. FACTORS Specifies the generalized cost factors and control information for the route enumeration and evaluation processes. the program assumes the index is 1. Example LOOP iter=1. although two or more classes may reference the same file. others apply to one or the other. ENDLOOP This loop terminates either when iter=11 or the condition specified by expression is met. #. FACTORS statements must be input in a separate file with FACTORI keywords on the FILEI control statement. all-or-nothing routes. The values can be input in any order. the program uses the last value specified. AONMAXFERS |IK| Optional. FACTORS keywords Keyword ALPHA Subkeyword |RK| Description Optional. Default value is 45. A value of 1 indicates that the walk and onward costs have equal weight. Multirouting models only enumerate the all-or-nothing route if the number of transfers exceeds MAXFERS.Public Transport Program Control statements 12 The keywords on this statement are all “trigger” keys. For most of the keywords. Maximum permitted number of transfers on the minimum-cost.0.0 to 1. 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. Valid values range from 0. AONMAXFERS is not used) Valid values are 0 to 45. you need not code the control statement name FACTORS. if the keyword appears multiple times. Determines the relative weights for the generalized costs of the walk leg and the remainder of the route in walk-choice model. Cube Voyager Reference Guide 645 . Default value is 1. A traveler’s willingness to walk might relate to network familiarity. only those routes with MAXFERS or fewer transfers are enumerated (that is.0. When BESTPATHONLY=T. Lower values indicate the walk cost has more influence than the onward cost in the traveler’s choice. Only routes with AONMAXFERS (or fewer) transfers are enumerated to the routes file. Applies only to route evaluation. in minutes.6 then the penalty for boarding any line on mode 1 is three minutes. Valid values range from 0 to 9999. the program ignores settings for the FACTORS keywords ALPHA. 3. making higher MAXFERS settings appropriate.3*5. and SPREADFUNC. nonzero values specified for nontransit modes do not have any effect. and the enumeration process changes its mode of operation: Best paths using more then MAXFERS transfers are not enumerated. the program uses the FACTORS keywords SPREADCONST. When set to true. LAMBDAW. and REWAITMIN. The best-path-only method cannot be used with either the crowding model or the service frequency and cost model. SPREADFACT. Mode-specific boarding penalty. BRDPEN |RKV999*| Optional. The default value is false. onto which all demand is loaded. Applied only to transit modes. When using best-path modeling. the penalty for boarding any line on modes 2. Do not set BESTPATHONLY to true if PARAMETERS keyword FARE is true or AONMETHOD has value 3. if BRDPEN=3. If using best-path modeling with MUSTUSEMODE set to true. REWAITMAX.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword BESTPATHONLY Subkeyword |?K| Description Optional. otherwise the keywords are ignored. CHOICECUT. 646 Cube Voyager Reference Guide . and 4 is five minutes and the penalty for boarding a line on mode 5 is six minutes. LAMBDAA. For example. the evaluation process identifies a single best path. The default value is 0. Applied in addition to the transfer penalty specified by XFERPEN. AONMAXFERS. The default value is 0. Valid values range from 0 to 999. you can use this keyword to restrict access legs to the required mode (that is. DELEGRESSMODE |IKV999| Optional. For example. It takes the value of LAMBDAW or LAMBDAA.01. 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. Valid values range from 0 to 999. There is no default. There is no default. For example. DELACCESSMODE |IKV999| Optional. Specifies modes that cannot be used as access connectors (from zones to transit lines) during route enumeration. depending upon the point in the trip at which it is applied. walk or car) for a user class. car or walk) required for a user class.2.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword CHOICECUT Subkeyword |RK| Description Optional. Eliminates alternatives with low probabilities of use at walk or alternative-alighting decision points. Cube Voyager Reference Guide 647 . If p is the proportion of the demand that takes the least-cost alternative. when modeling walk and car connectors. when modeling walk and car connectors. Specifies modes that cannot be used as egress connectors (from transit lines to destination zones) during route enumeration. it is not used when modeling best path routes. Cost to destination by choice i Costi CostBest Cost to destination by the best choice CHOICECUT applies only to route evaluation. you can use this keyword to restrict egress legs to the mode (that is. Valid values range from 0 to 0. ). You can use this keyword to delete particular modes (transit or nontransit) from the model for a particular user class. EXTRAXFERS1 is one of three parameters controlling the exploration of routes. The default value is 3. The default value is 2. An upper bound on the number of transfers. EXTRAXFERS1 applies only to route enumeration. EXTRAXFERS2 applies only to route enumeration. in excess of the minimum required. Specifies modes that the program will not use during route enumeration. EXTRAXFERS2 |IK| Optional. Valid values range from 0 to 10. 648 Cube Voyager Reference Guide . There is no default. Valid values range from 0 to 999.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword DELMODE Subkeyword |IKV999| Description Optional. See “Route generation” on page 662 for more information. Maximum number of transfers explored in excess of the number of transfers required by the minimum-cost route. EXTRAXFERS2 is one of three parameters controlling the exploration of routes. Number of transfers at which the program stops exploration of less direct routes. EXTRAXFERS1 |IK| Optional. is controlled by EXTRAXFERS1 and MAXFERS (see “Route generation” on page 662. Valid values range from 0 to 10. The fare model must be one of the fare systems defined with the FARESYSTEM control statement in a FILEI FAREI file. you might describe a fare model in the FAREI files as: FARESYSTEM NUMBER=1. UNITFARE=70. FARESYSTEM MODE |IVt|1 Optional. you can apply that fare model to a selection of transit modes: FARESYSTEM=1. Cube Voyager Reference Guide 649 .0. List of operators that the fare model specified in FARESYSTEM applies to. MODE=7-11 FARESYSTEM applies only to route evaluation. but you must code one for each FARESYSTEM. STRUCTURE=FLAT. Default value is 0. NOTE: The MODE and OPERATOR subkeywords are mutually exclusive. NAME="DIST-Journ". Mixing the two could produce ambiguous allocations.50 In the factors file. through their modes or operators. By default. List of transit modes that the fare model specified in FARESYSTEM applies to.30. Program ignores any nontransit modes in the list. Number of the fare model that applies to the modes or operators selected with the subkeywords MODE or OPERATOR. IBOARDFARE=100. Valid values range from 1 to 99. none are specified. IBOARDFARE=50. Valid values range from 1 to 1999. The program allocates fare systems to lines. Default value is 0. Valid values range from 1 to 999.40 FARESYSTEM NUMBER=2. FAREFROMFS=40. MODE=1-6 FARESYSTEM=2. NAME="Flat". all FARESYSTEM keywords must apply to either modes or operators.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword FARESYSTEM Subkeyword |IK| Description Optional. FAREFROMFS=0. STRUCTURE=DISTANCE. FARESYSTEM OPERATOR |IVo| 2 Optional. For example. If using multiple fare models. In this case. and the average IVT is based on all modes. If modes 1 and 2 form a bundle. 650 Cube Voyager Reference Guide . If FREQBYMODE is false then multimodal transit leg bundles are allowed. The wait times are based on the headway of the mode under consideration.” and mode does not affect that boarding pattern. This corresponds to traveler behavior where a traveler selects a mode of travel. FREQBYMODE comes into effect when a transit-leg bundle (that is. By default the BESTPATHONLY enhancement identifies the best path using unimodal transit-legbundles. then either you use mode 1 or you use mode 2 depending on IVT and wait times in the two cases. and corresponds to traveler behavior where they “select the useful service that first arrives at the boarding point. and then waits for a service of that mode (ignoring any potentially useful services in the transit leg bundle of any other mode). The default value is true. Flag that determines wait-time calculation: • • False — Calculated at the transit-leg bundle level True — Calculated at the (lower) mode level FREQBYMODE is only applicable when BESTPATHONLY is true. This gives lower wait times.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword FREQBYMODE Subkeyword |?K| Description Optional. collection of lines from a boarding point to an alighting point) on a “potential best route” is multimodal. the wait time is based on combined frequency of all lines in the transit bundle regardless of mode. applies when they are the initial boarding points of trips. The default value is system generated. For example. The default value is the value of LAMBDAW.0001 to 99. Determines the proportion of trips allocated to each alighting node. given IWAITCURVE=2. IWAITCURVE NODES |IV10000| List of nodes to which the wait curve number specified by IWAITCURVE. Valid values range from 1 to the number of wait curves in the network. 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. The program ignores wait curves associated with zones or nodes that are not stops.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword IWAITCURVE Subkeyword |IK| Description Optional. Wait curve used to calculate the initial wait time for trips starting at nodes specified by NODES subkeyword. 2500-2600. Not used when modeling best-path routes. Applies only to the route-evaluation process. LAMBDAA |RK| Optional. This keyword is required if IWAITCURVE is specified. inclusive. IWAITCURVE applies only to the route-evaluation process. Cube Voyager Reference Guide 651 . based on the composite cost differences between the alternatives. Valid values range from 1 to the system’s highest node number. Valid values range from 0. Scaling factor for the alternative-alighting node model. NODES=10002000.0. The default value is 0. the default value should work for a medium-sized network of 400-500 zones.250. When there are transit choices. Valid values range from 0.000. 652 Cube Voyager Reference Guide . LAMBDAW applies only to the route-evaluation process. Valid values range from 1000 to 1. Used to dimension arrays that store components and their attributes. Scaling factor for the walk-choice model. This factor determines the proportion of trips allocated to each walk choice at a node. The default value is 50. Subsequently. MAXCOMPD applies only to route enumeration. the program does not use this factor when modeling best-path routes. MAXCOMPD |IK| Optional.0. based on the composite cost differences between alternatives. the service-frequency model allocates the transit share among the different transit choices.000.0001 to 99. The program only requires MAXCOMPD when using older algorithms. Number of components generated during the route-enumeration process. The number of components generated depends upon the number of lines in the public transport system and the connectivity of the network.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword LAMBDAW Subkeyword |RK| Description Optional.2. the program uses the transit modes’ composite cost to a destination to determine the transit share. triggered by the AONMETHOD keyword on the PARAMETERS control statement. AONMAXFERS sets the maximum number of transfers. Valid values range from 0. as best routes requiring more transfers are not enumerated. then the program enumerates viable routes.999.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword MAXFERS Subkeyword |IK| Description Optional. the the program will enumerate routes on the required mode that have a cost of up to 53 (that is. See “Route generation” on page 662. 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). you might use higher MAXFERS values. Valid values range from 0 to 10. then the program only enumerates the minimum-cost route (subject to any constraint imposed by the AONMAXFERS factor).999. The default value is 5. regardless of the number of enumerated routes (AONMAXFERS is not used). Maximum number of transfers allowed in routes between origin-destination pairs with more than one enumerated route. When BESTPATHONLY is true.1 to 999. MAXFERS works with EXTRAXFERS1 and EXTRAXFERS2 to control the number of routes generated. When an origin-destination pair has a minimum-cost route with at most MAXFERS transfers. The default value is 999. Cube Voyager Reference Guide 653 . When the PARAMETERS keyword AONMETHOD is set to 3. MAXFERS is the maximum number of transfers allowed in route enumeration. if the cheapest route for an origindestination pair is 23 and MUMEXTRACOST is 30. For pairs with only one enumerated route. MUMEXTRACOST |RK| Optional. Additional cost allowed on enumerated routes of a required mode (a mode specified in MUSTUSEMODE). If the transfers exceed the MAXFERS when using multirouting. For example. 23+30). Specifies required transit modes in a route for enumeration or evaluation.999.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword MUSTUSEMODE Subkeyword |IKV999| Description Optional. set to the value of BESTPATHONLY. REBESTPATHCOST |?K| Optional. By default. Default value is 999. Specified modes must be transit modes.01 to 999. 654 Cube Voyager Reference Guide . Upper cost limit that applies during route enumeration. If you specify two or more values. the program enumerates the route if any of the modes are used. The program excludes more expensive routes from enumeration. False — Computes transit • Cannot be false if BESTPATHONLY is true. and hence evaluation.999. Valid values range from 0 to 999. Valid values range from 0. See “Generalized cost” on page 771 for a description of costs. Flag that sets method for computing transit costs in route enumeration: • True — Computes transit costs closer to those used in evaluation. Must be false if program uses service frequency and cost model. RECOSTMAX |RK| Optional. The default value is 5. Minimum weighted wait time for a leg bundle during route enumeration. it is not applicable when modeling best-path routes. Maximum weighted wait time for any leg bundle in route enumeration.0 ensures that a minimum wait time is incurred for all leg bundles regardless of the frequency of their services.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. REWAITMIN applies only to route enumeration. if a leg bundle’s frequency sums to 60 vehicles per hour. Setting REWAITMAX to 0 excludes wait time from consideration during route enumeration.0 to 30. Valid values range from 0. it is not applicable when modeling best-path routes. Setting REWAITMIN to 1.0./Frequency)/2 For example.0 to 200. REWAITMAX applies only to route enumeration.0.0. REWAITMIN |RK| Optional. Cube Voyager Reference Guide 655 .5 minutes. Setting REWAITMAX to 3.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword REWAITMAX Subkeyword |RK| Description Optional. The default value is 1. The program computes a leg bundle’s wait time from the sum of the frequencies in the bundle’s legs: (60. the wait time is 0. if the frequency of a leg bundle sums to 5 vehicles per hour. The program computes a leg bundle’s wait time from the sum of the frequencies of the bundle’s legs: (60.0. the wait time is 6 minutes./Frequency)/2 For example. Valid values range from 0. exceeding 2.01 and 3. Service model to be used in routeevaluation.0. SPREADFACT |RK| Optional.1.2. run times for modes 2.0. Multiplicative factor used in multirouting function to compute SPREAD (see “SPREADFUNC” on page 657).0 are appropriate for most modeling requirements. SPREADCONST |RK| Optional.2.0 only in rare circumstances. Typical values range from 1. Valid choices are: • • FREQUENCY — Specifies Service-frequency model FREQUENCYCOST — Specifies Servicefrequency-and-cost model Default value is FREQUENCY.9. For example. The default value is 1.8 and run times for mode 5 by 1. Valid values range from 0.01 to 10. Values ranging between 0. Mode-specific weighting factor applied to transit in-vehicle times and nontransit leg times. Applies only to route enumeration. Applies only to route enumeration.0. Constant used in multirouting function to compute SPREAD (see “SPREADFUNC” on page 657). not applicable when modeling best-path routes. if you include RUNFACTOR=1. SERVICEMODEL |S| Optional. not applicable when modeling best-path routes.5. Default value is 1.5. Valid values range from 0 to 1000. skimming.8. Default value is 5. and loading-analyses processes.05 to 1.3*1.9 then the program multiples run times for mode 1 by 1. loading.0. 3 and 4 by 1. 656 Cube Voyager Reference Guide . Valid values range from 0 to 10.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword RUNFACTOR Subkeyword |RKVm*|3 Description Optional.0. GCost(MinRoute) + SPREADCONST) • SPREADFUNC=2: SPREAD = GCost(MinRoute)* SPREADFACT + SPREADCONST Where: • GCost(MinRoute) — Generalized cost of the minimum-cost route. NOTE: The parameter applies to each decision point (alighting/boarding node) on a route in addition to the destination. • The program enumerates routes with a cost less than or equal to SPREAD. The lower limit is the cost of the “minimum cost” route between the two zones. SPREADCONST — Time that may be added to the minimum generalized cost time between zone pairs. The generalized cost the route-evaluation process uses is more accurate.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword SPREADFUNC Subkeyword |IK| Description Optional. Integer specifying the function that computes SPREAD during route enumeration. Cube Voyager Reference Guide 657 . The program computes the upper limit based on value of SPREADFUNC: • SPREADFUNC=1: SPREAD = MAX(GCost(MinRoute)* SPREADFACT. • SPREADFACT — Factor that the minimum generalized cost time between zone pairs may be multiplied by. NOTE: This is an estimate. SPREADFUNC applies only to route enumeration. Default value is 1. SPREAD defines an upper cost limit for routes between an O-D pair. it is not applicable when modeling best-path routes. Default value is 1. Valid values range from 0. WAITFACTOR |RK| Optional. Valid values range from 0. the program will add three minutes to the transfer penalty specified by XFERPEN. Applies only to route evaluation. Only code if using fares. Node-specific wait-time weighting factor. TO=25 For transfers from mode 10 to mode 25. 30004500 The wait times for nodes 1000 through 2000 and nodes 3000 through 4000 will be multiplied by 1. consider: WAITFACTOR=1. Use FROM and TO to specify the applicable modes.0. Applies only to route evaluation. XFERCONST TO |IV100| Integer specifying the “to” mode for the transfer penalty specified with XFERCONST. Converts monetary fares into generalized cost.5.5. Typically. FROM=10. WAITFACTOR NODES |IV10000| List of nodes that WAITFACTOR applies to. applied to nodes specified with NODES subkeyword. NODES=1000-2000. consider: XFERCONST=3. 658 Cube Voyager Reference Guide .0.0. For example. ignored in such cases.0 to 9999. XFERCONST |RKVt [t]|1 Optional. The default value is 0.0.01 to 10. in monetary units per hour.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword VALUEOFTIME Subkeyword |RKVt*|1 Description Optional. Transit-mode-to-transit-mode constant that can be added to the weighted transfer penalties obtained from XFERPEN. sufficient values for most modeling range from 0. Valid values range from 1 to the network’s highest mode number. For example. Valid values range from 1 to the network’s highest mode number. XFERCONST FROM |IV100| Integer specifying the “from” mode for the transfer penalty specified with XFERCONST. Valid values range from 0. Does not apply to nontransit modes. Transit-mode-specific value of time.01 to 3.0 to 5000. FROM=10. TO=25 For transfers from mode 10 to mode 25. XFERFACTOR TO |IV100| Integer specifying the “to” mode for the transfer penalty factor specified with XFERFACTOR.0.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword XFERFACTOR Subkeyword |RKVt [t]|1 Description Optional. the program multiplies the transfer penalty specified by XFERPEN by 1. Valid values range from 1 to the network’s highest mode number. Cube Voyager Reference Guide 659 . Valid values range from 1 to the network’s highest mode number.5. For example. Use the subkeywords FROM and TO to specify the applicable modes. Transit-mode-to-transit-mode weighting factor for transfer penalties specified by XFERPEN. Applies only to route evaluation. Valid values range from 0.5. The default value is 1. consider: XFERFACTOR=1.0. XFERFACTOR FROM |IV100| Integer specifying the “from” mode for the transfer penalty factor specified with XFERFACTOR.01 to 10. The default value is 0. Code a high penalty to ban transfers between modes. a penalty of 999 minutes is sufficient. Valid values range from -99 to 9. TO=25 For transfers from mode 10 to mode 25.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword XFERPEN Subkeyword |RKVt [t]|1 Description Optional. Valid values range from 1 to the network’s highest mode number. Use negative transfer penalties in conjunction with boarding penalties to reflect the relative attractiveness of transfers between some modes compared to others.5 minutes. FROM=10. A high penalty makes any route with such transfers “unattractive” to the choice models.999. to mode) and BRDPEN(to mode) must be greater than or equal to zero. consider: XFERPEN=5. XFERPEN only applies to route evaluation. Transit-mode-to-transit-mode transfer penalty. For example.5. In most cases. The program ignores any nontransit legs traversed between the two. Transfer penalties may be negative but the sum of XFERPEN(from mode. XFERPEN FROM |IV100| Integer specifying “from” mode for transfer penalty specified with XFERPEN. in minutes. The program applies XFERPEN in addition to BRDPEN. Transfer penalties apply between the alighting and boarding transit modes. 660 Cube Voyager Reference Guide . Valid values range from 1 to the network’s highest mode number. the program adds 5. Use the subkeywords FROM and TO to specify the applicable modes. XFERPEN TO Integer specifying “to” mode for transfer penalty specified with XFERPEN. XWAITCURVE applies only to route evaluation. The default is a systemgenerated wait curve.3 Cube Voyager Reference Guide 661 . consider: XWAITCURVE=4. Valid values range from 1 to the network’s highest node number. Wait-curve number used to calculate wait times for trips that involve transfers to nodes specified with NODES subkeyword. 1. The program ignores wait curves associated with zones or nodes that are not stops.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword XWAITCURVE Subkeyword |IK| Description Optional. when those nodes form transfer points in a trip. XWAITCURVE NODES |IV10000| List of nodes that the wait curve specified in XWAITCURVE applies when they are boarding stops at transfer points.1 SPREADCONST = 10. o indicates number of transit operators 3.0 LAMBDAW = 0. t indicates number of transit modes 2. 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.0 REWAITMIN = 5 REWAITMAX = 30 //Evaluation Controls ALPHA = 1. For example. Valid values range from 1 to the maximum number of wait curves in the network. NODES=1000-1500 The program uses wait curve number 4 to compute the wait time at nodes 1000 through 1500. 5. number of transfers must be no greater than MAXFERS. to=8-12. XFERFACTOR=1. to=7-12. XFERPEN=2.0. n=150-1600 WAITFACTOR=2. RUNFACTOR[8] = 2.25. XFERCONST=2.0. from=11-12.5.0. XFERFACTOR=2. If number of transfers exceeds MINXOD.3 //Wait time IWAITCURVE=1.12 Public Transport Program Control statements LAMBDAA = 0. to=7-12. nodes=1300-1400 XWAITCURVE=2.5. from=7-10. Next. Second. Attractive routes depend on the number of transfers: • • If the number of transfers equals MINXOD. the program generates minimum-cost routes for all O-D pairs and records the number of transfers required for these routes. number of transfers must be less than or equal to the minimum of: MINXOD+EXTRAXFERS2 EXTRAXFERS1 MAXFERS The search for routes has two stages. from=7-10.5 XFERPEN=3. n=25-1000 //IVT factor by mode RUNFACTOR[7] = 1. XFERCONST=5. to=8-12. the program determines the connections required to transfer between lines. First. First. from=7-10. The program ensures that routes do not exceed the specified constraints. the program searches for “attractive” routes for each O-D. RUNFACTOR[11] = 2. from=11-12. from=11-12. 662 Cube Voyager Reference Guide . Route generation MAXFERS works with EXTRAXFERS1 and EXTRAXFERS2 to control the number of routes generated.5 //Penalties BRDPEN[7] = 4*2. MINXOD. to=7-12. to=7-12.0. the program explores the connections and generates routes by progressing through a sequence of lines and connections. This is consistent with observed travel patterns: 70-80% of trips are completed within two transfers or three transit legs.Public Transport Program Control statements 12 The following table shows the number of transfers that the program explores for various values of EXTRAXFERS2 if MAXFERS=5 and EXTRAXFERS1=4 (the default condition). EXTRAXFERS1=4 and EXTRAXFERS2=2. The program expends more effort where travelers make a greater proportion of tips. Cube Voyager Reference Guide 663 . the program explores more routes for directly connected zone pairs than for less directly connected zone pairs. If O-D pairs have minimum-cost routes with 0. the program will explore routes with up to 2. for O-D pairs that have minimum-cost routes with 5 transfers. Finally. 1. 3. 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. or 2 transfers. Thus. Use separate FARESYSTEM statements to define multiple fare systems in public transport network. FARESYSTEM Defines fare systems that the program uses to calculate trip fares. or 4 transfers (the MINXOD+EXTRAXFERS2 constraint applies). If O-D pairs have minimum-cost routes with 3 or 4 transfers. the program explores 5 transfers (the MAXFERS constraint applies). the program explores routes with up to 4 transfers (the EXTRAXFERS1 constraint applies). 1. loading.1. IBOARDFARE=1. FAREMATRIX=FMI. FAREZONES=NI.FAREZONE 664 Cube Voyager Reference Guide . STRUCTURE=FROMTO.12 Public Transport Program Control statements You input the FARESYSTEM statements to the Public Transport program with the FILEI FAREI file. UNITFARE=0.83 Example 2: Zone based “FROMTO” fare system with no FAREFROMFS FARESYSTEM NUMBER=8. The program uses fare systems for the evaluation. The program does not use fares in enumeration. NAME=DISTANCE. SAME=SEPARATE. The program allocates fare systems to lines. Example 1: Distance with IBOARDFARE + UNITFARE + SAME=SEPARATE FARESYSTEM NUMBER=4. When modeling fares. or directly with the LINE control statement.35. LONGNAME="WITH FROM-TO FARES". STRUCTURE=DISTANCE. travelers incur fares when using the lines. skimming. SAME=CUMULATIVE. either indirectly through transit modes and operators with FACTOR FARESYSTEM. 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. you must allocate all lines to fare systems. You can code a NULL fare system to run lines effectively free. NAME="FAREZONE-FROMTO". and loading-analyses processes. FAREFROMFS=10*0. LONGNAME="WITHOUT FAREFROMFS". and the column the highest fare zone traversed. 30 The costs of transferring from fare systems 1. FAREMATRIX is required for STRUCTURE=HILOW or STRUCTURE=FROMTO statements. 2. and the column the alighting fare zone traversed.Public Transport Program Control statements 12 FARESYSTEM keywords Keyword FAREFROMFS Subkeyword |RVn| 1 Description Optional. For STRUCTURE=FROMTO. You must code FAREFROMFS in monetary units. The program converts the fare. You can include boarding fares applicable at transfers in FAREFROMFS. Valid strings are standard matrix names of the type: FM. FAREMATRIX |S| Optional. For STRUCTURE=HILOW. the row of the matrix represents the boarding fare zone traversed. Name of the fare matrix for this fare system. and 30 monetary units. and 3 to fare system 3 are 45.#. the program converts to generalized cost with VALUEOFTIME. Fare incurred when transferring from fare systems defined by other FARESYSTEM control statements to this fare system. and cannot be used for any other types.# or FMI. negative fares) between select fare systems.#. 70. and incentives (that is. the row of the matrix represents the lowest fare zone traversed. into generalized cost with VALUEOFTIME.Name. You can also provide the cost of transferring between the same fare system. Must be input with FILEI FAREMATI. Cube Voyager Reference Guide 665 . respectively. 70. derived from FAREMATRIX. consider: FARESYSTEM NUMBER=3 FAREFROMFS=45. The default value is 0. For example. 2. LONGNAME="WITH FARE ZONES". List of X.4. STRUCTURE=COUNT. in monetary units.10.FAREZONE.and Y-coordinates that define the table used to compute fares for a trip’s “length” component (rather than boarding or transfer components). 4. FARETABLE=1-1.85.1.5. COUNT. 2. Separate each pair of coordinates with a comma. FAREZONES=NI. the curve runs parallel to the X-axis up to the first coded point and beyond the last. must always be greater than zero. If the measure of trip length is greater than the last coded value of X.10.75. 5. SAME=CUMULATIVE. The fare. the fare is the last coded fare.85. the fare is the first coded fare. if STRUCTURE is DISTANCE. 5-5.5. Separate each pair of X and Y values with a comma or hyphen. 3-2. the X-axis represents distance and the Y-axis represents fare. and either stay the same or increase with trip length. Other mechanisms available are UNITFARE and FAREMATRIX. 2-1.00. Thus. 3.75.12 Public Transport Program Control statements FARESYSTEM keywords (continued) Keyword FARETABLE Subkeyword |RKV32000| Description Optional. For example. You can use fare tables when STRUCTURE is DISTANCE. NAME="FAREZONE-COUNT". 666 Cube Voyager Reference Guide . the X-axis represents trip length and the Y-axis represents the fare.1. Y. 44. or ACCUMULATE.5 or FARETABLE=1. When STRUCTURE is DISTANCE.00. For example: FARESYSTEM NUMBER=11. the fare can never decrease. In the coordinates. if the measure of trip length is less than the first coded value of X. 2. consider: FARESYSTEM NUMBER=2 LONGNAME="ALL" NAME="ALL" STRUCTURE="DISTANCE". X values must range from 1 to the number of fare zones and increase monotonically. When STRUCTURE is ACCUMULATE. Flag that specifies interpolation between coded points in the fare table.5. The fare for each zone must be greater than zero. 10. FARETABLE INTERPOLATE |?| Optional.15. the program assume the curve is a step function.0. However.20 for the 12-km trip.0.60 for both the 5-km trip and the 9-km trip. The program converts the fare derived from FARETABLE into generalized cost with VALUEOFTIME.50.0.50 INTERPOLATE=T The fare would be 0. 4.32 for a 12-km trip. For example. X values must range from 1 to the number of fare zones and increase monotonically. 1. Cube Voyager Reference Guide 667 . The fare.Public Transport Program Control statements 12 FARESYSTEM keywords (continued) Keyword FARETABLE (continued) Subkeyword Description When STRUCTURE is COUNT.10 for a 9-km trip.1. must always be greater than zero and increase with trip length.60. and 1. FARETABLE=2. Default value is F. if INTERPOLATE was F.SAME=SEPARATE.70 for a 5-km trip. and 1. the fare would be 0. If STRUCTURE is COUNT or ACCUMULATE. Y.1. There are two possible values: • • T — Linear interpolation between coded points F — Step function. INTERPOLATE only applies if STRUCTURE is DISTANCE. The program uses the fare system of the line on which the traveler completes the first leg. NOTE: Must be first keyword in FARESYSTEM control statement. LONGNAME NAME NUMBER |S| |S| |I| Optional. A transit leg might take a part or the entire length of a line.Name. Optional. Fare zones may represent groups of nodes or single nodes. If STRUCTURE is COUNT. 668 Cube Voyager Reference Guide . You must code IBOARDFARE in monetary units. or ACCUMULATE. Fare incurred upon boarding the first transit leg of a trip. FROMTO. Second unique string identifier for a userdefined fare system. Valid values range from 1 to 1999. Unique string identifier for a user-defined fare system. or ACCUMULATE. The technique for grouping nodes into fare zones depends on the fare zone system used. Required if STRUCTURE is HILOW.12 Public Transport Program Control statements FARESYSTEM keywords (continued) Keyword FAREZONES Subkeyword |S| Description Name of node variable in the input network file that contains the node’s fare zone number. you must use an annular grouping. If STRUCTURE is HILOW. FROMTO. IBOARDFARE |R| Optional. Valid strings are standard names for node variables of the type: NI. Unique numeric identifier for a user-defined fare system. COUNT. The default value is 0. The program converts the fare into generalized cost with VALUEOFTIME. you use sequential grouping. lines with such systems give free rides. DISTANCE — Trip length is in-vehicle distance. FREE — Defines a NULL fare system. where the fare is calculated at the end of the leg or trip from the total number of fare zones traversed. See “Fares” on page 818. 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). do not code any other FARESYSTEM keywords. 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. Possible values include: • FLAT — Trip length is not relevant for this fare structure. Cube Voyager Reference Guide 669 . ACCUMULATE — Trip length is the number of fare zones crossed. String that indicates how the program calculates the fare for consecutive legs of a trip with the same fare system. FROMTO — Trip length is an attribute of the boarding and alighting fare zones. STRUCTURE SAME |S| Optional. This differs from COUNT. Each fare zone has an associated fare which is accumulated as the zone is traversed. measured in user-specified units (such as miles or kilometers).Public Transport Program Control statements 12 FARESYSTEM keywords (continued) Keyword STRUCTURE Subkeyword |S| Description Measure unit for trip length. For this value. Calculate fare from IBOARDFARE and FAREFROMFS. used to compute fares. • • • • • • Data requirements of fare systems vary with STRUCTURE. Use with caution. For example LINEI can have up to 32 files. Code in monetary units. n is number of fare systems FILEI NOTE: See “FILEI” on page 44 for general information about FILEI and for important limitations when using Application Manager. 670 Cube Voyager Reference Guide . Due to a restriction on the total number of files. Default value is 0. All FILEI keywords are “trigger” keywords and need not be preceded by the control statement name. For example. Specifies files that may be input to the Public Transport program. 1. the trip cost is UNITFARE * trip distance + boarding and transfer fares. NOTE: The Public Transport program allows certain types of files to have multiple files. Cost per unit of the measure defined in STRUCTURE.12 Public Transport Program Control statements FARESYSTEM keywords (continued) Keyword UNITFARE Subkeyword |R| Description Optional. The program converts to generalized cost with VALUEOFTIME. fewer files than permitted for a particular file type may be active in Application Manager. if STRUCTURE is DISTANCE. Example FACTORI for USERCLASSES=1. corresponding to the classes defined by PARAMETERS USERCLASSES statement.FAC. [#]. You may input up to ten input factor files. • Default value is N. Flag that indicates to validate fare data in the factor file. loading. User class 3 and 4 use the same factors. the program assumes it to be 1. FACTORI is required for the route-enumeration. and loading-analyses processes. You must code explicitly for each user class. The output network file may not be suitable for use with fares in subsequent runs of the Public Transport program. FACTORI[4]=FACTSUC3.Public Transport Program Control statements 12 FILEI keywords Keyword FACTORI Subkeyword |FKVu| 1 Description Optional. one per user class. do not specify FACTORI because the network contains FACTOR data. if you input a Public Transport network with NETI. • • Y — List the lines file as input N — Do not list the lines file as input Default value is N.FAC. for each. though you can assign the same file to two or more classes. Cube Voyager Reference Guide 671 . Specifies the names of the input factor files. N — Validate fare-related data in the factor file. Maximum number of errors allowed in the factor file before the program stops processing factors. Possible values: • Y — Omit validation of fare-related data in the factor file. Specify an index. FACTORI[3]=FACTSUC3. FACTORI OMITFARES |?| Optional. routeevaluation. Flag that indicates whether to list the lines file as input.3-4.FAC See “FACTORS” on page 644 for a list of keywords you can use. Default value is 0. FACTORI LIST |?| Optional. FACTORI MAXERRS |I| Optional. FILEI FACTORI[1]= FACTSUC1. If there is no index. However. Input files may contain either standard Cube Voyager binary matrices or records containing matrix data in the pattern: M. If you do not specify an index. Flag that indicates whether the list the fare systems as input. I J f[j] Fare for line j. Append an index to each..x. 672 Cube Voyager Reference Guide . Name of input file defining the fare systems.. Row number. Name of the input file that contains one or more matrices used for computing fares. depending upon how you specify FARESYSTEM FAREMATRIX. the program assumes the index is 1.x. J.y. followed by the fare for line j+1 and so on.12 Public Transport Program Control statements FILEI keywords (continued) Keyword FAREI Subkeyword |FK| Description Optional. If FAREMATRIX=FMI. then M must match name.. f[j].f[j+n] where: M Either a name or number. If FAREMATRIX=FMI. The file contains one or more FARESYSTEM control statements. Possible values: • • FAREMATI |FKV| Y — Lists the fare systems as input N — Do not list the fare systems as input Optional. FAREI LIST |?| Optional. y (x specifies the FAREMATI index.I. There may be multiple records for a line. Required if the program will consider fares during routeevaluation and skimming processes.f[j+1]. There must be a row for each fare zone that will use the matrix. See “FARESYSTEM” on page 663 for a list of keywords you can use. You may input up to 99 files. Column number for the 1st f[j] that follows.name. Delimit files with either commas or white space. then M must be the table number.). if you input Public Transport network with NETI. Possible values: • Y — Downgrade data errors found when reading lines data to data warnings. you need not specify an index. The program will be able to read the entire input file without termination due to data errors. and loading-analyses processes. described with the LINE control statement). Default value is 0. Name of input file containing lines. LINEI LIST |?| Optional. if inputting only one file. Append an index to each. LINEI is required for the route-enumeration. Therefore. 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. Indexes need not be monotonic or sequential. do not specify LINEI should not be specified because the network contains line data.Public Transport Program Control statements 12 FILEI keywords (continued) Keyword LINEI Subkeyword |FKVf|2 Description Optional. Without an index. To input the lines from a Cube geodatabase stored in an MDB file. Cube Voyager Reference Guide 673 . You must convert any lines files in TRIPS format to Cube Voyager format. See “LINE” on page 720 for a list of keywords you can use. routeevaluation. The file can contain lines in Cube Voyager format (that is. or in TP+ format. the program stops processing lines. Maximum number of errors permitted in lines files. Optional. Flag that indicates whether to list the lines file as input. specify the file name followed by a backslash and the name of the geodatabase feature class. You may input up to 32 lines files. When errors exceed this number. • The default value is the value of PARAMETERS SKIPBADLINES. Flag that indicates whether to treat data errors as warning. the program assigns an index of 1. loading. LINEI SKIPBADLINES |?| Optional. However. N — Treat data errors as errors. Valid index numbers range from 1 to 32. Because the run can compute trips. Therefore. For example: FILEI MATI[1]= TRIPSUC1.MAT.MAT This statement names the input matrix files. and then manipulate. MATI[4]=TRIPSUC3. the program assumes the index is 1. If you do not specify an index. report.12 Public Transport Program Control statements FILEI keywords (continued) Keyword LOOKUPI Subkeyword |FKV999| Description Optional. You can define up to 10 matrix files to input. you need not input trip matrix files. Index values can range from 1 to 10. Equivalent to the FILE keyword of the LOOKUP control statement.MAT. Name of file containing records for a lookup function implemented with the LOOKUP control statement. The Public Transport program only requires trip matrix files for the loading process. You must index LOOKUPI. and output the data with MATO. MATI |FKVf|2 Optional. MATI[3]=TRIPSUC3. the PARAMETERS TRIPSIJ statement specifies which demand matrix the Public Transport program loads for each user class. 674 Cube Voyager Reference Guide . Name of an input matrix file. you can use the MATI keyword to input any type of matrix data into working matrices. NTLEGI and LINEI files unless you invoke the Public Transport Network Development function. input with FACTORI Nontransit legs. the public transport network may also contain nontransit and transit loads. generated with the GENERATE control statement. input with NTLEGI. Networks produced by the Network program contain just the basic public transport infrastructure. They contain. in addition to the basic infrastructure. Files can be produced by the Network program or a previous run of the Public Transport program. zones. you need not provide SYSTEMI. you must supply all other components. Thus. Files can be a Cube binary network file or a Cube geodatabase network store in an MDB file. In this case. all the components that make a public transport network: • • • • System data input with SYSTEMI Line data. stops. and links. nodes. enter the filename followed by a backslash and the name of the Cube geodatabase network. Cube Voyager Reference Guide 675 . If specifying a Cube geodatabase network. or both When produced by a Public Transport run in which trips were loaded. FACTORI. Networks produced by the Public Transport program are complete public transport networks. if NETI specifies an input network produced by the Public Transport program. the program only takes the basic network infrastructure from the NETI file.Public Transport Program Control statements 12 FILEI keywords (continued) Keyword NETI Subkeyword |FK| Description Name of the input network file. input with LINEI Factor data. consider: FILEI ROUTEI[1]= ROUTESUC1. To input the nontransit legs from a Cube geodatabase stored in an MDB file.RTE This statement defines input route files for user classes 1. and loading-analyses processes. 3. the program assumes the index is 1. The PARAMETERS USERCLASSES statement defines user classes. For example. Append each keyword with the index of the user class. the program bypasses the route-enumeration process for that user class. such as NTLEGI[5]. See “NT” on page 734 for a list of keywords you can use. ROUTEI I |IV1000| Optional. and 4. the program assumes the index is 1. ROUTEI[4]=ROUTESUC4. The GENERATE READNTLEGI statement defines valid indexes that the program will process. If you do not specify an index. You can define up to 10 route files to input. Valid values range from 1 to the network’s highest zone number. If you do not specify an index. Index values can range from 1 to 10 (the number of user classes). loading. one per user class.RTE.RTE. ROUTEI[3]=ROUTESUC3. ROUTEI |FKVu|1 Optional. specify the file name followed by a backslash and the name of the geodatabase feature class. Indexes need not be monotonic or sequential.12 Public Transport Program Control statements FILEI keywords (continued) Keyword NTLEGI Subkeyword |FKVf|2 Description Optional. Explicitly specify a unique file for each user class. Append each keyword with an index. Name of the input route files. When you define an input route file for a user class. Name of input files containing nontransit legs. Specify origin zones with single numbers or pairs of numbers separated by a dash. You can define input route files for some user classes and generate them for other user classes. You can define up to 32 input files. Use commas to delimit each number or pair. List of origin zones for the route-evaluation. Index values can range from 1 to 32. skimming. 676 Cube Voyager Reference Guide . each user class has its own route file. List of destination zones for reporting evaluated routes. Use commas to delimit each number or pair. skimming. Valid values range from 1 to the network’s highest zone number. Use commas to delimit each number or pair. Specify destination zones with single numbers or pairs of numbers separated by a dash. The program writes the report to file specified with REPORTO. and loading-analyses processes. Specify destination zones with single numbers or pairs of numbers separated by a dash. Specify origin zones with single numbers or pairs of numbers separated by a dash.Public Transport Program Control statements 12 FILEI keywords (continued) Keyword ROUTEI Subkeyword J |IV1000| Description Optional. List of origin zones for reporting evaluated routes. List of destination zones for the routeevaluation. ROUTEI REPORTJ |IV1000| Optional. Valid values range from 1 to the network’s highest zone number. Valid values range from 1 to the network’s highest zone number. ROUTEI REPORTI |IV1000| Optional. loading. See “Evaluated routes” on page 762 for an example of this report. Cube Voyager Reference Guide 677 . Use commas to delimit each number or pair. List of origin zones for printing evaluated routes. and SELECTBYMAT subkeywords together. the turns-count format is not supported. Normally. For example. loading. using the tabular-format route report. you specify the trip matrix being loaded. MI. and loading-analyses processes for Is and Js that have trips from and to them. 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. skimming. Use commas to delimit each number or pair. List of destination zones for printing evaluated routes using the tabular-format route report. The file contains the definition of the screenlines (in terms of constituent links).NAME.12 Public Transport Program Control statements FILEI keywords (continued) Keyword ROUTEI Subkeyword SELECTBYMAT |S| Description Optional. ROUTEI TRACEI |IV1000| Optional. ROUTEI TRACEJ |IV1000| Optional. Routes are reported in the file specified by REPORTO. 678 Cube Voyager Reference Guide . Matrix used to produce I and J selections such that the program only performs the evaluation. You can create the file with Cube or a text-file editor. Use commas to delimit each number or pair. Valid values range from 1 to the network’s highest zone number. The program merges them to produce the final I and J lists.x. Specify origin zones with single numbers or pairs of numbers separated by a dash. Specify destination zones with single numbers or pairs of numbers separated by a dash. J. The file must use the “link-count” format used by Cube Analyst’s Matrix Estimation program. Valid values range from 1 to the network’s highest zone number. Name of a screenline file that produces intercept data for Public Transport matrix estimation. SCREENLINEI |FK| Optional. along with link count and confidence-interval data. and WAITCRVDEF control statements. 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. and wait curves. operators. This file contains data for modes. Cube Voyager Reference Guide 679 .Public Transport Program Control statements 12 FILEI keywords (continued) Keyword SYSTEMI Subkeyword |FK| Description Optional. Name of the input file containing public transport system data. as described in the MODE. SYSTEMI LIST |?| Optional. OPERATOR. you support an incremental approach for forecast years by controlling a line’s travel times with RUNTIME RT or NNTIME. Separate the data fields in a record with white space (either a space or a comma). Most model runs that incorporate junction delays require one turn-penalty input file. You can enter one set per record. 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. Turn penalty movement records cannot contain function specifications. one with base-year delays and one with forecast-year delays. you select which sets the model uses.12 Public Transport Program Control statements FILEI keywords (continued) Keyword TURNPENI Subkeyword |FKV2| Description Optional. For such runs. for forecast years. they ignore banned turns and only use the junction delay data. Set is a number in the range 1-8. Usually written by the Highway program. NOTE: As transit vehicles follow user-defined routes (which can differ from general traffic). 680 Cube Voyager Reference Guide . measured in minutes. model runs require two turn-penalty input files. Names of one or two turn-penalty files. However. these files contain records detailing turn penalties or prohibitions. Penalty is either -1 to indicate a prohibited turn in the Highway model or the value of the junction delay. Possible values: • T — Program prints a report that lists turn-penalty values used. TURNPENI LIST |?| Optional. Flag indicating whether to generate a report of turn-penalty values. F — Program does not print a report that lists turnpenalty values used. and NNTIME values. • Default value is F. Possible values: • T — File contains base-year junction delays. the program reads two turn-penalty files. which contains forecast-year turn penalties. which scale transit-line travel times to RUNTIME. RT. F — File does not contain base-year junction delays. When the MAXLINKDELAY subkeyword limits values. the report lists the value read from the file and value the model run used. Cube Voyager Reference Guide 681 . When applying the incremental approach to junction delays. The program uses this file to obtain scaling values. and to F for the other file. Flag indicating whether turn penalty file contains base-year junction delays. Set BASEDATA to T for the file containing the base-year junction delays.Public Transport Program Control statements 12 FILEI keywords (continued) Keyword TURNPENI Subkeyword BASEDATA |?| Description Optional. • Default value is F. Optional. such as bus-only lanes.VarName or lw. By default. Default value is 0. input turn-penalty values apply to all transit modes. Valid values range from 0 to 999. setting its value to zero would eliminate junction delays for that link. Therefore. 682 Cube Voyager Reference Guide .12 Public Transport Program Control statements FILEI keywords (continued) Keyword TURNPENI Subkeyword MAXLINKDELAY |SVn|3 Description Optional. alternatively you can have the program read the variable from the input network by setting MAXLINKDELAY=MaxDelay. that reduce delays to public transit vehicles at turns. Integer that specifies the error handling when the input network does not contain a link specified in the turn penalty file. Name of a link variable that contains the maximum delay values (measured in minutes) permitted on each link in the network. 999) for links without bus-only lanes or other delayreduction measures. The link variable must specify large values (for example. Use this keyword to limit the junction delay a transit vehicle experiences at a particular turn or junction. You can reference the variable as li. List of transit modes that do not have turning penalties. The Highway program assumes that all turning vehicles are equally delayed. TURNPENI MISSINGLINK |I| Optional. 2 — Program generates a fatal error message. 1 — Program prints a warning message. use this keyword when modeling provisions. Default value is 0.VarName. Possible values: • • • TURNPENI NOTMODES |I| 0 — Program ignores such errors. Set numbers from the turn-penalty file that the program includes in the run. FILEI u represents user class 2. list=t NETI = inetwork. n represents name of link variable Example //Some files that may be input to PT FILEI FACTORI = factor. list=t LINEI[1] = lines. the program uses the record with the highest set number. the program selects movements from all sets.ntl Cube Voyager Reference Guide 683 . When you specify the default value.fac. When a movement has multiple records. If a turn has several records.net NTLEGI = geno. the program selects those matching the SETS list. f represents file number 3. the program discards any non-matching set numbers. Valid values range from 0 to 8. 1.lin. The program uses the record with the highest set number among those selected. The default value is 0.Public Transport Program Control statements 12 FILEI keywords (continued) Keyword TURNPENI Subkeyword SETS |I| Description Optional. Runs that create matrix estimation intercept data should either read a single screenline file. Append each keyword with the index of the user class.12 Public Transport Program Control statements FILEO Specifies files that the Public Transport program outputs. This file lists all the lines in the public transport system. the program assumes the index is 1. Must be the same geodatabase specified in NETI or BASEGDBNETWORK. fewer files than permitted for a particular file type may be active in Application Manager at any point. Therefore. in the LINE control statement format. or write one or more screenline files (one for each user class). NOTE: The Public Transport program allows certain types of files to have multiple files. Name of the output lines file. For example PRINTO can have up to 99 files. The PARAMETERS USERCLASSES statement defines user classes. specify the file name followed by a backslash and the name of the geodatabase feature class. 684 Cube Voyager Reference Guide . one per user class. which provides link and count information for the screenline. If you do not specify an index. LINEO |FK| Optional. Application Manager restricts the total number of files. All FILEO keywords are “trigger” keywords and need not be preceded by the control statement name. To output the lines to a Cube geodatabase stored in an MDB file. However. You can define up to 10 intercept files to output. FILEO keywords Keyword INTERCEPTO Subkeyword |FKV10| Description Optional. Name of an output intercept file. Cube Analyst uses this file along with its associated screenline file when estimating matrices. which contain link and count information obtained from the input network. This file details which origin-destination pairs have routes that cross the screenlines. O — Program lists lines from the output network. you reference the network used as input in the step that produced the lines. and line and link loads). but the loads can vary depending upon the options selected.Public Transport Program Control statements 12 FILEO keywords (continued) Keyword LINEO Subkeyword NET |S| Description Optional. Flag that indicates whether to include loading results (that is. Name of the geodatabase base-highway network associated with the output lines file. LINEO VOL |?| Optional. N — Do not include loading results with lines data. Default value is Y. This network must be consistent with the lines data. If NETI specifies a geodatabase network. Input and output networks have identical line attributes and node lists. Typically. Cube Voyager uses that network as the base-highway network. Possible values: • • I — Program lists lines in the input network. you need not specify a value. boardings. Specifies whether the output lines file contains lines from the output network or the input network. LINEO BASEGDBNETWORK |S| Optional. alightings. Cube Voyager Reference Guide 685 . The default value is O. Possible values: • • Y — Include loading results with lines data. 12 Public Transport Program Control statements FILEO keywords (continued) Keyword LINKO Subkeyword |FKV4| Description Optional. 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. specify the file name followed by a backslash and the name of the geodatabase feature class. This file contains all nontransit legs and transit links. Name of output links file. To output the links to a Cube geodatabase stored in an MDB file. You can specify up to four files. Each file might contain different outputs from a single run of the program. the output contains one record for each line. You can specify a DBF file or an MDB file. The standard output contains data on the following link attributes: • • • • • • • A-node B-node Mode number Name of line traversing link (for nontransit legs. 686 Cube Voyager Reference Guide . Flag indicating whether lines data is included in the output links 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). N — Program writes data not separated by user class • Default value is N. summed by user class. Optional. and so forth. Possible values: • • Y — Program writes the flow-metered volumes from the crowding run. Default value is Y. LINKO FMVOLS |?| Optional. Flag indicating whether outputs from a crowding run contain demand volumes or flowmetered volumes. you can obtain true nontransit loads for walk links. N — Does not convert records of nontransit legs. and the attributes used in the run for each user class. N — Do not include line data. like _1 and _2. User class–specific fields have names with suffixes.Public Transport Program Control statements 12 FILEO keywords (continued) Keyword LINKO Subkeyword BYCLASS |?| Description Optional. N — Program writes the loaded volumes (represents the demand volumes for crowding runs). • Default value is N. LINKO LINES |?| Optional. Possible choices: • • LINKO NTBYLINK |?| Y — Include line per link data. Cube Voyager Reference Guide 687 . Possible values: • Y — Program writes the run totals. Flag indicating whether outputs are summed by user class in the links file. Default value is N. Flag indicating treatment of nontransit legs in output file. From the output. Possible choices: • Y — Output file contains one record for each highway link. the file summarizes the data. 688 Cube Voyager Reference Guide . you can easily merge data into the highway network for graphic displays. LINKO ONELINKREC |?| Optional. Do not use ONELINKREC when ONOFFS is set to Y. combining headways and summing volumes. Default value is N. 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.12 Public Transport Program Control statements FILEO keywords (continued) Keyword LINKO Subkeyword NTLEGS |?| Description Optional. you use this keyword when NTBYLINK is set to Y. Typically. Flag indicating whether to include nontransit legs in output file. When multiple transit lines traverse a single link. • N — Output file contains one record for each transit line traversing a highway link. Flag that indicates whether the program combines transit data per highway link. Possible values: • • Y — Include nontransit legs in output file N — Do not include nontransit legs in output file Default value is Y. Multiple transit lines traversing the same highway link result in multiple records for a highway link. program includes boardings and alightings at each stop in output file. Do not use ONOFFS when ONELINKREC is set to Y. In the reverse direction of travel. 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. Cube Voyager Reference Guide 689 . These are only nonzero values for lines that have ONEWAY set to F. When set to Y. * Only available if the public transport network contains loads The data records are in line-order (and stop-order within line).Public Transport Program Control statements 12 FILEO keywords (continued) Keyword LINKO Subkeyword ONOFFS |?| Description Optional. 0 otherwise. Output may be produced for run totals and individual user classes in a run (see “BYCLASS” on page 687). and offs in the reverse direction of travel. The file format differs from the standard output. ons. STOPB — 1 if the line stops at the B-node. travelers reach the B-node before the Anode. 0 otherwise VOL* — Transit load using this line on this link. Default value is N. 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. Flag indicating whether to include boardings and alightings. If you do not specify an index. but other types of matrices. N — Omit volume fields from output files. 3. The Public Transport program produces skim and select link-analysis matrices. LINKO VOLFIELDS |?| Optional. 690 Cube Voyager Reference Guide . Explicitly specify a unique file for each user class. • MATO |FKV10| Default value is Y. Flag indicating whether to include volume fields in output file. Optional.MAT This statement generates output matrix files for user classes 1. The PARAMETERS USERCLASSES statement defines user classes. one per user class.MAT. then fields contain zero values. Name of an output matrix file. For example. the program assumes the index is 1. either generated or input with MATI. and 4. MATI[4]=SKIMUC4. Append each keyword with the index of the user class. If there are no loadings. Flag indicating whether to omit links with zero loads from output file. consider: FILEO MATO[1]= SKIMUC1. Possible values: • Y — Include volume fields associated with total loadings. 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. MATI[3]=SKIMUC3.12 Public Transport Program Control statements FILEO keywords (continued) Keyword LINKO Subkeyword SKIP0 |?| Description Optional. You can define up to 10 matrix files to output.MAT. may be manipulated and output with MATO. MATO NAME |SV255| Optional.Public Transport Program Control statements 12 FILEO keywords (continued) Keyword MATO Subkeyword DEC |SV*255| Description Optional. • • Default value is 2. You may specify the same working matrix for more than one index. Cube Voyager Reference Guide 691 . because the statement defines no working matrix for these index values. Matrices 11 through 18 will be dummy matrices. consider: MO=1-5. spaces. Valid matrix names contain only alphanumeric characters. If you do not define a value for an index. Valid values: • 0-9 — Convert output matrix cells to integers. D — Store cells in double-precision floatingpoint format. Output matrices do not require names. Cube Voyager programs reading the file can reference the matrices by name and/or number. the program writes 20 matrices. String that specifies the numeric format of the working matrices written to the output matrix file. The program numbers output matrices sequentially beginning with 1. Specify a separate DEC for each MO. but including names helps document the file. MO[19]=31 Given this statement. MO[20]=1.11-15. the program outputs a dummy matrix. Name of matrix (for TP+ and Cube Voyager matrices). You may index MO. For example. See “Considerations on numeric formats” on page 704 MATO MO |IVP255| Lists the working matrices (MWs) included in the output matrix file. S — Store cells in single-precision floatingpoint format. The highest implicit or explicit index determines the number of matrices included in the file. and underscores (_). preserving indicated number of decimal places. or both If produced by a run of the Public Transport program in which trips were loaded. input with SYSTEMI Line data. unless you invoke the Public Transport networkdevelopment process. and links. String specifying the format of the output matrix file.12 Public Transport Program Control statements FILEO keywords (continued) Keyword MATO Subkeyword TYPE or FORMAT |S| Description Optional. 692 Cube Voyager Reference Guide . generated with the GENERATE control statement. input with LINEI Factor data. The Public Transport program outputs a complete public transport network containing the following components: • • • • • Basic network infrastructure of zones. You can input this network to the Public Transport program with NETI. 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. nodes. in which case the file does not require SYSTEMI. input with FACTORI Nontransit legs. NTLEGI and LINEI files. input with NTLEGI. Name of the output network file. the public transport network may also contain nontransit and transit loads. produced by the Network program System data. FACTORI. String that specifies precision for storing transit and nontransit loads in the network. you reference the network used as input in the step that produced the legs. Default value is 2. Typically. you need not specify a value. Name of the geodatabase base-highway network associated with the nontransit legs file. Single-precision values take up four bytes and retain precision up to 6 or 7 decimal places. Cube Voyager uses that network as the base-highway network. Name of output nontransit legs file. specify the file name followed by a backslash and the name of the geodatabase feature class. Double-precision values require eight bytes and preserve full precision. If NETI specifies a geodatabase network. NTLEGO |FK| Optional. To output the nontransit legs to a Cube geodatabase stored in an MDB file. Integer values require the least space and preserve precision to the number of decimal places specified by DEC. NTLEGO BASEGDBNETWORK |S| Optional. Cube Voyager Reference Guide 693 . This network must be consistent with the nontransit legs data. Must be the same geodatabase specified in NETI or BASEGDBNETWORK. This file contains all the nontransit legs in the public transport system. 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. in the nontransit controlstatement format. Possible values: • • • 0-9 — Convert loads to integers.Public Transport Program Control statements 12 FILEO keywords (continued) Keyword NETO Subkeyword DEC |S| Description Optional. NTLEGO VOL |?| Optional. Possible values: • Y — Output any nodes between the start and end nodes of nontransit legs. Optional. to a file. Default value is O. • Default value is Y. Default value is Y. or to both the standard output and a file. Possible values: • • O — Include nontransit legs from the output network in the nontransit legs output file. depending on the options selected. All diagnostics from these processes are output to the standard Public Transport–program print file. See XN under “NT” on page 734. REPORTO |FK| Name of the file to which the program writes reports from the route-enumeration and routeevaluation processes. 694 Cube Voyager Reference Guide . Flag indicating whether to include loads with nontransit legs. N — Do not output nodes between the start and end nodes of nontransit legs. but the loads might vary. which you have defined in a PRINT FILE control statement. NET Both files contain identical attributes for nontransit legs. PRINTO |FK| Optional. String indicating whether to include nontransit legs from the output network or input network. Use the PRINT control statement to format data items and write them as a single line to the standard printed output. Possible values: • • NTLEGO XN |?| Y — Write loads with nontransit legs. N — Do not write loads with nontransit legs. I — Include nontransit legs from the input network in the nontransit legs output file. Name of an output file. Flag indicating whether to output nodes.12 Public Transport Program Control statements FILEO keywords (continued) Keyword NTLEGO Subkeyword Description |S| Optional. Valid values range from 1 to the network’s highest zone number. Delimit each number or pair with a comma. Explicitly specify a unique file for each user class. List of origin zones for which the program enumerates routes and saves. the program assumes the index is 1. Cube Voyager Reference Guide 695 . ROUTEO J |IV1000| Optional. You can define up to 10 output files. If you do not specify an index. You can input previously created enumerated-route files for some user classes and build files for other user classes in the same run. one per user class. 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. By default. the program enumerates and saves routes originating from all zones.Public Transport Program Control statements 12 FILEO keywords (continued) Keyword ROUTEO Subkeyword |FKVu|1 Description Optional. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. the program enumerates and saves routes bound for all zones. Append each keyword with the index of the user class. ROUTEO I |IV1000| Optional. By default. Name of output file containing enumerated routes. The statement ROUTEO[x] invokes the routeenumeration process for user class x. The PARAMETERS USERCLASSES statement defines user classes. Valid values range from 1 to the network’s highest zone number. Delimit each number or pair with a comma. or loadinganalyses processes. ROUTEO SELECTBYMAT |S| Optional. MI. Valid values range from 1 to the network’s highest zone number. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range.NAME. The program only includes route evaluations completed by the skimming.x. ROUTEO REPORTJ |IV1000| Optional. loading. skimming. and loadinganalyses processes. loading. Valid values range from 1 to the network’s highest zone number. 696 Cube Voyager Reference Guide . The program reports routes in the file specified in REPORTO.12 Public Transport Program Control statements FILEO keywords (continued) Keyword ROUTEO Subkeyword REPORTI |IV1000| Description Optional. specify the trip matrix being loaded. Normally. List of origin zones for which the program reports enumerated and evaluated routes. See “Enumerated routes” on page 761 and “Evaluated routes” on page 762 for examples of these reports. 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. Delimit each number or pair with a comma. 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. For example. For the evaluation. Delimit each number or pair with a comma. 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. List of origin zones for which the program prints evaluated routes using the tabular-format route report. Delimit each number or pair with a comma. 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. List of destination zones for which the program prints evaluated routes using the tabularformat route report. ROUTEO TRACEJ |IV1000| Optional. See “Evaluated routes” on page 762 for examples of these reports. The program reports routes in the file specified in REPORTO. Valid values range from 1 to the network’s highest zone number.Public Transport Program Control statements 12 FILEO keywords (continued) Keyword ROUTEO Subkeyword TRACEI |IV1000| Description Optional. Valid values range from 1 to the network’s highest zone number. Cube Voyager Reference Guide 697 . Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Explicitly specify a unique file for each user class.12 Public Transport Program Control statements FILEO keywords (continued) Keyword SCREENLINEO Subkeyword |FKV10| Description Optional. The PARAMETERS USERCLASSES statement defines user classes.varname. The confidence level is expressed as an integer value. You can define up to 10 output files. You must define either CONFVAR or DEFCONF. Append each keyword with the index of the user class. one per user class. Name of the input network’s link variable that contains confidence-level data. SCREENLINEO SCREENLINEO COUNTVAR DEFCONF |S| |I| Name of the input network’s link variable that contains the link-count data. If you do not specify an index. You can reference variables. you can use a subkeyword to read a variable from the input network. You pass this file with an associated intercept file to a Cube Analyst run to perform matrix estimation tasks. Cube Analyst will read that file instead. Name of the screenline file the program writes from the network data. ranging from 1 to 10000. such as CONFAR=varname. Optional. Confidence level that applies to all output links. SCREENLINEO CONFVAR |S| Optional.varname or lw. the program assumes the index is 1. use the CONFVAR subkeyword. The program ignores this keyword if you specify the SCREENLINEI keyword.000. If confidence levels vary from link to link (or screenline to screenline). The file contains screenline definitions and count and confidence-level data. Use the DEFCONF keyword when a single confidence-level value applies to all links. Use subkeywords to specify the source or value of the data fields that the program writes to the file. such as li. 698 Cube Voyager Reference Guide . Alternative. Valid values range from 1 to 10. transit and nontransit) N — Program restricts link use to only transit modes.Public Transport Program Control statements 12 FILEO keywords (continued) Keyword SCREENLINEO Subkeyword MEUSESNT |?| Description Optional. Cube Voyager Reference Guide 699 . if specified. considering link use of all modes (that is. Possible values: • Y — Program creates intercept data. and a zero value for all other links. This variable has a value ranging from 1 to 9999 when a link forms part of a screenline. • Default value is taken from PARAMETERS MEUSESNT. SCREENLINEO SCREENVAR |S| Name of the input network’s link variable that contains the screenline number. otherwise Y. Flag indicating whether link use is restricted to transit modes. 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. The two sets of data fields are mutually exclusive. 700 Cube Voyager Reference Guide .12 Public Transport Program Control statements FILEO keywords (continued) Keyword STOP2STOPO Subkeyword |FKV4| Description Optional. Use subkeywords to select the types of stop-to-stop movements captured. 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. Name of file where the program saves the results of the stop-to-stop analyses. you can output a number of different analyses from a single run of the program. The data saved to the file can relate to a selection of stop-nodes or groups of stop-nodes. You can specify up to four output files. Therefore. but not both. File is either DBF format or MDB format. See “More on stop-to-stop analysis” on page 705. • All movement types other than ADJACENT can contain one or more transit legs.7. STOP2STOPO GROUPEDMODES |IV999| Optional. Must specify MODES subkeyword. ADJACENT — Movements for each leg of a trip. ALLONOFFS — Movements for all on-off combinations. See “More on stop-to-stop analysis” on page 705. Default value is FIRSTLAST. Cube Voyager Reference Guide 701 . Thus. subsequent numbers are the modes recoded. Possible types include: • • • • FIRSTLAST — Movements from a trip’s first node to last node. consider: GROUPEDMODES = 3. ADJACENTBYMODE — Through movements from first node to last node on a particular mode. First number is the mode number assigned during recoding. FIRSTLASTBYMODE — Movements from first node to last node on a particular mode. any transit legs with modes listed in the second are subsequent positions are assigned to the mode listed first. (Relevant when transit movement type is ADJACENTBYMODE or FIRSTLASTBYMODE). 7. or 8 to mode 3.Public Transport Program Control statements 12 FILEO keywords (continued) Keyword STOP2STOPO Subkeyword ACCUMULATE |S| Description Optional. List of numbers the program uses to recode the modes on transit legs before completing stop-to-stop analysis on a route. For example.6. Valid values range from 1 to the network’s highest mode number. regardless of intervening modes. Must specify MODES subkeyword.8 The program recodes any transit legs using modes 6. Specifies types of transit movements included in the stop-to-stop analysis. If you do not code NODES. Delimit each number or pair with a comma. You define a node’s stop-group number on the input network’s node record in the variable specified in STOPGROUP.12 Public Transport Program Control statements FILEO keywords (continued) Keyword STOP2STOPO Subkeyword GROUPS |IV9999| Description List of stop-groups for which the program extracts stop-to-stop movements for the ACCUMULATE subkeyword. 702 Cube Voyager Reference Guide . Thus. Note that the program does not explicitly report nodes in the output file. Identify stop-groups by number. the program outputs stop-to-stop movements for the specified groups that will include only the specified nodes. Valid values range from 1 to the network’s highest stop-group. the program generates a fatal error. Stop-groups are either single stop-nodes or a collection of stop-nodes. the program includes all nodes belonging to the specified groups in the analysis. Flag indicating whether to list the contents of the DBF file to the printer file. If you code both GROUPS and NODES. STOP2STOPO LIST |?| Optional. such as platforms within a station or clusters of bus stops on either side of a road. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. NOTE: If you code neither NODES nor GROUPS. 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. you can exclude nodes from their groups. FILEO NETO = onetwork. Valid values range from 1 to the network’s highest node.15. Name of the node variable that contains the stop-group number. STOP2STOPO STOPGROUP |S| Optional. J=1. Default value is all modes.24 Cube Voyager Reference Guide 703 . 15. you must code STOPGROUP. used in GROUPS.9. Delimit each number or pair with a comma.net REPORTO = reports.15. STOP2STOPO NODES |IV9999| List of stop nodes for which the program extracts stop-to-stop movements for the ACCUMULATE subkeyword.24 REPORTJ=1.Public Transport Program Control statements 12 FILEO keywords (continued) Keyword STOP2STOPO Subkeyword MODES |IV999| Description Optional. with STOPGROUP=SGNAME.24. 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. For example. but cannot disaggregate those movements to the nodes in the group. I=1. If you code GROUPS. This subkeyword is required if GROUPS is not coded. REPORTI=1. 1. then the node variable NI. When using stop groups. the program reports on intragroup movements. List of modes for which the program accumulates stop-to-stop movements when ACCUMULATE is FIRSTLASTBYMODE or ADJACENTBYMODE. Valid values range from 1 to the network’s highest mode.24. u represents user class Example Some files that may be output by the Public Transport program.prn ROUTEO = enumroute. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range.rte.SGNAME stores the stop-group numbers. computers could process integers much faster than floating point numbers.DAT". 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 in most cases. only a few decimal places are required for each cell value. Single-precision floating point provides only six to seven digits of precision. writing double-precision numbers to the matrix files would generate very large files. 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. this is not necessarily true with newer computers.RTE" FILEO SCREENLINEO = "PT ANALYST EXAMPLE\PAPTR00B. The 704 Cube Voyager Reference Guide .12 Public Transport Program Control statements Example of SCREENLINEO & INTERCEPTO RUN PGM=PUBLIC TRANSPORT FILEO REPORTO = "PAPTR00B. Therefore. and to not lose precision or accuracy when computing. However.PRN" FILEO ROUTEO[1] = "PAPTR00B.NET" .ICP" FILEI NETI = "PAPTR00D. In the past. However. 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 Public Transport program stores matrix values with a special packing routine that tries to minimize the file’s space requirements. PT network output from PT program ENDRUN Considerations on numeric formats Traditionally planners have maintained most transportation planning matrices in integer format. SCREENVAR=SCRLNO COUNTVAR=PTCOUNT CONFVAR=PTCONF FILEO INTERCEPTO = "PAPTR00B. If DEC were S. the result is accurate to about seven digits. If converted to an integer while DEC is 0. Upon reading. you eliminate this detail from the analysis. that might not be precise enough for the programs that read it. You might be more interested in transfer to or from rail than in changes between the different rail modes. requiring two bytes to store. The S and D formats require more storage space.Public Transport Program Control statements 12 program uses the lowest level that converts to an integer with no loss of precision. requiring four bytes to store. consider a cell computed as 10/3. When the movement type is 4 or 5 (ACCUMULATE is FIRSTLASTBYMODE or ADJACENTBYMODE). a model might use two or more mode numbers for different types of rail travel. Cube Voyager Reference Guide 705 . you can group distinct modes of the route together. allowing them to appear as one mode for analysis and in subsequent data output. it would be stored as an 8-byte double-precision. the value would be stored as a 4-byte single-precision.33. another application will automatically restore the number to 3.. and if DEC were D.. By grouping the discrete rail modes together. the result is 3. and the cell would require only one byte to store—a significant reduction. The result is 3. the program skips the integer conversion attempt and stores all cells as either 8-byte double values or 4-byte single values. When changed to single precision. to sixteen digits. However. If a scaled cell value is too large to fit within a 32bit integer. For example. More on stop-to-stop analysis For stop-to-stop analysis. The program analyzes a transit route based on the values of other STOP2STOPO subkeywords. DEC defaults to 2. If DEC is D or S. Use the GROUPEDMODES subkeyword to recode modes prior to transit-route analysis. For example. the resulting integer is 333.. If not specified. the movement type affects the output records. the program writes output records that reflect the modes used in the route’s transit legs. and saves the appropriate records. the program stores the cell as a double-precision value.33333333. If DEC is 2 for that number. With this keyword. 1-4. 3-4. 3-10. 9-10 1-10 mode 1 5-6 mode 2 1-4 mode 1 5-6 mode 2 7-10 mode 1 ADJACENTBYMODE GENERATE Generates nontransit legs in the public transport network. The program keeps one leg for each Anode–B-node combination in the table—the leg with the lowest EXTRACTCOST. 5-6 on mode 2 4. 5-6. 1-6. 5-6. The program dynamically updates the table while processing GENERATE statements. 1-8. followed by the leg with the lowest distance (DIST ). You can generate. 7-8. 3-6. 7-8. 9-10 1-2. 5-8. 5-10. input. 1-10. 1-2 on mode 1 2. 3-4 on mode 1 3. 7-10. two-mode trip: 1. Use the READNTLETI keyword to input previously generated and validated nontransit legs or externally generated ones. 9-10 on mode 1 Value of ACCUMULATE FIRSTLAST ADJACENT ALLONOFFS FIRSLASTBYMODE Movements analyzed 1-10 1-2. The Public Transport program maintains one table of nontransit legs. each with different criteria. 706 Cube Voyager Reference Guide . 7-8 on mode 1 5. or generate and input nontransit legs. 3-8.12 Public Transport Program Control statements Example of ACCCUMULATE subkeyword Suppose you have a five-leg. You can use one or more GENERATE control statements to generate nontransit legs. 3-4. If you specify neither file. you must code all keywords on a GENERATE control statement. adding acceptable legs to the legs table.Public Transport Program Control statements 12 and then the leg with the lowest NTLEGMODE. If SLACK is not specified. Use the necessary keywords to control the nontransit linkgenerating process produced by the GENERATE statement. the program saves the leg. and legs that service that same mode and whose cost does not exceed the cost of the best leg for that mode plus the SLACK for that mode. If the cost for at least one of the modes is less than the mode’s MAXCOST and if the specification in DIRECTLINK is satisfied. Merges legs using any special transaction codes. The program adds the best leg for a mode. After processing all GENERATE statements. GENERATE statements must be in the DATAPREP phase. For example. the program saves the legs in the table to the Public Transport network file specified by NETO and/or the file specified by NTLEGO. Examines each saved leg. computes the cost to the node. and compares the cost to the mode’s MAXCOST. The program ignores nodes specified in TONODE that are not stop nodes. Finds transit modes at each node specified in TONODE. the slack for a mode effectively becomes the difference between the best cost and the MAXCOST for the mode. the program: • Builds minimum-cost routes between each node specified with FROMNODE to each node specified with TONODE that is a transit stop. MAXNTLEGS specifies the maximum number of legs the program will generate for a mode from a FROMNODE. Cube Voyager Reference Guide 707 . See NTLEGI under “FILEI” on page 670. With this statement. the program discards the legs at the end of the run. you might specify that the program replace a generated leg with a longer leg. • • • None of the GENERATE keywords are “trigger” keys. the program generates the link. the program adds that value to the link’s cost. You specify pairs of numbered sets. Separate each access link with a comma. If you specify ACCESSLINK. Specify an access link as: A-S. The program obtains the cost from the route to the A-node. If the link does not exist in the network. Distance traveled on this access link (real). the program ignores any TONODE keywords. Valid values for A and S are 1 to the network’s highest node number. Paired values indicate the start of new access links. Enter paired values in the correct order to avoid generating an error. If ACCESSLINK provides numeric values for cost and distance. Cost of using this access link (real). 708 Cube Voyager Reference Guide .12 Public Transport Program Control statements GENERATE keywords Keyword ACCESSLINK |R| Description Optional. distance — Optional. One or more access links from park-and-ride facilities to stop nodes. If ACCESSLINK only contains one value. the program adds them to the link’s cost and distance.distance where: • • • • A — Surrogate access point (integer) S — Stop node (integer) cost — Optional.cost. Public Transport Program Control statements 12 GENERATE keywords (continued) Keyword COST |N| Description Expression for computing network link costs. Used to determine the minimum-cost nontransit legs between the nodes specified in FROMNODE and TONODE (or ACCESSLINK). Enclose expressions in parentheses. The expression can contain network data items, such as link distance, time, and speed. The cost of nontransit legs may be the cost on the basis of which they are built or, you can skim the cost specified by EXTRACTCOST from the network links underlying the nontransit legs. For example, consider: GENERATE, COST=li.Distance, EXTRACTCOST=li.Time, NTLEGMODE=32 This script fragment generates nontransit legs on the basis of minimum distance, but skims time along the minimum-distance legs and saves as the cost. To obtain the perceived nontransit cost, you can factor the nontransit leg cost, derived from COST or EXTRACTCOST, with the FACTORS RUNFACTOR control statement, which is specified by mode. The sample script fragment produces nontransit legs with a mode of 32. You can factor with RUNFACTOR[32]=x.x. The route-enumeration and evaluation processes use perceived (or factored) costs; both actual and perceived costs may be skimmed. DIRECTION |I| Optional. Integer indicating direction of the generated nontransit legs. Possible values: • • • DIRECTLINK |I| 1 — Forward direction, FROMNODE to TONODE 2 — Reverse direction, TONODE to FROMNODE 3 — Both directions, FROMNODE to and from TONODE Default value is 3. Optional. Maximum number of network links a nontransit leg can traverse. By default, the program applies no limit to number of links. EXCLUDELINK |N| Optional. Expression that computes the network links to exclude from the generation of nontransit legs. Enclose expressions in parentheses. You may exclude links from the GENERATE process with network data items, such as link distance, cost, and classifiers. Cube Voyager Reference Guide 709 12 Public Transport Program Control statements GENERATE keywords (continued) Keyword EXTRACTCOST |N| Description Optional. Expression that computes the network link costs skimmed from nontransit legs built on the basis of COST. The skimmed costs become the costs of the nontransit legs. Enclose expressions in parentheses. The expression can use network data items, such as link distance, time, and speed, to compute the cost. If you do not specify this keyword, the program derives the cost of nontransit legs from the COST keyword. To compute perceived nontransit costs for use in the enumeration and evaluation processes, you can factor the nontransit leg-cost derived from COST or EXTRACTCOST with the FACTORS RUNFACTOR control statement. FROMNODE |S| Optional. Node or list of nodes that program generates nontransit legs from. You may specify nodes as numeric values or names of variables that store valid numeric values. For example, you might specify: FROMNODE=1-NUMZONES Valid values range from 1 to the network’s 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. 710 Cube Voyager Reference Guide Public Transport Program Control statements 12 GENERATE keywords (continued) Keyword MAXCOST |RVt*|1 Description Maximum cost allowed for a particular transit mode to enable generation of nontransit legs. Specify cost per mode. The program generates a leg to a TONODE serviced by a transit mode only when the cost to that node is less than the MAXCOST for that transit mode. You must specify MAXCOST for at least one mode. The default value is 0. Therefore, the program generates no trips to nodes serviced by modes without a MAXCOST specified, unless other non-zero modes service the node. When determining the maximum cost for a leg, the program uses the mode of the TONODE. However, if the TONODE specifies a zone, the program uses the mode of the FROMNODE. The value of SLACK affects the value of MAXCOST. Valid values are 0 to 500 (in the same units specified in COST). MAXNTLEGS |IVt| 1 Optional. Maximum number of nontransit legs to generate for a particular transit mode from a FROMNODE to a TONODE serviced by that mode. Valid values range from 1 to 999. Default value is 5. If both FROMNODE and TONODE are zones, the program ignores MAXNTLEGS. MINCOST |RVt*|1 Optional. Minimum cost allowed for a particular transit mode to enable generation of nontransit legs. Specify cost per mode. The program generates a leg to a TONODE serviced by a transit mode only when the cost to that node is more than the MINCOST for that transit mode. When determining the minimum cost for a leg, the program uses the mode of the TONODE. However, if the TONODE specifies a zone, the program uses the mode of the FROMNODE. Valid values are 0 to 500 (in the same units specified in COST). Default value is 0. NTLEGMODE |I| Nontransit mode assigned to the generated nontransit legs. Valid values range from 1 to 999. You must specify a value. ONEWAY |?| Optional. Flag indicating how to use one-way links when generating nontransit legs. Possible values: • • F — Permits one-way links to be traversed in both directions T — Restricts one-way links to the coded direction Default value is T. Cube Voyager Reference Guide 711 12 Public Transport Program Control statements GENERATE keywords (continued) Keyword READNTLEGI |I| Description Optional. Index number of the input nontransit leg file. You must code a corresponding FILEI NTLEGI statement. When you code READNTLEGI, the program reads nontransit legs from a file and merges them into the generated links table. The NT control statement determines the format of the input records. Delimit data fields with commas or spaces. Use FROMNODE and TONODE with READNTLEGI to filter input records through the from- and to-nodes. No other keywords are valid with READNTLEGI. Use a separate GENERATE statement for each nontransit leg file input. Valid values range from 1 to 7. SLACK |RVt| 1 Optional. Amount added to the best-cost nontransit leg between the two nodes to determine the maximum cost of legs saved. Specify per mode. SLACK provides a secondary control for restricting the generation of nontransit legs. MAXCOST provides the primary control. The program generates legs from a FROMNODE to a TONODE if their costs is less than or equal to MAXCOST for the mode that services the TONODE. With SLACK specified, the program only generates legs from a FROMNODE to a TONODE if their costs is also less than or equal to the best cost between the nodes plus the SLACK for the mode that services the TONODE. For example, consider: MAXCOST[4]=20, SLACK[4]=8 If the best leg has a generalized cost of 6 minutes, the program will save legs with a cost up to 14 minutes. If you do not specify SLACK, the program only uses MAXCOST to limit nontransit-leg generation. If SLACK is set to zero, the program only saves the best-cost legs. SLACK generally refers to the modes serviced by the TONODE. However, if the TONODE is a zone, the program obtains the mode from the FROMNODE. If both FROMNODE and TONODE are zones, the program ignores SLACK. Valid values are 0 to 500 (in the same units specified in COST). Default value for any mode is the value of MAXCOST for that mode. 712 Cube Voyager Reference Guide Public Transport Program Control statements 12 GENERATE keywords (continued) Keyword TONODE |S| Description Optional. Node or list of nodes to which the program generates nontransit legs. Specify nodes as numeric values or names of variables that store valid numeric values. The program ignores TONODE if the GENERATE control statement contains the ACCESSLINK keyword. Valid values range from 1 to the network’s highest number. By default, set to include all nodes (number of zones +1 to the network’s highest node number). XFERMETHOD |I| Optional. Integer that specifies algorithm program uses to execute GENERATE control statement. Version 4.1 introduced a new algorithm that creates nontransit legs between pairs of nodes where a transit line operates. Earlier versions excluded such legs, possibly preventing valid routes. Possible values: • 0 — Use the latest algorithm (currently, the algorithm developed with version 4.1). Use this setting when modeling best-path routes (that is, when FACTOR BESTPATHONLY=T ). 1 — Use the algorithm from version 4.0 when creating nontransit legs. 2 — Supplement the version 4.0 algorithm for generating connectors with the additional connectors created with the version 4.1 algorithm. The program creates an initial set of nontransit legs using keywords such as MAXCOST, MAXNTLEGS, and SLACK as in version 4.0. Next, the program uses the version 4.1 algorithm to create additional legs, using the maximum costs from the initially-generated legs as limits. The total number of legs generated might exceed limits specified in MAXNTLEGS. This value is appropriate for models developed under version 4.0, if you wish to use newly identified connectors while not losing any previously generated connectors. • 3 — Use the algorithm from version 4.1 (currently the same result as setting to 0). • • Default value is 0. 1. t indicates number of transit modes Cube Voyager Reference Guide 713 12 Public Transport Program Control statements Example The first GENERATE statement produces access legs from zones to the public transport system and egress legs in the reverse direction. The second GENERATE statement produces transfer legs between stops. PHASE=DATAPREP //Note: the GENERATE command must precede controls //GENERATE 1: Access and Egress links for zones 11272 GENERATE, NTLEGMODE=100, MAXCOST=20*20.0, COST=li.time, FROMNODE=1-1272, TONODE=1273-5644, DIRECTION=3, INCLUDELINK=(li.LINKTYPE=30-32), SLACK=20*5. MAXNTLEGS=20*5, DIRECLINK=5 //GENERATE 2: Transfer legs for the PT Network GENERATE, NTLEGMODE=100, MAXCOST=20*10., COST=LI.Distance*60/4.80, FROMNODE=1273-5644, TONODE=1273-5644, DIRECTION=3, INCLUDELINK=(li.LINKTYPE=1,4,8-13,20,30-32), SLACK=20*5., MAXNTLEGS=5, ENDPHASE More on using LIST keyword You may use one or more GENERATE statements to generate nontransit legs. While processing statements, the program adds legs to a table of nontransit legs. The table stores exactly one leg for each combination of A-node and B-node—the one with the lowest EXTRACTCOST, followed by the one with the lowest distance (DIST ), followed by the one with the lowest NTLEGMODE. 714 Cube Voyager Reference Guide Public Transport Program Control statements 12 If a GENERATE statement has LIST set to T, the program lists the legs in the table when that statement is processed. Though the program might list a leg during GENERATE, that leg might not be included in the final table of legs. Similarly, a GENERATE statement might list one leg, and a later GENERATE statement a different leg, if the later statement revises the leg. To view or report the final set of nontransit legs, save them to the file specified with the FILEO NTLEGO control statement. The following example illustrates this process: LIST='GEN1' GENERATE COST=(li.distance), EXTRACTCOST=(lw.xcost), MAXCOST=12*1, NTLEGMODE = 36, LIST=T, DIRECTION=3, FROMNODE=1, TONODE=2052 LIST='GEN2' GENERATE COST=(li.distance), EXTRACTCOST=(lw.xcost), MAXCOST=12*1, NTLEGMODE = 36, LIST=T, DIRECTION=3, FROMNODE=1, TONODE=2052 LIST='GEN3' GENERATE COST=(li.distance), EXTRACTCOST=(lw.xcost), MAXCOST=12*1, NTLEGMODE = 35 LIST=T, DIRECTION=3, FROMNODE=1,TONODE=2052 The printed result of this will be: GEN1 Link 1 2052 36 0.18 Link 2052 1 36 0.18 GEN2 GEN3 Link 1 2052 35 0.18 Link 2052 1 35 0.18 M(625): 2 Nontransit Legs 0.36 0.36 1 3674 1 3674 0.36 0.36 1 3674 1 3674 The final nontransit legs saved will be: 1 - 2052 - 35 (and reverse) GOTO Jumps immediately to a named statement. GOTO label Cube Voyager Reference Guide 715 12 Public Transport Program Control statements When GOTO is processed, flow immediately branches to the target statement, named “:label.” Each GOTO statement must have an associated :label statement. Use care when the :label statement is within a different IF or LOOP block. The target statement must begin with a semicolon (:). 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 716 Cube Voyager Reference Guide Public Transport Program Control statements 12 • • • • COMP CONTINUE EXIT GOTO PRINT • Example Two of uses of the single IF statement. IF (matrix.time_to_bcd > 200000) GOTO :SKIPZONE IF (expression) EXIT One example of the IF block statement. IF((j=3-5,6-30,57 & k=(2*j-4)) || ((J*k) = 14-20,56)) .... ELSEIF (loop_cntr > 10) .... ELSEIF (loop_cntr > 5 && diff.time < 32) .... ELSE .... ENDIF JLOOP ... ENDJLOOP Controls a loop over the column cells (J) of the current row (I) in a matrix. Each row represents an origin (I) zone and each column represents a destination (J) zone. Typically, you use JLOOP ... ENDJLOOP blocks for matrix computations that you cannot complete with a single COMP MW control statement. JLOOP blocks may not be nested, and may not overlap other JLOOP, LOOP, or IF blocks. Cube Voyager Reference Guide 717 12 Public Transport Program Control statements JLOOP keywords Keyword J |I| Description Optional. List of up to three integers that define the value of the loop control variable. You may define each integer with an expression. Specify as: J=Jbeg, Jend, Jinc where: • Jbeg defines the initial value of the loop’s control variable, J. Default value is 1. If you do not define Jbeg, you cannot define Jend or Jinc. In that case, Jend defaults to the number of zones in the network, and Jinc defaults to 1. Jend defines the terminal value of the loop’s control variable, J. Valid values range from 1 to the network’s maximum number of zones. If not specified, Jend defaults to Jbeg, and Jinc defaults to 1. Jinc defines the increment for the loop’s control variable, J. If not specified, set to 1 or -1, depending on the direction from Jbeg to Jend. • • Because the list of values for J can be expressions, you must separate the values with commas. Enclose expressions containing commas in parentheses. A JLOOP block causes the program to loop between the JLOOP statement and its ENDJLOOP statement, moving J from Jbeg to Jend in increments of Jinc. The logic for JLOOP and ENDJLOOP processing is: • At JLOOP: 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. 718 Cube Voyager Reference Guide Public Transport Program Control statements 12 The program processes all statements between the JLOOP and ENDJLOOP statements, including COMP MW statements, with the current value of J. The following statements are valid within a JLOOP block: • • • • BREAK COMP CONTINUE EXIT GOTO (:label statement must be inside current JLOOP) IF... ELSEIF ... ELSE ... ENDIF PRINT • • • JLOOP processing varies by phase. Phase NODEREAD and LINKREAD1 DATAPREP1 MATI and MATO JLOOP processing Program executes JLOOP for each node or link processed. Program executes JLOOP once. Program executes JLOOP once per matrix row (or origin zone). You may use J keyword to select destination zones. JLOOP is invalid (the phase is executed once per IJ pair) SELECTIJ and SKIMIJ 1. Program performs no matrix processing during these phases. Therefore, there is no destination zone. However, JLOOP statements are valid, and will act as a zonal loop. Cube Voyager Reference Guide 719 12 Public Transport Program Control statements Example 1 Compute the sum of each row for two matrices. ROWSUM1 = 0 ROWSUM3=0 JLOOP ROWSUM1 = ROWSUM1 + MW[1] ROWSUM3 = ROWSUM3 + MW[3] ENDJLOOP Example 2 Print the first ten cells of each row. JLOOP J=1,25 TRIPSIJ=MI.1.1 * 0.75 IF(J > 10) BREAK PRINT LIST=I, J, TRIPSIJ ENDJLOOP LINE Describes the attributes of public transport lines, including the nodes the line traverses and attributes of those nodes. LINE keywords describe the line’s attributes. Some are required; some are optional. None are “trigger” keys; you must code all keywords on a LINE control statement. You may input lines to the Public Transport program in ASCII format, in up to seven files with FILEI LINEI, or in the Public Transport network file with FILEI NETI. The Public Transport program outputs lines to the binary Public Transport network defined by FILEO NETO and to the ASCII file defined by FILEO LINEO. When crowding is used, the Public Transport program’s Loading Models append results of a crowd run to the output LINE data with the FMCAPACITY keyword. 720 Cube Voyager Reference Guide Public Transport Program Control statements 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 program’s 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 line’s 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 boarding—that is, boarding and transfer penalties plus wait time—for routes passing this node. Cube Voyager Reference Guide 721 12 Public Transport Program Control statements 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. Line’s fare-system number. Overrides value provided by FACTORS FARESYSTEM control statement, and applies for all user classes. The value specified with the FACTORS control statement may vary by user class. The FARESYSTEM control statement defines fare systems (see “FARESYSTEM” on page 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. Line’s capacity when the program runs a crowding model and writes the resulting line data file. The program does not read in or store this value when processing a FILEI LINEI file containing this data. Valid values range from 1 to 20,000. 722 Cube Voyager Reference Guide Public Transport Program Control statements 12 LINE keywords (continued) 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 factor—the percentage of seats occupied when standing first occurs. At this seat-occupancy point, passengers begin experiencing increases in perceived travel time due to crowding. You may code in conjunction with the VEHICLETYPE keyword to override the load-distribution factor specified with the VEHICLETYPE control statement and provide a line-specific factor instead. Valid values range from 0.0 to 100.0. The default value is the value specified with the VEHICLETYPE keyword. LONGNAME 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. Cube Voyager Reference Guide 723 12 Public Transport Program Control statements LINE keywords (continued) Keyword NODES or N Subkeyword |I| Description List of nodes that the transit line traverses. Use negative node numbers to indicate nonstopping nodes. You must specify at least two stop-nodes for a line. If two consecutive nodes do not map to a link in the underlying Public Transport network, the program generates a link, calculating the link’s distance from the node coordinates and taking the speed from XYSPEED or XYSPD. Separate node numbers with spaces, commas, or dashes. Citilabs suggests coding the NODES keyword as the line’s last keyword. If you code the NODES keyword multiple times for a line, the program joins the last node of the previous node list and the first node of the next node list to form a link. If you insert a subkeyword in the list of nodes, you must enter the NODES keyword again, following the subkeyword value. To ease the coding in such cases, you may use N as an alias for NODES. Valid values range from 1 to the network’s highest node number. NODES ACCESS |I| Optional. Integer indicating whether a stop node is for access only, exit only, or access and exit. Valid values are: • • • 0 — Stop for access and exit 1 — Stop for access only 2 — Stop for exit only Default value is 0. The program inverts the access restriction for the line’s reverse direction. NODES ACCESS_C |I| Optional. Integer indicating ACCESS value for a stop node and all subsequent stop nodes until you specify the next ACCESS or ACCESS_C keyword. When using ACCESS_C, you must check that the line’s last node allows exiting (that is, that node’s value must be 0 or 2), otherwise passengers cannot ride to the end of the line. Valid values are 0, 1, or 2. Default value is 0. NODES DELAY |R| Optional. Additional time delay added to the link time. Code between the two nodes that compose the link. Valid values are any number greater than or equal to 1. 724 Cube Voyager Reference Guide Public Transport Program Control statements 12 LINE keywords (continued) Keyword NODES Subkeyword DELAY_C |R| Description Optional. Additional time delay added to the link time and all subsequent link times until you specify the next DELAY_C or DELAY keyword. Valid values are any number greater than or equal to 1. NODES DWELL |I| Optional. Dwell time, in minutes, the line spends at the preceding stop node. Valid values range from 0 to 999. Default value is 0. NODES DWELL_C |I| Optional. Dwell time, in minutes, the line spends at the preceding stop node and all subsequent stop nodes until you specify another DWELL or DWELL_C subkeyword. Valid values range from 0 to 999. Default value is 0. NODES FMOFF 1 |R| Optional. Flow-metered number of passengers alighting from the line at the preceding node. This is the result from running a crowding model, which accounts for bottlenecks in the public transport system when loading demand data (see “Crowd modeling” on page 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 1 |R| NODES FMVOL 1 |R| Cube Voyager Reference Guide 725 12 Public Transport Program Control statements LINE keywords (continued) Keyword NODES Subkeyword NNTIME |R| Description Optional. Travel time, in minutes, between the most recent node and the node preceding the last NNTIME keyword. The PARAMETERS keyword TRANTIME sets the expression for computing base transit travel time for links in the highway network. The LINE keyword XYSPEED and subkeyword XYSPD set speeds for links not in the highway network. The program adjusts (that is, overrides) the computed link and delay times between the nodes to reflect the NNTIME value. Statements that set NNTIME to -1 (or to 0) start the time counter from the last node listed. The program does not set travel time between nodes to zero; the program retains the computed travel time. Statements that set NNTIME to a non-zero, positive value set the travel time between the last node listed and the previous node where the time counter started, and restart the time counter at the last node listed. The program automatically starts the time counter at a line’s first node. For example: NODES=1,2,3,4, NNTIME=10 Sets the time from node 1 to node 4 to ten minutes. NODES=1,2,3,4, NNTIME=10, NODES=5,6,7, NNTIME=15 Sets the time from node 1 to node 4 to ten minutes, and sets the time from node 4 to node 7 to fifteen minutes. 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. 726 Cube Voyager Reference Guide Public Transport Program Control statements 12 LINE keywords (continued) Keyword NODES Subkeyword OFF 1 Description |R| Optional. Number of passengers alighting from the line at the preceding node. This is the result of a loading operation performed by the load models. Valid values are numbers greater than or equal to 0. Optional. Number of passengers boarding the line at the preceding node. This is the result of a loading operation performed by the load models. Valid values are numbers greater than or equal to 0. Optional. Intermediate run time from the line’s first node to the most recently coded node. The program adjusts the accumulated time to the most recent node to match the specified value, and adjusts accumulated times to downstream nodes. If you code more than one RT subkeyword, the program makes subsequent adjustments from the node of prior adjustment. Do not code RT at the first node; the program implicitly sets to zero. If coding multiple RT subkeywords, the values must increase. RT and keyword RUNTIME are mutually exclusive. Valid values are numbers greater than or equal to 1. NODES ON 1 |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. Cube Voyager Reference Guide 727 12 Public Transport Program Control statements LINE keywords (continued) Keyword NODES Subkeyword TIME |R| Description Optional. Time to traverse the link that connects that last node specified with the next node specified. Replaces link time computed using coordinates and XYSPD or XYSPEED. For example: N=100,101,102, TIME=5, N=103 Sets the time for link 102-103 to five minutes. The link time is subject to adjustment by NNTIME, RT, or RUNTIME. Valid values are numbers greater than or equal to 1. NODES VOL 1 |R| Optional. Number of passengers the loading models assign to the link from the preceding node to the next node. Valid values are numbers greater than or equal to 0. Optional. Sets the line’s speed for the current link and any subsequent links not in the input network until encountering the next XYSPD subkeyword. Overrides the value of XYSPEED. Do not code XYSPD for two-way lines. Doing so produces an error. Valid values are numbers greater than or equal to 1. 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. 728 Cube Voyager Reference Guide SEATCAP |I| Optional. then the program increases the value of RUNTIME to this total. The program only scales the link’s travel time and DELAY and DELAY_C components. Valid values range from 1 to 30. VEHICLETYPE |I| Optional. You may code in conjunction with the VEHICLETYPE keyword. The program retains the original values of dwell times and intersection delays. Line’s scheduled time. Cube Voyager Reference Guide 729 . you can code the vehicle type or its attributes in the LINE statement. Use the VEHICLETYPE keyword to override the seating capacity value with a line-specific capacity. and intersection delays exceeds the specified value. Qualified links do not exist in the input network. in minutes. Integer indicating vehicle type operating on this transit line. Seating capacity of vehicles operating on this line. If you set PARAMETERS EXTENDRUNTIMES to true and the total time calculated from link times. The Public Transport program saves the results of a loading operation to this NODES subkeyword. When including crowd modeling. enabling distance computation. TIMEFAC |R| Optional. The program applies this factor until encountering a NODES TF keyword or NODES SPEED keyword. When you specify RUNTIME. and both nodes in the link have valid coordinates. the program adjusts the time on all of the line’s links so that the time sums to this value. Valid values are numbers greater than or equal to 1. Speed on qualified links in this transit line. dwell times.000. XYSPEED |R| Optional. Time factor applied to the travel time of all links the line traverses.000 minutes. Valid values range from 1 to 255. Defaults to value specified with VEHICLETYPE. 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. 1. Valid values range from 1 to 10.Public Transport Program Control statements 12 LINE keywords (continued) Keyword RUNTIME Subkeyword |R| Description Optional. Valid values range from 1 to 300. delays. from the first node to the last node. as appropriate. MODE=7. 765. Adjust link time using the prevailing value of TIMEFAC. SPEED. OWNER=11. DELAY and DELAY_C values. The program does not scale dwell times and junction delays. 730 Cube Voyager Reference Guide . 764. -756. Add turn penalties to the approach link of the modelled intersection. 2. CIRCULAR=F. N=778. If the link does not exist in network.12 Public Transport Program Control statements Example LINE NAME="GMB1-24M". 759. 773. HEADWAY=12. ONEWAY=T. -3673. 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. 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. but retains their original settings. The program uses a twopart approach to process the keywords and obtain a line’s final link times: 1. 776. Add DELAY or DELAY_C to link time. Set link time to TIME if specified. 752 Calculation of line/link times You can adjust the time to lines use to traverse links with several LINE keywords and NODES subkeywords. Adjust link times based on applicable keywords: NODES NNTIME NODES RT RUNTIME The program applies scaling to link travel time. if specified. -777. -763. or TF. 3674. 774. 760. then the program increases the NNTIME. LINKLOOP .. Incr Statement set ENDLOOP where: Cube Voyager Reference Guide 731 . The program supplies all link arrays in a LINKLOOP block with the number-of-links dimension. By default. LOOP blocks may be nested. delays.Public Transport Program Control statements 12 If you set PARAMETERS EXTENDRUNTIMES to true and the total time calculated from link times. LOOP Var = Begin. Example Double LW. but do not overlap LINKLOOP blocks with IF blocks. to reference the current link number. You can only use LINKLOOP in the DATAPREP phase. the default loop index.. but they may not overlap other LOOP blocks or IF blocks. dwell times. and branches to the statement following the LOOP block if the comparison fails. ENDLINKLOOP Controls a loop for processing link records. the LINKLOOP statement processes all link records with a loop increment of one. and intersection delays exceeds the specified value. You can use LINKNO.VAR*2 ENDLINKLOOP ENDIF . End. compares the variable to a constant.. ENDLOOP Initializes a variable.VAR=LW.. no [LINKNO] subscript needed LOOP . You may nest LINKLOOP blocks. RT. or RUNTIME value to this total.VAR for even number zones IF (I%2==0) LINKLOOP LW. LOOP iter=1. The program does not protect the value of Var during the loop.12 Public Transport Program Control statements • Var is the required user-specified name of the loop-control variable. You must specify a value. Example 1 Executes the code within the LOOP block 10 times. . • • • Processing of the ENDLOOP statement depends on the value of Incr: • If Incr is positive. the program branches back to the statement following the LOOP statement. the program goes to the statement following LOOP. If the result of the comparison is true. Begin is the constant value to which the program initializes Var. program. ENDLOOP 732 Cube Voyager Reference Guide . the program goes to the statement following LOOP otherwise the program goes to the statement following ENDLOOP.10 . If Incr is negative. computation. • The program tests the ENDLOOP condition (without incrementing the variable value) when initializing the loop-control variable. End is the constant value that the program compares Var to when processing the ENDLOOP statement. You must specify a value. when the value of Var is greater than or equal to End. If the test fails. when the value of Var is less than or equal to End. Incr is the constant the program adds to Var before processing the ENDLOOP statement. and other LOOP statements may alter the value of Var. the program does not perform any statements within the LOOP block. If it is false. control is passed to the statement following ENDLOOP. otherwise the program goes to the statement following ENDLOOP. Use to supplement NAME.1.-2 LOOP abc=1. LOOP xyz=10.Public Transport Program Control statements 12 Example 2 A nested loop. Although not mandatory. Second unique string identifier for a mode.2 . You can include descriptive names in reports and graphics. ENDLOOP ENDLOOP MODE Defines the transit and nontransit modes that the public transport system uses.4. Unique string identifier for a mode. Citilabs recommends that you define the modes in use with the MODE statement. Valid values range from 1 to 999. 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. with the innermost loop executing twice for each value of variable xyz: 10. Optional. MODE keywords Keyword NUMBER |I| Description Unique numeric identifier for a mode.8. . NAME LONGNAME |S| |S| Optional. Cube Voyager Reference Guide 733 .6. specified with SYSTEMI. Input MODE statements in the public transport system data file. NUMBER must be the first keyword on the MODE control statement.2. reporting. NT keywords Keyword LEG |S| Description Nodes defining a nontransit leg. NOTE: LEG must be the first keyword in NT control statements.12 Public Transport Program Control statements NT Specifies the format of nontransit legs in the Public Transport network. You can feed these saved nontransit legs back to the modeling process with a NTLEGI statement. 734 Cube Voyager Reference Guide . You can use this format for reviewing and editing. The program saves nontransit legs with the public transport network when processing a NETO statement. You can also save nontransit legs in the file specified with the NTLEGO statement. Specify the starting node number followed by the ending node number. and displaying. separated by a hyphen. Only one leg can connect any two nodes. You can use the output for modeling. Passengers use nontransit legs to: • • • Access the public transport system Egress from the public transport system Transfer between lines You can generate nontransit legs with GENERATE statements or produce them with a process external to the Public Transport program. You can feed the saved nontransit legs back to the modeling process when inputting the public transport network with a NETI statement. Enter the same value for FMVOLT for leg A-B and leg B-A. • • • Default value is A. and nontransit mode. Possible values: • A — Add the input leg.01. No action is taken if the leg is not already in the table. Optional. in user-specified units. Useful for eliminating nontransit legs from the network. of the nontransit leg.01. in user-specified units. to traverse the nontransit leg. D — Delete the leg from the table. Valid values are great than or equal to 0. Cube Voyager Reference Guide 735 .Public Transport Program Control statements 12 NT keywords (continued) Keyword ACTION |S| Description Optional. Nondirectional flow-metered passenger volume (total number of flow-metered passengers that the loading models assigned to the nontransit leg in the forward and reverse directions). generated or input. Valid values are great than or equal to 0. the one with the least cost. or if it does not already exist in the table. for each combination of A-node. only if it is shorter than the existing one. if it is shorter than a matching one in the table. The program merges the legs from each GENERATE statement. Valid values are great than or equal to 0. The table stores only one leg. This crowd-modeling data accounts for constraints that bottlenecks impose in the public transport network. The Public Transport program maintains a single table of nontransit legs. into this table. Directional flow-metered passenger volume (total number of flow-metered passengers that the loading models assigned to the nontransit leg). FMVOLT |R| Optional. Length. R — Replace an existing leg in the table with the input one. String that designates how the program merges input nontransit legs with generated nontransit legs. RS — Replace an existing leg in the table with the input one. COST DIST FMVOL |R| |R| |R| Cost. even if it is longer than the existing one. No action is taken if leg is not already in the table. B-node. This crowd-model data accounts for constraints that bottlenecks impose on the public transport network. Valid values are great than or equal to 0. if it exists. 35 DIST=52.00 ONEWAY=T LEG=8-814 MODE=5 TIME=0.00 ONEWAY=T LEG=7-806 MODE=5 TIME=8. Flag indicating whether nontransit leg is a one-way leg.00 ONEWAY=T XN=792 LEG=6-2056 MODE=5 TIME=5. Valid values are great than or equal to 0.00 ONEWAY=T 736 Cube Voyager Reference Guide .00 ONEWAY=T XN=800 LEG=7-803 MODE=5 TIME=1. Valid values are great than or equal to 0. VOL |R| Optional. Directional passenger volume (number of passengers that the loading models assign to the nontransit leg).40 DIST=53. List of nodes between the start and end nodes in a nontransit leg.00 ONEWAY=T LEG=6-2054 MODE=5 TIME=5. Optional.92 DIST=43. Speed. Optional.16 DIST=29. Valid values range from 1 to 999.00 ONEWAY=T XN=2058 LEG=7-2058 MODE=5 TIME=4. in user-specified units per hour. NT NT NT NT NT NT NT NT LEG=6-800 MODE=5 TIME=1. LEG defines the start and end nodes.92 DIST=39.88 DIST=12. that the transit vehicle traverses the nontransit leg. Possible values: • • SPEED |R| T — Nontransit leg is a one-way leg F — Nontransit leg is a two-way leg Default is T. Enter the same value for VOLT for leg A-B and leg B-A. Nondirectional passenger volume (total number of passengers that the loading models assign to the nontransit leg in both the forward and reverse directions). Valid values are great than or equal to 0. VOLT |R| Optional.00 ONEWAY=T LEG=9-812 MODE=5 TIME=1. XN |S| Optional. Example A selection of nontransit legs generated by the Public Transport program.52 DIST=41.01.35 DIST=29.12 Public Transport Program Control statements NT keywords (continued) Keyword MODE ONEWAY |I| |?| Description Mode of the nontransit leg. Cube Voyager Reference Guide 737 . Unique string that identifies a transit operator. OPERATOR keywords Keyword NUMBER |I| Description Unique number that identifies a transit operator. Valid values range from 1 to 999. Supplements NAME. Citilabs recommends that you define the operators in use with the OPERATOR statement. Optional. Input OPERATOR statements in the public transport system data file. You can include these names in reports and graphics. Must be the first keyword coded with the OPERATOR control statement.0 Default value is 0. The OPERATOR control statement associates descriptive names with operators. specified with SYSTEMI. Although not mandatory. PARAMETERS keywords Keyword AONMETHOD |IK| Description Optional. Unique secondary string that identifies a transit operator. NAME LONGNAME |S| |S| Optional. Possible values: • • • 0 — Use latest available algorithm 3 — Use algorithm from version 3. PARAMETERS Specifies global parameters for the Public Transport run.2 4 — Use algorithm from version 4. All lines belong to operators and refer to them by their numeric identifiers. Integer specifying all-or-nothing path-building algorithm to use.Public Transport Program Control statements 12 OPERATOR Defines the operators in the public transport system. Possible values: • T — Program prints messages when a line’s calculated travel time exceeds the values specified by RUNTIME. DELAY_C. DWELL. The program determines run times along transit lines from junction delays and link travel time. DWELL_C. transfers may occur at any of the nodes. Flag that indicates how transfers between routes occur. EXTENDREPORT |?| Optional. When calculated travel times exceed the travel time limits imposed by the RUNTIME. NNTIME. Possible values: • T — Method from version 3. or NODES RT. • Default value is F.2 and earlier releases: When two routes share a common sequence of stopping nodes. you might edit the LINE statement or extend the line’s run time with the EXTENDRUNTIMES keyword. NODES NNTIME. or RT keywords and subkeywords in the LINE control statement. Default value is F. Flag that specifies whether to print messages for excessive calculated travel times.12 Public Transport Program Control statements PARAMETERS keywords (continued) Keyword CHANGEATLASTSTOP |?K| Description Optional. 738 Cube Voyager Reference Guide . using data in keywords such as TRANTIME. Citilabs recommends this setting only when required for consistency with earlier runs. • F — When two routes share a common sequence of stopping nodes. transfers occur at the last stopping node in the sequence. F — Program does not print messages for excessive calculated travel times. DELAY. If required. Cube Voyager Reference Guide 739 .Public Transport Program Control statements 12 PARAMETERS keywords (continued) Keyword EXTENDRUNTIMES |?| Description Optional. 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. FARE does not impact the selection of fare skims chosen with the skimming functions FAREA and FAREP. Flag indicating whether fares are included in generalized cost during the route-evaluation process. using data in keywords such as TRANTIME. 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 LINE control statement and its RUNTIME. DWELL. Input descriptions of fare systems with FILEI FAREI. Fare data is required only for the route-evaluation and skimming processes. or RT keywords and subkeywords set control values for travel time. • Default value is F. • Default value is F. then link travel times have already been calculated and cannot be amended. Possible values: • T — When calculated travel times along a line exceed control values. Only set EXTENDRUNTIMES to T when reading LINEI files. Possible values: • T — Program includes fares as part of the generalized cost during the route-evaluation process. F — Program does not include fares as part of the generalized cost during the route-evaluation process. If the program reads line data from a network file. DELAY. DWELL_C. FARE |?K| Optional. DELAY_C. the program scales calculated values to match control values. Flag that indicates whether the program automatically extends travel time along a line when it exceeds control values. The program calculates run times along transit lines from junction delays and link travel time. input descriptions of fare matrices with FILEI FAREMATI. NNTIME. the program estimates a value from the link data. The program only validates this data if fares are included in the route-evaluation or skimming processes. Maximum index for work matrices (MWs). HDWAYPERIOD |IK| Optional. Factor indicating coordinate units divided by distance unite. if more than one such field is coded. Optional. MEUSESNT |?| You can override this default setting with keywords in the FILEO SCREENLINEO statement. If not specified. MAXMW |IK| Optional. Possible values: • • Y — Program considers link use of all modes when creating intercept data. the default is 1 (HEADWAY[1]). 740 Cube Voyager Reference Guide . Default value is 999. Message 770 describes missing or inconsistent data in the FILEI FAREI. Valid values range from 1 to 5.12 Public Transport Program Control statements PARAMETERS keywords (continued) Keyword FAREMSG |IK| Description Optional. Normally. If you do not specify HDWAYPERIOD. Integer indicating how the program treats message 770. The program uses this value in conjunction with LINE XYSPEED. Flag indicating whether program considers link use of nontransit modes. Valid values range from 1 to 999. Possible values: • • • 0 — Treat as message 1 — Treat as warning 2 — Treat as error Default value is 2. Default value is Y. Integer indicating which HEADWAY and HEADWAY_R fields to use from the LINE control statement. N — Program considers only link use of transit modes when creating intercept data. You can code up to five headways for each line. MAPSCALE |RK| Optional. you do not specify this keyword and override default value. • N — Treat data errors as errors. NOROUTEMSGS |IK| Optional. the program terminates. leading to program termination. Valid values are greater than or equal to 0. NOROUTEERRS applies to all user classes. Generally. Number of zone pairs that the program can process with trips between them but no valid routes.Public Transport Program Control statements 12 PARAMETERS keywords (continued) Keyword NOROUTEERRS |IK| Description Optional. Cube Voyager Reference Guide 741 . When the number of zone pairs with trips but without valid routes exceeds this value. Number of messages the program reports for loaded zone pairs that have trips between them but no valid routes. Flag indicating whether to treat data errors when reading transit line data as warning. Default value is 5. This setting allows the program to read an entire input file without termination due to data errors. Default value is N. You may override this global setting with the FILEI LINEI control statement. SKIPBADLINES |?| Optional. This keyword permits you to accommodate unconnected zones. Valid values are greater than or equal to 0. The program terminates when the number of such zone pairs exceeds NOROUTEERRS. if necessary. NOROUTEMSGS applies across all user classes. Possible values: • Y — Downgrade data errors to warnings when reading transit line data. Default value is 10. all zones in a public transport network are connected. SPEED) The settings in these examples apply to all modes. You can override these settings with a mode-specific expressions. if mode 3 uses a different formula.TRANTIME.14*LI. Examples: TRANTIME TRANTIME computed TRANTIME = LI. the results are unpredictable.DISTANCE*60/LI.name) or link work arrays (LW. Denote these arrays as LW. Denote input-network link variables as LI. you might define: TRANTIME[3] = (1.name = LW. Name of a link work array that you computed in the LINKREAD phase. You might specify: • Name of an input-network link-based variable that contains link transit times. Expression involving one or more link variables. = (LI. Include only input-network link variables (LI.name. For example.SPEED) 742 Cube Voyager Reference Guide .name).name. • • NOTE: If you set TRANTIME to any other variables. You can refine this time with the LINE control statement and the NODES keyword. LW. You must enclose expressions in parentheses. May vary per mode.12 Public Transport Program Control statements PARAMETERS keywords (continued) Keyword TRANTIME |NKVt|1 Description Expression specifying how to compute base transit time for links that transit lines traverse.TRANTIME was in the LINKREAD phase.DISTANCE*60/LI. The index is defined by USERCLASSES. you need not code the index.Public Transport Program Control statements 12 PARAMETERS keywords (continued) Keyword TRIPSIJ |NVu|2 Description Optional. Numeric expression used to compute trips loaded for a particular user class. Examples FILEI MATI[1]=TRIPS. Cube Voyager Reference Guide 743 .MAT PARAMETERS TRIPSIJ[1] = MI.3-5. all ten user classes are available in the Public Transport network. Possible values: • • T — Program writes older. TRIPSIJ applies to all I-J pairs. For example: USERCLASSES=1.1 * 0. see “More on user classes” on page 744. USERCLASSES |IK| Optional. Delimit each number or pair with a comma. V4ROUTEFORMAT |?K| Optional. List of modeled user classes. You might assign an input or generated trip matrix.7. For more information.1. By default.3 Loads 70% of the input trip matrix to user class 1 and 30% to user class 2.1 Loads the cells of an input trip matrix.7 Valid user classes range from 1 to 10. TRIPSIJ[2] = MI. version 4-compatible route file format with FILEO ROUTEO F — Program writes current route file format Default value is F. If USERCLASSES=1.1. unless using the SELECTIJ phase. Flag indicating formatting of route file.1 * 0. the program can compute trips for individual or sets of I-J pairs in the SELECTIJ phase. User classes need not be monotonic or sequential. FILEI MATI[1]=TRIPS.MAT PARAMETERS TRIPSIJ[1] = MI.1. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. You must provide a value for all user classes. 2 PARAMETERS TRIPSIJ[1] =MI. the program writes no zonal messages. and loading processes.2 NOPATHMSGS=10 NOPATHERRS=25 More on user classes You can use user classes for multiple purposes. 1. Similarly. such as by purpose or fare type.1 PARAMETERS TRIPSIJ[2] =MI. other than TRIPSIJ.exe.12 Public Transport Program Control statements PARAMETERS keywords (continued) Keyword ZONEMSG |IK| Description Optional. and links) produced by the Network program 744 Cube Voyager Reference Guide . Frequency with which the program writes zonal timing messages to the run monitor or console. Note most PARAMETERS keywords.1. you can use user classes to stratify demand. u represent number of user classes Example Parameters for the data-preparation. the program writes a message for every 10 zones. Default value is 1. The Public Transport network contains several components that are common to all user classes: • Basic network infrastructure (such as zones. each user class might have different behavior patterns. With a value of 10. Program writes to the run monitor when initiated through Application Manager or voyager. Valid values are greater than or equal to zero. t represents number of transit modes 2. For example. with a value of 1. are trigger keywords and need not be preceded by the control statement name. With a value of 0. nodes/stops. PARAMETERS USERCLASSES=1.1. Specify a larger value to reduce run times.exe. route-evaluation. the program writes a message for every zone. The program writes to the console when initiated through runtpp. For example. Value corresponds to number of zones. which you model with user-class-specific cost functions. Routes are enumerated and evaluated by user class. input with NTLEGI. FACTORI[3]=FACTSUC3. The program outputs user-class-specific enumerated routes files (ROUTEO). User class 3 and 4 use the same factors and enumerated route files. For example. the program might produce the enumerated route file for one user class and reuse the file for the other user classes.FAC FILEI ROUTEI[1]=ENROUTEUC1.RTE. you can point those user classes to the same files. Skim data. generated with the GENERATE control statement. suppose you want to define input files for user classes 1. matrices (MATO). Cube Voyager Reference Guide 745 . nontransit legs. 3. 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. and line data) and that contains the factors for all user classes. input with MATI Nontransit legs. and 4. ROUTEI[3]=ENROUTEUC3. and output with ROUTEO. and skims and select link analyses. input with LINEI Other data and processes vary by user class: • • • Factor data.Public Transport Program Control statements 12 • • • • System data input with SYSTEMI Demand data. specifies level-of-service data that can vary by user class. or both Line data. If two or more user classes have the same cost function.RTE. output with MATO. system data. However. if there are no differences between the behavior for some user classes. specifies cost functions that can vary by user class.FAC. input with FACTORI. FACTORI[4]=FACTSUC3.FAC. You might create the following control statements: FILEI FACTORI[1]= FACTSUC1. You must specify FACTORI files by user class. Routes are input with ROUTEI. See “PRINTROW” on page 69 for details about the standard Cube Voyager control statement. a file. ten columns per line.2 TITLE='COMPCOST' PRINTROW MW=2 FORM 10. The program prints one line for each PRINT statement. when running the loading process.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. PRINTROW MW=2 FORM 10. 746 Cube Voyager Reference Guide . Example Print two skim matrices. See “PRINT” on page 62 for details about the standard Cube Voyager control statement.12 Public Transport Program Control statements 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. The length of the printed line is determined by the formatting of each listed item. PRINTROW Specifies format for reporting work matrices to the main print file. or both. which shows passenger transfers between modes and operators. Valid values range from 0 to 5. Flag indicating whether to omit lines without loads in the summary report produced by LINES. Cube Voyager Reference Guide 747 . Flag indicating whether to generate summary report of line attributes. More than one LINES report may be selected in a run. LINES SKIP0 |?| Optional. Default is 2. Summary includes passenger distance and hours if line loads are available. and distance.Public Transport Program Control statements 12 REPORT keywords Keyword LINES Subkeyword |?| Description Optional. Optional. route time. but displays in order of input. String specifying field that the summary report uses to sort lines. F — Do not produce summary report. showing attributes like number of stops. See “Transit line summary” on page 767 for an example of this report. Possible values: • • • NAME MODE OPERATOR By default. • Default value is F. report does not sort lines. Possible values: • • LINES SORT |S| T — Omit lines without loads F — Include lines without loads Default value is F. Possible values: • T — Produce summary report of line attributes. LINES DEC |I| Optional. Number of decimal places to include in the “Pass” and “PassDist” columns in the summary report produced by LINES. Flag indicating whether to include stop nodes only. Flag indicating whether to include only stop nodes with flows. • LINEVOLS STOPSONLY |?| Default value is F. 748 Cube Voyager Reference Guide . F — Include all nodes in report. F — Do not report passenger loadings. F — Include all nodes in report. Flag indicating whether to report passenger 8loadings (boardings. alightings. Possible values: • T — Report passenger loadings by line. Valid values range from 0 to 5. By default. LINEVOLS SKIP0 |?| Optional. You can produce reports for individual user classes with subkeyword USERCLASSES. Default is 2. do not include nonstopping nodes. Possible values: • T — Produce passenger loadings report only for stop nodes with nonzero flows. Default value is F. LINEVOLS DEC |I| Optional. program generates single report summed over all user classes. Possible values: • • T — Produce passenger loadings report for stop nodes only.12 Public Transport Program Control statements REPORT keywords (continued) Keyword LINEVOLS Subkeyword |?| Description Optional. See “Transit line loadings” on page 768 for an example of this report. • Default value is F. Number of decimal places in passenger loading fields. ignore nonstopping nodes and nodes that have no passenger activity. Optional. and flows) by line. Flag indicating whether to produce an access-leg report. Delimit each number or pair with a comma. and the program produces a single report. • F — Do not produce this report. The statement outputs reports to the file specified with REPORTO. REREPORT Produces reports showing the input simplified public transport network and allied data structures that the route enumeration process uses. GENERATE control statements generate or input access legs. Default value is F. you must code all on a REREPORT statement.Public Transport Program Control statements 12 REPORT keywords (continued) Keyword LINEVOLS Subkeyword USERCLASSES |IV10| Description Optional. Possible choices: • T — Produce a report showing access legs in the public transport network. 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. Access legs connect zones to serviced boarding nodes. REREPORT keywords Keyword ACCESSLEGS |?| Description Optional. Specify included nodes with N. A run can have multiple REREPORT statements. see “Network simplification” on page 782. Cube Voyager Reference Guide 749 . Valid values range from 1 to 10. none are included. For examples. You may specify up to ten user classes. None of the REREPORT keywords are “trigger” keys. By default. These basic reports help you understand the network-simplification and route-enumeration processes. summed over all user classes. A statement’s selections apply to the reports generated by that statement. Flag indicating whether to produce a line-attribute report. Default value is F. Egress legs connect zones to serviced alighting nodes. Possible values: • T — Produce a report showing egress legs in the public transport network.” such as MUNICENTRAL and MUNINORTH. Specify included nodes with N. TRNLEGS3. while LINE=MUNI-?? selects lines that have names beginning with MUNI. such as MUNI-01 and MUNI-02. List of lines included in the reports produced by LINES.12 Public Transport Program Control statements REREPORT keywords (continued) Keyword EGRESSLEGS |?| Description Optional. LINES |?| Optional. For example. GENERATE control statements produce or input egress legs. You can mask names with “*” and “?” to specify multiple lines. Default value is F. Flag indicating whether to produce an egress-leg report. The program compares nonmasked portions of a line’s name when selecting lines. LINE=MUNI* selects all lines that have names beginning with “MUNI. and TRNLEGS4. “*” applies to any number of characters. Specify included lines with LINE.and any two additional characters. Default value is all lines. while “?” applies to single characters. Possible values: • T — Produce a report showing transit-line attributes and the nodes the lines traverse. • LINE |S| F — Do not produce this report. • F — Do not produce this report. The list can contain up to 1000 comma-separated items. Optional. 750 Cube Voyager Reference Guide . Flag indicating whether to produce a line-to-line transfer-leg report. This report expands on the access-leg and egress-leg reports produced with ACCESSLEGS and EGRESSLEGS. Cube Voyager Reference Guide 751 . in line order.Public Transport Program Control statements 12 REREPORT keywords (continued) Keyword LINELINELEG |?| Description Optional. Flag indicating whether to produce a line-ordered lineto-zone nontransit-leg report. Specify included nodes with N. You might use this report to improve performance of the route-enumeration process. Possible values: • T — Produce a report showing line-to-zone nontransit legs. Optional. • LINEZONLEG2 |?| F — Do not produce this report. • LINEZONLEG1 |?| F — Do not produce this report. Possible values: • T — Produce a report showing the line-to-line transfer legs. This report expands on the access-leg and egress-leg reports produced with ACCESSLEGS and EGRESSLEGS. Default value is F. GENERATE control statements generate or input nontransit transfer legs. in zone order. You might use this report to improve performance of the route-enumeration process. You might use this report to improve performance of the route-enumeration process. • F — Do no produce this report. in line order. Possible values: • T — Produce a report showing line-to-zone nontransit legs. Default value is F. produced with XFERLEGS. This report expands upon the direct-andnontransit-transfer-leg report. Flag indicating whether to produce a zone-ordered line-to-zone nontransit-leg report. Optional. Default value is F. TRNLEGS1. Flag indicating whether to produce a stop-node report. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. STOPNODES |?| Optional. access. Delimit each number or pair with a comma. Default value is F. 752 Cube Voyager Reference Guide . EGRESSLEGS=T. Default is to include all nodes. Possible values: • T — Produce a report showing all transit legs in the public transport network. The report calculates perceived in-vehicle time as: Actual in-vehicle time*RUNFACTOR[mode] + BRDPEN[mode] • F — Do not produce this report. F — Do not produce this report. N=1000-2000. or egress.12 Public Transport Program Control statements REREPORT keywords (continued) Keyword N |IV1000| Description Optional. and XFERLEGS. For example. List of nodes included in the reports produced by ACCESSLEGS. Optional. if REREPORT ACCESSLEGS=T. Flag indicating whether to produce a node-ordered transit-leg report that shows perceived costs (including BRDPEN) during route enumeration. • TRNLEGS1 |?| Default value is F. Possible values: • T — Produce a report showing all nodes in the public transport network where transit lines stop for transfer. This report shows actual and perceived in-vehicle time that the route-enumeration process uses. LINEZONLEG2. The list can contain up to 1000 comma-separated items. 3000-4500. sorted by node. then the selected reports will include nodes 1000 through 2000 and nodes 3000 through 4500. TRNLEGS2. EGRESSLEGS. Specify included nodes with N. Public Transport Program Control statements 12 REREPORT keywords (continued) Keyword TRNLEGS2 |?| Description Optional. The report calculates in-vehicle time as: Actual in-vehicle time*RUNFACTOR[mode] + BRDPEN[mode] The perceived time for the bundle’s top leg also includes the estimated wait time for the bundle. This report shows actual and perceived in-vehicle time that the route-enumeration process uses. Default value is F. Cube Voyager Reference Guide 753 . Possible values: • T — Produce a report showing transit-leg bundles in the public transport network. • TRNLEGS3 |?| F — Do not produce this report. Flag indicating whether to produce a line-ordered transit-leg report that shows perceived costs (including BRDPEN) during route enumeration. Default value is F. Specify included lines with LINE. Optional. Possible values: • T — Produce a report showing transit legs and attributes. The report calculates perceived in-vehicle time as: Actual in-vehicle time*RUNFACTOR[mode] + BRDPEN[mode] • F — Do not produce this report. sorted by node. Flag indicating whether to produce a node-ordered transit-leg-bundle report that shows the perceived costs (including BRDPEN) during route enumeration for all legs and that identifies a bundle’s fastest line and shows that leg’s estimated waiting time. This report shows actual and perceived in-vehicle time that the route-enumeration process uses. sorted by line. Specify included nodes with N. Specify included nodes with N. Optional. GENERATE control statements generate or input nontransit transfer legs. Possible values: • T — Produce a report showing direct and nontransit transfer legs in the public transport network. List of user classes included in the reports produced by the REREPORT statement. • USERCLASS |IPa| F — Do not produce this report. and line-based reports apply to lines with line names beginning with MUNI. Example In the REREPORT statement below. Possible values: • T — Produce a report showing transit legs and attributes. This report shows actual and perceived in-vehicle time that the route-evaluation process uses. reports produced for each defined user class. Default value is F. • F — Do not produce this report. The report calculates perceived in-vehicle time as: Actual in-vehicle cost * RUNFACTOR[mode] NOTE: The report TRNLEGS3 produces includes BRDPEN. Flag indicating whether to produce a direct-andnontransit-transfer-leg report. all reports are for user class 1. Default value is F. By default. XFERLEGS |?| Optional. Flag indicating whether to produce a line-ordered transit-leg report that shows perceived costs used for route evaluation. Specify included lines with LINE. You define valid user classes with USERCLASSES. sorted by line.12 Public Transport Program Control statements REREPORT keywords (continued) Keyword TRNLEGS4 |?| Description Optional. 754 Cube Voyager Reference Guide . Node-based reports only apply to nodes 250-450. LINEZONLEG2=T. TRNLEGS3=T. Crowd curve used to adjust link travel times for a particular user class. The vehicle definitions provide a template that you can associate with one or more transit lines. STOPNODES=T. EGRESSLEGS=T. or hovercraft. VEHICLETYPE keywords Keyword NUMBER |I| Description Unique numeric identifier for a vehicle type. Cube Voyager Reference Guide 755 . LINEZONLEG1=T. You can amend vehicle attributes on a line-by-line basis when needed. When transit lines operate with particular vehicle types. N=250-450. TRNLEGS4=T. LINE='MUNI*'. A vehicle can be any form of transport that provides public transit service over fixed routes. LINES=T. XFERLEGS=T. You must input VEHICLETYPE statements in the Public Transport system data file. Valid values range from 1 to 255. Required to adjust link travel time. tram. you may specify the vehicle type in the LINE statement. ferry. CROWDCURVE |IV10| Optional. such as a bus. Valid values range from 1 to 255. Specify per user class. TRNLEGS1=T. You may define up to 255 vehicle types. train. USERCLASS=1 VEHICLETYPE Defines the main vehicle types used by the transit lines operating public transit services. TRNLEGS2=T. none is used. specified with SYSTEMI. ACCESSLEGS=T. NOTE: Number must be the first keyword coded on the VEHICLETYPE control statement. The program includes no default vehicle types. By default.Public Transport Program Control statements 12 //The REREPORT control statement name must be coded at the beginning of the statement REREPORT. LONGNAME NAME SEATCAP |S| |S| |I| Optional. Represents load factor at which passengers begin experiencing additional perceived travel time due to crowding. LOADDISTFAC=0. CRUSHCAP=55. NAME="Bus single deck".0 to 100.000. Unique string that identifies the vehicle type.9. Required for adjustment to link travel time. Optional. vehicle has unlimited seating capacity. See “Generalized cost” on page 771 for a description of the wait-time calculation.0. Vehicle’s seated capacity. Second unique string that identifies the vehicle type (in addition to NAME). model does not consider crowding and load factors. Use IWAITCURVE when the node is a trip’s first boarding point and use 756 Cube Voyager Reference Guide . Optional. LOADDISTFAC |R| Optional. You may define up to 255 wait curves. SEATCAP= 40. By default.12 Public Transport Program Control statements VEHICLETYPE keywords (continued) Keyword CRUSHCAP |I| Description Vehicle’s crush capacity (the sum of seated capacity and maximum standing capacity). VEHICLETYPE NUMBER=1. CROWDCURVE=1 WAITCRVDEF Defines wait curves used to compute initial and transfer wait times at stop nodes based on the frequency of services. Required for adjusting link travel time. Must be greater than or equal to the value of SEATCAP. You may allocate two wait curves to each stop node with IWAITCURVE and XWAITCURVE. Valid values range from 0.000. By default. Percentage of seats occupied when standing first occurs. Example Define vehicle type number 1 for a single-deck bus. Valid values range from 1 to 10. Valid values range from 1 to 20. For example: WAITCRVDEF NUMBER=1 LONGNAME="InitialWait" NAME="InitWait". Separate each pair with a comma.0. 20-8. WAITCRVDEF keywords Keyword NUMBER |I| Description Unique number that identifies a wait curve. Valid values range from 1 to 255. Optional.8. Second unique string the identifies the wait curve (in addition to NAME). NAME LONGNAME CURVE |S| |S| |RKV10000| Optional. 27. 60-20 See “More on wait curves” on page 758 for information about default wait curves. You must input WAITCRVDEF statements in the Public Transport system data file. NOTE: Must be the first keyword coded in a WAITCRVDEF control statement. See “More on wait curves” on page 758 for details about wait curves. List of pairs of X-Y coordinates that define wait curve.15. CURVE=1-0. Separate X and Y values in a pair by a comma or a dash.5. Unique string that identifies a wait curve.5. The X-axis shows headway and the Y-axis shows wait time. 40-15.Public Transport Program Control statements 12 XWAITCURVE at transfer points. The program provides default wait curves for initial boarding and transfers at stop nodes where you do not assign wait curves. 160. 16. specified with SYSTEMI. 48.12. Cube Voyager Reference Guide 757 . 4-2.20 WAITCRVDEF NUMBER=2 LONGNAME="TransferWait" NAME="XferWait". Use the mode-specific WAITFACTOR to weight the wait time. CURVE=1. 12-6. 12 Public Transport Program Control statements Example Defining wait curve number 1 for stops in the central business area. 15-7. NAME="CENTRAL-AREA" CURVE= 1-0. WAITCRVDEF NUMBER=1. At each stop node.5. 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. Default wait curve for initial boarding 758 Cube Voyager Reference Guide . and XWAITCURVE.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.5. 100-12. used when the node is the trip’s first boarding point. The following diagram shows the default wait curve at the first boarding point. you may assign two wait curves: IWAITCURVE. causing the relationship between wait time and headway to break down. Wait time is fixed at 0. Extrapolation beyond the last coded point occurs at the same gradient as immediately below that point.5) to the first coded point. the default wait time is set to half a minute. Wait time (Y-axis) may not decrease as headway (X-axis) increases. The default wait curve for transfer points is half the headway of all services visiting the stop.Public Transport Program Control statements 12 For transit services with a frequency of 60 vehicles per hour or more. • Only the route-evaluation process uses wait curves. The default curve uses a constant wait time in this case because services with very small headways tend to have irregularly arriving vehicles.0. Cube Voyager Reference Guide 759 .5 minutes for headways less than one minute. The curve runs from the point (1. 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. Linear interpolation applies between coded points.5. See “Network simplification” on page 782 for examples of these reports.12 Public Transport Program Reports Reports This section describes the reports that the Public Transport program produces. 760 Cube Voyager Reference Guide . You select reports using a variety of control statements. The program can produce the following reports: • • • • • • • Enumerated routes Evaluated routes Fare matrices Transit line summary (including passenger hours and distance if loads are present) Transit line loadings Transfers between modes (transit and nontransit) Transfers between operators The REREPORT control statement produces a series of basic reports that let you examine and understand the network-simplification and route-enumeration processes. The program writes the reports to the main Cube Voyager print file unless otherwise stated. 896 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 806 -> 806 lines PLB127B PLB129A 806 -> 812 -> 9 lines PLB129A Cost=20.896 1 -> 773 773 -> 771 -> 771 lines GMB1-36A 771 -> 799 -> 799 lines GMB1-39MB 799 -> 812 -> 9 lines PLB129A Cost=17. Cube Voyager Reference Guide 761 . The first line for each route shows the access leg from the origin zone to the first boarding point.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 program writes the report to the file specified by REPORTO.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. REPORTI and REPORTJ.Public Transport Program Reports 12 Enumerated routes You can produce a report of enumerated routes with the ROUTEO keyword and its subkeywords. 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. it is not the cost used for evaluating routes.364 1 -> 2052 2052 -> 2058 -> 806 lines ISL-UP 806 -> 812 -> 9 lines PLB129A Cost=19. The shown cost is used for selecting potential routes. 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 program writes the report to the file specified by REPORTO. The Evaluated Routes report (“Evaluated routes” on page 762) lists routes that are actually used between the zones. In this example.12 Public Transport Program Reports The program will discard some of these routes for various reasons. The following topics show: • • Example produced with REPORTI Example produced with TRACEI 762 Cube Voyager Reference Guide . Some offer more than one combination of services. the report lists all routes used and the probability of taking each of them. the program finds five (potential) physical routes between zones 1 and 9. or alighting and reboarding the same line. When using multirouting. Reports produced with REPORTI list routes taken. Specify the required origin zones with the REPORTI or TRACEI subkeywords and the required destination zones with the REPORTJ or TRACEJ subkeywords. such as a probability of use less than a user-specified minimum. 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. reports produced with TRACEI give a tabular output detailing component costs and summaries for each mode. 226877 1 -> 773 773 -> 771 -> 771 lines GMB1-36A 771 -> 799 -> 799 lines GMB1-39MB 799 -> 812 -> 9 lines PLB129A Cost= 15.937 Probability=0.17571 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 806 -> 806 lines PLB127B 806 -> 812 -> 9 lines PLB129A Cost= 19.764 Probability=0.0848007 1 -> 773 773 -> 769 -> 769 lines GMB1-36A 769 -> 796 -> 796 lines PLB1-113A 796 -> 799 -> 799 lines GMB1-39MB 799 -> 812 -> 9 lines PLB129A Cost= 17.17571 1 -> 2052 2052 -> 2058 -> 806 lines ISL-UP 806 -> 812 -> 9 lines PLB129A Cost= 19.0468973 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 812 -> 9 lines PLB129A Cost= 17.Public Transport Program Reports 12 Example produced with REPORTI Sample evaluated-route report produced with REPORTI REval Route(s) from Origin 1 to Destination 9 1 -> 773 773 -> 769 -> 769 lines GMB1-36A 769 -> 796 -> 796 lines PLB129A 796 -> 799 -> 799 lines PLB144B 799 -> 812 -> 9 lines PLB129A Cost= 17.249 Probability=0.137 Probability=0.00468973 1 -> 773 773 -> 769 -> 769 lines GMB1-36A 769 -> 812 -> 9 lines PLB129A Cost= 14.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.849 Probability=0.249 Probability=0.896 Probability=0.121547 Cube Voyager Reference Guide 763 .096 Probability=0. 00 82.000) 23.953) -> 4538 31 3.00 0.50 34.00 3.53 -> 757 30 16.00 91.75 19.95 949(1. weighted by the probability of use.27 5. Subsequent lines for the route show pairs of transit and nontransit legs with the names of the transit lines running on the transit legs.00 0.75 -> 4544 2 5.85 31 3.00 14.02 19.66 1359(1.30 48.00 38. but not wait time.00 47.00 0.03 18.333) -> 4201 31 1.50 30 30.50 98.5248 N: 1129 Mode WaitA TimeA Actual B/XPen Percvd Dist -> 5409 30 14.00 0.00 3.27 76(0.00 9.10 Mode TimeA Dist IWaitA XWaitA 2 11.00 14.50 30 30.25 -> 4209 7 7.50 17.85 75.00 7 17.47521 Total Lines(weight) 0.30 40.92 0.05 Total Lines(weight) 0.00 20.11 -> 4209 7 7.00 81.00 11.00 9.03 5. This cost includes walk and invehicle times.92 -> 757 30 16.000) 19.30 0.00 30.00 33.35 1.35 107.03 79(0.85 0.00 7.76 764 Cube Voyager Reference Guide .50 1.667) 79(0.00 39.00 0.00 91.75 9. which the program computes from the routes’ common segments for the origin-destination pair as a whole.00 0.00 14. 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.85 8.00 0.00 7.30 0.53 0. 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.13 23.00 7 34.00 18.70 65.00 41.00 4.75 -> 4249 2 5.78 76(0.85 8. and boarding and transfer penalties.11 Probability=0.016) 80(0.00 0.25 Probability=0.12 Public Transport Program Reports This report shows multiple routes from zone 1 to zone 9.85 31 1.70 4.00 0.031) 10.00 18. The cost shown is the generalized cost of each route in minutes.10 Mode TimeA Dist IWaitA XWaitA 2 20. Mode information. distance. cumulative actual total cost. the printed line shows destination node. mode. Probability of taking the route. perceived boarding and transfer penalties. in monetary units. • • • Cube Voyager Reference Guide 765 . cumulative perceived cost. For each mode used. cumulative distance. the report lists actual travel time. followed by alternating transit and nontransit legs.Public Transport Program Reports 12 This report shows two possible routes from 1129 to 757. wait time. and wait times. the report lists: • Leg-by-leg information. distance. If you model fares. Trip fare. starting with the access leg. and transit lines used (along with probability). and ending with the egress leg. The report contains a printed line for each leg. the report includes the trip fare. For each leg. travel time. For each route. Sample fare-matrices report FareMatrix(FMI.---------.---.---------.---.---. 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.-1: 1 1 2 3 4 J: I=2 FareSystem 3 Tot= 14 -.1.---------.-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 -.FROMTO) for FareSystem 3 (FAREZONE-FROMTO): -----------------------------------------------------------J: I=1 FareSystem 3 Tot= 11 -.---------.-1: 4 5 6 7 1 766 Cube Voyager Reference Guide .---.12 Public Transport Program Reports Fare matrices You can produce a report of fare matrices with the FAREMATI keyword in the REPORT control statement.---------.--.--.---.--.--.--. The program writes the report to the main print file.-1: 1 1 3 4 5 J: I=3 FareSystem 3 Tot= 20 -. 712.35 19.646. the program only reports transit line attributes once.08 19.97 20.01 GMB1-29AB 7 11 4 3.561.86 202.090.27 7.26 4.60 13.39 22.680.79 22.67 1.72 0.805.698.07 8.694.60 13.165.67 1.009.36 15.20 GMB1-39MA 7 11 6 8.20 9.16 15.192.16 906.25 GMB1-55A 7 11 13 5.384.90 5.01 13.21 GMB1-24MA 7 11 10 6.96 1.713.05 7.320.460.26 GMB1-52A 7 11 6 8.772.059.836.89 306.91 GMB1-1B 7 11 5 7.630.98 7.808.21 GMB1-53B 7 11 14 7.27 3.119.16 GMB1-2A 7 11 5 2.67 2.90 23.756.80 GMB1-16MA 7 11 4 8.89 GMB1-55B 7 11 12 4.892. This report shows data for all user classes.329. as the attributes are common to all user classes.05 568.20 GMB1-24MB 7 11 10 5.259.96 4.202.35 39. The program also produces a separate report for each user class.785. Because the public transport network includes line loadings.56 28.409.36 3.14 11.96 This example shows transit lines sorted by mode.53 31.516. 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.07 10.18 10.755.29 26.540.13 4.998.901.14 568.14 2.401.23 451.797.007.68 9.79 22.403.44 GMB1-16MB 7 11 6 10.562.492. If the public transport network does not include line loadings.38 465.992.12 3.41 1.456.28 2.77 21.93 2.70 8.684.46 6.56 16.232.590.10 44.13 GMB1-52B 7 11 6 8.497.557.796.81 1.824.92 12.99 4.28 16.95 GMB1-49MB 7 11 2 1.84 477.15 5.802.800.25 22.407.35 GMB1-29AA 7 11 3 2.Public Transport Program Reports 12 Transit line summary You can produce a report summarizing transit lines with the LINES keyword in the REPORT control statement.507.42 1.939.178.14 ISL-DN 1 1 14 13.527.77 699.790.02 1.51 6.295.74 GMB1-39MB 7 11 7 8.716.24 3. this report includes passenger distance and passenger hours.436.11 5.50 1.49 17.15 370.56 46.82 22.52 2.61 4.13 GMB1-49MA 7 11 5 2.308.20 438.07 17.48 1.00 GMB1-2B 7 11 5 3.51 8. Cube Voyager Reference Guide 767 .765.531.05 16.16 2.99 4.49 915.25 GMB1-1A 7 11 5 6.87 4.86 0.383.76 31. 66 2066 3.37 13.42 17.20 2070 -874.81 6. and riding through the nodes of a transit line.40 7.883.02 7.893.073.30 2004 8.47 29.735.73 2054 5.78 2056 1.876.290.817.135. This report shows data for all user classes.02 -- This example report shows the number of passengers boarding.30 8.68 25.20 -7.95 1.02 2001 -8.12 Public Transport Program Reports Transit line loadings You can produce a report of transit line loadings with the LINEVOLS keyword in the REPORT control statement.78 1.75 577. This report shows only stopping nodes with some passenger activity because STOPSONLY and SKIP0 are set to T. alighting.383.084.03 2062 7.132. alighting. You can request a separate report for each user class.692.72 4.737. 768 Cube Voyager Reference Guide .73 2052 45.34 2058 1.62 29.423. If the program performed crowd modeling with wait-time adjustments.072.628.75 22.651.031.526. the program would supplement reports showing all user classes with columns showing the flow-metered boarding.526.073. and through-ridership volumes.06 1.97 15.39 2068 20. Sample of transit-line-loading report REPORT LINEVOLS UserClass=Total Name Mode Op N ON OFF VOL ------------------------------------------ISL-DN 1 1 ----------------------2072 7.35 23.234.108. 10.228.51 33 38.03 124. the program automatically produces two reports showing transfers between modes: • • A report showing transfers between all modes (that is.01 3.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 -.97 17.51 10.731.21.35.769.419.723.629.930.77 10.769.796.94 8 -.98 126.60 49.930.75 58.94 131.01 MODE names: 1 = Train 7 = Bus 8 = Underground 11 = Light Rail 33 = Access/Egress 34 = Walk Xfer Cube Voyager Reference Guide 769 .739.92 63.77 7 -.476.91 1.255.91 1.931.669.58 7 19.472.92 63.931.06 29.20 21.008.669.743.60 5.189.Public Transport Program Reports 12 Transfers between modes When performing loading.45 17.88 2.398.346.60 11 116.255.03 8 17.26 116.07 47.58.88 2.77 10.346.22 580.849.75 11 -.96 444.189.326.97 17.228.476.008.40 39.459.35 --34 36.22 580.60 5.131. Sample of transfers-between-modes report REPORT XFERSUM=MODE UserClass=1 MODE 1 7 8 11 33 34 ---------------------------------------------------------------------1 ----.459. 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.629.06 29.24 19.739. the program automatically produces a report showing transfers between operators.930.06 29. Sample of transfers-between-operators report REPORT XFERSUM=OPERATOR UserClass=1 OPERATOR 1 11 14 19 ---------------------------------------------------1 -.51 10.Fenchurch Street 14 = BR .Via Stratford 770 Cube Voyager Reference Guide .88 2.12 Public Transport Program Reports Transfers between operators When performing loading.255.346.008.75 58.739.22 580.Lea Valley Services 11 = BR .629.01 OPERATOR names: 1 = BR .228. The program produces this report for each user class and for all classes combined.94 131.459.91 1.931.97 17.Upminster Branches 19 = BR .77 10.03 14 17.476.60 5.669.58 11 19.Stratford .60 19 116.Liverpool Street .21.769.92 63.189. Public Transport Program Theory 12 Theory This section discusses the theory used in the Public Transport program: • • • • • • • • • • Generalized cost Modeling approach Network simplification Route-enumeration process Route-evaluation process SFM and SFCM examples Skimming process Loading process Fares Crowding Generalized cost Generalized cost is a measure of the main components of a Public Transport trip. The generalized cost of a public transport trip has three components: • Time Walk time (nontransit time) Wait time In-vehicle time • Inconvenience Boarding penalty Transfer penalty Cube Voyager Reference Guide 771 . Fares. as part of a transfer between services Between an origin and destination zone. at the start and end of the trip Between stop nodes.12 Public Transport Program Theory • Cost Fare The route-evaluation process considers each component separately. using minutes as the s working units. and fare. Subsequent sections provide details about individual components and their weighting factors. depending on the values of keywords in the FACTORS control statement. uses a slightly simpler estimation. 772 Cube Voyager Reference Guide . weighted by coefficients. are input in monetary terms and converted into the corresponding time units. the cost might include wait time. described in “Route enumeration cost calculation” on page 775. or you can develop the walk links when developing the public transport network. without using any transit mode You can develop walk links outside the Public Transport program and input the links to the program. Generalized cost is a linear function of its components. A trip’s generalized cost automatically includes walk and in-vehicle time. Walk time (nontransit time) Walking may occur at the following points in a trip: • • • Between stop node and zone centroid. The route enumeration process. boarding and transfer penalties. if used. 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. a network bottleneck might occur (where demand exceeds capacity. To convert the times to perceived values (for inclusion in generalized costs). the value is the total in-vehicle time for all legs. See “Default wait curves” on page 758 for a description of the default wait curves. For example.Public Transport Program Theory 12 A link’s walk time (nontransit time) is typically the actual travel time. The program uses default wait curves at nodes where you do not assign wait curves. a transit service might be so loaded that a passenger cannot board (and must wait for a later service). the program computes wait time from wait curves that you specify. If you do not specify any wait curves. the program uses default wait curves. In-vehicle time In-vehicle time is the time passengers spend travelling in a public transport vehicle for each transit leg of a trip. passengers might experience additional wait time attributable to crowding. you may specify different wait curves for initial and subsequent boardings at each node. To represent passengers’ ability to control wait time at the start of a trip but not at transfer points. Specifically. You can weight the wait times with the node-specific WAITFACTOR keyword. You model these additional wait times with a node-specific WAITFACTOR keyword in the FACTORS control statement. You define wait curves with the WAITCRVDEF control statement. Similarly. If a trip has more than one leg. You assign wait curves to nodes with IWAITCURVE and XWAITCURVE keywords in the FACTORS control statement. and some passengers cannot proceed forward within the modeled period). When the program performs crowd modeling with wait time adjustments. Cube Voyager Reference Guide 773 . 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. You specify transfer penalties with the XFERPEN keyword. even if there is walking between the two modes. You specify boarding penalties by mode with the BRDPEN keyword. Transfer penalty Transfer penalty is the transit-mode-to-transit-mode interchange penalty. All mode-to-mode penalties default to zero—that is. there are no penalties by default. The program applies this penalty at transfer points. The default penalty for each mode is zero (that is. and you may weight transfer penalties with the XFERFACTOR keyword. 774 Cube Voyager Reference Guide . the program also weights in-vehicle time with a crowding factor. You may specify separate penalties for each mode. You may add constants to transfer penalties with the XFERCONST keyword. You can ban changes between modes by setting a high transfer penalty. which represents the inconvenience of transferring between 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. no penalty). at the start of the trip) and at each interchange. Boarding penalty Boarding penalty is a fixed penalty applied at each boarding (that is. 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. When performing crowd modeling with link travel-time adjustments.12 Public Transport Program Theory You can weight in-vehicle time with a transit-mode-specific value specified with the RUNFACTOR keyword. for that mode-to-mode combination. For transfers between the same mode. such as 999. the process bundles together transit legs with the same boarding and alighting points. Data compression techniques improve the performance of the route-enumeration process. (The process disaggregates transit leg bundles for analysis. and specify the input file with the FILEI control statement and FAREI keyword. For example. 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. and enumerates routes only for the cheapest leg in the bundle. You define fare models with the FARESYSTEM control statement. weighted by WAITFACTOR and subject to a range defined by REWAITMIN and REWAITMAX • • Cube Voyager Reference Guide 775 .Public Transport Program Theory 12 Fare By defining fare models. The route-enumeration process converts the following components to generalized cost units: • In-vehicle time.) For this reason. You associate fare models with transit lines two ways: • • Directly with the LINE statement and FARESYSTEM keyword Through their mode or operator attribute. weighted by mode-specific factor specified with the RUNFACTOR (using the value of the bundle’s fastest transit line) Boarding penalty Wait time. Fare models describe how the program computes the fare for part of a trip or for an entire trip. you can include fares in the routeevaluation and skimming processes. the process cannot use all the components of generalized cost. the route-enumeration process handles some of these components differently. the process computes these times across all modes in a transit leg bundle. and XFERPEN) when identifying discrete routes. 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. the process computes these times for individual modes (and the value for fastest mode subsequently used in enumeration). XFERFACTOR. weighted by WAITFACTOR. For best-path models. • 776 Cube Voyager Reference Guide . the route-enumeration process uses transfer penalties (based on XFERCONST. taken directly from nontransit legs and weighted by an appropriate RUNFACTOR When modeling best paths (or when REBESTPATHCOST is T). • In-vehicle time is based on the average value for lines in the transit leg bundle. The process sets the wait time to half this headway. When false. Wait time is calculated using initial or transfer wait curves and WAITFACTOR (as in the route-evaluation process). You can exclude wait time from the route-enumeration process by setting these factors to zero. • Walk time. The process uses the headway of the transit-leg bundle (or the lines of a particular mode in the bundle) after discarding any slow routes. the process adjusts the resulting value to fall within the range set by REWAITMIN to REWAITMAX. Where necessary. In this case: • Calculations of wait and in-vehicle time depend on the value of FREQBYMODE: When true (default value).12 Public Transport Program Theory The route-enumeration process uses a simple estimate of wait time for each leg bundle. The process computes the headway for each bundle’s boarding node from the sum of the frequencies of the bundle’s legs. Routes transferring from a mode-3 leg to a mode-5 leg would be eliminated. route enumeration. For both modeling methods. suppose these legs are the top legs in bundles that contain legs of other modes. However. the program finds attractive or reasonable routes. route evaluation. These other legs would also be eliminated. Using fares and transfer penalties with leg bundles during route enumeration could eliminate valid routes. For example. (that is. in three steps: network simplification. consider a banned transfer between transit modes 3 and 5. the route-evaluation process disaggregates transit-leg bundles by mode to apply transfer penalties. The program supports two distinct modeling methods: multirouting and best-path. Instead. The route-enumeration process adds wait time to the time of each bundle’s top leg to obtain a transit-leg cost.Public Transport Program Theory 12 The route-enumeration process does not consider fares. You can restrict modeling to consider just those routes that use a particular transit mode at some stage in the trip. routes that have some probability of use). Modeling approach This section discusses the algorithms that the Public Transport program uses. This section discusses: • • • • • • Multirouting and best-path methods Network simplification Route enumeration Route evaluation Limiting selected routes to particular transit modes Advantages of the Public Transport program for multirouting Cube Voyager Reference Guide 777 . 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. and ignores transfer penalties except when modeling best paths. 17 or 21. passengers must choose between the transit lines that enable progress toward the destination. 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. or modeling philosophies. passengers must decide where to board the next transit leg. When on a transit line. At the origin and on completion of a transit leg. The cost to the destination is the wait time plus travel time. travelers are prepared to board whichever bus comes first. travelers choose between the two routes and then wait for a service on the chosen transit line (ignoring any service on the other line). In a best-path model. which runs every 20 minutes and takes 15 minutes to reach the destination after boarding. suppose travelers waiting at node N have a choice between two routes to reach the trip’s destination. that is.4 minutes. For example. The second route uses line M.12 Public Transport Program Theory Multirouting and best-path methods During a public transport trip. Assuming equal spacing of departures. The first route uses line L. There are a total of five services per hour. 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). either 11+6 or 15+6. Travelers assess attributes of each route: L 778 Cube Voyager Reference Guide . Assuming route usage proportional to service frequency. Best-path — Identify a single “best path” route for an origindestination pair. the average time to destination is 19. the combined headway is 12 minutes and average wait is 6 minutes. A number of possible methods. which runs every 30 minutes and takes 11 minutes to reach the destination. passengers might need to decide which stop to alight at (in order to transfer or walk to their destination). you can compute an expected travel time from the stop to the destination. In a multirouting model. At a stop. passengers must make decisions at several points on their route. the route-enumeration process finds all potentially attractive routes and enumerates them. 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. The process follows three principles: • • The trip should move progressively from the origin to the destination. travelers using the best-path method would select transit line L. well-developed public transport systems. M has an average wait of 15 and travel time of 11. for a total cost of 25 minutes. Model developers must decide between the two methods. Travelers prefer simpler trips. Therefore.Public Transport Program Theory 12 has an average wait of 10 minutes and travel time of 15 minutes. for a total of 26 minutes. that is. Many modelers prefer the multirouting method in cities with extensive. with an average trip cost of 25 minutes. direct trips or trips that involve few transfers. The appropriate method might depend on externally imposed requirements or practices (for example. Network simplification To improve performance and to minimize memory and storage requirements. guidelines from government departments) or a choice regarding the suitability of each method. Cube Voyager Reference Guide 779 . Route enumeration For multirouting modeling. The route-enumeration process allows for possible transfer-penalty values. alight from a service. 780 Cube Voyager Reference Guide . Next. First. 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 process identifies the route attributes—basic cost and number of transfers—and compares them. selecting reasonable routes for evaluation. The process limits routes by choosing simpler trips and trips with shorter walking distances during line-to-line transfers. the program uses information about the trip sequence to preclude alighting and reboarding the same service. The program uses conventional algorithms to forecast these individual choices. 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. The route-enumeration process uses the same cost components as the route-evaluation process. Route evaluation For multirouting models. the route-enumeration process identifies possible routes for the best single path between an origin and a destination. This step is analogous to travelers examining a map and identifying the sequence of lines they can use to travel from their origin to their destination. and enumerates any route which potentially could be the best route. or walk elsewhere to board another service. the process establishes connectivity between transit lines. For best-path modeling. The route-enumeration process uses these principles to identify reasonable routes. See “Route-enumeration process” on page 793 for a detailed description of this process. This step is analogous to travelers rejecting routes that are very long relative to more direct alternatives.12 Public Transport Program Theory • Travelers are unwilling to walk very long distances. with the exception of transfer penalties. For example. and assigns all demand to that route. Sometimes you might want routes to use a particular mode. Such paths do not retain the history of a trip at a node (that is. the route-evaluation process identifies the best path using a similar evaluation method. biasing could lead to modeling distortions affecting route costs or identification of the best route.Public Transport Program Theory 12 For best-path models. you need not use biases. such as station-to-station movements. or mode-to-mode and operator-to-operator transfers. such packages cannot easily extract route-based information. perhaps having different transfer points. matrices of trips using selected links or transit lines. how the path reached the node or where the path came from). 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. Earlier software packages used biases to attract travelers toward one mode and away from other modes. you can specify a “must-use-mode”—a mode that must be used during at least one leg of a public transport route in order for the Public Transport program’s route-enumeration process to select that route. and using different modes. The Public Transport program requires more computational time but produces more useful and better quality results. unlike traditional software packages. Advantages of the Public Transport program for multirouting Some software packages trace paths from all zones to a particular zone or vice-versa. The Public Transport program finds discrete multiple routes between pairs of zones. Instead. With the Public Transport program. When using multiroute paths. The enumerated routes may vary widely in characteristics. the Public Transport program operates at the zone-pair level rather than at the zonal level. Cube Voyager Reference Guide 781 . However. Therefore. followed by a the route-evaluation process to evaluate the routes. The program stores the simplified network in intermediate data structures. This section introduces the network representations used for: • • • • • Transit legs Transit-leg bundles Nontransit legs Line-zone legs Line-line legs 782 Cube Voyager Reference Guide . which you can examine to gain an understanding of how multirouting works in the Public Transport program. egress. the Public Transport program simplifies the network for enumerating and storing routes. DELACCESSMODE. and transfer choices Modeling combination of frequent and infrequent services Network simplification Public transport networks are often quite detailed and data intensive. The program does not use specified legs at any stage in the modeling. and DELEGRESSMODE factors to remove legs of particular modes from the network representation.12 Public Transport Program Theory The Public Transport program addresses other common problems associated with multirouting: • • • Calculating wait time at stops using the combined frequency of visiting services Modeling access. To improve algorithm performance and minimize memory and temporary disk storage. Use the DELMODE. the last of which is the egress leg.54 1.42 3 0 875 1. 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.12 2 0 -947 0.00 0.15 5 3 -881 6.92 7 4 -745 8. from a boarding point to an alighting point.80 4 2 751 5.00 1 1 -897 0.36 1.28 0.40 2.33 4.15 7. and one or more pairs of transit leg bundles and nontransit legs. that uses a single transit line. (A trip consists of an access leg.97 0.39 8 0 -746 12.99 0.08 10 5 Cube Voyager Reference Guide 783 .16 9 0 747 19.) Use the REREPORT control statement and LINES keyword to produce a line-attribute report.10 1.55 6 0 748 7. Travel on the transit line can be over one or more links in the public transport network.Public Transport Program Theory 12 Transit legs A transit leg is a trip segment. 16 * Top leg of a leg bundle.35 875 748 5. see “Transit-leg bundles.00 0 10 5 GMB1-1B Top ON OFF Time Time DisLeg Node Node Actual REnum tance ---------------------------------------------727 875 1.55 0.93 * 748 747 12.92 * 727 747 19.99 4.54 8.61 5.61 16.10 1.10 10.11 1.” 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.54 1.12 * 875 747 17.08 875 751 3. 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.77 * 751 747 13.05 5.11 8.28 751 748 1.15 7.56 0.15 22.05 15. Transit-leg bundles have the following properties: • The “top leg” of the bundle is the cheapest in terms of travel time (in the example all legs within bundles have the same time).16 20.15 727 748 7. • 784 Cube Voyager Reference Guide .56 4. They may or may not traverse the same links of the underlying network.55 6.12 Public Transport Program Theory Use the REREPORT control statement and TRNLEGS3 keyword to produce a line-ordered transit-leg report.16 6.80 727 751 5.99 0. 66 GMB1-24MA * 875 774 7.35 PLB1-113A 875 751 3.55 3.30 1.85 1. including three sets of leg bundles: from node 875 to nodes 753.37 5. Use the REREPORT control statement and TRNLEGS2 keyword to produce a node-ordered transit-leg-bundle report. 757.53 0.35 PLB129A 875 751 3.12 GMB1-1B This sample shows transit legs from node 875.03 6.06 PLB1-113A 875 757 5.95 GMB1-24MA * 875 773 8.85 1.04 16.35 GMB1-24MA 875 751 3.35 GMB1-24MA * 875 776 13.04 0.35 GMB1-1B 875 751 3.32 6.83 RES-903R * 875 757 5.55 0.97 GMB1-24MA * 875 751 3.55 4.30 9.32 5.36 1.37 20.75 10.55 3.55 0.26 11.91 0.03 5.04 4.83 PLB129A 875 753 5. if all have equal Cube Voyager Reference Guide 785 .38 1.32 6. the report marks the top line (the fastest line or the first line.26 0.30 GMB1-24MA * 875 778 17. The program individually evaluates each leg within a transit-leg bundle when determining “attractive” routes for loading and skimming.26 2.06 GMB1-24MA 875 757 5.03 5.55 3.11 7.35 GMB1-2B 875 751 3. When multiple lines connect node 875 to an alighting node.35 RES-903R * 875 748 5. and 751.55 3.06 PLB129A 875 757 5.83 PLB1-113A 875 753 5.03 0.12 GMB1-2B 875 748 5.32 1.83 GMB1-24MA 875 753 5.53 0.75 1.11 5.91 0.11 1.55 0.06 RES-903R * 875 765 6. thus simplifying and reducing the data to examine and enumerate.55 4.32 5.03 6. Excerpt from node-ordered transit-leg-bundle report REPORT: TRANSIT LEGS II (Leg Bundles from Nodes) (REnum Time = Actual Time * RUNFACTOR + BRDPEN) (And top leg in Bundle includes Estimated Wait time for Bundle) Top ON OFF Time Time DisLine Leg Node Node Actual REnum tance Name --------------------------------------------------* 875 753 5.Public Transport Program Theory 12 The route-enumeration process treats transit-leg bundles as single entities. input user-specified nontransit legs. The program derives leg attributes from link attributes. traversed by nonmechanized modes. The program associates a cost with these nontransit legs. The program automatically generates a third type of “notional” nontransit leg.) Nontransit legs Nontransit legs are minimum-cost segments. which allows transfers between two lines visiting the same node. one. or do both. (Do not confuse this waiting time with the wait time calculated during the route-evaluation process.12 Public Transport Program Theory time) with “*.” All legs in a bundle have the same actual in-vehicle time. but the REnum time for the bundle’s top leg includes an estimate of the bundle’s waiting time. The program can generate nontransit legs with the GENERATE control statement. 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). or multiple physical links. 786 Cube Voyager Reference Guide . See “Generalized cost” on page 771. Such nontransit legs do not have any associated cost. Boarding and transfer costs apply to both types of transfers—those occurring at a node and those between two nodes connected with a physical nontransit leg. 23 33 705 19 0.36 33 1 3674 2.40 0.92 0.19 33 709 19 0.64 2.80 0.52 0.06 33 3 749 3.70 0.30 33 735 23 2.11 33 6 796 1.52 0.24 33 728 22 0.00 0.96 0.70 0.40 0.43 33 749 3 3. EGRESSLEGS.39 33 6 2054 5.20 33 734 22 0.53 33 6 2056 5.24 33 721 21 1.76 0.18 33 2 778 1.12 0.41 33 5 959 2.96 0.70 0.52 0.80 0.78 33 Cube Voyager Reference Guide 787 .46 33 747 24 1.36 33 730 22 0.12 0. and XFERLEGS keywords to produce nontransit-leg reports.22 33 716 20 1.72 0.70 33 714 20 1.Public Transport Program Theory 12 Use the REREPORT control statement and ACCESSLEGS.78 33 4 750 0.92 0.25 33 1 2052 8.31 33 4 875 1.43 33 Sample nontransit-leg report: REREPORT EGRESSLEGS REPORT: EGRESS LEGS DestiDisOrigin nation Time tance Mode ---------------------------------------703 19 0.36 1. Sample nontransit-leg report: REREPORT ACCESSLEGS REPORT: ACCESS LEGS DestiDisOrigin nation Time tance Mode ---------------------------------------1 773 2.68 0.56 0.42 33 725 22 6.92 0.64 0.32 33 4 2004 7.38 33 6 800 1.32 0. 27 34 813 813 0.00 0.00 0. For multirouting models.00 0.00 0.00 0. the program expands access and egress nontransit legs—legs from zone to stop node and vice versa—into zone to line and line to zone legs. When multiple access and/or egress legs exist between a zone and a line. because the program selects exactly one best route.00 0.16 34 823 2062 4.00 -1 830 2066 4.00 0. 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.12 Public Transport Program Theory Sample nontransit-leg report: REREPORT XFERLEGS REPORT: TRANSFER LEGS DestiDisOrigin nation Time tance Mode ---------------------------------------701 701 0.00 0. without any walking.04 34 803 803 0.00 0.00 -1 813 2060 4. For best-path models.00 0.00 -1 838 838 0. the program eliminates multiple access legs by applying the following rules: 788 Cube Voyager Reference Guide . Line-zone legs During network simplification. The program stores line-zone legs as pointers to the corresponding access and egress nontransit legs along with some additional information that helps improve the performance of the route-enumeration algorithm.00 0.00 0.00 -1 838 2072 3. overlapping segments are not possible.00 0. the program uses all connectors to ensure identification of the best route.00 -1 703 703 0.00 0.00 -1* 702 702 0.00 0.00 0.00 -1 806 806 0.00 -1 800 2056 4.02 34 837 837 0.00 -1 806 2058 4.11 34 830 830 0.11 34 * -1 indicates a direct transfer.00 -1 800 800 0. ) Always retain the first access leg (that is. If the cost of the “first access + riding to the next” is more than the cost of the next access. this may be the stop after the previous valid egress or the beginning of the line. select the upstream leg. select the leg with the least generalized cost and discard the others. those boarding at the first access may only ride until the stop before the next access. Cube Voyager Reference Guide 789 . select the leg with the least generalized cost and discard the others. • • • • Both sets of rules apply to circular lines. (Between legs of equal cost. If the cost of the an egress leg is less than the cost of “riding to the next + next egress.) Always retain the last egress leg (that is. If the cost of the “first access + riding to the next” is less than the next access. the leg connected to the transit line’s earliest stop). • • • • For multirouting models.Public Transport Program Theory 12 • Among a set of legs accessing consecutive stops (disregarding intermediate nonstopping nodes). Each egress has a stop that specifies the beginning of a range of valid boarding stops. 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). either to the stop before the next valid access or to the end of the line. (Between legs of equal cost. Each access has a stop up to which those boarding can ride. discard the next access. the leg connected to the transit line’s latest stop).” then only those boarding after the current egress can use the next one. select the downstream leg.” discard the leg. If the cost of an egress leg is more than the cost of “riding to the next + next egress. 52 0.41 Access GMB1-49MA 803 7 1.52 1.80 0.52 0.80 0.39 Egress GMB1-49MA 7 803 1.52 0.12 0.92 0.78 Egress GMB1-2B 4 875 1.32 Access GMB1-2B 875 4 1.12 0.32 Egress GMB1-2B 15 852 1.39 Access GMB1-49MA 800 6 1.88 0.97 Egress GMB1-29AA 852 15 1.52 0.33 Egress GMB1-29AB 16 855 1.Access/ Line Node Node Time tance Egress Name --------------------------------------------6 800 1. Sample line-ordered line-to-zone nontransit-leg report (REREPORT LINEZONLEG1) REPORT: LINE ZONE I (In Line Order) Origin Dest Dis.36 Access GMB1-2A 728 22 0.92 0.12 Public Transport Program Theory Use the REREPORT control statement and LINEZONLEG1 LINEZONLEG2 keywords to produce line-to-zone nontransit-leg reports.88 0.33 Access GMB1-29AA 855 16 1.78 Access GMB1-2A 22 728 0.12 Egress GMB1-49MB 3 749 3.97 Access GMB1-29AB 790 Cube Voyager Reference Guide .52 0.52 1.52 0.36 Egress GMB1-2A 749 3 3.41 Egress GMB1-49MA 8 814 0.12 Access GMB1-49MA 814 8 0. When generating line-to-line legs.70 0. direct transfers at the same stop node.36 Egress ISL-DN 2 778 1.70 0.25 Egress GMB1-36A 773 1 2.56 0.40 0.31 Access PLB127A 4 750 0.36 1.25 Egress GMB1-24MB 773 1 2.40 0.56 0.56 0.36 Access ISL-UP 1 2052 8.56 0.31 Access PLB129B 4 750 0.25 Egress GMB1-36B 2052 1 8.36 Access ISL-DN 773 1 2. The route-enumeration process eliminates some transfer legs.70 0. and walk transfers between stops into line-to-line legs.25 Egress GMB1-24MA 773 1 2.12 0.56 0.31 Access RES-91R Line-line legs During network simplification.36 Egress ISL-UP 2052 1 8.12 0. 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.25 Access GMB1-36A 1 773 2.40 0.Access/ Line Node Node Time tance Egress Name --------------------------------------------1 773 2.Public Transport Program Theory 12 Sample zone-ordered line-to-zone nontransit-leg report (REREPORT LINEZONLEG2) REPORT: LINE ZONE II (In Zone Order) Origin Dest Dis. the program expands nontransit legs between stop nodes.56 0.25 Access GMB1-36B 1 2052 8.56 0. the program applies the following rules: Cube Voyager Reference Guide 791 .31 Access PLB127B 4 750 0.36 1.40 0.40 0.70 0.25 Access GMB1-24MA 1 773 2.06 Access GMB1-24MB 778 2 1.78 Access GMB1-2A 749 3 3.56 0.25 Access GMB1-24MB 1 773 2.78 Egress GMB1-2B 4 750 0.31 Access PLB1-113B 4 750 0.06 Egress GMB1-24MA 3 749 3. the program only records one transfer location between Lines A and B instead of four—the last stop. record only one transfer location for consecutive stops. diverging between them. permit boarding at the first node and alighting at the last node. if stop 2 is a stopping node for line A and not for line B. prohibit transfers involving backtracking. discard the others. If two lines meet at nonconsecutive stops. However. For example. 792 Cube Voyager Reference Guide . then the program records two transfer locations: one at stop 1 and one at stop 4 (representing transfers at stops 3 and 4). consider the following transit lines. among multiple connectors between consecutive stops on a “from-line” and consecutive stops on a “to-line. • • • • • Interchanges between two parallel lines In this case. If two lines traverse the same physical route with the same stop characteristics. For circular lines with the same first and last nodes. especially when modeling crowding. The program relaxes this restriction during route evaluation to give flexibility in transfer location. Do not permit transfers to a transit line’s last node. the program records a transfer location at each stop where they meet. Do not permit transfers from a transit line’s first node.12 Public Transport Program Theory • For multirouting. such as if the node prior to alighting is the same as the one after boarding.” retain only the lowest-cost connector. For multirouting. passengers must use the line before transferring. See “Route enumeration cost calculation” on page 775. Use keywords in the FACTORS control statement to control the routeenumeration process.Public Transport Program Theory 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. The program measures trip cost differently during routeenumeration than during route-evaluation. Route enumeration has three distinct stages: • Finding minimum-cost routes Cube Voyager Reference Guide 793 . and one or more pairs of transit and nontransit legs. 476. Using explicit couples of transit and nontransit legs is consistent with the multirouteenumeration process. 478. Because the process starts with transit-leg bundles rather than individual transit legs. and an egress leg between node 1654 and node 100. 486.12 Public Transport Program Theory • • 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. 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. or 495. 493. Finding minimum-cost routes The route-enumeration process finds minimum-generalized-cost routes between zone pairs to establish a baseline cost. • 794 Cube Voyager Reference Guide . described in “Enumerating routes” on page 797. Triplet 1276->1572->1583 represents a transit leg between node 1276 and node 1572 on line 744 or 746. 489. the process might disaggregate a minimumcost route into one or more discrete routes. the last of which is an egress leg. Each route has an access leg. Triplet 1583->1654->100 represents a transit leg between node 1583 and node 1654 on line 399. and a nontransittransfer leg between node 1572 and node 1583. For example. This is a reason to prefer multirouting. EXTRAXFERS1. 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. the other routes may have the same or slightly longer vehicle travel time.” an upper cost limit for routes between an O-D pair when using multirouting. not the number of transfers. and specify function parameters with the SPREADFACT and SPREADCONST keywords. Similarly. Therefore. You can specify a “spread. If a destination’s 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.Public Transport Program Theory 12 The route via lines 744 and 399 will have the best travel cost. Establishing connectivity between lines For each transit line. The route minimizes the generalized cost. and EXTRAXFERS2. you can reflect the impact of transfers in the generalized cost with sensible boarding penalties. However. which includes both the direct and indirect routes in the full list of enumerated routes. Cube Voyager Reference Guide 795 . Select the function for calculating the spread with the SPREADFUNC keyword. to set the maximum number of transfers permitted on “reasonable” routes to a destination. identified routes might have more than MAXFERS transfers. the route-enumeration process generates a set of connectors that describe available connections with other transit lines. Minimum-cost routes minimize some combination of userspecified trip attributes. Connectors are subject to constraints imposed by the keywords MAXFERS. the route-enumeration process uses the number of transfers from the minimum-cost routes along with EXTRAXFERS1 and EXTRAXFERS2. Passengers might not select such routes. When generating connectors. The process examines alternative transfer points between lines when enumerating the route—in the next stage. The connector’s length (that is. the number of transfers) is controlled by the three keywords mentioned. consider the illustrated public transport network. the “to” line. Simple public transport network illustrating line connectivity For this network. 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 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 796 Cube Voyager Reference Guide . and intervening lines required to reach the “to” line. 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 default configuration specifies all zones. For example.12 Public Transport Program Theory Each connector consists of a set of lines: the “from” line. the process treats lines like nodes and treats line-to-line connections like links in a network. and the process builds connectors for all lines. and the time to the next boarding point (that is. • Output valid routes Examine expanded routes to find routes that link to nontransit legs terminating in zones. and destination-zone selection (ROUTEO J) criteria. Repeat the process for the subsequent lines in the connector set until connections have been fully expanded. and by walking. 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. transfer. Examine each interchange between the two lines in the same way. Cube Voyager Reference Guide 797 . If the transit leg used on the first line is the bundle’s top leg.Public Transport Program Theory 12 Line-to-line legs handle all transfers—direct. If the complete route between the O-D pair meets the spread. between lines A and B and lines A and D. the routeenumeration process enumerates routes for each selected origin zone connecting to the line via a valid access leg. and the number of transfers meets the constraints set by MAXFERS. between lines A and B and lines B and C. Enumerating routes After generating the connectors for a transit line. EXTRAXFERS1 and EXTRAXFERS2. extend the route by the transfer. output as a route between that O-D pair. the sum of time for transit and nontransit legs) is within the spread established earlier. ” shown in the example in “Establishing connectivity between lines” on page 795. The route-enumeration process generates the routes in the following table. Enumerating routes with a must-use mode specified When enumerating routes required to use a particular transit mode. For a particular origin-destination pair. If this value exceeds the total of the cost (along the minimum-cost path) plus MUMEXTRACOST.12 Public Transport Program Theory For example. regardless of whether they use the specified transit modes. The limit on transfers is based on the number of transfers on the minimum cost route. the process considers all possible routes. shown in italics. When establishing the minimum-cost route. “line A to line C via line B. 798 Cube Voyager Reference Guide . the process calculates a cost limit using spread factors as described in “Finding minimum-cost routes” on page 794. If you specify two or more must-use modes. the route-enumeration process uses a similar procedure. the process enumerates any route that uses at least one of the modes. consider the connector. EXTRAXFERS1 and EXTRAXFERS2. then the process reduces the cutoff value to this total. 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. 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. making Cube Voyager Reference Guide 799 .Public Transport Program Theory 12 The route-enumeration process only outputs routes that use a specified must-use mode at some point in the trip. Passengers continue. (The process compresses data for efficiency. At a stop.) Starting at the origin. passengers choose between one or more transit alternatives for the next stage of the trip. The process enumerates routes if at least one line in the bundle uses the specified mode. such as routes with a probability of use less than the minimum specified by CHOICECUT. the process removes routes that alight and reboard the same service. One or more second-level branches linked to the first-level branch represent the available choices. passengers might use one or more access legs (first-level branches). The process discards enumerated routes that fail to meet certain criteria. Before computing probabilities. See “Generalized cost” on page 771 for a description of the trip cost used in route evaluation. 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 uses the servicefrequency model. (Trips arriving at the node may proceed towards the destination along any of the alternative next-level branches. (The routeenumeration process only ensures that at least one line in a transitleg bundle satisfies the condition. the process uses the two-pass algorithm. the first pass starts at the destination zone and calculates the conditional probabilities of each alternative at any decision point in the tree structure. but assigns all demand at any decision point to the cheapest alternative. “Models applied at decision points” on page 803. and calculates the probability of choosing each discrete route. The calculations of the servicefrequency model are described in “Deriving cost used” on page 801. passing through the data tree twice.12 Public Transport Program Theory choices from additional branches. Conditional probabilities define what proportion of the trips arriving at a node proceed along each alternative branch. For best-path models. When making transit-line choices. If routes have a must-use mode. This is simply the product of all conditional probabilities along the route. the route-evaluation process calculates routes in two steps. The expected (generalized) cost to destination is the cost along a discrete route. though they arrive via different branches. the composite cost obtained from skimming is identical to the route’s generalized cost.) Like the calculation of hierarchic logit models. the process selects the cheapest route to the destination and discards all other alternatives. until reaching their destination. Because demand along a discrete route is not divided among alternatives. All routes arrive at the same destination. the route-evaluation process checks to ensure that all routes satisfy the condition.) The second pass starts at the origin. the process does not support the servicefrequency-and-cost model. and 800 Cube Voyager Reference Guide . For multirouting models. When the decision tree includes walking or alternative alighting choices. the calculations consider all lines in a transit-leg bundle. working away from the destination. but for best-path models. Deriving cost used The route-evaluation process computes a single expected cost to destination (ECD) from any choice or decision point in a trip to the destination. at the start of the egress leg. when FREQBYMODE is set to F. For multileg trips. the costs are usually simple. the process allocates routes assuming “all reasonable lines forward from a node” (as with multirouting). For multirouting models. Often called composite cost. where there are alternative routes. the cost includes walk. By default. Cube Voyager Reference Guide 801 . For example. the process computes service-frequency-model calculations for identical-mode lines in a transit-leg bundle. At points further from the 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. For each route forward. and wait times. Computed at decision points using the composite-cost formula. the process computes the expected cost to the destination for each leg.Public Transport Program Theory 12 “SFM and SFCM examples” on page 809. the process combines the costs to form a single value for the expected cost to destination from a single point. without separating by mode. However. the process uses this generalized cost for calculating the probability that passengers will use alternative routes. the process allocates specific routes. transit. At points close to the destination. Adding new services or improving existing services does not increase the cost—improving service enhances passenger utility. the cost of the leg is the cost to reach the destination. the process computes the expected cost to destination. 12 Public Transport Program Theory At choices between walking and alighting transit. the process uses logit models. Then. 802 Cube Voyager Reference Guide . In calculating the transit element of the expected cost to destination. the process combines the values for the transit alternatives into a single value for the expected cost from the node to the destination.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. producing a single value that represents the set of alternatives: – 1. The logit composite cost formula combines costs. Specifically. This is calculated as the average of the costs associated with each alternative (weighted by the probability of passengers taking the alternative). 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 applies an additional condition to ensure that adding (or improving) services does not increase costs. 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. 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.0 C ( comp ) = --------. This set of services is known as the basic choice set. or walk to another stop for the next transit leg. board a different line at that stop. This model has a logit structure: i ai e P ( walktoi ) = ----------------------------------------------– λ ( CW i + αECD j ) e – λ ( CW + αECD ) ∑ j Cube Voyager Reference Guide 803 . when passengers leave the origin or alight from a service. 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.Public Transport Program Theory 12 Models applied at decision points This section describes the mathematical models that calculate the conditional probabilities for choices made at a route’s decision points. For example. they might walk to their destination. 12 Public Transport Program Theory 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. Next. represents the true cost to the destination (or trip cost). calculated as part of any logit model. For example. To adjust for an ALPHA value less than 1.0.0. and has a different numeric value from the discounted form. shown above. the process uses ALPHA to calculate the value of choice for the walk-choice model. The composite-cost specification. is the expected (generalized) cost to destination from j. the process subtracts this value of choice from the average cost (evaluated with ALPHA set to 1. represents the value of choice. the cost from the end of the walk leg to the destination is discounted. CWi α ECDi ECDj Composite cost adjustment for ALPHA The difference between the average and composite cost values. the process estimates a composite cost consistent with the nondiscounted cost to the destination. 804 Cube Voyager Reference Guide . a traveller’s willingness to walk may relate to familiarity with the network.0) to estimate the nondiscounted (true) composite cost. lower values indicate that the walk cost has more influence than onward cost in the traveller’s choice. or the benefit travelers gain from choosing between available alternatives. A value of 1 indicates that the walk and onward costs have equal weight. First. is the expected (generalized) cost to destination from i. When the ALPHA value that the walk-choice model uses is less than 1. Thus. Conversely.Public Transport Program Theory 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.2. The Y-axis shows the proportion of trips allocated to the longer choice when a binary choice is available. the longer route gets 26.5.0.67% of trips. The diagram plots three different values for the scaling factor: 0. Impact of the different values of scaling factor LAMBDAW The X-axis shows the difference between the time by service i. 0. longer routes get a larger share of the trips as the scaling factor is reduced.2. more trips are allocated to the best route.5 shows that a choice five minutes longer than the best would be allocated 7. the longer route gets only 0. Cube Voyager Reference Guide 805 . Large the scaling factors produce a smaller spread of trips between alternatives—that is. low scaling factors produce trips spread over a wider range of alternatives. With a scaling factor of 0.6% of the total trips. but with a scaling factor of 1.9% of trips. ECDi. and 1. ECDbest. The curve for LAMBDAW = 0. and the time by the best service. Service-frequency-and-cost model The service-frequency-and-cost model is an extension of the service-frequency model. Service-frequency model Applied at stops with a basic set of transit choices. which may be different from the basic choice set described in “Deriving cost used” on page 801. This model defines its own set of transit choices. Frequency(line k) is the frequency of line k (in services per hour). and that the traveller is less willing to use slower alternatives. Frequency(line l) is the frequency of line l (in services per hour).12 Public Transport Program Theory Transit choices Two models are available to allocate passengers to the transit choices available at a stop: the service-frequency model (SFM) and the service-frequency-and-cost model (SFCM). the servicefrequency model calculates the conditional probabilities of the individual lines in proportion to their frequency. SFM considers only service frequency while SFCM also considers the cost to the destination. The model assumes that travellers have knowledge of the travel time to the destination associated with each of the alternative routes. 806 Cube Voyager Reference Guide . Frequency lineI P uselineI = ----------------------------------------------Frequency lineK ∑ k where: P(use line l) is the probability of using line l. The model is equivalent to travelers who arrive randomly without knowledge of the timetables and take the first reasonable service forward from the node. See “SFM and SFCM examples” on page 809 for examples that show how the two models treat transit choices at a stop. the model considers the next fastest line. the model adds the line to the set of selected lines and repeats the process. Therefore. the line is valid some of the time. Next. the line is no slower than those already selected).Public Transport Program Theory 12 To define a set of transit choices. Specifically. If that line passes the validity test. Once a line fails the validity test. then the line is not valid. If the excess time is greater than zero but no more than the expected cost of waiting. and any wait factors): • If the excess time has a value of zero (that is. then the line is always a valid choice. excess time divided by the cost of waiting defines the proportion of time that travellers are better off ignoring the line. the frequency of the combined services takes account of probability of use. as follows: Frequency ( combined ) = ∑ P(use l) Frequency(line l) l Cube Voyager Reference Guide 807 . The validity test computes the line’s “excess time” — the difference between its time to destination and the average value for the lines already selected (excluding wait time at the stop). • • As the probability of use varies between lines. considering the next fastest line. the process terminates and the model uses the set of lines currently selected as possible routes to the destination. travellers are better off ignoring this line and waiting for the next service from the selected set. the model selects the line with lowest expected cost to the destination. The test compares the line’s excess time to the expected cost of waiting (which is based on the headway of the combined services already selected. If the excess time is more than the expected cost of waiting. one minus this proportion defines the probability of using the line when its service arrives at the stop. During loading. 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).12 Public Transport Program Theory where: P(use l) Frequency(line l) is the probability of using line l when a service is at the stop. the proportion of demand using a particular line is given by: P (use l) Frequency (line l) Pr (line l) = -------------------------------------------------------Frequency (combined) Alternative alighting choices The route-evaluation process applies the alternative-alighting model when a line has two or more valid alighting points. This model has a logit structure similar to the walk-choice model: e P (alight at i) = -------------------------– λECD j e – λECD i ∑ j 808 Cube Voyager Reference Guide . is the expected (generalized) cost to destination via alternative alighting point j. the service-frequency model allocates the transit demand to the various services at the stop. λ is the scaling factor for the model (LAMBDAA).Public Transport Program Theory 12 where: P(alight at i) is the probability of alighting at stop i. Opportunities for transfer At transfer points between transit services. the walk-choice model allocates demand between true walk alternatives and an imaginary alternative that represents the transit services available at the node. Next. see “Impact of the different values of scaling factor LAMBDAW” on page 805. For an example. First. the route-evaluation process applies a combination of models. NOTE: LAMBDAA affects the choice of alighting points just as LAMBDAW affects walk choices. ECDi ECDj is the expected (generalized) cost to destination via alternative alighting point i. SFM and SFCM examples This section provides examples of the service-frequency model and the service-frequency-and-cost model: • • Example of the service-frequency model Example of the service-frequency-and-cost model Example of the service-frequency model This example shows: • • Choices available Results of the service frequency model Cube Voyager Reference Guide 809 . 545 20.0 810 Cube Voyager Reference Guide . with the addition of each line. A wait factor of 2 was used to weight the waiting times.385 25.357 0.0 26.0/(4) * 0.429 0.0 25.5 * Wait Factor Column (6) = (2)*(3).12 Public Transport Program Theory 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. the overall time to destination improves.286 4.286 25. Column (5) = 60.333 (9) Include Line Y Y Y Y N Notes: • Lines 1-4 are included in the basic choice set because.0 Cum Travel Time 100 226 270 294 320 (7) Average Travel Time 20 20.143 0.455 4.615 4.769 21 21.0 5.0714 0. Line 5 is excluded from the basic choice set because including it makes the time to destination worse.333 (8) Travel + Wait Times 32. 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. 798 1 1.0/(7) * 0.868 1 0.742 0.500 11. accumulated over lines Column (9) = 60.983 12.52 20.293 5.1) Column (8) = (2)*(7). accumulated over lines) / (8) Cube Voyager Reference Guide 811 .326 - 12 5.707 20.007 4.714 5.48 3.5 * Wait Factor Column (10) = ((2)*(3)*(7).007 4.202 12 5.714 5.Public Transport Program Theory 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.917 0.342 0 5 10. Column (7) = 1-MIN( (5)/(6)).707 20.868 - 20 20.52 20.798 Notes: • • • • • Example uses a wait factor of 2 to weight the waiting times. the program can provide several skims.983 12. operational statistics. 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.406 0.500 11.483 0. Because the Public Transport program finds multiple routes between zone pairs.120 0.12 Public Transport Program Theory Results of the service frequency & cost model (3) (2) (1) Line 1 2 3 4 5 Line frequency 5 6 2 1 1 Effective frequency at stop 5 5.028 - Notes: Column(5) = (3)/cumulative frequency at stop Skimming process The skimming process extracts the cost of a public transport trip into a zone-to-zone matrix.343 (4) Cum frequency at stop 5 10. 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.446 0.500 1. 812 Cube Voyager Reference Guide .326 (5) Proportion of trips 0. The skim calculates composite costs from each decision point in the trip to the destination. With more low-cost choices. also referred to as the expected cost to destination (see “Deriving cost used” on page 801 for a description of how they are derived). the skim ensures that adding new routes or improving services does not lead to an increase in the cost.Public Transport Program Theory 12 Composite-cost skim For each zone pair. Cube Voyager Reference Guide 813 . To enable you to model demand or evaluate schemes. 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. or the total utility of the trip including the choices available to the traveller. or choices where the lesser alternatives are considerably more expensive than the best route. The value-of-choice skim is equivalent to the difference between the composite-cost skim and the average-generalized-cost skim. the value-of-choice skim computes the value of choice. whereas lower values indicate a lack of route choice. The value of choice provides a measure of the resilience or robustness of the public transport system. The route-evaluation process uses composite costs. the composite-cost skim computes the composite cost. a measure of the extent to which travellers can choose between alternative routes. the system can continue functioning following the failure of one or more components. Higher values indicate travellers can choose between routes of similar costs. the best-trip skim computes the actual time for the best route (that is. such as passenger miles. the time if travellers make the best choice at every decision point).12 Public Transport Program Theory Average skims Average skims compute the costs a typical traveller incurs while making a public transport trip. average skims can compute costs other than wait time by mode. Average skims are appropriate for model validation and skimming operational statistics. and revenue. average skims weighting each route according to its probability of use. There are three broad areas: • Time Walk (nontransit) Wait In-vehicle • Inconvenience Boarding Transfer • Cost Fare Because multiple routes might connect zone pairs. hours. Several average skims can compute either actual values—true measures of the cost—or perceived values—the cost’s contribution to generalized cost (usually a product of the cost and a weighting coefficient). Best-trip skim For each zone pair. Within each route set. You can extract average skims for all components of the trip. 814 Cube Voyager Reference Guide . Average skims compute component costs at network and route-set level. therefore. Cube Voyager Reference Guide 815 . calculated during the route-evaluation process. The skim bases the wait time and the transit-leg time on the lowest expected values. The process assigns the zone pair’s trips to the available routes according to each route’s probability of use.Public Transport Program Theory 12 Because the skim uses actual values for all trip components. walk (nontransit) legs have only one time attribute. The loading process uses routing and travel time information obtained from the route-evaluation process. See “Walk time (nontransit time)” on page 772. NOTE: At present. The skim computes wait times from the appropriate wait curve. the skim does not reflect traveller behavior. to services (transit lines) and nontransit legs. inappropriate for demand modeling. the one used to construct them (perceived time). The skim computes transit-leg times from the fastest line in the leg-bundles used. and is. using the combined frequencies of all acceptable lines from the node towards the destination. The loading process considers one origin-destination zone pair at a time. Loading process The loading process (assignment) allocates trips. either computed or from the input trip matrix. consider the reports of enumerated and evaluated routes between zones 1 and 3. 816 Cube Voyager Reference Guide .631438 1 -> 773 773 -> 759 -> 759 lines GMB1-24MB 759 -> 875 -> 875 lines RES34R 875 -> 749 -> 3 lines GMB1-2B Cost= 28.12 Public Transport Program Theory For example. The enumerated-routes report shows used costs. The second report lists the routes with their probability of use.668 1 -> 773 773 -> 759 -> 759 lines GMB1-24MB 759 -> 875 -> 875 lines RES34R 875 -> 749 -> 3 lines GMB1-2B Cost=34. none are eliminated. 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.142594 1 -> 2052 2052 -> 2004 -> 875 lines ISL-DN 875 -> 749 -> 3 lines GMB1-2B Cost= 30.668 Probability=0.04 Probability=0.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. However.225968 The first report shows three bundles of enumerated routes from zone 1 to zone 3.028 1 -> 2052 2052 -> 2004 -> 875 lines ISL-DN 875 -> 749 -> 3 lines GMB1-2B Cost=31.628 Probability=0. All routes meet the evaluation criteria. the loading process assigns travelers to transit line ISL-DN for the trip to node 875. From node 751. all trips arriving at node 773 board this service.774032. and alight at node 749 where they walk to zone 3. The loading process considers two walk choices from zone 1: to nodes 773 and 2052. The time via 764 is less than the time via 759. not the composite costs used to calculate the probability of use. The process saves the number of trips assigned to the four transit legs for each leg. • At node 2052.225968. travelers go to zone 3 via node 749 and line GMB1-2B. Thus the probability of using node 764 is 0. These are saved for the nontransit (egress) leg 749-3. while the probability of going to node 2052 is 0. All trips from zone 1 to 3 use line GMB1-2B as the last transit leg in the trip. GMB1-24B. and PLB127A in proportion to their relative frequencies for trips to node 751. There are two alighting points: nodes 764 and 759.Public Transport Program Theory 12 the evaluated-routes report shows the average cost for the route bundle. The loading process splits trips at node 773 between the two alighting points and saves the trips for the two transit legs. The loading process splits trips from zone 1 to zone 3 in this proportion and saves the trips for the nontransit (access) legs: • At node 773. The route-evaluation process determined that the probability of going to node 773 is 0. reflecting the shorter time via node 773. the loading process assigns arriving trips to lines PLB1-113B.631438 and the probability of using node 759 is 0. 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 764.142594. Cube Voyager Reference Guide 817 . PLB129B. there is a single transit service. and then to transit line GMB1-2B for the trip to node 749 before ending at zone 3. To incorporate fares. 818 Cube Voyager Reference Guide . 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. 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. you might exclude fares from the route-evaluation process and skim and calculate revenue from the evaluated routes. Therefore. Fares This section describes how to model fares in the Public Transport program. To reduce run times.12 Public Transport Program Theory 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. it is import to incorporate fares fully into the Public Transport modeling process. and the cost of transferring between fare systems (IBOARDFARE. FAREFROMFS) • Cube Voyager Reference Guide 819 . LONGNAME) Unit of measure for trip length. that uses a single transport line. A transit leg is one part of a trip. Transit legs are the basic unit the program uses to calculate fares. If multiple consecutive legs have the same fare system. The program calculates fare for a single leg of the trip. from a boarding point to an alighting point. NAME. The Public Transport program provides a framework which you can use to directly represent or approximate most fare systems. such as distance. HILOW. and how it interfaces with other lines. You define fare system attributes with FARESYSTEM keywords and subkeywords: • • Unique numeric and character identifiers (NUMBER. To model fares. COUNT. FROMTO. the Public Transport program requires a programwide “fare system” that describes each transit line’s individual fare system. or boarding-alighting fare zones. You can specify fare systems and value of time by user class. its data requirements. The program assigns each line to a fare system. or ACCUMULATE) Boarding costs at the initial boarding and subsequent transfers. (STRUCTURE. In fact. with possible values: FLAT. DISTANCE.Public Transport Program Theory 12 The Public Transport program must accurately represent the fare systems that passengers face. number of fare zones crossed. You define fare systems with the FARESYSTEM control statement and input fare systems with the FILEI FAREI file. you can represent different types of fare systems within a single public transport network. either directly or through its mode or operator. the program assumes integrated or through ticketing and calculates fare for that sequence of legs. You might do this to use readily available ticket type data to segment and model demand by ticket type. a table. each line must have an assigned fare system. by selecting skimming functions FAREA and FAREP in the SKIMIJ phase. Include fares in the route-evaluation process by setting PARAMETERS FARE to T. 3 Permitted but use is questionable. The following table provides a quick reference to the various fare systems and their data requirements. FARETABLE. When modeling fares. 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. and FAREMATRIX). The program assigns fare systems to transit lines indirectly through the line’s mode and operator with the FACTORS FARESYSTEM keyword or directly with the LINE control statement. or matrix (UNITFARE. which may be specified with a coefficient per unit measure of the trip.12 Public Transport Program Theory • Trip cost. as it could be included in the FAREMATRIX. Skim fares. 820 Cube Voyager Reference Guide . Requirements can vary from minimal to substantial. FARETABLE.2 One of the two items is required. 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. FAREMATRIX) Rules for computing costs when transferring to the same fare system and interpreting fare tables (SAME. whether or not they are included in route-evaluation. Fares derived by leg using the boarding and transfer costs specified with IBOARDFARE and FAREFROMFS. Description of trip-length units Value of STRUCTURE FLAT Method for calculating trip length and fare Trip length not used for fare calculation. Each value results in a different method for calculating trip length and fare. Fare zones are single nodes or groups of nodes. You specify the trip-length unit with the FARESYSTEM keyword STRUCTURE. Appropriate for an annular fare-zone structure. Trip cost obtained from the fare table specified by FARETABLE. specified with IBOARDFARE and FAREFROMFS (boarding costs are added to the fare matrix) Trip cost. and columns contain the higher fare zone) • Cube Voyager Reference Guide 821 . or fare zones. extracted from the fare matrix specified with FAREMATRIX (rows contain the lower fare zone. There are six possible values. actual distance. in user-specified units. The value of INTERPOLATE determines whether the program uses linear interpolation or a step function between coded points.Public Transport Program Theory 12 Trip length The units for measuring trip-length is a key attribute of the fare system. Fares based on: • Boarding and transfer costs. Fares calculated by leg or for sets of consecutive legs using the same fare system. specified with IBOARDFARE and FAREFROMFS. Fares based on: • • • Boarding and transfer costs. Trip cost computed by multiplying in-vehicle distance by UNITFARE. HILOW Trip length measured by the highest and lowest fare-zones crossed. Trip-length units might be based on legs. DISTANCE Trip length measured as in-vehicle distance. Fares calculated by leg or for sets of consecutive legs using the same fare system. Best suited to a sequential zone system. Fares calculated by leg or for sets of consecutive legs using the same fare system. specified with IBOARDFARE and FAREFROMFS Trip cost. and columns contain the higher fare zone) • ACCUMULATE Trip length measured by accumulating fares associated with each fare zone traversed. where program counts the number of fare zones traversed to compute fare. The fare table has a fare for each fare zone in the system. Fares based on: • • Boarding and transfer costs. Fares based on: • • Boarding and transfer costs. the program interpolates the fare table as a step function. specified with IBOARDFARE and FAREFROMFS (boarding costs are added to the fare matrix). extracted from the fare matrix specified with FAREMATRIX (rows contain the lower fare zone. specified with IBOARDFARE and FAREFROMFS Trip cost. extracted from the fare table specified with FARETABLE. 822 Cube Voyager Reference Guide . extracted from the fare table specified with FARETABLE. Fares calculated by leg or for sets of consecutive legs using the same fare system. Fares calculated by leg or for sets of consecutive legs using the same fare system. In this case. FROMTO Trip length measured as function of the boarding and alighting fare zones. Differs from COUNT. Best suited to a sequential zone system. Trip cost.12 Public Transport Program Theory 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 based on: • Boarding and transfer costs. The program determines trip cost using one of three methods: • UNITFARE — Coefficient used to calculate fares. To obtain fare. If two consecutive legs of a trip use different fare systems. Trip costs Trip cost is a key attribute of the fare system. the program multiplies UNITFARE by in-vehicle distance of a leg or a sequence of consecutive legs using the same fare system. COUNT. See “IBOARDFARE” on page 668. Cube Voyager Reference Guide 823 . where X is the trip length and Y is the fare. the program always calculates the fare separately for each leg. See “FAREFROMFS” on page 665. FAREFROMFS — Fare incurred when transferring from lines using other defined fare systems. Only available when STRUCTURE is DISTANCE. FARETABLE — Table of fares. 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.Public Transport Program Theory 12 Multiple fare systems For public transport networks with multiple fare systems. Define FARETABLE with a • list of paired X and Y coordinates. or ACCUMULATE. You specify boarding and transfer costs with FARESYSTEM keywords: • • IBOARDFARE — Fare incurred upon boarding the first transit leg of a trip. Boarding and transfer costs Boarding and transfer costs are key attributes of the fare system. Used when STRUCTURE is DISTANCE. Fare table for STRUCTURE=DISTANCE and INTERPOLATE=T Fare table for STRUCTURE=DISTANCE and INTERPOLATE=F 824 Cube Voyager Reference Guide .12 Public Transport Program Theory See “FARETABLE” on page 666 for more information about coding FARETABLE. Some graphic examples follow. FROMTO. a node can be in only one fare zone. The program converts fares to generalized costs using the FACTORS keyword VALUEOFTIME. COUNT.Public Transport Program Theory 12 Fare table for fare-zone based fare systems • FAREMATRIX — Matrix of fares. Therefore. Input matrices with FILEI FAREMATI in either standard Cube Voyager binary matrix format or as text records. Fare zones Fare systems that have the STRUCTURE set to HILOW. See FAREMATRIX for information about coding fare matrices. Cube Voyager Reference Guide 825 . or ACCUMULATE require fare zones. but a fare system must have only one zone scheme. You code fares in monetary units. use the REPORT keyword FAREMATI. A public transport network might have multiple fare-zone schemes. To report on fare matrices. Used when STRUCTURE is HILOW or FROMTO. Fare zones are either groups of nodes or single nodes. Add a new node attribute. In the Add Note Network Variable dialog box. Add a new node attribute. and choose Add. 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. From the Node menu. or ACCUMULATE structure 1. COUNT. a. Display the network in Cube. b. To identify and code fare zones for fare systems with a FROMTO. FAREZONE. Display the network in Cube. FAREZONE. one at a time 4. 2. type FAREZONE and click OK. 2. 3. 826 Cube Voyager Reference Guide . Use the Polygon menu to define fare zones.12 Public Transport Program Theory The HILOW structure requires an annular fare zone system while the other structures require sequential fare zones. point to Attribute. Associate the number of the outermost fare zone to the FAREZONE attribute of all nodes. type FAREZONE and click OK. From the Node menu. b. Assign the number of the penultimate fare zone to the FAREZONE attribute of the nodes within the polygon 6. Use the Polygon menu to define a ring separating the outermost fare zone from the other zones.Public Transport Program Theory 12 a. In the Add Note Network Variable dialog box. 4. and choose Add. Example of an annular zone system Cube Voyager Reference Guide 827 . Repeat the last two steps until all fare zones have been completed. 3. point to Attribute. 5. 2. 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. 10.50 FARESYSTEM NUMBER=2. UNITFARE=60 FARESYSTEM NUMBER=3. individually and in combination. 100. 100. 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. 5. MODE=1 FACTOR FARESYSTEM=2.0. STRUCTURE=FLAT. all with STRUCTURE set to DISTANCE but with different unit cost for trip length.75.12 Public Transport Program Theory Examples This section shows how fares are calculated for a four-leg trip using different fare models. NAME=Flat Fare British Rail’. 100 FARESYSTEM NUMBER=2. IBOARDFARE=50. FAREFROMFS[1]=75. IBOARDFARE=100. FAREFROMFS[1]=100. 0. FARETABLE=1. FAREFROMFS[1]=0. 0 FACTOR FARESYSTEM=1. which is the sum of fares for each leg. STRUCTURE=DISTANCE. MODE=2. NAME=’Distance Bus’. 0. FARESYSTEM NUMBER=1. IBOARDFARE=100. SAME=CUMULATIVE. STRUCTURE=DISTANCE.0. 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. for transferring from FARESYSTEM 1 to = = 0 {FAREFROMFS[2] for C-D. IBOARDFARE=100.3. NAME=Flat Fare Underground+Bus’. NAME=’Distance Underground’. STRUCTURE=FLAT. 100. STRUCTURE=DISTANCE.0. FAREFROMFS[1]=0.50. UNITFARE=50 828 Cube Voyager Reference Guide .3 FARE(A-E) = 175 pence. NAME=’Distance British Rail’.0. FAREFROMFS[1]=50. 50. IBOARDFARE=50. 1. MODE=3 FARE(A-E) = 950 pence. row NI.FAREZONE FACTOR FARESYSTEM=1. NAME=’Trip Based’. and the program extracts the fare from fare matrix number 5. Example 3: FROMTO fare system FARESYSTEM NUMBER=1. MODE=1-3 FARE(A-E) = 350 pence. In this example. FAREZONES=NI. MODE=1 FACTOR FARESYSTEM=2. legs B-C and C-D have the same fare system and SAME is set to CUMULATIVE. depending upon the setting of SAME.FAREZONE. There is no cost for transferring from fare type 2 to another leg using the same fare type. input on FAREMATI[1]. STRUCTURE=FROMTO. SAME has no effect in this case because UNITFARE is used rather than FARETABLE. NI. There are no boarding costs or costs for transferring between the same fare system.5. calculated as: Leg A-B = 100 + 350 (IBOARDFARE + trip cost) Legs B-D = 100 + (5*60) (FAREFROMFS[1] + total distance * UNITFARE) Leg D-E = 50 + (1*50) (FAREFROMFS[2] + total distance * UNITFARE) NOTE: Where two consecutive legs have the same fare system. so the fare is calculated for B-D. FAREMATRIX=MI. defines the fare zones for stops A through E.FAREZONE(E). which is the sum of fares for trip legs. 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. MODE=2 FACTOR FARESYSTEM=3. Cube Voyager Reference Guide 829 . the fare can be calculated for each leg separately or cumulatively.FAREZONE(A) and column NI. The node variable.Public Transport Program Theory 12 FACTOR FARESYSTEM=1. FAREZONE FARESYSTEM NUMBER=3. STRUCTURE=FROMTO.FAREZONE(A).1. FAREMATRIX=FMI. NAME=’Underground’. 0.FAREZONE(B)) Leg B-D = -25+200 (FAREFROMFS[1] and FAREMATRIX FMI. row NI. FAREFROMFS[1]=-25.FAREZONE(D)) Leg D-E = 50 + 1*50 (FAREFROMFS[2] + trip cost) Crowding An iterative process.2. FAREZONES=NI.FAREZONE(B). 0.FAREZONE FARESYSTEM NUMBER=2. NAME=’British Rail’. calculated as: Leg A-B = 250 (FAREMATRIX FMI. FAREMATRIX=FMI.UndGrnd. as calculated during route evaluation. NAME=’Bus’. FAREZONES=NI. STRUCTURE=FROMTO. STRUCTURE=DISTANCE.1. or when in crowded vehicles. FAREFROMFS[1]=50. -25.2.BritRail. The Public Transport program supports two types of crowd models: • • Link-travel-time adjustment Wait-time adjustment This section also discusses: • Crowding process Link-travel-time adjustment A link-travel-time adjustment models a passenger’s perception that travel time is more onerous when standing (rather than sitting). IBOARDFARE=50.BritRail. crowd modeling enables a public transport system’s capacity to influence the system’s travel times and thus the routes found and their probability of use.UndGrnd. Specify this adjustment with a “crowding factor.12 Public Transport Program Theory FARESYSTEM NUMBER=1. which is the sum of fares for legs. FAREFROMFS[1]=0. column NI. column NI. UNITFARE=50. 0. SAME=CUMULATIVE. row NI. 0 FARE (A-E) = 525 pence. 50.” 830 Cube Voyager Reference Guide .” The program multiplies the crowding factor by in-vehicle time to determine the perceived “crowded in-vehicle time. 0 for the first few standing passengers. Once standing starts. 34 seats—are occupied). the crowding factor might increase slowly from 1. and load distribution factor of 0.85 (standing occurs when more than 85% of 40—that is. Example of crowding factor values (as a function of vehicle load) Cube Voyager Reference Guide 831 . crush capacity of 50. then more steeply once vehicle loading exceeds 40. suppose a vehicle has a seating capacity of 40.Public Transport Program Theory 12 For example. Utilization.0 for standing passengers when the vehicle is fully loaded with standing occurring. and a user class.0 to 1. crowding curves show utilization on the X-axis. c) for utilization U U is the utilization measure (as a percentage) 832 Cube Voyager Reference Guide . The corresponding crowding curve is shown below.4 for seated passengers and 1. v. Crowding curve definition. The program calculates crowded link travel time as: T c = T u CCrv v.5 to 3. Derived from the crowd-factor curve.0 in uncrowded conditions. c ( U ) where: Tc Tu is the crowded link travel time is the link travel time (in uncrowded conditions) CCrvv. the percentage of standing places occupied.c (U) is the crowd curve value (where the curve is specific to a vehicle type. can vary between 0 and 100. as a function of utilization Crowd factors are 1. and typically rise to values in the ranges 1.12 Public Transport Program Theory The Public Transport program uses crowding curves. LDFv is the load distribution factor for the vehicle type. this becomes less realistic. As loadings on services increase. this is the total of seated and standing capacities. Wait-time adjustment The wait-time adjustment reflects the ability to board a service. as travellers will choose the first appropriate service that has available capacity. is the seating capacity (per hour) for the line. U. 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 loads increase this is the proportion of seats occupied when standing starts to occur. With heavily loaded services. Cube Voyager Reference Guide 833 . is defined by the expression: P – ( LDF v SeatCap ) U = -----------------------------------------------------------------------CrushCap – ( LDF v SeatCap ) where: P SeatCap is the passenger demand (per hour). If the values of seating capacity and crush capacity are identical for any line. and 0% otherwise. CrushCap is the crush capacity (per hour) for the line.Public Transport Program Theory 12 The utilization measure. some travellers will wait for the next service. Using measures of demand and available capacity. (Note: the LDF value specified in commands is coded as the corresponding percentage.0. incurring additional wait time at the boarding node. the wait-time adjustment computes the probability of being able to board a service.) 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). then utilization is 100% whenever demand exceeds the seating capacity. It may be less than 1. indicating that standing occurs before all seats are used. The demand remaining at the end of the modeled period would discharge once peak travel volumes subside. those travelers experience additional delays. “Flow metering” handles the bottleneck effect and the inability of demand to pass through that point. 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. the program assigns demand with the servicefrequency model (SFM). 834 Cube Voyager Reference Guide . thus demand at any downstream point reflects the number of travellers who can reach that point. If demand exceeds capacity and no alternative routes are available. demand unable to reach its destination due to network bottlenecks). resulting in diversion of demand to other enumerated routes for the origin-destination pair. which form a second component to the wait-time adjustment. Flow metering removes the excess demand from later stages in the trip.12 Public Transport Program Theory Without crowding. or service-frequency-and-cost model (SFCM). the program can calculate the proportion of flow-metered demand (that is. 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. and the number of trips affected. For any origin-destination pair. those travellers incur additional wait time. The additional wait time might make this route less attractive. then this transit leg acts as a “bottleneck”—not all of the travel demand is able to use the service during the modeled period. Crowded networks might cause instabilities in the loadings between iterations. 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. In turn. or might continue oscillating. oscillation is more likely in highly overloaded networks. and thus less attractive at the next iteration. as demand switches toward less congested routes.Public Transport Program Theory 12 The crowding process is viewed as a stochastic assignment. These changes might converge toward a solution. those routes might become more heavily loaded. and results are obtained from the final iteration. Cube Voyager Reference Guide 835 . based on data values stored in the input network 836 Cube Voyager Reference Guide .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. You can create a screenline file with: • • Cube. Screenline data files specify the links that compose each screenline and contain associated data. Cube Analyst uses screenline count data to update a “prior” matrix. See Cube Analyst Reference Guide for detailed information about the methods used. 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. and read the file in to the Public Transport run Public Transport run. Confidence levels determine how much each input influences the estimation process. such as link counts and confidence levels. Matrix estimation requires an intercept file. Confidence levels reflect the accuracy of count data and affect the weighting during the estimation process. A run of the Public Transport program produces the intercept file. or text-file editors. which provides data on routes crossing the defined screenlines for each origin-destination pair. All control statements available in the Public Transport program are described in “Control statements” on page 632. and CROWDCRVDEF LINE NT Cube Voyager Reference Guide 837 . WAITCRVDEF. the script must specify a FILEO INTERCEPTO command. VEHICLETYPE. This section shows which files contain which data items. MODE. Defining input and output files You define input and output files for the Public Transport program with control statements FILEI and FILEO. To configure the intercept file to contain only transit use of the links. 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. and not in the script file. the software may save just a screenline output file without performing any route evaluation. use the MEUSESNT keyword on PARAMETERS and FILEO SCREENLINEO commands. For a Public Transport run to produce matrix estimation data. These are present in the main script file. LINE. OPERATOR. These are usually contained in files defined by FILEI and FILEO. and NTLEGS). and confidence level. link count. Alternatively.Public Transport Program Using the Public Transport program 12 Link variables in the input network contain the screenline number (zero if the link is not part of a screenline). Use control statements to define input and output data items (that is. transit plus nontransit use of all links). along with either a FILEI SCREENLINEI or a FILEO SCREENLINEO command. or all demand (that is. 12 Public Transport Program Using the Public Transport program Linking Highway and Public Transport models In studies that model both highway and transit demand. which provide control values. transit-line run times are influenced by the highway network’s congestion levels. However. The Public Transport program calculates a line’s travel times using TRANTIME (a global parameter that represents link travel times). Link travel times include link delays. Junction delays can affect transit vehicles. RT. LINE definitions can include RUNTIME. junction delays. Cube Voyager can export junction delay data from Highway program runs. TRANTIME and junction delays are network components. and dwell time values. though provisions like bus-only lanes can reduce or eliminate such delays at particular locations. or NNTIME keywords. 838 Cube Voyager Reference Guide . you can link the two models. link delay. When junction delays are included. and trip time also includes junction delays. To model bus-only lanes or other provisions designed to reduce transit-line delay at junctions. For networks with congestion. and include these delays in the run times of transit lines. Transit vehicles travel through junctions and take some of the junction capacity. because Highway assignment does not support turn-based preloads. You might use control values in base-year models to ensure that the line’s travel time matches an expected value. and delay and dwell time are line components. The Highway program can export delays for turning movements to a TURNPENO file. The program scales the line’s travel times up or down to match these control values. a typical highway model estimates delays on links and 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. The Public Transport program can then read this file. Cube Voyager cannot import transit-vehicle turn volumes from Public Transport to Highway. You might model turning delays at a transit line’s last node. When reading LINE data from a network file. Typically. modeled stops are close to a junction node. Instead. nodes/stops. The program calculates the line’s travel times for the base year. This network can contain any node and link attributes you choose. produced specifically for modelling a public transport system Cube Voyager Reference Guide 839 . You should configure the model to read the TURNPENI file at the same time as the LINEI files. and compares these times to the control values to generate scaling factors for the increase or decrease in travel times. Coding network times/speeds The Public Transport program requires a network that provides the basic infrastructure over which public transport services operate— zones. the program has already calculated link travel times and cannot amend turn penalties. The method uses two sets of TURNPENI data. even though the vehicle does not pass through the node. links. the program adds the entire junction delay to the travel time of the link approaching the modeled junction. any changes reflect increases and decreases in junction delay along the route. the program does not scale dwell times and junction delays. Because the program does not scale these travel times to control totals. you cannot code the time as part of the line.Public Transport Program Using the Public Transport program 12 For forecast years. Possible sources of the network include: • Network program. when you do not know the line’s travel time. each with its own MAXDELAY variable (to reflect possibly different bus-lane provisions each year). The program applies scaling to link travel times and delay values. Therefore. The program accounts for such delays as occurring before the line reaches its final stop. the program determines travel times with an incremental approach. The program adds that node’s lowest turning delay to the travel time along the final link. The program applies these factors and the forecast-year junction delays to compute the line’s travel times in the forecast year. to skim distance from routes.TIME_CONGESTED (assuming the links contain a variable named TIME_CONGESTED). The program uses link distance to calculate link times when you provide only speeds. and walk and transit times or speeds.DISTANCE or another variable from which distance can be derived). Create a network variable that stores transit speeds with the Network program.12 Public Transport Program Using the Public Transport program • • Existing highway network produced by the Network or Highway programs Public Transport program.) You can use different techniques to specify a link’s transit time. • 840 Cube Voyager Reference Guide . in which case only the network information is used (the public transport element is discarded) The network must provide basic link attributes that support the Public Transport program’s modelling functions: link distance. (You can factor each line’s base linktime in a variety of way. as described in “LINE” on page 720. This is supplied to the program with PARAMETERS TRANTIME. Possible techniques include: • Set a link’s transit time to the congested time resulting from a highway assignment: TRANTIME = LI. Subsequent sections in this topic offer guidance on how to code transit and nontransit times and/or speeds in the network: • • Transit times/speeds Nontransit times/speeds Transit times/speeds The Public Transport program requires a base transit time for links that public transit lines traverse. and to calculate fares for distancebased fare models. Link distance is required (specified by LI. you can loop through all the links in the network and set desired link values. you must ensure that you use costs—perceived or actual—consistent with the cost components that the routeenumeration and route-evaluation processes use.TTIME • TRIPS users only.TTIME = LI.SPEED endif ENDPHASE PARAMETERS TRANTIME=LW. However.2 else LW. When developing the nontransit network outside the Public Transport program.SPEED * 1.DISTANCE *60 / LI. Keywords in the GENERATE statement set the method for obtaining nontransit legs.DISTANCE*60/LI. 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. Nontransit times/speeds You can develop nontransit legs outside the Public Transport program. The Network or Public Transport programs can derive transit and nontransit link times from the link record’s link-type field and the LTYP data in the lines file. As in the LINKREAD phase. For example: PHASE=LINKREAD if (link condition…) LW. you might need to precede the GENERATE statement with a script that manipulates link attributes. inside the Public Transport program.TTIME = LI. Input the TRIPS link records directly to the Network program to create a Cube Voyager network. Regardless of the process. Cube Voyager Reference Guide 841 . or some combination.Public Transport Program Using the Public Transport program 12 (If the highway network stores public transport links. See “Example 2: Preparing a public transport network from TRIPS link data” on page 851. you must use GENERATE statements within the DATAPREP phase to develop a nontransit network. 66 ONEWAY=T XN=4268 4269 4270 4271 15687 8710 8709 4273 4274 NT LEG=1-4309 MODE=2 COST=2. egress.6 else LW. and transfer legs.20 DIST=3.NTCOST > 100) ENDPHASE Generating nontransit access and egress legs The GENERATE statement is a powerful and flexible tool that generates the components of the nontransit network—access.87 DIST=3. However. EXCLUDE=(LW.03 ONEWAY=T XN=4227 4006 4007 3963 3965 3966 NT LEG=1-4000 MODE=2 COST=1.66 ONEWAY=T XN=4005 4004 15646 4003 15647 3961 NT LEG=1-4143 MODE=2 COST=3. resulting in poor quality routing.12 ONEWAY=T XN=4268 4269 4307 4306 4308 NT LEG=1-4322 MODE=2 COST=3. Example 1: Drive-walk nontransit legs Consider the routes from zone 1 to zone 11 in the network shown.27 ONEWAY=T NT LEG=1-4263 MODE=2 COST=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.NTCOST = LI.66 DIST=2.20 ONEWAY=T XN=4226 4267 4266 4265 4302 4303 4301 4144 4773 NT LEG=1-4227 MODE=1 COST=12.NTCOST * 2.12 Public Transport Program Using the Public Transport program Example: PHASE=DATAPREP LINKLOOP if(link condition…) LW.39 ONEWAY=T XN=4268 4269 4270 4271 15687 8710 8709 4273 4315 4314 4316 4319 842 Cube Voyager Reference Guide .03 DIST=2.96 DIST=0.39 DIST=3. NT LEG=1-3967 MODE=2 COST=2.66 DIST=1. for modes 1 (walk) and 2 (drive).5.12 DIST=2. Travellers access the transit system through nontransit legs generated with two GENERATE statements.8 endif ENDLINKLOOP GENERATE COST=LW.DISTANCE * 1.NTCOST = LI.TIME*3. misuse can generate unnecessary legs. the process will find no routes between the two zones.) Cube Voyager Reference Guide 843 . the last being the egress leg.36 DIST=0. Although a nontransit-only route. they ride a transit line to 4278 and walk to 11 from there. which marks base times for the routeenumeration “spread.Public Transport Program Using the Public Transport program 12 NT LEG=1-4386 MODE=2 COST=3.07 ONEWAY=T NT LEG=4278-11 MODE=1 COST=14. the algorithm will not enumerate that route. NT LEG=4276-11 MODE=1 COST=3.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.” finds that 1->4276 is the best access leg to the public transport system for zone 11.40 ONEWAY=T XN=4268 4269 4307 4306 4308 4309 4774 4349 4775 Travellers egress from the public transport system to zone 11 with the nontransit legs reproduced below. generated by a GENERATE statement. Because travellers cannot cannot walk directly to 11 from 4276. (Where transit alternatives are either not available or not feasible. 1->4276->11 exists. The all-or-nothing process.40 DIST=3. even a nonsensical one. Rather than being an algorithmic problem. In this case. remove the drive accesses and connect zone 1 to the transit system only with walk legs.3364 The fourth route in the list accesses and egresses the transit system at node 4276 and takes a transit line in between. A good nontransit network is essential for identifying good quality routes. REval Route(s) from Origin 1 to Destination 11 1 -> 4322 4322 -> 4280 -> 4280 lines AM4L5 AM4L6.12 Public Transport Program Using the Public Transport program Because the program found a route.2803 1 -> 4276 4276 -> 4278 -> 11 lines AM4L12. 844 Cube Voyager Reference Guide .98 Probability=0. validating and refining the network produced by the GENERATE statements over a few cycles.AM4L18 4280 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 30. then you should consider generating a drive-walk nontransit-only route between zones 1 and 11.AM4L89 4280 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 34.2803 1 -> 4322 4322 -> 4325 -> 4325 lines AM4L5 AM4L6. this arises due to the quality of the input data.42 Probability=0. Otherwise. Removing routes that access and egress the transit system at the same node would alleviate just one symptom rather than the underlying cause. if you allow drive access from zone 1 to 4276.AM4L18 4325 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 30.AM4L89 Cost= 31. You develop a nontransit network through an iterative process.8287 Probability=0.83 Probability=0. the program finds base times at nodes and enumerates and evaluates routes.62 Probability=0.0959 1 -> 4322 4322 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 19. raising questions about the quality of the evaluated routes.0071 1 -> 4276 4276 -> 4280 -> 4280 lines AM4L12. Even when nontransit-only routes are not of interest. If the cost difference between the two is outside the range of the route-enumeration SPREAD. Thus the program will not connect zones by transit. they have to be dealt with. for no apparent reason. and zones may appear unconnected when they are not. Cube Voyager Reference Guide 845 . the program will not enumerate the transit routes either. Thus. and one or more pairs of transit leg bundles and nontransit legs. nontransit-only routes never get enumerated. the last of which is the egress leg.Public Transport Program Using the Public Transport program 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. Nontransit-only routes might be much faster than expected transit routes. No drive-drive routes are generated. the all-or-nothing process determines that the best stop to access line MAIN is 1109.16 ONEWAY=T NT LEG=81-1109 MODE=12 COST=1.65 ONEWAY=T XN=1108 1105 846 Cube Voyager Reference Guide . The program generates several nontransit legs at 1109. including a drive egress: NT LEG=1109-99 MODE=12 COST=1. Therefore.41 DIST=0.68 DIST=0.20 DIST=0.40 ONEWAY=T XN=1094 NT LEG=81-1104 MODE=11 COST=7.47 ONEWAY=T VOL=430 VOLT=430 XN=1104 The transit time from 1109 to 1092 is just under a minute. NT LEG=81-1092 MODE=11 COST=19.53 DIST=0.12 Public Transport Program Using the Public Transport program 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. because the route is so much faster than any of the possible transit routes. when validating a network. because the NT statement identifies the drive-only route. zones 81 and 99 will appear unconnected.19 REval Route(s) from Origin 81 to Destination 99 81 -> 99 Cost= 2. 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). you might establish why zone pairs do not connect. skims.Public Transport Program Using the Public Transport program 12 The best-cost route from 81->99 is to drive from 81 to 1109 and then to 99.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. the route-enumeration and route-evaluation processes enumerate that route: REnum Route(s) from Origin 81 to Destination 99 81 -> 99 Cost=2. However. However. the program will not enumerate the transit routes either. you can leave such zone pairs unconnected. NT LEG=81-99 MODE=14 COST=2. MAXCOST[1]=5.19 Probability=1. unless you define a very large route-enumeration SPREAD. however. However. TONODE=99 This statement generates short drive-only routes between zones that cost 5 units or less. Further.OFFPSPD. Therefore. then drive-only connections between zones should be generated: GENERATE. If. and loads. because this is a nontransit-only route neither the all-or-nothing process nor the enumeration process will enumerate the route. NTLEGMODE = 14.0000 Cube Voyager Reference Guide 847 . nontransit-only routes are required. making any transit-based routes even less competitive. FROMNODE=81. If you are not interested in nontransit-only routes. COST=(li.DIST * 60) /li.19 DIST=0. 19 REval Route(s) from Origin 81 to Destination 99 81 -> 99 Cost= 2. Although the program enumerates transit routes. REnum Route(s) from Origin 81 to Destination 99 81 -> 1109 1109 -> 569 -> 569 lines SMAIN 569 -> 1107 -> 99 lines SMAIN SMAIN Cost=58.61 81 -> 99 Cost=2. the transit routes are much slower than the driveonly one.12 Public Transport Program Using the Public Transport program In this example. the program only uses the drive-only route. fast nontransitonly routes when there are transit alternatives.19 Probability=1. The route-evaluation process discards the other routes because they cannot compete with the drive-only route. 848 Cube Voyager Reference Guide .95 81 -> 1109 1109 -> 1107 -> 99 lines SMAIN Cost=59.0000 You must carefully consider how to model short. nontransit-only routes can result in poor quality routing as described in “Generating nontransit access and egress legs” on page 842. and are only enumerated when SPREADFACT is 1. Undetected.5. 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.Public Transport Program Examples 12 Examples This section contains examples showing different ways to run the Public Transport program. You can only code GENERATE statements in this phase. Cube Voyager Reference Guide 849 . providing the basic infrastructure of zones. The script explicitly codes the DATAPREP phase. Parameter TRANTIME provides the location of transit time in the link record. 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. COST=li. INCLUDELINK = li. TONODE=26-4000 ENDPHASE ENDRUN 850 Cube Voyager Reference Guide . skimming.WalkTime. MAXCOST[1]=16*15.generate xfer non-transit legs list='\nGenerate Transfer Legs' GENERATE. loading.Globals PARAMETERS TRANTIME = li. MAXCOST[1]=16*20.12 Public Transport Program Examples This script produces a public transport network. containing validated input and the described generated components. NTLEGMODE=33.WalkTime>0.FAC FILEI LINEI[1] = ISL_PTLINES.Output files FILEO REPORTO = LDPRN00A. ONEWAY=F. LIST=T. FROMNODE=26-4000.WalkTime.TrnsTime PHASE=DATAPREP .PRN FILEO NETO = LDNET00B. You can also display the network in Cube. route evaluation.Prepare a Public Transport Network RUN PGM = PUBLIC TRANSPORT .NET . INCLUDELINK = li. and loading analyses. You can save this network and for subsequent use by the Public Transport program for route enumeration. COST=li. NTLEGMODE = 34.generate access/egress links list='\nGenerate Zone Access/Egress Legs' GENERATE. LIST=T.Input Files FILEI SYSTEMI = PTSYSTEM.WalkTime>0 .NET .LIN FILEI NETI = LDHWN00A. .PTS FILEI FACTORI[1] =FACTORLD. and transfer links. PHASE=NODEREAD print list=ni. • . identified by link type. ni. and X.Output files FILEO NETO =LDNET00B. “transit” only. . DATAPREP produces some diagnostics and generates access.NTL FILEO REPORTO =LDPRN00A.LIN FILEI NETI = LDHWN00A. TRIPS networks have links.NET FILEO NTLEGO = LDNTL00A. LIST=T FILEI SYSTEMI = PTSYSTEM.xxx. LINKREAD calculates walk and transit times for all links in the network.and generate node variables Nw.xxx. The LINKREAD phase produces walk and transit time fields for each link. the other field contains a zero.y ENDPHASE Cube Voyager Reference Guide 851 . The generation process only includes links with a walk link-time greater than zero. or “both” walk and transit.GLOBALS PARAMETERS TRANTIME = li.NET FILEI FACTORI[1] = FACTORLD.NODEREAD phase loops over nodes.PRN .Input files FILEI LINEI[1] = \ISL_PTLINES.x.FAC.PTS . Can access network node variables N.Prepare a Public Transport Network from TRIPS data RUN PGM = PUBLIC TRANSPORT . The script uses three phases: • • NODEREAD reports the number. egress. For links where only one activity can take place. ni. You can input the TRIPS network directly into the Network program to prepare the base network. that are “walk” only.n.TrnsTime .and Y-coordinates of all nodes in the input network.Public Transport Program Examples 12 Example 2: Preparing a public transport network from TRIPS link data This example prepares a public transport network from TRIPSformatted link data. PHASE=LINKREAD .28.WalkTimePT = 0 if(li.WalkTimePT = 60.2).STFLAG == 'S') lw.RSPDTIME) endif list =li. li.RSPDTIME endif if(lw. Can access network link variables L.LType(3).0 && li. li.(This demonstrates the use of the command LINKLOOP which loops over links) WalkLnkCnt = 0 TrnsLnkCnt = 0 852 Cube Voyager Reference Guide .TrnsTime = 0.LType == 10.RSPDTIME=li. walk only and both walk and .accessed and manipulated and non-transit legs are generated.2).A(9).32) lw.12 Public Transport Program Examples .2) li. .Network and line variables can be . or links with invalid .li. 28. li.this phase is used to generate walk and transit times for . PHASE=DATAPREP .31.29.RDIST/4.RDIST(8.TrnsTime(8.TrnsTime =(60. li.STFLAG == 'S') lw.* lw.31.2).32 && li.28.29.STFLAG ENDPHASE .0 else lw.the links of a TRIPS Public Transport network .2).WalkTimePT = 60.ltype == 10.Count & report number of transit only.28.convert TRIPS distance and speed/time fields from 100dths to units lw.LType == 18) lw.WalkTime(8.WalkTimePT=lw. . lw.RSPDTIME elseif(li.LINKREAD phase loops over links.30.SPDTIME/100.32 && li.generate link variables Lw.31. lw.DATAPREP is the non-transit leg generation/input phase.transit links.xxx and .STFLAG == 'T') lw.xxx.WalkTimePT(8.29.RDIST/lw.B(9).links with LT codes 10.TrnsTime(8.* lw.DISTANCE(8.29.32 are walk only lw. endif if(li. lw.RSPDTIME elseif(li. lw.18. If no walk or transit links.LType == 10.time. the run is aborted with a suitable message .* lw.TrnsTime != 0.31.RDIST=li.RDIST/lw.TrnsTime = lw.DISTANCE/100.2). TrnsTime endif ENDLINKLOOP PRINT LIST = '\nNumber of walk only links = '. '\n' . INCLUDELINK = lw. COST=lw.a. lw.Generate xfer non-transit legs list='\nGenerate Transfer Legs ' GENERATE. LIST=T. FROMNODE=26-4000. COST=lw. NTLEGMODE = 34.TrnsTime > 0. ONEWAY=F. INCLUDELINK = lw. BothLnkCnt. li.WalkTimePT>0 . TrnsLnkCnt.WalkTimePT.0) BothLnkCnt = BothLnkCnt+1 else ErrLnkCnt = ErrLnkCnt+1 PRINT LIST = li. LIST=T.Public Transport Program Examples 12 BothLnkCnt = 0 ErrLnkCnt = 0 LINKLOOP if(lw.Generate access/egress links list='\nGenerate Zone Access/Egress Legs ' GENERATE.0 && lw. MAXCOST[1]=16*20. NTLEGMODE = 33. WalkLnkCnt.WalkTimePT == 0.0 && lw.0) WalkLnkCnt = WalkLnkCnt+1 elseif(lw. '\nNumber of transit only links = '.WalkTimePT>0.0 && lw.TrnsTime == 0. lw.WalkTimePT. '\nNumber of walk and transit links = '.b.TrnsTime > 0.Note if and 'if' statement does not fit on one line and closing 'endif' . TONODE=26-4000 ENDPHASE ENDRUN Cube Voyager Reference Guide 853 .WalkTimePT. MAXCOST[1]=16*15.WalkTimePT > 0.WalkTimePT > 0.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 .0) TrnsLnkCnt = TrnsLnkCnt+1 elseif(lw. avg .transfer wait time. Skim functions select the skims for extraction. IWAITP.Skim Route Attributes from a previously prepared Public Transport network RUN PGM=PUBLIC TRANSPORT . evaluated and skimmed before this phase.Input files FILEI NETI = LDNET00B. BESTJRNY.initial wait time. BRDINGSAM. (Skimming automatically invokes the route-evaluation process. DEC=22*2 FILEO ROUTEO[1] = LDRTE00B.SKIMIJ loops over IJ pairs.12 Public Transport Program Examples Public transport skimming This example extracts skim or level-of-service matrices. avg . DISTAM. The ROUTEO file indicates that the script will enumerate routes. Skim are saved in working matrices. BRDINGSTM.RTE . ValOfChoice. A previously prepared public transport network is input with NETI. XFERPENAM. . reports them.NET . NAME = Compcost. you could input routes prepared in an earlier run with ROUTEI.Output files FILEO REPORTO = LDPRN00A. avg .11-23.PRN FILEO MATO[1] = LDMAT00E. perceived.time for all modes. actual. perceived. (Alternatively.MAT. TIMEPNTM. . BRDPENTM.Routes are enumerated.) The SKIMIJ phase selects skimming. which the script must explicitly code. XWAITP.composite cost MW[3]=ValOfChoice(0) . TIMEPTM. TIMEATM. XFERPENTM. XWAITA. TIMEAAM. avg . MO=2-9. IWAITA. DISTNTM. PHASE=SKIMIJ MW[2]=COMPCOST(0) . actual.value of choice MW[4]=IWAITA(0) MW[5]=XWAITA(0) MW[6]=IWAITP(0) MW[7]=XWAITP(0) MW[8]=TIMEA(0.ALLMODES) .transfer wait time. BRDPENAM.) The optional MATO phases reports skims.initial wait time. TIMEPAM. and saves them to the file indicated by MATO[1]. actual 854 Cube Voyager Reference Guide . You must enumerate and evaluate routes before extracting skims. DISTTM. TMODES) perceived. . perceived.2 FORM=10. BASE1=T.above.in-vehicle time for transit modes.MATO loops over J for each I. All skims extracted above are reported PHASE=MATO if(ROWSUM(2) if(ROWSUM(3) FORM=10. BASE1=T.8. avg .ALLMODES) MW[12]= TIMEP(0.2 FORM=10.best travel time . avg .number of boardings for all modes. 1. . > > > > 0) 0) 0) 0) PRINTROW PRINTROW PRINTROW PRINTROW mw=4 mw=5 mw=6 mw=7 TITLE='IWAITA'.ALLMODES) MW[19]= DIST(0.2 > 0) PRINTROW mw=3 TITLE='ValOfChoice'. avg MW[11]=TIMEP(0. . avg MW[23]=BESTJRNY ENDPHASE .number of boardings for transit . TITLE='IWAITP'.7. avg .transfer penalty for all modes.ALLMODES) avg MW[22]= BRDINGS(0. .in-vehicle distance for transit .distance for all modes.1.33. TITLE='XWAITA'.ALLMODES) MW[15]= BRDPEN(0.7. . MW[13]= TIMEP(0.boarding penalty for transit modes.walk/ride distance for non-transit . ALLMODES) actual.transfer penalty for transit modes.TMODES) modes. TITLE='XWAITP'. BASE1=T.boarding penalty for all modes.time for all modes. FORM=10.avg .TMODES) avg MW[16]= XFERPENA(0. same as . BASE1=T.avg MW[14]= BRDPEN(0. . avg MW[20]= DIST(0. avg MW[17]= XFERPENP(0.TMODES) modes.perceived. FORM=10.Public Transport Program Examples 12 MW[9]=TIMEA(0.11) perceived.-35) .2 if(ROWSUM(4) if(ROWSUM(5) if(ROWSUM(6) if(ROWSUM(7) > 0) PRINTROW mw=2 TITLE='Compcost'. avg . . MW[18]= DIST(0.-8.walk/ride time for non-transit modes.11) actual. avg MW[21]= BRDINGS(0.in-vehicle time for transit modes.2 FORM=10.NTMODES) modes. BASE1=T. BASE1=T.2 Cube Voyager Reference Guide 855 . 2 if(ROWSUM(17) FORM=10. > 0) PRINTROW mw=18 > 0) PRINTROW mw=19 > 0) PRINTROW mw=20 TITLE='DIST ALLMODES'. TITLE='TIMEP TMODES'.2 if(ROWSUM(15) FORM=10.2 if(ROWSUM(18) FORM=10.2 if(ROWSUM(20) FORM=10. > 0) PRINTROW mw=21 > 0) PRINTROW mw=22 > 0) PRINTROW mw=23 TITLE='BRDINGS ALLMODES'. BASE1=T. BASE1=T. BASE1=T.12 Public Transport Program Examples if(ROWSUM(8) FORM=10. BASE1=T. TITLE='BESTJRNY'. FORM=10. TITLE='BRDINGS TMODES'. BASE1=T. BASE1=T. TITLE='XFERPEN ALLMODES'.2 if(ROWSUM(13) FORM=10. BASE1=T. TITLE='BRDPEN TMODES'.2 if(ROWSUM(12) FORM=10.2 if(ROWSUM(11) FORM=10. TITLE='TIMEP NTMODES'. BASE1=T. 856 Cube Voyager Reference Guide .2 if(ROWSUM(19) FORM=10. BASE1=T. TITLE='DIST TMODES'. TITLE='TIMEA TMODES'. on to a previously prepared public transport network. BASE1=T.2 if(ROWSUM(16) FORM=10. BASE1=T. TITLE='XFERPEN TMODES'. BASE1=T.2 if(ROWSUM(14) FORM=10. BASE1=T. BASE1=T. TITLE='DIST NTMODES'. > 0) PRINTROW mw=14 > 0) PRINTROW mw=15 > 0) PRINTROW mw=16 > 0) PRINTROW mw=17 TITLE='BRDPEN ALLMODES'.2 if(ROWSUM(21) FORM=10. BASE1=T. > 0) PRINTROW mw=11 > 0) PRINTROW mw=12 > 0) PRINTROW mw=13 TITLE='TIMEP ALLMODES'. input with MATI[1].2 Public transport loading This example loads a trip matrix.2 if(ROWSUM(9) FORM=10.2 if(ROWSUM(23) ENDPHASE ENDRUN > 0) PRINTROW mw=8 > 0) PRINTROW mw=9 TITLE='TIMEA ALLMODES'.2 if(ROWSUM(22) FORM=10. RTE FILEO REPORTO = LDPRN00B. SKIP0=T ENDRUN Public transport user classes This example prepares a public transport network.1 . skims. Essentially. you can input routes prepared in an earlier run with ROUTEI. LINEVOLS=T.Output Files FILEO NETO = LDNET00C.NET FILEO ROUTEO[1] =LDRTE00C.1. enumerates and evaluates routes. SORT=MODE.) The REPORT statement selects two loading reports—line summary and passenger loading. STOPSONLY=T.PRN . /*Load a previously built PT Network & Produce Loading Analyses Reports */ RUN PGM=PUBLIC TRANSPORT .Public Transport Program Examples 12 You must enumerate and evaluate routes before loading trips.Globals this invokes Loading PARAMETERS TRIPSIJ[1] = MI. The ROUTEO file indicates that the script will enumerate routes. and loads for two user classes. (Alternatively.MAT FILEI NETI =LDNET00B.Input files FILEI MATI[1] = OD. this example performs the main functions of the Public Transport program for two user classes. First.NET .) TRIPSIJ[1] indicates that loading is to be performed. 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] Cube Voyager Reference Guide 857 .Selection of Loading Reports REPORT LINES=T. (Loading automatically invokes the route-evaluation process. FAC FILEI FACTORI[1] = FACTORUS1. . Enumerate. Evaluate Routes.MAT FILEI MATI[1] = MSMAT00B.MAT FILEI SYSTEMI = PTSYSTEM.12 Public Transport Program Examples • • Public Transport system data input on SYSTEMI GENERATE statements for generating the nontransit network The script codes the DATAPREP phase.RTE FILEO NETO = LDNET00E. Next. a mandatory phase for public transport network development. the script saves a public transport network containing the results of the loadings for both user classes to NETO. and reports.Generate Non-transit network.PTS FILEI FACTORI[2] =FACTORUS2.RTE FILEO ROUTEO[1] = LDRTE00A. You can display the results with Cube. Loading — Loads trip matrices input on any MATI file (not necessarily the one subscripted by the user class) to the evaluated routes. the script performs the following functions for each user class: • • • • Route enumeration — Saves routes on ROUTEO[1] and ROUTEO[2]. The script codes the MATO phase to report the output skim matrices.NET :input FILEI MATI[2] = MSMAT00B. Skim and Load for two User Classes. Route evaluation Skimming — Extracts composite and value-of-choice skims.FAC 858 Cube Voyager Reference Guide . saves on MATO[1] and MATO[2]. Finally. RUN PGM=PUBLIC TRANSPORT :Output Files FILEO REPORTO = LDPRN00A.PRN FILEO ROUTEO[2] = LDRTE00D. Skims are saved in working matrices in this phase PHASE=SKIMIJ MW[1]=COMPCOST(0) . INCLUDELINK = li.composite cost MW[2]=ValOfChoice(0) .Globals PARAMETERS PARAMETERS PARAMETERS PARAMETERS TRANTIME=li. ONEWAY=F.Routes are enumerated.01.2 TRIPSIJ[1] = Mi.LIN FILEI NETI =LDHWN00A.MATO loops over J for each I. COST=li. FORM=10. TONODE=26-4000 ENDPHASE ' .2 ENDPHASE Cube Voyager Reference Guide 859 .WalkTime.1 PHASE=DATAPREP . MAXCOST[1]=16*15.WalkTime>0 . FROMNODE=26-4000.Public Transport Program Examples 12 FILEI LINEI[1] = ISL_PTLINES.02. LIST=T.WalkTime>0. NTLEGMODE = 34.TrnsTime USERCLASSES=1. COST=li.value of choice ENDPHASE . BASE1=T.SKIMIJ loops over IJ pairs.generate xfer non-transit legs list='\nGenerate Transfer Legs ' GENERATE. BASE1=T. NTLEGMODE = 33. INCLUDELINK = li. Skims are reported for each user class PHASE=MATO if(ROWSUM(1) > 0) PRINTROW mw=1 TITLE='Compcost'. MAXCOST[1]=16*20. FORM=10. LIST=T.generate access/egress links list='\nGenerate Zone Access/Egress Legs GENERATE.1 TRIPSIJ[2] = Mi.2 if(ROWSUM(2) > 0) PRINTROW mw=2 TITLE='ValOfChoice'.NET . evaluated.WalkTime. skimmed and loaded for each user class . 12 Public Transport Program Examples ENDRUN 860 Cube Voyager Reference Guide . Cube Voyager Reference Guide 13 Utilities This chapter describes utilities. Topics include: • • • • UB2TPP TPP2UB SYNCHIMP Saturn conversion Cube Voyager Reference Guide 861 . 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. Statement FILEI FILEO PARAMETERS Description Specify input SUMMIT UB file Specify output TPP/Cube Voyager file Set static parameters FILEI Inputs data file. The following control statements are available in the Cube Voyager UB2TPP utility program. MATI Keyword MATI |KF| Description Specifies the filename of the binary user benefit file created by the FTA SUMMIT program 862 Cube Voyager Reference Guide . Optional. The VARO file contains the variable information from the user benefit file header. 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. for example: run pgm=matrix filei mati=t10_36.1*UBAUTOCOEF endrun PARAMETERS Sets general parameters. The MATO file must be specified even if HEADERONLY=T.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.mat read file=ubout.Utilities UB2TPP 13 FILEO Outputs data files.var mw[1]=mi. Cube Voyager Reference Guide 863 . A sample of the VARO file is listed below: UBTRNCOEF=2. Specifies the filename of the user benefit VARO file.1.34567 UBAUTOCOEF=8. MATO VARO Keyword MATO VARO |KF| |KF| Description Specifies the filename of the converted TP+/Cube Voyager binary matrix file. Matrix) by “reading” the file in. Set static parameters. Control statement FILEI FILEO PARAMETERS Description Specify input TP+/Cube Voyager input file and the user benefit variable file. 864 Cube Voyager Reference Guide . FILEO Outputs data files. Specify output binary user benefit file.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. 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. MATO Keyword MATO |KF| Description Specifies the filename of the converted binary user benefit file. FILEI Inputs data files. The following control statements are available in the Cube Voyager TPP2UB utility program. 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.Utilities TPP2UB 13 PARAMETERS Set general parameters. They may be coded directly with the PARAMETERS statement. 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 Cube Voyager Reference Guide 865 . The program must have values for all PARAMETERS. Specifies the filename of the input SYNCHRO LAYOUT file. 866 Cube Voyager Reference Guide . Control statement FILEI FILEO PARAMETERS Description Specify input SYNCHRO files. NOTE: Cube has a SYNCHRO data import wizard accessible from the Tools menu.13 Utilities SYNCHIMP SYNCHIMP Use the SYNCHMP utility program to convert SYNCHRO data to Cube Voyager intersection data format. Set static parameters. LAYOUTI LANESI PHASINGI TIMINGI VOLUMEI FILEI keywords Keyword LANESI LAYOUTI |KF| |KF| Description Specifies the filename of the input SYNCHRO LANES file. The following control statements are available in the Cube Voyager SYNCHMP utility program. FILEI Inputs data files. Specify output Cube Voyager files. Utilities SYNCHIMP 13 FILEI keywords (continued) Keyword PHASINGI TIMINGI VOLUMEI |KF| |KF| |KF| Description Specifies the filename of the input SYNCHRO PHASING file. Specifies the filename of the output node file. Specifies the filename of the input SYNCHRO TIMING file. PARAMETERS Sets general parameters. Specifies the filename of the output link file. Specifies the filename of the input SYNCHRO VOLUME file. NODEO LINKO JUNCDATAO Keyword JUNCDATAO LINKO NODEO |KF| |KF| |KF| Description Specifies the filename of the output intersection data file. PLANID VOLDATE VOLTIME Cube Voyager Reference Guide 867 . FILEO Outputs data files. The values of these parameters are stored in the associated SYNCHRO input CSV data files. 868 Cube Voyager Reference Guide .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 units of the LANES file. Specifies the time value in the VOLUME file. Specifies the date value in the VOLUME file. Valid values are meters or feet. The window contains two fields and several command buttons: • Input Saturn Path File — Enter the existing file containing the Saturn output.Utilities Saturn conversion 13 Saturn conversion The SaturnPath utility program converts output from the Saturn assignment program into a Cube Voyager path file.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. The Cube installation program installs this program in the Cube directory (C:\Program Files\Citilabs\Cube\SaturnPath. Cube Voyager Reference Guide 869 . you will open the program window. 870 Cube Voyager Reference Guide . the program automatically writes the output 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”). flow. If there are no errors during the conversion. • • Close — Click to close the program window. and number of nodes in path). with fields showing any parameter values that you did specify. Running from command line When called from a command line or batch file. Convert — Click to run the utility and convert the specified input into a Cube Voyager-formatted path file and write the results to the specified output file. If the specified output file does not exist. the program automatically starts converting the input file. Show Saturn File Statistics — Click to show statistics about the Saturn file (number of paths. otherwise. minimum and maximum zone number. node number. the program window will open. the program will close automatically.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. route number. class number. If you do not specify all three parameters. too. the program will prompt to overwrite the file. Topics include: • • • Using Cube Cluster Control statements Utilities Cube Voyager Reference Guide 871 .Cube Voyager Reference Guide 14 Cube Cluster This chapter discusses Cube Cluster. an optional extension you can use with Cube Voyager. High availability clusters are configured for redundancy and make use of redundant nodes to provide continuous service when primary nodes fail. Clusters are usually deployed to improve speed and/or reliability over that provided by a single computer. The components of a Cluster are commonly. 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. This type of cluster would commonly be used for a Web server for high volume web sites where continuous access is in demand. Clusters are typically configured for either high availability or high performance. This includes computations where intermediate results from one node’s calculations affect future calculations on other nodes. connected to each other through fast local area networks. but not always. Highperformance clusters are optimal for workloads that require the processes on separate computer nodes to communicate actively during the computation.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. while typically being much more cost-effective than single computers of comparable speed or reliability. 872 Cube Voyager Reference Guide . Alternatively. An example is shown in the figure below. 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. This implies a Cube Voyager Reference Guide 873 . 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. 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. Many office environments already have such local networks of computers in place which can be utilized to support Cube Cluster. Model step dependencies are easily visible from the data flows presented in the flow chart. Cube’s Application Manger flow chart view of your model provides a convenient tool for identifying the model steps in an application that can be distributed. Some reconfiguration of the model flow may be required to group those steps together that can be run simultaneously. Most travel demand models will also have many steps that can be run at the same Itime if independent processing nodes are available. 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. Assume that each of these steps run in approximately 9 to 11 minutes. Each of these steps is independent of each other.Cube Cluster Using Cube Cluster 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. 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. 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). This is a fairly typical transit network development and skimming (level of service) process that might be present in many models. 14 Cube Cluster Using Cube Cluster total run time for this group of about 40 minutes if run sequentially as is the normal practice. 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 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. then all four steps would be executed simultaneously. If four processing nodes are available so that each step is distributed to a separate node using Cube Cluster. It was felt that this level of hardware would 874 Cube Voyager Reference Guide . The test utilized readily available off the self computer hardware that was rented from a computer rental firm. The results of the run time test are shown in the figure below for varying numbers of processing nodes.Cube Cluster Using Cube Cluster 14 be reasonably representative of the type of hardware that our typical clients would already have in place. IDP works for most type of Matrix (zone based. 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. Currently only the Matrix and the Highway programs are available for IDP. 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. Ten identical computer workstations were rented and loaded with the beta version of Cube Voyager and Cube Cluster. Also shown are the theoretically ideal run times if all processors could be utilized at all times during the model runs. not RECI) and Highway processing as long as each zone can be Cube Voyager Reference Guide 875 . you can assign peak and off-peak period transit networks concurrently in most models. For example. However. Cube Voyager uses a simple file based signaling method for communication between the main process and the sub-processes. 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. • 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. 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. unless the CommPath 876 Cube Voyager Reference Guide . However. This should not be a problem if used with models in “production” mode that should not have any syntax or logic errors. it requires carefully planning and setup by the user to implement this system. 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.14 Cube Cluster Using Cube Cluster independently processed (see “Procedures that disable intrastep distributed processing” on page 885 for a discussion of the types of process not supported by IDP). 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. For distributed processing to work. 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. Because of the zone independent requirement on IDP and the step independent requirement on MDP. Understanding these basic relationships and dependencies in a model is very important to successfully implementing MDP. you can not run skimming procedures at the same time or before you have updated the speeds in the network you intend to skim. Ends a MDP script block in Pilot. combining 3 matrix files into one matrix file). 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. DP works well for computation-intensive applications (for example. 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. Running on a network drive could significantly slow down a run for disk intensive applications depending on the computer network’s throughput capacity so there may be little runtime benefit or take even longer when using DP on certain steps. Therefore. When you are satisfied with the results of your model or model process when running on a single processing node then implement Cube Cluster Cube Voyager Reference Guide 877 . the run will fail. 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. 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.Cube Cluster Using Cube Cluster 14 feature is used. Working with Cube Cluster Implementing Cube Cluster should generally be performed after model development and calibration/validation. it is important to “tune” the DP setup to get the best performance. In general. 14 Cube Cluster Using Cube Cluster to distribute sub-process of your model and fine tune the distribution process to achieve the optimal or satisfactory run time reduction. you must ensure that all read/write permissions are properly set across the machines in the cluster. MULTISTEP=T) when a Cube Voyager run is started. Set the working directories of the Cube Voyager instances running in wait mode on each cluster node to this common drive location. If turned off. 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. all the file I/O references in the scripts that run from any of the node processors will correctly reference the model folder. distributed processing will not be invoked even if there are DistributeINTRASTEP and DistributeMULTISTEP statements in the following script. The node machines and the main control machine must have read/write permission to the mapped model folder. 878 Cube Voyager Reference Guide . With this configuration. 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. 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. users logged in without full administrator privileges on the main or node machines can cause access problems. MinGroupSize is the minimum distributed zone group size. only 4 sub-processes will be used to process 20 zones each and the main process will process 20 zones itself. SavePrn=T This statement will invoke intrastep distributed processing in the program unless the global switch is off. Cube Voyager Reference Guide 879 . if there are 100 zones and MinGroupSize is 20 and ProcessList=1-10. Intrastep distributed processing (IDP) To implement IDP. It is a list of numbers and put in as individual numbers or ranges (for example. 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.10-20. MinGroupSize=20. ProcessList=1.25). ProcessList=1-4. Each sub-process must be assigned a unique process number. The ProcessID and the process numbers in the ProcessList are used to make up the name of the wait file.Cube Cluster Using Cube Cluster 14 For machines configured with multiple user accounts that have different permission settings. If there are more sub-processes than there are zone groups of this size. then some sub-processes will not be used.5. The ProcessID is the prefix for the file names used to communicate with the sub-processes. Before running the job in the main computer. add the following statement in the appropriate Matrix or Highway script (within the Run/EndRun block): DistributeINTRASTEP ProcessID='TestDist'. For example. 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. ProcessList is a list of sub-processes to use for DP. 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. then no drive/path is needed when specifying the script file name. For example. full path name should be used when specifying the script file. otherwise. The default is F (false) for this keyword. Each processor node in the cluster should correspond to one of your process numbers set with the ProcessList= keyword. The IDP process automatically merges the script generated information (from Print statements etc. on the first computer in the cluster.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. If the current directory is the work directory.script Sub 3 : TestDist3.script Sub 2 : TestDist2. With the example of ProcessID='TestDist' and ProcessList=1-4 above.script. The script files that each of the sub-process is looking for is {ProcessID}{Process#}. the 4 sub-process will start with the following script file to look for: Sub 1 : TestDist1. Cube Voyager would be launched and placed into wait mode after setting the Input Job File 880 Cube Voyager Reference Guide . Cube Voyager can also be started with command line parameters: Voyager TestDist1. So in this example.14 Cube Cluster Using Cube Cluster SavePrn is a switch to control if the sub-process print files should be saved or not.script /wait This will put Cube Voyager in the wait mode automatically. four sub-processes will be used. 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.) 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. 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. 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. Note also that both these conditions can apply. See “Utilities” on page 895 for additional information on getting multiple instances of Cube Voyager open and configured in wait mode.Cube Cluster Using Cube Cluster 14 and the common working directory. add the following statement in the CLUSTER script at the beginning of the distributed script block: Cube Voyager Reference Guide 881 . 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. Multistep distributed processing (MDP) To implement MDP. start the Cube Voyager run like a normal run in the main computer. When all the sub-processes are in wait mode. end. ProcessID is the same as defined above for IDP. Use the Wait4Files command to wait for the . 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. ProcessNum is a single process number since the steps are distributed to one process only. variable 882 Cube Voyager Reference Guide . When a sub-process is done.script. Any variables with the first part of the name matching an UpdateVars name will be merged back. 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. It is the user’s responsibility to check for sub-process completion before using output files generated by the sub-process. For example: Wait4Files Files=TestDist1. UpdateVars=vname. TestDist2.end.14 Cube Cluster Using Cube Cluster DistributeMULTISTEP ProcessID='TestDist'.script. 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.Matrix. When a block of operations is distributed to another processing node.xname. ProcessNum=5 Also.end file to be created in Pilot.end. PrintFiles=Merge. for UpdateVars=vname. the main computer will continue running the script without waiting for the sub-process on this other processing node to finish. the whole run will stop if a sub-process returns with a code 2 (fatal) or higher. The ProcessID and the ProcessNum number are used to make up the name of the wait file.script. Before running the job in the main computer. it will create a file named {ProcessID}{Process#}.script. See “Utilities” on page 895 for additional information on getting multiple instances of Cube Voyager open and configured in wait mode. the sub-process node participating in this MDP must be started and in the wait mode with the correct file to wait for. When true.xname. TestDist3. CheckReturnCode=T. For example.end.Matrix. . will all be merged back to the main process. The default is true. Consider the following example: ThisVar=1 DistributeMULTISTEP ProcessID='TestDist'.Cube Cluster Using Cube Cluster 14 vname1. EndRun Run pgm=Network .vnameabc. meaning to remove all temporary files.end.Matrix.. UpdateVars=ThisVar. DELETE means no merge but delete them and SAVE means no merge but save them.” “MERGESAVE. 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. This is because the sub-process inherits a copy of all the global variables to start with (ThisVar=1). MERGESAVE means to merge the files but not delete them. Care must be taken to merge back ONLY the variables that need to be returned to the main process.. It can be “MERGE.” MERGE means the print files will be merged back into the main print file then deleted. after the Wait4Files statement. The DelDistribFiles keyword controls the disposition of the MDP temporary communication files.” or “SAVE. EndRun EndDistributeMULTISTEP ThisVar=2 Wait4Files Files=TestDist5script. the variable ThisVar will have the value of 1. DelDistribFiles=F During execution. The default is SAVE. Examples Intrastep distributed processing: Run pgm=Matrix Cube Voyager Reference Guide 883 . the update process will change ThisVar back to 1. so even though the sub-process never modify the value of ThisVar.. CheckReturnCode=T. PrintFiles=MERGE. ProcessNum=5 Run pgm=Matrix .” “DELETE.xnamevar etc. . GroupB 1-4. continue running on successful end of the sub-process 5 Run pgm=Network .. PM and Off-Peak assignments in parallel: DistributeMULTISTEP ProcessID='GroupA'.end.... run the following 2 steps while the sub-process is doing the 3 steps above Run pgm=Public Transport .... EndRun Multistep distributed processing: DistributeMULTISTEP ProcessID='TestDist'.. FileO MatO=.14 Cube Cluster Using Cube Cluster FileI MatI=. EndRun .. the following 3 steps will be distributed to another processing node Run pgm=Matrix . DistributeINTRASTEP ProcessID='TestDist'.. CheckReturnCode=T . EndRun Run pgm=Fratar .ProcessList=1-4 . EndRun Run pgm=Highway .ProcessList=2-4 884 Cube Voyager Reference Guide .ProcessList=2-4 .. EndRun EndDistributeMULTISTEP ......script. GroupC 2-4) to do AM. Using both Intra and Multi Step Distribution with 12 processing nodes (main. ProcessNum=1 . ProcessNum=5 .. EndRun Run pgm=Highway DistributeINTRASTEP ProcessID='GroupA'.. GroupA 1-4. EndRun Run pgm=Network . the following 2 steps will be distributed to sub-process GroupA1 Run pgm=Matrix DistributeINTRASTEP ProcessID='GroupA'. wait for the sub-process to finish before continuing Wait4Files Files=TestDist5.. . ProcessNum=1 ..script. 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 Cube Voyager Reference Guide 885 .ProcessList=2-4 . the following 2 steps will be distributed to sub-process GroupB1 Run pgm=Matrix DistributeINTRASTEP ProcessID='GroupB'. GroupB1.ProcessList=2-4 . EndRun Run pgm=Highway DistributeINTRASTEP ProcessID='GroupB'..end..end. EndRun EndDistributeMULTISTEP DistributeMULTISTEP ProcessID='GroupB'. Procedures that disable intrastep distributed processing In addition to the requirement of independent zone processing in IDP.CheckReturnCode=T Run pgm=Network . wait for all the sub-processes to finish before continuing Wait4Files Files=GroupA1.ProcessList=2-4 .ProcessList=2-4 . run the following 2 steps while the sub-processes are running Run pgm=Matrix DistributeINTRASTEP ProcessID='GroupC'.. EndRun Run pgm=Highway DistributeINTRASTEP ProcessID='GroupC'.. EndRun .... EndRun EndDistributeMULTISTEP ..script.Cube Cluster Using Cube Cluster 14 . 14 Cube Cluster Using Cube Cluster 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. 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. The main process will then abort the run. the last zone processed and what is the current process number: • • • 886 Cube Voyager Reference Guide . Change the checks to use the following 3 new system variables to determine if it is the first zone processed. 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. SFDU*SFOcc[zi. For example.94 SFOcc[5]=0.95 SFOcc[6]=0. 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. initial occupancy table SFOcc[1]=0.1. 0 for the DP main controller. With this a script can tell if it is running in non-DP mode (ThisProcess = -1).ZoneType]=SFbyType[zi.ZoneType]+zi. For example. has fields ZoneType and SFDU reco=lusum. ‘IF (I=FirstZone)’ to perform initialization on the first zone processed. However.dbf. write RECO at last zone Cube Voyager Reference Guide 887 .97 SFOcc[8]=0. z=zone . a step may be restructured to utilize IDP. it is running as the main (ThisProcess = 0). For example. 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. “IF (I=LastZone)” to perform finalization on the last zone processed.93 SFOcc[4]=0. 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: . • LASTZONE — The last zone processed in the current processor. and the process number in a DP sub-process. • THISPROCESS — The current process number. Using IDP for steps that summarize zonal values In general.96 SFOcc[7]=0. original script.Cube Cluster Using Cube Cluster 14 • FIRSTZONE — The first zone processed in the current processor.SFDU array SFbyType=9.91 SFOcc[2]=0. fields=ZoneType.99 endif SFbyType[zi.SFOcc=9 zones=3000 if (i = 1) .98 SFOcc[9]=0.1. any step that summarizes zonal values may not use intrastep DP because zones are processed in independent processes.1.dbf.Zone Type] if (i = zones) .92 SFOcc[3]=0. under certain circumstances. It will be -1 for a normal run. sum occ. or it is running as a node (ThisProcess > 0). SFDU by ZoneType run pgm=matrix zdati=lu.1. SFDU=SFbyType[zt] write reco=1 endloop endif endrun This step can be restructured into two steps.9 ro.SFDU=SFbyType[zt] write reco=1 endloop endif endrun .zones 888 Cube Voyager Reference Guide . use more precision on SFDU field reco=tlusum.99 endif SFbyType[zi.ZoneType]=SFbyType[zi.SFOcc=9 zones=3000 if (i = FirstZone) .SFDU(10.1.dbf.92 SFOcc[3]=0. z=zone .dbf.94 SFOcc[5]=0.Zone Type] if (i = LastZone) loop zt=1. write out the combined dbf record in the first zone processed loop zt=1.96 SFOcc[7]=0.97 SFOcc[8]=0.1.dbf.2) zones=9 .ZoneType=zt ro.ZoneType=zt ro.0). write to temp reco file.98 SFOcc[9]=0.SFDU(13.SFDU*SFOcc[zi. fields=ZoneType(3. extra step to combine RECO back to one record per ZoneType run pgm=matrix zdati=tlusum.14 Cube Cluster Using Cube Cluster loop zt=1.sum=SFDU reco=lusum.91 SFOcc[2]=0.9 ro. fields=ZoneType(3.93 SFOcc[4]=0. can not use if (i=1) SFOcc[1]=0.ZoneType]+zi.0).1.dbf.95 SFOcc[6]=0. has fields ZoneType and SFDU .5) array SFbyType=9. z=ZoneType. PROCESSLIST=1-3 zdati=lu. 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: .1. Cluster script run pgm=matrix DISTRIBUTEINTRASTEP PROCESSID='TESTDIST'. 1.SFDU[zt] write reco=1 endloop exit endrun Cube Voyager Reference Guide 889 .ZoneType = zt ro.Cube Cluster Using Cube Cluster 14 ro.SFDU = zi. PROCESSID PROCESSNUM COMMPATH 890 Cube Voyager Reference Guide . MULTISTEP INTRASTEP DISTRIBUTE keywords Keyword MULTISTEP INTRASTEP |?| |?| Description Global MULTISTEP DP on/off Global INTRASTEP DP on/off DISTRIBUTEMULTISTEP Invoke multistep distributed processing.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. This will work regardless of the location of the script file and the work directory of the main process. Defaults to null (working directory used). it will go back and wait for further commands in the COMMPATH directory. the node reverts to waiting for the communication file in the COMMPATH directory. In addition to a string constant. In addition to a single numeric constant. a Pilot string variable can be used to set the ProcessID by putting it within @ characters (for example. Single process number since the steps are distributed to one process only. then when a model run requests the node it will switch to the work directory for that particular model and run the steps. PROCESSNUM |I| COMMPATH |S| ENDDISTRIBUTEMULTISTEP Statement to end current MULTISTEP subprocess. WAIT4FILES When a block of operations is distributed to another computer. It is the user’s responsibility to check for sub-process completion before using output files generated by the Cube Voyager Reference Guide 891 . ProcessNum=MyProcess). Common path for checking for availability of processors. ProcessID=@MyID@). The node switches its work directory to be the same as the main process before running the multistep (or intrastep) distributed process. a Pilot numeric variable can also be used to set the process number dynamically (for example. the main computer will continue running the script without waiting for the sub-process to finish. Nodes can be waiting in the COMMPATH directory. After completing the steps. When it is done. The common path is only used for initial communication with the node.Cube Cluster Control statements 14 DISTRIBUTEMULTISTEP keywords Keyword PROCESSID |S| Description Prefix for the file names used to communicate with the sub-processes. it will create a {ProcessID}{Process#}. FILES CHECKRETURNCODE UPDATEVARS PRINTFILES DELDISTRIBFILES WAIT4FILES keywords Keyword CHECKRETURNCODE |?| Description Specifies if the return codes from the subprocesses should be checked.end file to be created. the whole run will stop if a sub-process returns with a code 2 (fatal) or higher.script. When true. The default is true. When a sub-process is done.end file. DELDISTRIBFILES |?| 892 Cube Voyager Reference Guide . meaning to remove all temporary files. Controls the disposition of the MDP temporary communication files.14 Cube Cluster Control statements sub-process. Use the Wait4Files command in the Pilot program to wait for the . xnamevar etc.” “MERGESAVE. variable vname1. DELETE means no merge but delete them and SAVE means no merge but save them. Specifies a list of global variables computed in Pilot and logged from individual programs that should be merged back from the subprocess run.Cube Cluster Control statements 14 WAIT4FILES keywords (continued) Keyword FILES |S| Description Specifies a list of all the files to wait for.Matrix. For example. It can be “MERGE. for UpdateVars=vname. PROCESSID PROCESSLIST MINGROUPSIZE SAVEPRN Cube Voyager Reference Guide 893 . In addition to a string constant. Any variables with the first part of the name matching an UpdateVars name will be merged back. The default is SAVE. a Pilot string variable can be used to set the file names by putting it within @ characters (for example. will all be merged back to the main process.vnameabc. PRINTFILES |S| UPDATEVARS |S| DISTRIBUTEINTRASTEP Programs: Matrix. Highway Invoke intrastep distributed processing. Currently only available in Matrix and Highway.” or “SAVE. Files=@MyFile@).xname. MERGESAVE means to merge the files but not delete them.” MERGE means the print files will be merged back into the main print file then deleted.Matrix. Controls the disposition of the print files from the sub-processes.” “DELETE. Switch to control if the sub-process print files should be saved or not. List of sub-processes to use for DP. if there are 100 zones and MinGroupSize is 20 and ProcessList=1-10. Defaults to null (working directory used). Each sub-process must be assigned a unique process number.25). then some sub-processes will not be used.14 Cube Cluster Control statements COMMPATH DISTRIBUTEINTRASTEP keywords Keyword COMMPATH |S| Description Common path for checking for availability of processors. It is a list of numbers and put in as individual numbers or ranges (for example.5. 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. MINGROUPSIZE |I| PROCESSID PROCESSLIST |S| |I| SAVEPRN |?| 894 Cube Voyager Reference Guide . ProcessList=1. Minimum distributed zone group size. For example. If there are more sub-processes than there are zone groups of this size.10-20. Cube Cluster Utilities 14 Utilities This section describes: • • Cluster executable Utility functions Cluster executable Use the cluster. You can access this utility from Cube Base. to start multiple processing nodes on the local machine. From the Tools menu. Cube Voyager Reference Guide 895 .exe utility program. choose Cluster Node Management to open the Cluster Node Management dialog box. found in the Cube program folder. you can use the COMMPATH keyword to send information to active instances of Cube Voyager. A Cube Cluster processing node corresponds to a single.exe program in the Cube Voyager program directory and setting the script and working directory. properly configured instance of Cube Voyager running and waiting. You can also run this program from a Windows command line. and click List Nodes to return the status of any processing node (remote or local). Click Close Nodes to close any processing node (remote or local). enter the number of seconds Cube Cluster should wait for a response from a node before determining that the node is unavailable. or by running the Cluster. Alternatively. 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. You cannot start instances of Cube Voyager on remote nodes over a network.exe or the Cluster. You can start an instance of Cube Voyager manually by running the Voyager.exe program on that machine. 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.bat batch file or from a Cube Voyager * command call. you can run the program from either a . Typically. you must physically go to each machine and run either the Voyager.14 Cube Cluster Utilities In Time to Wait for Response. You must start remote nodes directly on the remote machines. Processing nodes can either be additional processors on the local computer (local nodes) or processors on remote computers connected to the main computer over a local network (remote nodes).exe program as described in “Cluster executable” on page 895. 896 Cube Voyager Reference Guide . which are open and running on remote processing nodes. Therefore. 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. MyProcessList) FirstReadyNode('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. For example. The function takes one string argument (constant or variable) and if there are more than one file to check.') — This function will check for the existence of one or more files.. the node reverts to waiting for the communication file in the COMMPATH directory. After completing the steps. If none of the files exist. For example. 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.'1-5.10. then the return value will be zero.'1-5. setting the work directory to a common path like z:\wait. Then. NumReadyNodes('ProcessID'. you can use this value as the COMMPATH keyword value. NumReadyNodes('TestDist'. The return value is the number of files that exist. the result will be 6..15-20') • • Cube Voyager Reference Guide 897 . Citilabs recommends starting an instance of Cube Voyager on each remote processor that you will use. 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.10. FirstReadyNode('TestDist'.'ProcessList') — This function will check for availability of a list of Cube Cluster nodes and return the process number of the first available node. and leaving them run. The node will switch its work directory to be the same as the main process before running the multistep distributed process.Cube Cluster Utilities 14 You use COMMPATH only for initial communication with the node.15-20') or NumReadyNodes(MyProcess. The second argument is a string with the list of process numbers to check. they are put into one string and separated by '|'. This can be use instead of the Wait4Files command if you only want to check if a node is done but don’t want to wait for it to get done. The return value is the number of ready nodes. 14 Cube Cluster Utilities 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.’11-20’)) MyProcessID=’DP1’ MyProcessList=’1-10’ ELSE MyProcessID=’DP2’ MyProcessList=’11-20’ ENDIF RUN PGM=Matrix DistributeIntraStep ProcessID=@MyProcessID@.’1-10’) > NumReadyNodes(‘DP2’. the script wants to select the one with the most available nodes: IF (NumReadyNodes(‘DP1’. ProcessList=@MyProcessList@ 898 Cube Voyager Reference Guide . Cube Voyager Reference Guide 15 Cube Avenue This chapter discusses Cube Avenue. an optional extension to Cube Voyager. Topics include: • • • • Using Cube Avenue Control statements Theory Examples Cube Voyager Reference Guide 899 . However. Cube Avenue shares the same PHASE structure but has additional commands and keywords to implement dynamic traffic assignment. Of course. these models are not useful for forecasting routing (if they do so at all).” or how long queues can disrupt traffic flows through upstream junctions (“blocking back”). these models can show how signal offsets and synchronization can create a “green wave.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. For example. Microsimulation models also model day-to-day variation by using different random number “seeds. 900 Cube Voyager Reference Guide . convergent trend into travel patterns. introducing a systematic. However. most analysts only complete enough runs to obtain a representative sample and extract averages. Older traffic models tend to fall into two categories: • • Operational traffic models Planning models Operational traffic models. Derived from the Cube Voyager Highway program. random day-to-day variations differ from the way travellers learn by experimenting with different routes on different days.” Sufficient runs can provide measures of trip time reliability. such as Cube Dynasim (microsimulation) and SYNCHRO (signal optimization). which implements static traffic assignment. are useful for modeling network component interactions as queues and delays vary during the model period. finding “Wardrop User Equilibrium” solutions to the travel assignment problem. to evaluate the costs generated by a set of routing decisions. if you have enough local knowledge of the study area. However. are known as mesosimulation models. like Cube Avenue. Cube Avenue tries to find a middle ground between these two extremes. Bucket rounding the matrix before assigning it is probably the easiest way of cleaning a non-sparse demand matrix but. • • Cube Voyager Reference Guide 901 . Cube Avenue simulates the movement of vehicles through the network. such as trips to work. The target packet size should be at least as big as the expected number of iterations. Cube Avenue uses a path builder in a capacity-restraint loop to model drivers finding routes and modifying those routes based on experience. These models are sometimes described as macrosimulation models.Cube Avenue Using Cube Avenue 15 Planning models. Avoid small matrix cells. do capture how drivers’ experiences over long periods of time allow them to pick optimal travel strategies for regular. Therefore a matrix with many small cells can cause lots of time and RAM to be wasted. If there are any nodes or links where demand exceeds supply by a factor of two or more. These models iterate on capacity restraints. you will need to clean up the network and/or matrix before continuing. on the other hand. Typical actions include checking that the matrix is for the right period and checking that the capacity coded in the network is correct. you may be able to clean the matrix better by hand. Hybrid models. frequent trips. 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. a bigger value may be appropriate. If the matrix is large. But packets consume computer memory and processor cycles. Every non-zero cell must generate packets. LI. In particular it executes twice per iteration (once before phase ILOOP and once before phase ADJUST) but it does not execute time segment by time segment.15 Cube Avenue Using Cube Avenue 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. Variables and input fields applicable to this phase include: • • • • • DISTANCE LINKCLASS LI. This functionality may be used. is only available in this phase. future releases will allow you to vary STORAGE. to model tidal flow lanes. DYNAMIC. you can vary the values of the C variable by time segment. too. for example. With this command. The command.SPDCLASS.LANES SPEED 902 Cube Voyager Reference Guide .CAPCLASS LI. only C my be varied in this way. LINKREAD phase This phase behaves similarly in a Cube Avenue assignment to the corresponding phase in a Cube Voyager Highway assignment. At present. Distance is usually measured in miles or in kilometers. Cube Voyager Reference Guide 903 . LinkClass functions as the index for functions TC and COST. it defaults to one. LI. In Cube Avenue. If the script does not set the variable. if that variable exists and has a non-negative value. free-flow time must be provided independently of speed for zero distance links. and appropriate speed or capacity tables are defined in the network. it will be initialized from LI. in conjunction with Li. and output speeds are not meaningful for them. they will be used. LI.Lanes. Failing that.CAPCLASS If these field(s) exist. LINKCLASS In Cube Avenue.DISTANCE. and the values in them are positive. LI. as it does in any other highway assignment.SPDCLASS. Failing that. or in the script. a link distance of zero may also cause STORAGE to default to zero (with disastrous consequences for the modeling).LINKCLASS will be used if the variable exists and has a positive value. it defaults to zero.” As in any network. Zero distance links are sometimes described as “dummy links. to look up base speed and capacity values.Cube Avenue Using Cube Avenue 15 • • • • C T0 T1 STORAGE DISTANCE If the user does not set this variable in script. Thus the defaulting behavior of SPEED is only significant if it is used to calculate a default for T0. 904 Cube Voyager Reference Guide . If none of these values exists. in vehicles per model period. a value of zero will be applied (with disastrous consequences for Cube Avenue modeling).Capacity is used as the default. This capacity differs from STORAGE. SPEED is a dependent variable. such as “NumberOfLanes. Note that the field name required in the input network is “LANES” and that fields with similar names. If there is no such field or if the value in the field is non-positive.Lanes will be taken from the input network.Lanes does. if PARAMETERS CAPFAC has been coded.LANES may also take part in the default STORAGE calculations. the value in Li.Capacity does not exist but Li. Li. C This is the flow capacity of the link. Speed will be initialized to zero. If all defaults fail.Lanes does. which measures how many vehicles can occupy the link simultaneously. may be used as an index into speed or capacity tables.Speed does not exist. Scripts can use the DYNAMIC command to specify that the value of C varies by time segment. but Li. In Cube Avenue. Note that.” will not be recognized as the number of lanes. a value of one will be used. or if they result in a negative value. If Li. a capacity table lookup will be attempted. during the modeling.Lanes. SPEED If the user does not set this variable in script. then defaulting will be from Li. If the script does not explicitly set this variable.LANES The variable Li. Finally. that factor will be applied. Note that this measures how quickly the link can discharge or accept vehicles. If Li. Speed is in distance units per hour. a speed table lookup will be attempted. the independent variable is TIME. As in any highway assignment.15 Cube Avenue Using Cube Avenue LI. LI.Speed if that exists. LI. Both queuing and moving vehicles on the link will use up storage. where vpd denotes the value of PARAMETERS VEHPERDIST. a default of zero will be applied. Note that in Cube Avenue it is applied to every time segment. will be tried. It defaults to T0 unless the user explicitly sets the value in script.LANES*DISTANCE*vpd. If all else fails. the program will look in turn for Li. in that order. in minutes. T0 This is the free-flow time for the link. Li.Time and Li. impassable). the storage does not directly limit the flow on the link. although there may be some merit to using observed times where these are available. If the user script does not supply a positive value for STORAGE. If it still cannot find a value it will try to use 60*Speed/Distance. 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. so long as vehicles leave the link as fast as new vehicles arrive.Time1. Thus. If the user does not set a value in script. If all else fails a value of zero will be applied (with the disastrous consequence that the link will always be full. STORAGE This is the number of vehicles that can fill the link. a zerocapacity link can delay packets forever. Thus every link has two capacities: the standard capacity. It is used during application of the function. and hence. the program will try to extract a value from LI.STORAGE. It is very common to accept this value. TC. C. Cube Voyager Reference Guide 905 . However. the number of vehicles on the link does not change. If a positive value still cannot be found.Cube Avenue Using Cube Avenue 15 Essentially. restrains flow while STORAGE restrains occupancy.T0. this value is the maximum frequency with which a vehicle can be discharged from or admitted to a link. a volume in one or more volume fields. and it remains full until it has discharged sufficient vehicles to reduce the occupancy back below 100%. a PATHLOAD statement) evaluates an expression (usually involving matrices) to determine the number of trips. but it defers updating the volume fields until the adjust phase. builds paths according to some attribute minimization criterion. but the packet’s volume exceeds the available storage. builds paths according to some attribute minimization criterion. A conventional load (that is. the volumes in the packets generated during the current iteration will be given by {expression value}/{iteration number} and the new 906 Cube Voyager Reference Guide . Thus for COMBINE=AVE. for each point on the route. where each packet contains a start time. packets generated during earlier iterations are not discarded. This script should contain one or more DYNAMICLOAD statements. in which time segment) the packet arrives there. and within each time segment for every origin. However. and a route. In particular. and then it loads the trips into the network’s volume fields. A dynamic load evaluates an expression (usually involving matrices) to determine the number of trips. The user script associated with this phase is executed for each time segment. The trips are placed into packets. (The link then becomes full. they just have their volumes modified according to the factors generated by the COMBINE methodology in force.) Thus the maximum number of vehicles that can be observed on a link may exceed that link’s storage slightly. ILOOP phase This phase is concerned with the creation of packets and the determination of routes. it will still be admitted to the link.15 Cube Avenue Using Cube Avenue Note that a link that has any spare storage will admit packets. if a packet arrives at a link with some storage available. when (that is. Note that on the second and subsequent iterations. the network’s volume fields may only be updated later after calculating. or if the end of the model period has been reached. when T1 is used). Since every event occurs at a specified time. some of the results are aggregated to obtain values relevant to the entire modeled period. a packet arrives at its destination. before the event processing is completed. the script associated with the ADJUST phase is executed for the time segment that has just been completed. Cube Voyager Reference Guide 907 . Initially the event queue contains one event for each packet’s departure from that packet’s origin and all the link queues are empty. All the packets from all the iterations so far will be simulated during the current iteration’s ADJUST phase. If not. it is easy to determine whether the next event occurs in the same time segment as the current one. 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. a “queue” of events is maintained. it is verified whether link A will accept the packet (if not it joins link A’s queue) and an arrival event is scheduled for the next link on the path. when a packet is scheduled to arrive at a link A from link B. 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. During the simulation. Initially.Cube Avenue Using Cube Avenue 15 volume for old packets will be ({iteration number} – 1){previous volume}/{iteration number}. It is these aggregate values that are passed to the Converge phase. ADJUST phase This phase is executed when the movement of packets through the network is simulated. For example. At the end of the entire simulation. There are four kinds of event that can be stored in the event queue: a packet departs an origin. a check is made to see whether any packets can be released from link B’s queue. or a packet becomes unblocked on a link. a packet arrives on a new link. As each event is processed more events are added to the queue. there is a queue of blocked packets waiting to get on each downstream link. In addition. It executes exactly the same as it would in a static highway assignment.15 Cube Avenue Using Cube Avenue CONVERGE phase The CONVERGE phase is only executed once per iteration. 908 Cube Voyager Reference Guide . Link capacity is initially defined as it normally would be for a static assignment (specified with COMP C= in the LINKREAD phase. DYNAMIC Changes the value of the capacity variable by time segment. For example: DYNAMIC C[3]=1800. Use the DYNAMIC statement to set segment-specific capacities. 1000 during time segment 4 and its usual value during all other time segments. 1800 results in C taking the value 1800 during time segments 3 and 5. Keyword C |NV99| Description Defines link capacity by time segment. link capacities are vectored by time segment. 1000. 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 Cube Voyager Reference Guide 909 . In Cube Avenue. read from the input network variable li. Only use this command during the LINKREAD phase. A link’s capacities by segment are initially set to the static capacities for all segments.CAPACITY or read from the internal speed/capacity table).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. DEMANDISHOURLY = t/f INCLUDEJ = list EXCLUDEJ = list VOL[n] = list PATH = time/cost/list EXCLUDEGRP = list PACKETSIZE = value PENI = list 910 Cube Voyager Reference Guide . 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. such as reversible lanes. the opening of HOV facilities to general purpose uses at specific times of day. respectively.CAP*li. the closing of HOV facilities at specific times of day.15 Cube Avenue Control statements This statement is useful for modeling time-dependent changes in link capacities.LANES2*3 where LANES1 and LANES2 contain the available lanes during the first two hours and the last hour. DYNAMICLOAD DYNAMICLOAD is the dynamic analog of the static PATHLOAD statement. For example.CAP*li. or construction closures.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. COST3. the path will be built to minimize the appropriate time varying function. LW. expr. The DYNAMICLOAD PATH= clause may take. and so forth. LW. such as 1. list) NOACCESS=real This statement may only occur in PROCESS PHASE = ILOOP. in which case simultaneous dynamic and static loadings will occur. so only the differences are noted in this document. In the last case.COST1. one per time segment). as its value. For example.Variables.COST2. 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. If you enter a single value that contains one or more occurrences of __TS__. In the first two cases. Cube Avenue expands the value into a list by replacing the __TS__ with the integers representing the time segments. and so forth. Several clauses of the DYNAMICLOAD statement require timesegmented lists as inputs (these lists contain one item per time segment).Cube Avenue Control statements 15 PENIFACTOR = value MW[n] = TRACE(real.” or a list of input link attributes (that is. it is intended to allow some other clauses of the PATHLOAD statement to be applied to dynamic loading once the relevant functionality has been implemented. Variables or LW.COST__TS__ is equivalent to entering PATH=LW. The predicted disutility for a vehicle of Cube Voyager Reference Guide 911 . “TIME. 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 time varying function to be minimized will be constructed by using the value from the appropriate link attribute in each time segment. entering PATH=LW. 2. A dynamic traffic assignment must include a “PARAMETERS MODELPERIOD= SEGMENTS=” clause and at least one DYNAMICLOAD statement. Furthermore. It may also contain one or more PATHLOAD statements. LI.” “COST. Most of the clauses have the same syntax and meaning as the corresponding clauses of the PATHLOAD statement. For example. false.15 Cube Avenue Control statements 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. 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 DYNAMICLOAD VOL[n] = clause is similar to the PATHLOAD VOL[n] = clause. The entered value must be a list of expressions with one entry per time segment. then the demand is 30 vph and 7½ vehicles will depart the origin during the time segment. 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. by default. expression. When the ILOOP is executed for time segment n. You can use __TS__ to abbreviate the list. However. and the corresponding expression in a DYNAMICLOAD VOL[n] = clause evaluates to thirty. penalty) 912 Cube Voyager Reference Guide . the nth element of the list will be the one that is evaluated. The DYNAMICLOAD MW clause specifies skims. Instead actual loading is deferred until the simulation runs in the PROCESS PHASE=ADJUST. 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. The DYNAMICLOAD DEMANDISHOURLY = clause is. If necessary. The paths will be assigned routes based on their departure time and their expectations of travel time and disutility. Otherwise thirty vehicles depart the origin during the time segment. If DEMANDISHOURLY. such as VOL[1]=MW[__TS__+3]. no change to the volume field values occurs during PROCESS PHASE=ILOOP. The DYNAMICLOAD PACKETSIZE = clause specifies the target number of vehicles per packet. suppose that there is a segment of 15 minutes. giving a departure rate of 120 vph. The value must take the form: TRACE(time. At least one packet will be generated for any IJ pair that has a positive demand. • Cube Voyager Reference Guide 913 . there may be more than one. specified in minutes since the beginning of the model period. PATHCOST. 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. In Cube Voyager a static assignment process contains no dynamic elements. A static assignment process is what users should be familiar with as the typical assignment process. • • You can use the special expression.Cube Avenue Control statements 15 where: • time is the start time. the assignment process will include dynamic elements but may also include static elements. It indicates that the skim should be for vehicles departing their origins at the specified start time. penalty is an optional list of turn penalty sets to include in the skim. A few rules apply to these two cases when using Cube Avenue as described below. expression is the expression evaluated and summed for each link on the route. If the expression contains the string __TS__. Case 1: Static assignment • There are no instances of “PARAMETERS MODELPERIOD= SEGMENTS=” in the entire script [this setting is the key that switches modes]. Negative values indicate that the start time is in the 'warm up' period. it will be evaluated as a dynamic expression that varies by time segment. There are two classes of assignment process now supported in Cube Voyager: Static and Dynamic. If using Cube Avenue to perform dynamic traffic assignment. to skim the value of the DYNAMIC PATH clause. There must be at least one instance of PATHLOAD in phase ILOOP. packets created. etc. • 914 Cube Voyager Reference Guide . Case 2: Dynamic assignment • • • • • • There is exactly one instance of “PARAMETERS MODELPERIOD= SEGMENTS =. If there are any instances of PATHLOAD. There may be instances of PATHLOAD in phase ILOOP. No variables are vectorized by segment and all apply to the model period as a whole. there may be more than one. During each of these executions of 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.” There must be at least one instance DYNAMICLOAD in phase ILOOP. a single item from the list of matrix expressions in each DYNAMICLOAD statement is evaluated (and paths built. There may not be any instance of PATHLOAD outside phase ILOOP. 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). There may not be any instances of DYNAMICLOAD. No PATHLOAD statements are executed during any of these executions of phase ILOOP. There is a single “static” time segment and it runs same as the Highway program has always run.). an additional execution of PHASE ILOOP occurs prior to any of the executions described above. no DYNAMICLOAD statements are executed but PATHLOAD statements are. There may not be any instances of DYNAMICLOAD outside of phase ILOOP. During this execution of phase ILOOP.15 Cube Avenue Control statements • • • • There may not be any instance of PATHLOAD outside phase ILOOP. Note that none of the discussion above depends on the ordering of PATHLOAD and DYNAMICLOAD statements. FILEO Highway program output files are not supported under FILEO if running a dynamic assignment process under AVENUE. If a DYNAMICLOAD PATHO=T control is found in the ILOOP PHASE. The results (except for volumes) are carried forward to the corresponding execution of ILOOP during the next iteration. Some users have keys implemented in their application scripts to turn on or off the Cube Voyager Reference Guide 915 .Cube Avenue Control statements 15 • Phase ADJUST is executed for each time segment. 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. aggregate values applying to the model period are calculated from the results individual time segments. It is their presence or absence from the ILOOP PHASE of the script (as a whole) that is significant. then these values (except for the volumes) will be carried forward to the “static” execution of phase ILOOP during the next iteration. These aggregate results are used for the calculation of convergence statistics. If there are any PATHLOAD statements in phase ILOOP. a fatal error will be generated. After ADJUST has been executed for each time segment. you can set AFTERITER to m-1 to save some run time by not writing the file during the first few iterations. Specified as FILEO PACKETLOG=filename. for every iteration). Specify each interval as an ascending pair of real numbers—minutes since the start of the model period. Cube Avenue writes the packet log for each simulation run (that is. PACKETLOG AFTERITER |I| Iteration number when Cube Avenue begins writing packet log. you can improve run times. if you know that Cube Avenue will require at least m iterations. FILEO keywords Keyword PACKETLOG Subkeyword |F| Description Produces the dynamic equivalent to the static path file. PACKETLOG ARRIVALTIME |RPV| List of time intervals. Packet log only includes packets that arrive at their destinations during the listed time intervals.15 Cube Avenue Control statements generation of the PATHO file. with all the information in the file. 916 Cube Voyager Reference Guide . overwriting the same file and ensuring that a valid packet log exists upon completion of a successful Cube Avenue run. even leading failed runs to succeed. However. By reducing required resources. The file is likely to be very large. Additional options on the FILEO PACKETLOG statement can reduce the number of packets included in the packet log and thus reduce the required resources. and disk space. 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. By default. However. The difference between these two times is the time that the packet spent queueing. you can filter displayed packets with Cube graphics. RAM. 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. NOTE: Writing a packet log requires computer resources: processor time. defines a set of links that packets must pass through for inclusion in the packet log. Either BIN or TXT. based on the value of MUSTMEETALL. By default. PACKETLOG DESTINATION |IV| PACKETLOG FORMAT |S| PACKETLOG MUSTMEETALL |?| • The default value is true. such as a matrix record-processing script. PACKETLOG SELECTGROUP |IV| PACKETLOG SELECTLINK |IPV| Cube Voyager Reference Guide 917 . NOTE: If none of these keywords (SELECTLINK. List of links. defined in previously executed ADDTOGROUP commands. based on value of MUSTMEETALL. log includes packets from all origins. which you can display in Cube graphics or postprocess with a user-defined program. False — Link set defines a special area: the packet log lists any packet that passes at least one link in the set. the PACKETLOG is a text file. Specify each interval as an ascending pair of real numbers—minutes since the start of the model period. PACKETLOG ORIGIN |IV| List of origin nodes. SELECTGROUP. List of destination nodes. Packet log only includes packets that depart their origins during the listed time intervals. defines a set of links that packets must pass through for inclusion in the packet log. log includes packets to all destinations. Along with SELECTLINK. but binary files are about 60% smaller. Packet log only list packets ending at the listed destinations.Cube Avenue Control statements 15 FILEO keywords (continued) Keyword PACKETLOG Subkeyword DEPARTTIME |RPV| Description List of time intervals. Packet log only lists packets starting at the listed origins. List of link groups. By default. Binary format is only suitable for display in Cube graphics. and MUSTMEETALL) is listed. By default. Along with SELECTGROUP. the packet log does not restrict packets based on links traveled. 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. It does not take turn penalties or junction modelling into account. 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. VfSMP_1. 918 Cube Voyager Reference Guide . 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. SPEEDSt_1 and SPEED_1 This field contains the ratio between distance and the time (as defined above). TIME_1 is similar. TIMESt_1 stores the amount of time that the vehicles spent traversing the link segment (averaged over all such vehicles). but applies to the model period (excluding any “warm up” segments).15 Cube Avenue Control statements Output data Cube Avenue produces additional output data over that produced by the Highway program. The output NETO network will include all NETI input variables unless explicitly excluded with the EXCLUDE keyword and any additional variables included with the INCLUDE keyword and the following dynamic results variables: • • • • • • TIMESt_1 and TIME_1 SPEEDSt_1 and SPEED_1 VfSt_1. VSt_1 and VSMP_1 VITSt_1 QUEUEVSt_1 BLOCKVSt_1 TIMESt_1 and TIME_1 For vehicles arriving on a link during a particular time segment. VSt_1 and VSMP_1 The volume of traffic entering the link. QUEUEVSt_1 This measures the average number of vehicles queuing on the link during time segment t. VITSt_1 The number of vehicles on each downstream link at the end of time segment. VfSMP_1. First. The value is found by summing across all packets of vehicles that are flowing or queuing on the link. At origin zone centroid connectors. excluding any “warm up” segments). but this is just a convention indicating that data has not been collected for these links. Packets of vehicles can be made to queue by either of two mechanisms. in volume field f. The values in the fields labelled with “MP” instead of a time segment number contain aggregate values for the “model period” (that is. a link that is full of traffic may block further vehicles from entering. VSt_1 is the result of applying the V function to V1St_1. Note there are two very different situations that can result in low volumes entering downstream links (that is. If there is very low demand for travel on the link. At the other extreme.” Cube Voyager Reference Guide 919 . the values in the volume fields should correspond to the appropriate matrix row totals.Cube Avenue Control statements 15 VfSt_1. the field value will be zero. Second. etc. links other than origin zone centroid connectors). links and turns in the network are associated with capacities and capacity bottlenecks may delay packets to ensure that these capacities are not exceeded. is recorded in this field. the flow will be low because the link is empty. At origin zone centroid connectors. the vehicles affected queue while waiting to proceed. during time segment. but are not recorded as “blocked.” and it will queue until space becomes available on the next link. t. V2St_1. if the packet tries to move onto a full link. it will be “blocked. t. PARAMETERS Set general parameters MODELPERIOD SEGMENTS VEHPERDIST COMBINE CAPLINKENTRY PKTPTHSIZ MAXPTHPERSEG All the parameters from Highway are also available in Cube Avenue. The value will always be less than or equal to the queue variable.” COMBINE must always be specified explicitly for AVENUE. COMBINE |KS| See “COMBINE” on page 216 for valid subkeywords and descriptions. Since the default value of COMBINE is “EQU. the link capacity only limits how quickly they can leave the link. For most uses of AVENUE. Combine type “EQU” is not valid for Avenue. 920 Cube Voyager Reference Guide . When CAPLINKENTRY=N. “AVE” is a good choice of combine value. but if it is on then the front of the queue is at the A node. Note that the primary difference between these two regimes is where the front of a queue occurs. Values can only increase in subsequent time segments. then the front queue due to a bottleneck link is at the B node.15 Cube Avenue Control statements BLOCKVSt_1 This records the number of vehicles in the queue that will remain in the queue at the end of the simulation. 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. If CAPLINKENTRY is off. This page only mentions those parameters that are new or different in Cube Avenue. Maximum number of nodes that a packet keeps in RAM. also in minutes. but need not (and. the ILOOP phase must contain a DYNAMICLOAD statement. Each packet’s node list is based on the nearest path build. If the number of distinct packet departure times is less than this value. usually. Windows imposes a 2 gigabyte limit on the total memory available to a program. and origin. Though this value can affect the packet’s route. Cube Avenue executes this many path builds. Defaults to 5. Cube Avenue builds paths for each packet—each packet’s node list is based on accurately built paths. of a segments clause that determines whether Cube Voyager runs Highway or Avenue. should not) contain a PATHLOAD statement. If the segments list is present. Otherwise. or absence. It is the presence. To save memory. distributed evenly through the time segment. iteration. the ILOOP phase must contain a PATHLOAD statement but must not contain a DYNAMICLOAD statement. the packet's simulated departure remains unchanged. The length of the list determines the number of time segments. If the segments list is absent. in terms of departure time. Packets use computer RAM when simulated. packets can swap their route information between RAM and temporary disk files. PKTPTHSIZ |KI| Cube Voyager Reference Guide 921 . The value of the subsidiary segments clause is a list of time segment durations.Cube Avenue Control statements 15 PARAMETERS keywords (continued) Keyword MAXPTHPERSEG |KI| Description Upper bound on the number of path builds executed for a given time segment. MODELPERIOD |S| The value of MODELPERIOD is the length of the model period in minutes. or in the input network.81 vehicles per kilometer gives a vehicle every 5.81.5 meters. If the sum of the segments is strictly greater than the model period. 922 Cube Voyager Reference Guide . so if storage is supplied explicitly in script. (181. then 181.15 Cube Avenue Control statements PARAMETERS keywords (continued) Keyword SEGMENTS |R*| Description The sum of the values in the segments list must be greater than or equal to the model period. If the distance unit is kilometers. there will already be vehicles driving on roads in the network interior. the extra time forms a kind of “warmup” period before the “true” modeling begins. Thus. 181.38 vehicles per mile. The value is only used for the calculation of default storage. Remember that the implied vehicle spacing must be greater than the average length of a vehicle.81 vehicles per kilometer is 295.81 vehicles per mile does not yield an appropriate vehicle length. This is the number of queuing vehicles that can sit in one lane of roadway one distance unit long. storage must include the average gap between the vehicles (vehicles do not queue bumper to bumper). when the “true” model period begins. the parameter value does not matter. The default value of this parameter is 181. See “PATHLOAD” on page 223 for a description of this command statement and its associated keywords and usage. 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.) The HCM2000 recommends that the following values be used. is reduced by the static loading. During dynamic simulation. an extra initial execution of the ILOOP is performed for every iteration. PATHLOAD statements are executed but DYNAMICLOAD statements are not executed.Cube Avenue Control statements 15 If a PATHLOAD statement is present in a Cube Avenue run. During this execution. See “Combined use of DYNAMICLOAD and static PATHLOAD” on page 913 if implementing both command statements in the same run. ESTMO (ALLJ) PATHO (ALLJ INCLUDECOST NAME PATHOGROUP (FULLPATH)) Cube Voyager Reference Guide 923 . the static loads (generated from PATHLOAD statements) are present (and constant) in every time segment. which is available for packets. PATHLOAD keywords not supported if using static PATHLOAD statements in a dynamic assignment process with DYNAMICLOAD in effect. The capacity. all variables take values associated with the model period. The demand for travel is assumed to be approximately constant during each time slice. during which the network is filled with traffic. 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. The time modeled is divided into two major periods: a warm-up period. It also has a route for each iteration of assignment. It is designed to enable the prediction of time-varying costs and flows given a timevarying demand for travel. However. Furthermore the time is also divided into smaller time-slices. The route is calculated based on the current estimate of each time segment’s delays and on the estimated time of arrival of the packet at each point on its route. the segment-by-segment times are recalculated independently. over which network statistics are aggregated. once modeling begins. and the model period. but to vary between time slices.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 divided into a number of packets of vehicles. 924 Cube Voyager Reference Guide . 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). So. Each packet has a start time and a number of vehicles in each volume field. When dynamic demand is required for some origin-destination pair for some time segment. Unlike a static load. a gate will work out a busy time proportional to the flow and inversely proportional to the capacity. the path-building algorithm is invoked to calculate routes. the packet that is trying to move is blocked and remains queued on its current link until space becomes available. it must compare the total volume of packets in transit on the destination link. Each link has a storage capacity. At any time. As they leave flows behind them in the network’s volume fields. if a packet wishes to move into a link. If the volume of packets in transit exceeds the storage of the destination link. it can pass straight through (but the gates most recent occupied time becomes now). but they are not considered to be blocked. Packets must take at least the link time to traverse a link. The simulation is run in continuous time (not segment-by-segment). During the ILOOP phase. Cube Voyager Reference Guide 925 . and any flows resulting from the movement of packets during previous iterations are removed from the volume fields. The packets in transit on a link are the packets traveling on the link and the packets queuing on the link. Furthermore. Such packets are queued on the link preceding the gate. no flows are assigned to the network at this stage in the process. Instead the packet volumes travel along each route in proportion to the lambda values for the appropriate iteration. Otherwise the packet will be delayed until the sum of the busy time with the time at which the gate was most recently occupied. Packets emerge from their origin zones at their start times and start moving along their routes.” Given a flow. each link capacity or turn capacity is represented as a “gate. The ADJUST phase runs the simulation. They must also take at least the turn time to traverse a turn. If a packet arrives at a gate and the gate was unoccupied for the corresponding busy time. the routes from previous iterations are not discarded.Cube Avenue Theory 15 On the second and subsequent iterations. • An update to the volume fields for a given link or turn in a given time segment proceeds as follows: 926 Cube Voyager Reference Guide . for all time segments. the ADJUST phase). As they move from link to link the network volume fields are updated as follows: • • When a packet departs the origin. the segment in which the first link is left. Paths are calculated for each packet and the packets are written to (a temporary file on) disk. for the current iteration are cleared to zero. When a packet moves from a link to another link. When a packet arrives at a destination no volume fields are updated. the volume fields for the second link. The packets are read from disk and the stored values of flow are multiplied by the appropriate factor.15 Cube Avenue Theory Cube Avenue calculations This section describes Cube Avenue calculations: • • • Volumes Times Speeds Volumes During the ILOOP phase. and for the turn between the two links. the packets are released onto the network and move along their predetermined paths. As the simulation progresses. Note that the volume fields are updated for a single time segment. the paths etc. from previous iterations are retained. the packets are appended to the existing disk file. At the start of the simulation (that is. the matrix cells in the demand trip matrix are calculated and split into packets. the volume for the origin zone centroid connector is updated. On the second and subsequent iterations. are updated. all the link volume fields. Note that in the absence of a userdefined function. In both cases the times are updated for each Cube Voyager Reference Guide 927 .Cube Avenue Theory 15 • • • First the packet is examined to determine which of the twenty possible volume fields are present. The link time is the sum of the flow time and the block time. V. The network time fields are calculated as the sum of the blocked and flow times. If the volumes are for a link. Any turns where these defaults do not yield a value are initialized to zero. the function. Unmodeled turns are those where there is no modeling or where there is a fixed turn penalty. T. flow times for all time segments are initialized to the T1 values read from the input network (or set by code in phase LINKREAD). Cube Avenue maintains two components of link time (called flow time and block time) and one component of turn time for each time segment. Times Logically. At the end of the iteration. and from times in the turn penalty file. Modeled turns are those with function turn penalties or with intersection models. is executed to update the total volume. Unmodeled turns never change their time and they do not apply capacity “gates” to regulate the movement of packets from their preceding link. the convergence tests decide whether Cube Avenue should continue or stop. V20 are increased by the values stored in the packet. the function. is used instead. …. Block times are initialized to zero. There are two kinds of turns in Cube Avenue: unmodeled and modeled. the volumes will be written to the output network. If the latter choice is made. Prior to any calculations. if the volumes are for a turn. Similarly turn times are initialized from the “EstimatedDelay” values stored in the intersection file. V2. The values of V1. these functions default to simple summation over all volumes. In subsequent time segments they are found by looking at the packets simulated to be waiting to make the relevant movement. Note that the speeds do not take turn times into account.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. the queues for each modeled turn are noted. 928 Cube Voyager Reference Guide . incurred during the segment. Prior to simulation. In the first time segment these are taken from the “InitialQueue” values stored in the intersection file. The costs are taken by applying the cost function to these fields. During path building. The turn times are updated by running the intersection model with the previously noted initial queues and the turning volumes obtained from the simulation. As the simulation progresses the packets move from link to link. Before a segment begins. They are calculated immediately prior to network output as Speed = 60 Distance / Time. Speeds The link speeds are not used during the path building or simulation. Sometimes the packets take longer than the sum (flow time + turn time) to do so. the link times are taken from the network time field. the blocked time for the segment becomes the average excess minutes per vehicle. all blocked times are zeroed. Any user code for the ADJUST phase is executed. The time fields in the network for the segment are now updated to be the sum of blocked and flow times. The flow times are updated by running the appropriate TC functions for the segment volumes. The program tracks in which time segments these excess vehicle minutes occur. After a segment has been simulated. SegmentStart This is the time in minutes between the start of the modeled period and the start of the time segment currently being processed. 2. This section describes only the new or changed variables: • • • • • Storage TimeSegment SegmentStart Period Time. It takes values 1. that may be set during the LINKREAD phase. Note that this is a signed value. It takes the value zero during a static assignment. and the interpretation of some other script variables is modified. 3. as the dynamic time segments are being processed. TimeSegment This is the time segment number. and Vol Storage There is a new script variable. Cost. etc. It takes the value zero during a static assignment. Refer to the description in “LINKREAD phase” on page 902. or during the static phase of a combined assignment.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. STORAGE. with negative numbers indicating the current segment is a “warm-up” segment and non-negative values indicating that this segment is within the model period. Cube Voyager Reference Guide 929 . However there are some new script variables. User script may not assign values to this variable. User script may not assign values to this variable. or during the static phase of a combined assignment. some care needs to be taken when calculations involve both “ordinary” link arrays and these time-segment vectors of link arrays. it will be in the context of the model period.CAR_COST2=DISTANCE/2+TIME*1. However. Time.5 930 Cube Voyager Reference Guide .5 ELSE LW.TRUCK_COST=DISTANCE+TIME LW.CAR_COST1=DISTANCE/2+TIME*1. For example. this will result in both link variables having the cost values applicable to the last time segment. It is the duration of the current time segment when time segments are being processed. It is the duration of the model period during a static assignment.CAR_COST=DISTANCE/2+TIME*1.15 Cube Avenue Theory Period This is the duration of the period currently being processed in minutes.5 In a Cube Avenue dynamic assignment. Cost. a common way of handling costs for multi user class assignment is to calculate costs into a work variable: LW.TRUCK_COST2=DISTANCE+TIME LW. or during the static phase of a combined assignment. and the costs associated with one time segment overwrite those associated with the previous one. more work variables must be used: IF (TIMESEGMENT=1) LW. the values referring to different time segments will be given different names (see “Output data” on page 918). (Although the values for each time segment in turn will be assigned to the link variables. they are not vectored. these link arrays become two-dimensional. or of the current time segment as appropriate. When script is being executed. with one dimension referring to the time segment and the other referring to the link number.) To correctly calculate costs by user class.TRUCK_COST1=DISTANCE+TIME LW. and Vol Internally. In the output network. User script may not assign values to this variable. TRUCK_COST__TS__ Cube Voyager Reference Guide 931 .Cube Avenue Theory 15 The new variables can be used in a DYNAMICLOAD statement. For example: DYNAMICLOAD PATH=LW. NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. statements using an editor..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. Use Application Manager. ENDRUN” block... RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT..NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT.. Do not change filenames or add or remove FILEI/FILEO . . You can specify an output print file after a “PGM=AVENUE PRNFILE=” statement. with “RUN PGM=.” Place all statements and keywords that control the run in a “RUN.MAT" ENDRUN 932 Cube Voyager Reference Guide . successive averages.MAT" PARAMETERS MAXITERS=10. statements using an editor. The internal random number generator randomly draws a departure time for each packet departing in a given interval. RUN PGM=AVENUE PRNFILE="{SCENARIO_DIR}\OUT.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. Seeding the random number generator makes results repeatable between multiple runs of the same assignment. AVE is the recommended method for equilibrium dynamic assignment. the method is AVE. . this example seeds the random number generator. In addition. COMBINE=AVE. the sum of the segments exceeds the model period.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. COMBINE specifies the method of combining iterations together. In this example. SEGMENTS specifies a list of durations for each modeled time segment. In this case.30.PRN“ FILEO NETO = "{SCENARIO_DIR}\OUTPUT. seed random numbers ENDRUN • • Cube Voyager Reference Guide 933 . MODELPERIOD specifies the duration of the modeled time period. in minutes.30.30.Cube Avenue Examples 15 Parameters This example adds some parameters to the Cube Avenue script: • • MAXITERS specifies the maximum number of iterations. SEGMENTS=30. Use Application Manager. Cube Avenue treats the excess time as a “warm up” prior to the model period. MODELPERIOD=90.30 min warm-up X=RANDSEED(165) . . Do not change filenames or add or remove FILEI/FILEO . NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.30. statements using an editor.15 Cube Avenue Examples LINKREAD Just as in the Highway model.FEET/5280 . This example shows: • • • • • • DISTANCE — Used with other variables to calculate default T0 and STORAGE values. in vehicles per model period.30 .30. T0 — Free-flow link travel time.5 .VEHPERLNMI IF (STORAGE=0) STORAGE=9999999 LINKCLASS = LI. Use Application Manager. Cube Avenue reads the input network and uses either user expressions or default rules to initialize important link variables.LANES*LI. COMBINE=AVE.MAT" PARAMETERS MAXITERS=10. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT. SPEED — Used with DISTANCE to calculate default T0 values. C — Flow rate capacity.MPH T0=60*DISTANCE/SPEED .scale to model period STORAGE = DISTANCE*LI. STORAGE — Number of vehicles that can physically fit on a link (should not be zero).30 min warm-up PHASE=LINKREAD DISTANCE=LI. .time in minutes C=LI. LINKCLASS — Function index number for calculating congested time and cost.LANES*LI.FTYPE ENDPHASE ENDRUN 934 Cube Voyager Reference Guide . MODELPERIOD=90. SEGMENTS=30.converting to miles SPEED=LI.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.LNCAP*1. Do not change filenames or add or remove FILEI/FILEO . You might need to convert from hourly capacities.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. the example uses the CAPFAC parameter to scale the value to the model period duration. . and TIME override any default calculations for these variables.81. you can define a network variable named STORAGE. Because the network’s input capacity is specified in vehicles per hour.MAT" PARAMETERS MAXITERS=10. In Cube. infinite storage. COMBINE=AVE.30 .Also use TIME from network for T0 . SEGMENTS=30. in Cube Avenue. they do not represent physical road features. as well as input CAPACITY for C . you must define these links to have infinite (that is.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. For example. Use Application Manager.30. CAPACITY.5. MODELPERIOD=90.Accordingly DISTANCE and SPEED are not used ENDPHASE ENDRUN Centroids Centroid connectors connect zones to the network. then Cube Avenue can compute STORAGE using the formula VehPerDist * LANES * DISTANCE.30. if the input network has values for LANES and DISTANCE.calculated in Cube editor window based on HCM: . Do not change filenames or add or remove FILEI/FILEO . RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT. freeway storage = 120 vehicles/ln-mi . very large) capacity. statements using an editor.Cube Avenue Examples 15 Simplifying LINKREAD Not every link variable needs an explicit expression. Therefore.Automatically use STORAGE from network. and zero travel time.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. Input network fields named STORAGE.) Citilabs recommends using different STORAGE values for arterials and freeways. (The default value for VehPerDist is 181.30 min warm-up PHASE=LINKREAD . Cube Voyager Reference Guide 935 . arterial storage = 220 vehicles/ln-mi . CAPFAC=1. which was . 15 Cube Avenue Examples Because links with zero capacity and storage can cause problems in dynamic assignment. 936 Cube Voyager Reference Guide . freeway storage = 120 vehicles/ln-mi . Do not change filenames or add or remove FILEI/FILEO .Also use TIME from network for T0 as well .30. This example assigns all centroid connectors LINKCLASS=2 using the ZONES variable. Use Application Manager. COMBINE=AVE. you must find such links and give them large capacity and storage values. which is initially the free-flow link travel time. 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.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. statements using an editor. arterial storage = 220 vehicles/ln-mi . . By default.calculated in Cube network editor based on HCM: .MAT" PARAMETERS MAXITERS=10.30. also.30 min warm-up PHASE=LINKREAD . and builds dynamic (time-varying) paths. SEGMENTS=30.5.Automatically use STORAGE from network. CAPFAC=1. which was . Cube Avenue loops through all the input zones. The statement DYNAMICLOAD PATH=COST tells Cube Avenue to build dynamic paths using congested travel costs by time segment.30 .NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. this is the same as TIME. creates packets for assignment.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT. MODELPERIOD=90. NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.mi.1.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.30.2. Use Application Manager.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. Cube Avenue uses delay functions to calculate congested travel times by segment. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT. The statement PACKETSIZE=10 groups the input vehicle trips into packets with a target size of ten vehicles.mi. Cube Avenue simulates the movement of packets through the network during the ADJUST phase. Do not change filenames or add or remove FILEI/FILEO .Cube Avenue Examples 15 The input matrix for this example contains three tables.1.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT.mi.1. including warm-up.1.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. statements using an editor. VOL[1]=mi.3 ENDPHASE ENDRUN ADJUST When a script calls one or more DYNAMICLOAD statements. MODELPERIOD=90. SEGMENTS=30.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. The tables listed in VOL[1] specify the matrix to use for each time segment. CAPFAC=1.30 . By default.MAT" PARAMETERS MAXITERS=10. After simulating packets and recording link volumes. .1.NET" Cube Voyager Reference Guide 937 . PACKETSIZE=10. one for each half hour of the model period. Use Application Manager. COMBINE=AVE. Do not change filenames or add or remove FILEI/FILEO .1.5. statements using an editor.30. Cube Avenue adjusts all links using the standard BPR formula: TC[1] = T0 *(1 + 0.15* (V/C) ^ 4) . is inadequate for Cube Avenue.1. where assignment volumes never exceed capacity. LI.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. LINKCLASS=2 represents centroid connectors. PACKETSIZE=10.MAT" PARAMETERS MAXITERS=10.1. which should not degrade performance.1. The example introduces a custom COST function that incorporates vehicle operating costs and tolls into route-choice behavior.2. The units of COST are monetary. MODELPERIOD=90.mi.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.5.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. Use Application Manager. based on facility type.3 PHASE=ADJUST ENDPHASE ENDRUN Enhancing ADJUST The standard BPR formula.NET" 938 Cube Voyager Reference Guide . VOL[1]=mi. statements using an editor.30.30. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.1.mi. COMBINE=AVE. .15 Cube Avenue Examples FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.mi. which does not degrade link performance significantly until volumes exceed capacity.1.DO represents free-flow signal delay. SEGMENTS=30. In this example: • • • LI.1. Do not change filenames or add or remove FILEI/FILEO . CAPFAC=1.30 .J represents a calibration parameter coded directly into the network. This example implements a performance function from Chapter 30 of the Highway Capacity Manual 2000. mi.2.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.Cube Avenue Examples 15 FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. PACKETSIZE=10. but not necessarily all of the links Cube Voyager Reference Guide 939 .30 . Cube Avenue generates an output log file containing simulated packet movements.3 PHASE=ADJUST Function TC[1]=T0+LI. 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.mi. specifying that links specify an area. CAPFAC=1.1.1.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. MODELPERIOD=90.mi. VOL[1]=mi.1. COMBINE=AVE.MAT" PARAMETERS MAXITERS=10.1. SEGMENTS=30.30.1.5.TOLL Function COST[2]=TIME ENDPHASE ENDRUN Packet logs With the FILEO PACKETLOG statement.1. hence output packets must pass through at least one of the specified links.30. 1.1. 940 Cube Voyager Reference Guide . PACKETSIZE=10.J*V/C*DIST^2)/30^2))) Function TC[2]=T0 Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.5. DEPARTTIME=1800-3600. This computation-intensive process can result in slow run times. DESTINATION=1-10.mi.LOG".mi. SEGMENTS=30. and builds time-varying paths for these flows.MAT" FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET. AFTERITER=9. COMBINE=AVE. CAPFAC=1. MUSTMEETALL=F.3 PHASE=ADJUST Function TC[1]=T0+LI.1.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. ARRIVALTIME=1800-3600.2. VOL[1]=mi.TOLL>0) AddToGroup=3 PHASE=ILOOP DYNAMICLOAD PATH=COST. FORMAT=BIN PARAMETERS MAXITERS=10.30 .30.mi.1.1.TOLL Function COST[2]=TIME ENDPHASE ENDRUN Tuning parameters Cube Avenue generates packet flows that depart intermittently throughout the model period.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.25*30)*((V/C-1)+ SQRT((V/C-1)^2+((16*LI.1. SELECTLINK=(L=101-1903*).D0+(0.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. ORIGIN=1-10. MODELPERIOD=90.30.15 Cube Avenue Examples • • 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. SELECTGROUP=3.PRN" FILEO NETO = "{SCENARIO_DIR}\OUTPUT. 1. This example has a segment duration of 30 minutes.2.5.30.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. This reduces the number of built paths and improves computation time.1. AFTERITER=9. MODELPERIOD=90. DEPARTTIME=1800-3600.Cube Avenue Examples 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. COMBINE=AVE.MAT" FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET. PACKETSIZE=10.3 PHASE=ADJUST Function TC[1]=T0+LI. ARRIVALTIME=1800-3600. SELECTGROUP=3.30.TOLL Function COST[2]=TIME ENDPHASE ENDRUN Reducing segment and volume lists When using many time segments.D0+(0. segment and volume lists can become long and unwieldy. VOL[1]=mi. A MaxPthPerSeg value of 10 forces packets within threeminute intervals to use the same path.1. SELECTLINK=(L=101-1903*).LOG".mi. ORIGIN=1-10. CAPFAC=1. DESTINATION=1-10. MUSTMEETALL=F.1. MaxPthPerSeg=10 PHASE=LINKREAD IF (A<=ZONES||B<=ZONES) LINKCLASS=2 IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999 IF (LINKCLASS==2||C==0) C=9999999 IF (LINKCLASS==2) T0=0 IF (LI.TOLL>0) AddToGroup=3 PHASE=ILOOP DYNAMICLOAD PATH=COST. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT. Cube Voyager Reference Guide 941 .1.1.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.30.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT.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. FORMAT=BIN PARAMETERS MAXITERS=10.mi. SEGMENTS=30.mi. but can introduce model granularity. MW[4]=mi. FORMAT=BIN PARAMETERS MAXITERS=10.1. VOL[1]=MW[__TS__] PHASE=ADJUST Function TC[1]=T0+LI.1. when the “_TS_” notation is used within MW brackets for VOL.1 MW[2]=mi.LOG".1.5. COMBINE=AVE. SELECTGROUP=3. DESTINATION=1-10.3 DYNAMICLOAD PATH=COST. AFTERITER=9. CAPFAC=1.TOLL Function COST[2]=TIME 942 Cube Voyager Reference Guide .MW[3]=mi. SELECTLINK=(L=101-1903*).NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.TOLL>0) AddToGroup=3 PHASE=ILOOP MW[1]=mi. 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.15 Cube Avenue Examples The SEGMENTS parameter supports the repetition (*) operator. If the time segments are of equal duration.2.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.D0+(0.MAT" FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET. ORIGIN=1-10.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.1. PACKETSIZE=10.J*V/C*DIST^2)/15^2))) Function TC[2]=T0 Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.25*15)*((V/C-1)+ SQRT((V/C-1)^2+((16*LI. Cube Avenue substitutes the expression with an MW vector that contains the number of time segments (replacing “_TS_” with the time segment’s index).1. MUSTMEETALL=F. 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. SEGMENTS=4*30. ARRIVALTIME=1800-3600. MODELPERIOD=90. DEPARTTIME=1800-3600. Cube Avenue Examples 15 ENDPHASE ENDRUN Cube Voyager Reference Guide 943 . 15 Cube Avenue Examples 944 Cube Voyager Reference Guide . Network variable 332 A A COMP keyword. Public Transport 716 @. Fratar 125 A2P BALANCE keyword. Pilot 91 GOTO 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.Cube Voyager Reference Guide Index Symbols %.. Generation 567 AAD convergence testing calculation 167 Highway variable 137 PARAMETERS keyword. Matrix variable 440 _COMPARE. 80 * command 83 ** command 83 :label GOTO keyword. 80 _BSEARCH.. Generation 573 ACCESS LINE NODES subkeyword. Network variable 332 _SKIPTOI. Public Transport 724 Cube Voyager Reference Guide 945 . Generation 568 Highway array 136 Network variable 332 REPORT keyword. Highway 208 GOTO keyword. Distribution 557 SETPA keyword.% 21. Generation 573 SETPA keyword.@ 21.. Highway variable 135 _ZONES. Public Transport 701 ACOMP REPORT keyword. Fratar 125 algorithm all-or-nothing path building 737 Cube Avenue 924 public transport transfers 738 ALIGN PLOTTER FOOTER subkeyword. Highway 225 PATHLOAD PATHO subkeyword. utility-based model 455 ALTNAME PARAMETERS keyword. Public Transport 737 APPEND FILEO NETO keyword. overview 265 JUNCTION keyword. Public Transport 724 ACCESSLEGS REREPORT keyword. utility-based model 448 XCHOICE keyword. common description 269 JUNCTION keyword. overview 265 APPROACH1 JUNCTION keyword. Pilot 95 aftersys NEWPAGE keyword. signals 282 ADDTOGROUP SETGROUP keyword. empirical roundabout 305 JUNCTION keyword. Public Transport 643 AFTERITER FILEO PACKETLOG subkeyword. Network 355 PRINT FILE subkeyword. Highway 231 ALLSTOPS LINE keyword. Public Transport 645 ALTERNATIVES CHOICE keyword. Public Transport 735 ACTUALGREEN JUNCTION keyword. common description 271 JUNCTION keyword. Network 367 ALL REPORT keyword. cost-based model 445 CHOICE keyword. Pilot 100 AONMAXFERS FACTORS keyword. Public Transport 643 APPROACH JUNCTION keyword. Highway 201 FILEO PRINTO subkeyword. general 72 946 Cube Voyager Reference Guide . cost-based model 452 XCHOICE keyword. Public Transport 721 all-way-stop-controlled intersections 302 ALPHA FACTORS keyword.Index A access legs generating 842 multiple. 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. overview 265 APPROACHWIDTH JUNCTION keyword. Highway 200 FILEO PRINTO keyword. Public Transport 749 ACCESSLINK GENERATE keyword. Network 376 ALLJ PATHLOAD ESTMO subkeyword. Public Transport 645 AONMETHOD PARAMETERS keyword. Pilot 95 AGF SETPA keyword. Distribution 556 ACTION NT keyword. general 63 APPLY CROWDMODEL keyword. Fratar 123 REPORT keywords. Cube Avenue 916 afterpgm NEWPAGE keyword. Public Transport 643 ADJUSTWAIT CROWDMODEL keyword. Public Transport 708 ACCUMULATE FILEO STOP2STOPO subkeyword. Highway 251 ADJUSTLINK CROWDMODEL keyword. Network 366 PLOTTER HEADER subkeyword. TPP2UB 865 ANSWER PROMPT keyword. Matrix 504 FILEO PRINTO subkeyword. Highway 244 ADJUST phase Cube Avenue 907 Highway program 159 stack for. eliminating 788 report 749 restricting to modes 647 ACCESS_C LINE NODES subkeyword. geometric signals 285 JUNCTION keyword. declaring in Matrix 437 user. Pilot 107 AUTOARRAY FILEI DBI subkeyword. generating 564 production and attraction. Highway 243 sorting 72 sorting. Network 350 Cube Voyager Reference Guide 947 . Cube Avenue 930 Matrix. RECI 483 populating with LOOKUP. Network 359 B B Highway array 136 Network variable 332 print format code.Index B arrays creating and populating 490 Cube Cluster and 886 field names in. declaring in Network 335 user-defined. utility-based model 448 BASEDEMANDMW XCHOICE keyword. Cube Avenue 916 ATTACHMENTS SENDMAIL keyword. Matrix 474 finding keys in. utility-based model 456 beforepgm NEWPAGE keyword. utility-based model 455 BASEGDBNETWORK FILEO LINEO subkeyword. example 60 production and attraction 115 production and attraction. Public Transport 681 BASEDEMAND CHOICE keyword. Matrix 511 BASEUTILS CHOICE keyword. convergence script 167 variables for 168 BANDWIDTH PLOTTER keyword. Matrix 487 MERGE keyword. cost-based model 445 BASECOSTSMW XCHOICE keyword. string items 68 BALANCE Generation control statement 567 Highway variable 137 BALANCE variable functions for 169 setting. referencing 549 route-enumeration components 652 setting to same value. TPP2UB 865 AVE FILEI ZDATI subkeyword. cost-based model 452 BASEDATA FILEI TURNPENI subkeyword. Highway 193 FILEI ZDATI subkeyword. Network 365 BASE1 PRINTROW keyword. reporting in Highway 243 link work. Matrix 474 AUTOCOEF PARAMETERS keyword. Public Transport 693 BASEMW FREQUENCY keyword. utility-based model 448 BASEUTILSMW XCHOICE keyword. number of 571 production and attraction. cost-based model 452 XCHOICE keyword. DBI 474 Matrix. reporting in Matrix 530 ARRAYSUM COMP function. Matrix 464 Matrix built-in function 395 ARRIVALTIME FILEO PACKETLOG subkeyword. overview 265 AVEX0 FILEI ZDATI subkeyword. declaring in Highway 175 user. Highway 150 internal. Network 377 specifying with keywords 25 string valued 487 user. denoting 742 link. general 69 BASECOSTS CHOICE keyword. Pilot 95 beforesys NEWPAGE keyword. Matrix 439 Highway 136 initializing. Pilot 95 BEG FILEI LINKI VAR subkeyword. Network 359 AVERAGELANEWIDTH JUNCTION keyword. Highway 193 FILEI ZDATI subkeyword. numeric items 66 print format code. Matrix 487 MERGE keyword. cost-based model 445 CHOICE keyword. Public Transport 685 FILEO NTLEGO subkeyword. sorting in Matrix 532 zonal data. Highway 245 sorting. including in 748 bottleneck modeling as generalized cost 773 modeling with crowding 834 queuing location. Network 378 CAPACITYFOR COMP function. Public Transport 600 skim function. Public Transport 646 skim function. summary 604 BRDPEN FACTORS keyword. overview 265 JUNCTION keyword. Network 376 SPDCAP keyword. empirical roundabout 306 JUNCTION keyword. saturation-flow priority junctions 325 JUNCTION keyword. Public Transport 601 skim function. overview 265 JUNCTION keyword. Cube Avenue 909 Highway variable 135 Highway variable. Public Transport 646 BIN FILEO TURNVOLO file format 203 boarding penalty example 855 mode specific 646 perceived. overview 266 CAPFAC applying in Cube Avenue 904 PARAMETERS keyword. Highway 245 SPDCAP keyword. saturation-flow priority junction 326 JUNCTION keyword. including in 689 number. empirical roundabout 307 JUNCTION keyword. Highway LINKREAD phase 152 variable. Cube Avenue 935 CAPLINKENTRY PARAMETERS keyword. skim function 600 reducing during transfers 774 boarding point first.Index C BESTJRNY skim function. Public Transport 687 C C DYNAMIC keyword. including in 685 link output. geometric signals 286 JUNCTION keyword. wait curve used 756 transit leg definition 783 wait time at 773 boardings example 855 line output. overview 265 BYCLASS FILEO LINKO subkeyword. outside LINKREAD phase 216 setting. skim function 603 BRDINGS 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. Cube Avenue 904 CALL Distribution control statement 440 Fratar control statement 440 Generation control statement 440 Matrix control statement 440 CANSHARELEFT JUNCTION keyword. example value 142 print format code. string items 68 set value. Highway 241 REPORT keyword. skim function 602 passenger loading report. overview 266 CAPACITYSLOPE JUNCTION keyword. signals 280 CANSHARERIGHT JUNCTION keyword. Cube Avenue 920 trips affected. Network 338 Highway function 137 Network function 333 CAPACITYINTERCEPT JUNCTION keyword. Cube Avenue 920 948 Cube Voyager Reference Guide . example in Cube Avenue 934 value computed. Public Transport 602 skim function. summary 604 BESTPATHONLY FACTORS keyword. default wait curve 758 first. signals 281 CAPACITY REPORT keyword. numeric items 66 print format code. Highway 216 scaling input capacity with. Pilot 89 Cluster. Public Transport 602 skim function. general 43 CROSSTAB keyword. Public Transport 809 transit choices. geometric signals 286 CONFVAR FILEO ESTMICPO subkeyword. Matrix 528 CHANGEATLASTSTOP PARAMETERS keyword. replacing 405 XCHOICE. Public Transport 738 CHECKRETURNCODE WAIT4FILES keyword.exe 895 CmpNumRetNum 32 CNT FILEI ZDATI subkeyword. Generation 569 FILEO RECO subkeyword. Public Transport 803 CHOICECUT FACTORS keyword. Public Transport 698 connectors access. starting Cube Voyager from 14 comments 22 COMMPATH DISTRIBUTEINTRASTEP keyword. restricting modes 647 egress. Pilot 84 example 98 COEFF CHOICE DESTSPLIT subkeyword 446 CHOICE SPLIT subkeyword 447 XCHOICE DESTSPLIT subkeyword 453 XCHOICE SPLIT subkeyword 454 COL CROSSTAB keyword. general 62 REPORT MARGINREC subkeyword. Public Transport 806 walk choice. overview 266 CFORM FILEO PAO subkeyword. differences with 458 choice modeling absolute logit model 407 alternative alighting. Cube Avenue 920 PARAMETERS keyword. geometric signals 287 JUNCTION keyword. Public Transport 808 destination choice model 428 general considerations 433 incremental logit model 415 introduction 405 mode-and-destination-choice model 430 route decisions. Cube Cluster 894 DISTRIBUTEMULTISTEP keyword. general 44 Cube Voyager Reference Guide 949 . Matrix 504 PRINT keyword. Public Transport 647 CIRCULAR LINE keyword. Pilot 107 CENTRALBUSINESSDISTRICT JUNCTION keyword. geometric priority junctions 320 JUNCTION keyword. Cube Cluster 892 CHOICE Matrix control statement 444 Matrix control statement. Network 342 COMBINE FILEI LINKI subkeyword. Network 359 CODE CLEARERROR keyword. Cube Cluster 891 COMP control statement. Highway 198 PARAMETERS keyword. Public Transport 721 CLEARERROR Pilot control statement 84 CLEARFILEO DOWNLOAD 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. Highway 194 FILEI ZDATI subkeyword.Index C CC SENDMAIL keyword. summary 604 composite cost skim function 602 confidence levels matrix estimation 836 output links 698 CONFLICTINGBIKE JUNCTION keyword. Highway 216 command prompt. Network 348 FILEO MATO keyword. Highway 197 FILEO SCREENLINEO subkeyword. overview 266 CENTRALRESERVATIONWIDTH JUNCTION keyword. restricting modes 647 CONSOLE control statement. Public Transport 803 transfer points. Matrix 487 MERGE keyword. Public Transport 630 Matrix program. Highway 132 target totals. iteration control 118 intersection modeling and 263 multiple purposes and 547 output matrices and 122 output matrices. adjusting for 125 COPY Pilot control statement 87 COS 34 COST GENERATE keyword. Highway 166 phases and. Highway 218 PATHLOAD keyword. Highway 200 COSTS CHOICE keyword. cost-based model 453 COUNTVAR FILEO ESTMICPO subkeyword. two-way stop 296 CROSSING2ENTRY JUNCTION keyword. overview 266 JUNCTION keyword. Highway 163 Distribution model 545 Fratar distribution 114 Fratar distribution. Public Transport 624 MATI phase. list of 436 Matrix program. Highway 197 CRITICALGAP JUNCTION keyword. geometric priority junctions 321 CROSSINGLENGTH GEOMETRIC priority junctions 321 JUNCTION keyword. Public Transport 709 Highway array 136 NT keyword. gap-acceptance roundabout 316 JUNCTION keyword. empirical roundabout 309 JUNCTION keyword. Public Transport 735 value set.Index C CONSOLIDATE PARAMETERS keyword. Highway program 250 subkeywords 26 tokens 21 CONVERGE phase Cube Avenue 908 Highway program 166 not specifying. Public Transport 625 Distribution program 552 fields 24 Generation program 566 Highway program 174 Highway program. Public Transport 629 stacks. Public Transport 623 null blocks 22 overview 41 Public Transport program 632 SELECTIJ phase. Public Transport 835 Cube Avenue 927 default testing. geometric priority junctions 321 CROSSING2EXIT JUNCTION keyword. empirical roundabout 308 JUNCTION keyword. types 133 keywords 25 LINKREAD phase. cost-based model 445 COSTSMW XCHOICE keyword. Highway LINKREAD phase 153 COSTDEC FILEO PATHO keyword. types 396 Network program 334 NODEREAD phase. Highway program 163 stack for. Highway program 251 convergence crowding model. summary 877 DATAPREP phase. Public Transport 627 MATO phase. 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. empirical roundabout 309 CROSSTAB Network control statement 341 950 Cube Voyager Reference Guide . writing 554 phase supporting. setting 687 process. string items 68 DATAPREP Public Transport phase 625 DBF FILEO PAO subkeyword. Public Transport 757 CWDCOSTP skim function. 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. Generation 569 FILEO TURNVOLO file format 203 DBF files dumping link and node records to 387 fields. summary 604 CWDWAITP skim function. Public Transport 756 CSV PATHLOAD TRACE subkeyword. signals 281 D D print format code. skim function 597 seat occupancy value 723 theory 830 CROWDMODEL Public Transport control statement 643 CRUSHCAP LINE keyword. Public Transport 722 VEHICLETYPE keyword. numeric items 66 print format code. Public Transport 755 crowding actual wait time. producing for 197 MATO file. overview 266 JUNCTION keyword. Public Transport 642 WAITCRVDEF keyword. writing to with Matrix RECO 505 Generation program output 569 linking to LOOKUPI file 52 Cube Voyager Reference Guide 951 . producing for 684 Public Transport screenline file. summary 604 CWDWAITA skim function. 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. skim function 597 perceived wait time. updating 834 link-travel-time adjustment 830 outputs. general 62 CTLFILE RUN keyword. producing for 501 Public Transport demand matrices 836 Public Transport intercept file. updating 834 control statement defining 643 in-vehicle-time effects 774 link travel times. Highway 234 PRINT keyword. Pilot 103 Cube Analyst intercept file. Public Transport 722 VEHICLETYPE keyword. Public Transport 599 skim function.Index D crowd modeling boarding probability. summary 604 CYCLETIME JUNCTION keyword. Public Transport 597 skim function. Public Transport 597 skim function. 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. producing for 698 screenline data file. Public Transport 691 FILEO NETO keyword 200 FILEO NETO subkeyword. Public Transport 648 DEMAND CHOICE keyword. Highway 231 REPORT LINES subkeyword. cost-based model 453 XCHOICE keyword.Index D DBF files (continued) matrix data input files. geometric signals 287 DELDISTRIBFILES WAIT4FILES keyword. utility-based model 456 DETAILS FILEI LINKI subkeyword. Matrix 487 DEFAULTCONF FILEO ESTMICPO subkeyword. DBI 473 Matrix program input. Highway 202 PATHLOAD PATH subkeyword. Public Transport 698 DELACCESSMODE FACTORS keyword. cost-based 453 pure mode-choice. Highway 201 FILEO TURNVOLO keyword. utility-based model 456 demand matrices Public Transport. specifying 458 description 428 example code 538 using gravity model 544 DESTSPLIT CHOICE keyword. cost-based (XCHOICE) 453 assigning zones. Public Transport 747 REPORT LINEVOLS subkeyword. Public Transport 724 DELAY_C LINE NODES subkeyword. Highway 198 DEFCONF FILEO SCREENLINEO subkeyword. Highway 199 FILEO MATO subkeyword. cost-based model 445 CHOICE keyword. Highway 203 writing to. Public Transport 725 DELAYEQUATION JUNCTION keyword. RECI 482 stop-to-stop analysis. utility-based (CHOICE) 448 assigning zones. utility-based model 448 XCHOICE keyword. Matrix 473 DCOSTS CHOICE keyword. Cube Cluster 892 DELEGRESSMODE FACTORS keyword. Matrix 533 DBI FILEI keyword. Public Transport 693 FILEO SUBAREAMATO keyword. Matrix 475 FILEI RECI subkeyword. Public Transport 748 REPORT ZDAT keyword. Network 348 DEVICE PLOTTER keyword. Public Transport 700 turning volume file. Matrix 483 FILEO LINKO subkeyword. Matrix 498 FILEO MATO subkeyword. Matrix 530 DEFAULT FILEI ZDATI subkeyword. cost-based (CHOICE) 446 assigning zones. Highway 194 FILEI ZDATI subkeyword. Network 352 FILEO MATO subkeyword. Cube Avenue 917 design concepts 2 DESTINATION FILEO PACKETLOG subkeyword. Matrix 478 Matrix program input. cost-based model 445 DCOSTSMW XCHOICE keyword. Public Transport 647 DELETE Network control statement 345 DELETESTR 34 DELIMITER FILEI DBI subkeyword. Highway 243 REPORT ZDAT subkeyword. Matrix 500 FILEO TURNVOLO keyword. utility-based (XCHOICE) 456 combined with mode-choice 430 demand. cost-based model 453 DEADLINKS REPORT keyword. Cube Avenue 917 destination zones. Highway 202 DELMODE FACTORS keyword. cost-based model 446 CHOICE keyword. cost-based model 453 XCHOICE keyword. utility-based model 456 DEPARTTIME FILEO PACKETLOG subkeyword. Network 376 DEC FILEO MATO keyword. Public Transport 647 DELAY LINE NODES subkeyword. utility-based 456 specifying name. Network 365 952 Cube Voyager Reference Guide . utility-based model 448 XCHOICE keyword. Matrix 514 destination-choice model assigning zones. cost-based model 452 specifying name. cost-based model 453 XCHOICE keyword. estimating 836 pure mode-choice model. utility-based model 455 DEMANDMW XCHOICE keyword. Public Transport 602 skim function. Public Transport 709 DIST Highway array 136 NT keyword. 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. Highway LINKREAD phase 153 DISTANCE Highway variable 135 script variable.Index E DIRECTION GENERATE keyword. Cube Avenue 903 setting. utility-based model 449 DUTILSMW XCHOICE keyword. 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. summary 604 value. general 48 Highway control statement 209 Network control statement 356 Pilot control statement 92 EMME/2 data bank file MATI. example in Cube Avenue 934 value computed. Network 364 DRAWLINK PLOT keyword. example 508 ZDATI. Network 364 DUPLICATES REPORT keyword. 560 examples 559 friction factors 550 introduction 542 overview 542 DLL CALL keyword. Public Transport 725 DYNAMIC Cube Avenue control statement 909 DYNAMICLOAD Cube Avenue control statement 910 example. general 48 Highway control statement 209 Network control statement 356 Pilot control statement 92 ELSEIF control statement. writing with 504 retrieving matrix data. 559. TRACEI 765 generating 842 report 750 EGRESSLEGS REREPORT keyword. Network 376 DUPSTR character function 34 DUTILS CHOICE keyword. writing with 497 output matrix names 503 RECO. 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. Matrix 441 DOWNLOAD Pilot control statement 88 DRAWA PLOT keyword. example 507 writing with FILEO RECO. specifying as input with 478 MATO. common description 271 ENDCOPY Pilot control statement 87 ENDDISTRIBUTEMULTISTEP Cube Cluster control statement 891 Cube Voyager Reference Guide 953 . Public Transport 750 ELSE control statement. Public Transport 725 DWELL_C LINE NODES subkeyword. Public Transport 735 skim function. utility-based model 456 DWELL LINE NODES subkeyword. Public Transport 709 DIRECTLINK GENERATE keyword. specifiying with 486 empirical roundabout difference with gap-acceptance roundabout 277 example 314 keywords 305 model overview 304 ENABLE JUNCTION keyword. input file 678 destination zones printed. Highway 225 setting to true 204 evaluated routes destination zones printed. Matrix 484 responding to 95 transit line 741 ESTIMATEDDELAY JUNCTION keyword. output file 696 report 761 user-class specific 745 using FACTORS statements for 590 EQUATION 161 EQUITURNCOSTFAC PARAMETERS keyword. Public Transport 603 skim function. output file 696 origin zones printed. Highway 178 COMP MW subkeyword. input file 677 origin zones reported. Network 361 maximum in RECI records. overview 266 enumerated routes destination zones 695 destination zones reported. Generation 572 PROCESS keyword. overview 266 ENTRYWIDTH JUNCTION keyword. overview 266 ESTMDATO FILEO keyword. output file 696 file containing 695 maximum transfers in 653 origin zones 695 origin zones reported. common description 272 JUNCTION keyword. overview 266 ENTRYGATE FILEI TOLLMATI subkeyword. 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. maximum number 671 listing in run print file. output file 696 quality issues 844 report 762 EXCESSDEMAND skim function. empirical roundabout 309 JUNCTION keyword. Highway 218 errors clearing 84 factor file. Public Transport 637 954 Cube Voyager Reference Guide . utility-based model 448 COMP MW subkeyword. output file 697 destination zones reported. Highway 240 ENDPROCESS Generation control statement 571 Highway control statement 239 Network control statement 374 ENDRUN Pilot control statement 102 ENTRYANGLE JUNCTION keyword. input file 677 destination zones reported. summary 604 EXCLUDE CHOICE DESTSPLIT subkeyword. Matrix 461 COMP MW subkeyword.Index E ENDIF control statement. Matrix 484 maximum in data records. cost-based model 446 CHOICE DESTSPLIT subkeyword. input file 678 origin zones printed. Highway 190 ENTRYRADIUS JUNCTION keyword. Highway 197 impact on Cube Avenue 915 impact on Cube Cluster 885 ESTMO impact on Cube Avenue 923 PATHLOAD keyword. output file 697 origin zones reported. empirical roundabout 312 JUNCTION keyword. Public Transport 603 skim function. empirical roundabout 311 JUNCTION keyword. summary 604 EXCESSPROP skim function. Highway 197 impact on Cube Avenue 915 impact on Cube Cluster 885 ESTMICPO FILEO keyword. Public Transport 739 EXTRACTCOST GENERATE keyword.Index F EXCLUDE (continued) FILEI LINKI subkeyword. overview 30 selection. defining 665 report 766 fare model assigning 649 defining 663 input file for. controlling with 590 FAIL LOOKUP keyword. cost-based model 453 XCHOICE DESTSPLIT subkeyword. general 52 FARE PARAMETERS keyword. Public Transport 672 FAREMATRIX FARESYSTEM keyword. Public Transport 710 EXTRAXFERS1 FACTORS keyword. overview 36 variables in 39 EXTENDREPORT PARAMETERS keyword. Network 352 FILEO NETO keyword. Public Transport 709 EXCLUDERECI FILEO RECO subkeyword. Matrix program 463 computing values with FUNCTION 206 LOOKUP statement 51 numeric. Public Transport 648 EXTRAXFERS2 FACTORS keyword. Public Transport 648 F factor file input. Public Transport 600 skim function. Highway 200 FILEO NETO subkeyword. overview 266 JUNCTION keyword. Fratar 125 XCHOICE DESTSPLIT subkeyword. overview 266 EXP 32 expressions COMP statements 43 COMP. Matrix 504 EXCLUSIVELANES JUNCTION keyword. Network 348 FILEO LINKO subkeyword. Public Transport 738 EXTENDRUNTIMES PARAMETERS keyword. Highway 190 EXITLANES JUNCTION keyword. utility-based model 456 EXCLUDEGROUP PATHLOAD keyword. Public Transport 665 FAREI FILEI keyword. summary 604 FAREFROMFS FARESYSTEM keyword. Public Transport 665 FAREMSG PARAMETERS keyword. Highway 211 SETPA keyword. Public Transport 739 fare matrices input file containing 672 name. Highway 225 EXCLUDEJ PATHLOAD keyword. Distribution 557 SETPA keyword. names of 671 maximum errors 671 validating fare data in 671 FACTORI FILEI keyword. common description 272 JUNCTION keyword. Public Transport 672 FAREMATI FILEI keyword. Highway 225 EXCLUDELINK GENERATE keyword. specifying 672 purpose 775 FAREA skim function. Network 354 JLOOP 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. Public Transport 671 FACTORS network development processing 588 Public Transport control statement 644 route enumeration. geometric signals 287 EXITONLY JUNCTION keyword. Public Transport 740 Cube Voyager Reference Guide 955 . Highway 242 FILEI control statement. Distribution 553 FIELDS FILEI DBI subkeyword. 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. Public Transport 649 LINE keyword. Matrix 524 REPORT MARGINREC subkeyword. Matrix 525 WAIT4FILES keyword. including cost in 739 skim functions for 600 system describing 663–670 validating in factor file 671 zones for 825 FARESYSTEM FACTORS keyword.Index F FAREP skim function. Matrix 476 FILEI MATI subkeyword. general 52 PLOTTER keyword. Matrix 528 REPORT VDTSPD keyword. Matrix 505 FILE COPY keyword. Network 376 SYNCHIMP control statement 866 TPP2UB control statement 864 UB2TPP control statement 862 FILEO control statement. specifying for 722 matrix reports 766 methods for defining structure 821 modeling in Public Transport 818–830 models for. Public Transport 668 FFACTORS GRAVITY keyword. matrices 672 input file. Pilot 89 example. general 62 READ keyword. Matrix 500 FILEO RECO subkeyword. overview 775 multiple systems in network 823 overview 818 route evaluation. Public Transport 666 FAREZONES FARESYSTEM keyword. Network 365 FILLMW Distribution control statement 510 Fratar control statement 510 Highway control statement 206 Matrix control statement 510 956 Cube Voyager Reference Guide . 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. Pilot 88 LOOKUP keyword. Network 376 SYNCHIMP control statement 867 TPP2UB control statement 864 UB2TPP control statement 863 FILES keyword RENUMBER keyword. general 45 Cube Avenue control statement 915 Distribution control statement 496 DOWNLOAD keyword. Network 374 Public Transport control statement 670 REPORT keyword. Matrix 479 FILEI RECI subkeyword. Public Transport 722 Public Transport control statement 663 FARETABLE FARESYSTEM keyword. network 366 PRINT keyword. Public Transport 600 skim function. 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. summary 604 fares boarding and transfer costs 823 determining trip cost from 823 examples 828 generalized cost component 772 input file. missing data 740 line. Matrix 484 FILEO MATO subkeyword. control statements 672 input file. general 71 RENUMBER keyword. use in 550 example. Matrix 501 FILEO MATO subkeyword. Matrix 506 PRINT keyword. Network 352 FILEO PAO subkeyword. Generation 570 FILEO RECO subkeyword. two-way stop 297 FRACTIONS PARAMETERS COMBINE keyword. Public Transport 735 FMVOLS FILEO LINKO subkeyword. Pilot 107 FROMNODE GENERATE keyword. Public Transport 658 FACTORS XFERFACTOR subkeyword. Network 367 PLOTTER LEGEND subkeyword. Network 359 FirstReadyNode function 897 FIRSTZONE Cube Cluster impact 887 Matrix built-in variable 394 FLARELENGTH JUNCTION keyword. Public Transport 660 SENDMAIL keyword. Network 342 CROSSTAB VAR subkeyword. Network 354 FILEO PACKETLOG subkeyword. Public Transport 710 FULLPATH PATHLOAD PATHO subkeyword. Cube Avenue 917 FILEO SUBAREAMATO keyword. Public Transport 725 FMON LINE NODES subkeyword.Index F FIRST FILEI ZDATI subkeyword. empirical roundabout 313 JUNCTION keyword. Highway 194 FILEI ZDATI subkeyword. typical process 58 expression. 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. Network 343 FILEO LINKO subkeyword. Matrix 487 MERGE keyword. Public Transport 722 FMOFF LINE NODES subkeyword. Highway 199 FILEO MATO subkeyword. two-way stop 296 FONT PLOTTER FOOTER subkeyword. two-way stop 297 FREQBYMODE FACTORS keyword. Network 366 PLOTTER HEADER subkeyword. general 69 REPORT MARGINREC subkeyword. 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. Network 371 FOOTER PLOTTER keyword. Public Transport 687 FMVOLT NT keyword. geometric priority junctions 321 JUNCTION keyword. Network 368 PLOTTER POSTLINKVAR subkeyword. two-way stop 296 FMCAPACITY LINE keyword. Public Transport 735 FOLLOWUPTIME JUNCTION keyword. overview 266 JUNCTION keyword. Highway 203 FOURLANEMAJOR JUNCTION keyword. Public Transport 659 FACTORS XFERPEN subkeyword. general 63 PRINTROW keyword. Highway 201 FILEO TURNVOLO keyword. Public Transport 725 NT keyword. overview 266 FLARESTORAGE JUNCTION keyword. overview 266 JUNCTION keyword. Public Transport 692 FILEO NETO subkeyword. specifying 553 FROM FACTORS XFERCONST subkeyword. Network 370 PLOTTER POSTNODEVAR subkeyword. overview 266 JUNCTION keyword. Matrix 528 FORMAT character function 34 FILEO LINKO subkeyword. Network 353 FILEO MATO keyword. Network 366 FORM CROSSTAB COMP subkeyword. Public Transport 725 FMVOL LINE NODES subkeyword. Highway 231 Cube Voyager Reference Guide 957 . gap-acceptance roundabout 316 JUNCTION keyword. built-in 395 numeric.Index G FUNCTION Highway control statement 206 functions character. priority junction 319 geometric priority junctions example 324 keywords 320 GEOMETRYSOURCE Network variable 332 GLOBAL control statement. two user class 858 keywords to avoid excessive legs 845 network development 588 nontransit network. Highway program 138 Cube Avenue 929 Highway program 136 lookup 36 matrix 180–183 Matrix program. 512 Pilot control statement 91 Public Transport control statement 715 958 Cube Voyager Reference Guide . 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. specifying 644 route evaluation. route enumeration 775 converting from monetary fares 658 fare component 775 fares. 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. general 33 utility. 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. Highway 218 using in BALANCE variable 168 gap-acceptance roundabout difference with empirical roundabout 277 example 317. general 34 COMP expression 464 convergence. general 32 trig. using for 799 theory. including in 739 in-vehicle time component 773 logit choice models 408 route enumeration and evaluation. general 46 GOTO Distribution control statement 512 Fratar control statement 512 Generation control statement 512 Highway control statement 208 Matrix control statement 512. supporting Cube Cluster 897 G GAP convergence testing calculation 166 Highway variable 137 PARAMETERS keyword. singly constrained 537 implementation guidelines 543 GROUPEDMODES FILEO STOP2STOPO subkeyword. 560 example. two-way stop 298 GRAVITY Distribution control statement 552 gravity model alternative to complete formulation 544 control statement for 552 description 542 example 559. general control statement 46 IDP commands that disable 885 description 879 using when summarizing zonal values 887 IF control statement. rules for 759 wait curve. subarea trip extraction 157 HOV facilities. invoking 893 examples 252–260 functions 136 ILOOP phase 154 intersection modeling 261 introduction 130 linking to Public Transport program 838 LINKREAD phase 150 logic. select link 156 zonal loop. use for 776 selecting 740 wait curve. Public Transport 740 HEADER PLOTTER keyword. getting started 141 control statement overview 133 control statements 174 CONVERGE phase 166 convergence functions 138 convergence variables 137 Cube Cluster. Public Transport 701 GROUPS FILEO STOP2STOPO subkeyword. Public Transport 676 FILEO ROUTEO subkeyword. selected zone loading 157 zonal loop. Highway 241 IBOARDFARE FARESYSTEM keyword. 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 Cube Voyager Reference Guide 959 . specifying 723 route enumeration. overview 266 JUNCTION keyword. default 759 wait curve. Public Transport 695 Highway variable 135 Matrix built-in variable 394 REPORT VDTSPD keyword. LINE keyword. assigning trips to 145 I I FILEI ROUTEI subkeyword. Public Transport 702 H HDWAYPERIOD PARAMETERS keyword. specifying in 757 HEADWAY. specifying 723 line. Network 367 HEADERONLY PARAMETERS keyword. maximum 219 multiple iteration 156 setting up scripts 141 using PATHLOAD statement 154 Highway program ADJUST phase 159 arrays 136 assignment. geometric signals 288 JUNCTION keyword. Public Transport 723 HEADWAY_R LINE keyword.Index H GRADE JUNCTION keyword. overview 248 SETUP phase 150 variables 135 zonal loop. UB2TPP 863 headway computing wait time from 773 line in reverse direction. Public Transport 668 ID. Public Transport 723 hierarchical logit model 421 highway assignment introduction 130 iteration volume combinations 163 iterations. Network 354 JLOOP keyword. Public Transport 606 network development. Highway 231 INCLUDEJ PATHLOAD keyword. Highway 200 FILEO NETO subkeyword. utility-based model 448 COMP MW subkeyword. empirical roundabout 314 JUNCTION keyword. skim function 598 INITIALQUEUE JUNCTION keyword. specifying 198 960 Cube Voyager Reference Guide . Public Transport 589 route enumeration. Public Transport 591 route evaluation. cost-based model 453 XCHOICE DESTSPLIT subkeyword. Distribution 557 XCHOICE DESTSPLIT subkeyword. Public Transport 667 LOOKUP keyword. requirement for 836 output file name. Matrix 461 COMP MW subkeyword. Public Transit 684 INTERPOLATE FARESYSTEM FARETABLE subkeyword. specifying 188 purpose 262 results file. 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. Public Transport 710 incremental logit model 415 initial wait time actual. Public Transport 638 FILEO LINKO subkeyword. utility-based model 456 INCLUDE0 FILEO TURNVOLO keyword. Highway 210 SETPA keyword. Highway 197 output file name. Network 376 input files See also FILEI phase-based processing. Public Transport 607 skimming. Public Transport 684 INTERCEPTO FILEO keyword. Network 353 FILEO NETO keyword. cost-based model 446 CHOICE DESTSPLIT subkeyword. general 52 intersection modeling control statements 265 description 263 introduction 262 invoking at nodes 188 keywords 269 limitations 263 nodes invoked at. Highway 178 COMP MW subkeyword. Fratar 125 SETPA keywords. 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. skim function 597 perceived. Highway 225 INCLUDELINK GENERATE keyword. Network 379 Public Transport program. Public Transport 592 select-link process. Highway 204 INCLUDECOST PATHLOAD PATHO subkeyword. overview 837 specifying 44 INPUT phase Network program 380 variable associations 382 inputs loading process.Index I ILOOP phase computing volumes. overview 266 INLIST function example 399 numeric function 33 INPUT REPORT keyword. Highway 251 INCLUDE CHOICE DESTSPLIT subkeyword. Public Transport 594 INSCRIBEDDIAMETER JUNCTION keyword. common description 273 JUNCTION keyword. Distribution 545 Cube Avenue parameters 933 highway assignment. Public Transport 597 skim function. Public Transport 598 skim function. general 70 REPORT VDTSPD keyword. specifying 198 JUNCTIONI FILEI keyword. summary 604 IWAITCURVE FACTORS keyword. Public Transport 695 Highway variable 135 JLOOP keyword. Public Transport 643 REPORT keyword. maximum 219 maximum. Distribution 556 testing for convergence 164. 166 writing output matrices. SYNCHIMP utility 867 JUNCTION junction file control statement 265 junction file control statements 265 input. Highway 188 JUNCTIONO FILEO keyword. Public Transport 651 IWAITP skim function. summary 604 J J FILEI ROUTEI subkeyword. Highway 138 convergence variables 137 convergence.Index J intersections control statements 265 keywords. 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. crowd-modeling runs 643 processing. Matrix 516 JLOOP keyword. Matrix 476 JOINTOFIELDS FILEI DBI subkeyword. specifying 188 output. Public Transport 677 FILEO ROUTEO subkeyword. Cube Avenue 916 writing path output file 201 ITERS FILEO PATHO keyword. common 269 priority junctions 318 roundabouts 303 signal controlled 279 stop. Highway 198 Cube Voyager Reference Guide 961 . Distribution 555 maximum. 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. Highway 201 IWAITA skim function. Cube Avenue 924 processing. Public Transport 718 Matrix built-in variable 394 PRINTROW keyword. all-way 302 two-way stop-controlled 294 two-way yield-controlled 318 INTRA Matrix keyword 397 intrastep distributed processing. Distribution 556 iterations ADJUST phase 160 assignment and capacity restraint 142 combining MATO matrices from 219 CONVERGE phase 166–173 converge phase functions. Fratar distribution 118 reported. Matrix 477 JUNCDATAO FILEO keyword. Highway 210 JLOOP keyword. Fratar 122 number. Distribution 554 writing packet log. Public Transport 750 LINEI FILEI keyword. example 767 REREPORT keyword. Highway 225 LINKIDLASTUSE PATHLOAD LINKIDARRAY subkeyword. Distribution 553 L L print format code. overview 266 JUNCTION keyword. Network 359 LASTITERATION. Highway 194 FILEI ZDATI subkeyword. Highway variable 135 LASTZONE Cube Cluster impact 887 Matrix built-in variable 394 LAYOUTI FILEI keyword. Network 378 LANESI FILEI keyword. Public Transport 751 LINKCLASS Highway variable 135 setting.SPDCLASS input field. Public Transport 750 lines. string items 68 LAMBDA. Public Transport 751 LINEO FILEO keyword. Public Transport 673 LINELINELEG REREPORT keyword. Highway LINKREAD phase 151 variable.Index K K keywords See also individual keyword names description 25 documentation descriptions 28 intersection modeling 269 subkeywords 26 values 28 KFACTORS GRAVITY keyword. SYNCHIMP utility 866 LAST FILEI ZDATI subkeyword. Highway 226 LINKLOOP Highway control statement 212 Public Transport control statement 731 962 Cube Voyager Reference Guide . Highway 226 LINKIDARRAY PATHLOAD keyword. Public Transport 651 LAMBDASEARCH PARAMETERS COMBINE keyword. Cube Avenue 903 LINE PLOTTER LEGEND subkeyword. Public Transport 734 LEGEND PLOTTER keyword. Public Transport 747 report produced. SYNCHIMP utility 866 LEFTDRIVE FILEO NETO subkeyword. Cube Avenue 903 LINKI FILEI keyword. Highway 218 LAMBDAW FACTORS keyword. Highway 245 SPDCAP keyword. Highway 225 LINKIDCNTMW PATHLOAD LINKIDARRAY subkeyword. Cube Avenue 904 LI. Highway 226 LINKIDMW PATHLOAD LINKIDARRAY subkeyword. Matrix 487 MERGE keyword. Public Transport 687 REPORT keyword. Public Transport 684 LINES FILEO LINKO subkeyword. Public Transit 652 LANEADJUST JUNCTION keyword. Network 368 Public Transport control statement 720 REREPORT keyword. Network 361 LEFTSTR 35 LEG NT keyword. Network 355 PARAMETERS keyword. Network 367 LEN FILEI LINKI VAR subkeyword. example in Cube Avenue 934 value computed. See transit lines LINEVOLS REPORT keyword. Cube Avenue 903 LI. numeric items 67 print format code. signals 282 LANES SPDCAP keyword.CAPCLASS input field.LANES input field. Public Transport 751 LINEZONLEG2 REREPORT keyword. Public Transport 748 LINEZONLEG1 REREPORT keyword. Network 350 LI. Highway variable 135 LAMBDAA FACTORS keyword. Network 347 LINKID#MW PATHLOAD LINKIDARRAY subkeyword.name Highway array 136 LI. Index L LINKMERGE phase controlling plotting 363 Network program 381 plotting 384 PROCESS block rules 375 records merging data 358 variable referencing 382 LINKNO. example 387 nontransit leg. specifying 917 demand using. Public Transport 671 FILEI FAREI subkeyword. Highway 191 FILEI TURNPENI subkeyword. nontransit legs 711 output file. characteristics of 365 dumping to DBF files. Public Transport 672 FILEI LINEI subkeyword. Public Transport 730 variables supporting 135 walk 772 links file defining output 686 lines data. Public Transport 723 VEHICLETYPE keyword. example 387 duplicate. Network 368 LINKPOST PLOT keyword. example 387 loops for processing. Network 361 LISTERRS FILEI RECI subkeyword. Public Transport 731 merging records from multiple files. Public Transport 756 loading analyses mode transfers 618 operator transfers 618 overview 617 stop-to-stop movements 618 loading process overview. Matrix 529 LIST_ERRS PARAMETERS keyword. Public Transport 679 FILEI TURNPENI subkeyword. Public Transport 815 trip matrix into public transport network 856 LOG control statement. Network 363 drawn. standard 49 impact on Cube Cluster 886 numeric function. maximum 709 one-way. selecting 609 drawing. Matrix 484 LN 33 LOADDISTFAC LINE keyword. including in 687 summing output by user class 687 LIST COMPARE keyword. Public Transport 702 GENERATE keyword. base 742 travel demand on. Public Transport 605 theory. Highway function 137 LINKO FILEO keyword. Highway variable 135 LINKNUM. Network 352 FILEO keyword. general 64 REPORT MARGINREC subkeyword. Public Transport 681 FILEO PAO subkeyword. Network 339 FILEI FACTORI subkeyword. Network 364 LINKREAD phase Cube Avenue 902 Highway program 150 Public Transport program 624 stack for. SYNCHIMP utility 867 LINKOFFSET PLOTTER keyword. Public Transport 673 FILEI SYSTEMI subkeyword. 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. loading 223 restricted use by mode 699 speed on. eliminating 358 group codes for. specifying in Public Transport 686 path. Generation 570 FILEO STOP2STOPO subkeyword. identifying 607 travel time computation. Public Transport 686 FILEO keyword. general 52 PRINT keyword. Public Transport 710 LOOKUP keyword. details about 714 GENERATE keyword. Highway 251 links arrays supporting 136 centroid connectors 935 computing walk and transit times 851 confidence level value 698 Cube Avenue packets. setting 244 listing in print file. non-input network 729 transit line time. practical considerations 435 Cube Voyager Reference Guide 963 . Public Transport 690 FILEO keyword. TPP2UB 864 FILEO keyword. Highway 213 input zones. Matrix 497 FILEO keyword. Highway array 136 M MAJORROADWIDTH JUNCTION keyword. Public Transport 644 using to control run order 76 LOS GRAVITY keyword. Highway 219 MATOEVERY PARAMETERS keyword. overview 267 MAPSCALE PARAMETERS keyword. Matrix 528 MARGINS impact on Cube Cluster 886 PLOTTER keyword. Pilot 90 LOOKUP keyword. Public Transport 731 general. Distribution 553 LOWCNT COMP function. Highway 189 FILEI keyword. Highway 198 FILEO keyword. general 53 LOOKUPI FILEI keyword. UB2TPP 863 Public Transport phase 630 MATOADJUST PARAMETERS keyword. Highway 210 terminating. Distribution 553 LOSRANGE GRAVITY keyword. Network 351 FILEI keyword. Network 369 MARGINREC impact on Cube Cluster 886 REPORT keyword. Public Transport 733 OPERATOR keyword. Highway 212 link records.name. Matrix 517 general variable. Public Transport 717 matrix columns. Public Transport 756 WAITCRVDEF keyword. Matrix 464 Highway function 137 Highway variable 135 Matrix built-in variable 394 matrix function. UB2TPP 862 Public Transport phase 626 MATO FILEO keyword.Index M logit models (continued) mode and destination choice 430 scale parameters 435 LONGNAME FARESYSTEM keyword. Matrix 529 MATI FILEI keyword. Highway 181 LOWEST COMP function. Public Transport 731 matrices. character function 35 LW. Public Transport 737 VEHICLETYPE keyword. Public Transport 757 LONGNAMECROSDCRVDEF keyword. Matrix 514 matrix column cells. general 51 LOOKUP NAME subkeyword. Network 368 MAPWINDOW PLOTTER keyword. Public Transport 668 LINE keyword. Public Transport 674 FILEI keyword. Highway 189 FILEI keyword. Public Transport 642 LOOKUP control statement. Public Transport 723 MODE keyword. Fratar 122 964 Cube Voyager Reference Guide . Distribution 554 PARAMETERS keyword. Cube Avenue 936 jumping to end 341 link records. Public Transport 740 PLOTTER keyword. Network 369 REPORT keyword. Highway 181 LTRIM. Matrix 478 FILEI keyword. Matrix 478 FILEI keyword. Matrix 465 Highway function 137 Matrix built-in function 395 matrix function. geometric priority junctions 322 JUNCTION keyword. TPP2UB 864 FILEI 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 465 Matrix built-in function 395 MATVALCACHE PARAMETERS keyword. Matrix 519 PARAMETERS keyword. Fratar 122 PARAMETERS keyword. Public Transport 653 MAXFIELDS FILEO MATO subkeyword. Matrix 520 zonal timing. Public Transport 673 FILEI RECI subkeyword. Matrix 485 MAXSTRING PARAMETERS keyword. Public Transport 699 PARAMETERS keyword. Matrix 487 MERGE keyword. list of 436 control statements. Public Transport 711 MAXERRS FILEI FACTORI subkeyword. Highway 219 MAXLINKDELAY FILEI TURNPENI subkeyword. Distribution 555 PARAMETERS keyword. Matrix 502 MAXITERS convergence testing calculation 167 PARAMETERS keyword. Pilot 99 MDP 881 MERGE Network control statement 358 REPORT keyword. Highway 219 PARAMETERS keyword. built-in 394 MATSTAT REPORT keyword. Highway 179 Matrix program control statements. COMP statement 464 introduction 392 variables. Distribution 555 PARAMETERS keyword. working with 397 variables. built-in 395 functions. Matrix 519 PARAMETERS keyword. Highway 233 MAXMW PARAMETERS keyword. Public Transport 671 FILEI LINEI subkeyword. Public Transport 652 MAXCOST GENERATE keyword. Highway 219 PARAMETERS keyword. Network 359 numeric function 33 Cube Voyager Reference Guide 965 . general 70 MAXPTHPERSEG PARAMETERS keyword. Public Transport 682 MAXMSG PATHLOAD SUBAREAMAT subkeyword. Network 350 FILEI ZDATI subkeyword. Public Transport 744 zone pairs without valid routes 741 MEUSESNT FILEO SCREENLINEO subkeyword. Matrix 484 MAXFERS FACTORS keyword. Highway 194 FILEI ZDATI subkeyword.Index M matrices applying part to logit model 434 functions. Public Transport 740 MAXNTLEGS GENERATE keyword. Matrix 477 FILEI RECI subkeyword. Highway 222 zonal timing. Pilot 107 message 770 740 messages displaying 44 excessive travel time 738 zonal timing. Fratar 123 MAXRECS FILEI DBI subkeyword. Fratar 123 MAXSCAN FILEI RECI subkeyword. Highway 194 FILEI ZDATI subkeyword. types 396 Cube Cluster. Public Transport 711 MAXPERLINE PRINTROW keyword. Network 361 MAXCOMPD FACTORS keyword. Matrix 519 MAX FILEI ZDATI subkeyword. Network 376 MESSAGE CONSOLE subkeyword 44 SENDMAIL keyword. Matrix 529 MATVAL COMP function. Highway 180–183 intrazonal cells. Matrix 487 MERGE keyword. Network 359 numeric function 33 MAX_IP_ERRS PARAMETERS keyword. Matrix 484 MAXRMSE PARAMETERS keyword. Public Transport 740 MIN FILEI LINKI VAR subkeyword. Cube Avenue 921 MAXPURPS PARAMETERS keyword. invoking 893 examples 534 functions. junction file 188 Highway program 219 modeling approaches. Public Transport 736 Public Transport control statement 733 mode-and-destination-choice model 430 model period crowd model. overview 267 minimum-cost routes finding. Public Transport 633 MULTISTEP DISTRIBUTE keyword. Public Transport 691 MODE FACTORS FARESYSTEM subkeyword. theory on 794 generation process 662 maximum transfers permitted 645 MISSINGLINK FILEI TURNPENI subkeyword. Cube Cluster 894 minimum system requirements 6 MINIMUMCAPACITY JUNCTION keyword. Highway 219 modes access connectors. Cube Avenue 917 must-use mode enumerating routes with. Public Transport 682 MISSINGZI RENUMBER keyword. common description 273 JUNCTION keyword. Highway 199 FILEO MATO subkeyword. Matrix 503 FILEO MATO subkeyword. Public Transport 654 MW COMP keyword. Highway 177 COMP keyword. Public Transport 777 MODELPERIOD PARAMETERS keyword. Highway 226 PRINTROW keyword. See MDP MUMEXTRACOST FACTORS keyword. extra cost allowed 653 stop-to-stop movement data collected 703 transfer penalty 774 transfers between. Fratar 126 966 Cube Voyager Reference Guide . Matrix 460 COMP keyword. Public Transport 643 Cube Avenue 921 duration. general 70 SETPA keyword. Highway 175 ABORT keyword. theory 798 evaluating routes with 800 specifying 654 MUSTUSEMODE FACTORS keyword. Public Transport 649 LINE keyword. Network 335 ABORT keyword. Matrix 525 MISSINGZO RENUMBER keyword.Index M MINCOST GENERATE keyword. common description 274 JUNCTION keyword. overview 267 MSG ABORT keyword. enumerating routes with 798 required in transit route 654 required. Highway 192 FILEI TURNPENI subkeyword. report 769 turn-penalty free 682 MODES subkeyword FILEO STOP2STOPO. Public Transport 723 NT keyword. Matrix 510 function description 31 Highway array 136 Matrix built-in variable 394 PATHLOAD keyword. selecting 612 modes (continued) egress connectors. Public Transport 711 MINGROUPSIZE DISTRIBUTEINTRASTEP keyword. Public Transport 703 MOVEMENT JUNCTION keyword. Matrix 437 ABORT keyword. Cube Cluster 890 multistep distributed processing. Public Transport 637 FILLMW keyword. prohibiting 647 fare model 649 intercept data and 740 limiting selected routes to 781 link use restricted 699 logit choice model 407 must-use. Cube Avenue 921 PARAMETERS keyword. 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. Matrix 525 MO FILEO MATO keyword. Public Transport 653 MUSTMEETALL FILEO PACKETLOG subkeyword. Highway 194 FILEO ESTMDATO keyword. revising speed and capacity 245 input data files 346 output file 352 plotting 384. output file name 200 highway. Public Transport 839 times. processing 330 highway. Highway 204 naming conventions string variables. general 53 NET FILEO LINEO subkeyword. Network 338 variables. introduction 130 Highway. Highway 247 NAME CROWDCRVDEF keyword. Network 351 Cube Voyager Reference Guide 967 . Public Transport 721 LOOKUP keyword. Matrix 506 FILEO SUBAREAMATO keyword. Highway 200 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. Matrix 503 FILEO MATO subkeyword. input file 189 highway. Public Transport 752 TURNS keyword. Highway 231 VEHICLETYPE keyword. Public Transport 588 highest node number 362 highway. Highway 188 Network variable 332 REREPORT keyword. Public Transport 737 PATHLOAD PATHO subkeyword. Public Transport 782 speeds. generating nontransit legs 706 public transport. Network 353 FILEO keyword. input file 675 Public Transport. Public Transport 733 OPERATOR keyword. Highway 199 FILEO MATO subkeyword. overview 267 NODEI FILEI keyword. Public Transport 849 development process overview. Public Transport 839 zones. Public Transport 694 NETI FILEI keyword. Highway 189 FILEI keyword. Matrix 478 FILEI RECI subkeyword. preparing 582 simplification of. general 39 NEAREST LOOKUP keyword. Highway 190 NETITOLLROAD FILEI TOLLMATI subkeyword. number in 362 NEWPAGE Pilot control statement 95 NHB BALANCE keyword. Highway 228 NODE JUNCTION keyword. Highway 197 FILEO MATO keyword. Public Transport 685 FILEO NTLEGO subkeyword. Public Transport 756 WAITCRVDEF keyword. Public Transport 757 NAMES FILEO PAO subkeyword. Matrix 485 FILEI ZDATI subkeyword. Highway 191 NETO FILEO keyword. Public Transport 675 NETIENTRY FILEI TOLLMATI subkeyword. Public Transport 726 NOACCESS PATHLOAD MW subkeyword. general 53 MODE keyword. Public Transport 691 FILEO RECO subkeyword. Public Transport 642 FARESYSTEM keyword. Public Transport 668 FILEI DBI subkeyword.Index N N N FILEI JUNCTIONI subkeyword. developing 625 public transport. Distribution 567 NNTIME LINE NODES subkeyword. Generation 570 FILEO TURNVOLO keyword. Highway 190 NETIEXIT FILEI TOLLMATI subkeyword. common description 275 JUNCTION keyword. Highway 201 LINE keyword. 384 public transport. output file 692 public transport. Public Transport 755 WAITCRVDEF keyword. Public Transport 724 PARAMETERS keyword. portion allocated to 651 approaches at 269 Cube Cluster processing. selecting 611 turning volumes accumulated 247 wait curve associated 651 wait curve associated. Public Transport 658 FACTORS XWAITCURVE subkeyword. Public Transport 711 NTLEGO FILEO keyword. 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. nontransit legs 713 drawing. Public Transport 757 NUMBEROFLANES JUNCTION keyword. nontransit legs 710 output. Public Transport 703 Highway variable 135 LINE keyword. Public Transport 741 NOTMODES FILEI TURNPENI subkeyword. overview 267 968 Cube Voyager Reference Guide . Public Transport 733 OPERATOR keyword. intermediate 736 nontransit legs. Cube Avenue 921 nontransit leg. Public Transport 682 NT Public Transport control statement 734 NTBYLINK FILEO LINKO subkeyword.Index N NODEMERGE phase description 380 variable referencing 382 NODEO FILEO keyword. Public Transport 687 NTLEGI FILEI keyword. Public Transport 741 NOROUTEMSGS PARAMETERS keyword. FACTORS IWAITCURVE subkeyword. Public Transport 668 MODE keyword. Public Transport 693 NTLEGS FILEO LINKO subkeyword. Cube Avenue 917 origin. avoiding 845 generating 706 generating. including in Public Transport 694 Public Transport report. Public Transport 651 FACTORS WAITFACTOR subkeyword. Network 364 NODEREAD Public Transport phase 623 nodes alighting. transit line flag 721 stop-to-stop movements collected for 703 transit line 724–728 travel demand on. including in report 748 stop. Public Transport 688 null blocks 22 NUMBER CROWDCRVDEF keyword. Public Transport 661 FILEO STOP2STOPO subkeyword. Public Transport 737 VEHICLETYPE keyword. transfer points 661 wait-time weighting factor for 658 NODES. Network 355 FILEO keyword. Cube Avenue 917 destination. starting 896 destination. SYNCHIMP utility 867 NODEPOST PLOT keyword. start and finish 734 origin. Public Transport 642 FARESYSTEM keyword. Public Transport 676 NTLEGMODE GENERATE keyword. including in 752 stop. Network 363 fare zones 825 highest number in network 362 intersection modeling invoked at 188 maximum in RAM. all-way stop 302 JUNCTION keyword. identifying 607 travel demand on. Network 362 nontransit legs direction 709 excessive. Public Transport 591 route evaluation. Fratar 126 P2A BALANCE keyword. geometric signals 288 JUNCTION keyword. Distribution 558 SETPA keyword. Public Transit 649 LINE keyword. Highway variable 135 NumReadyNodes function 897 NUMRECS SORT keyword. Public Transport ONRUNERRORGOTO Pilot control statement 95 OPERATOR FACTORS FARESYSTEM subkeyword. Public Transport 728 Public Transport control statement 737 operators defining 737 demand using. Public Transport ONELINKREC FILEO LINKO subkeyword. Generation 567 PACKETLOG FILEO keyword. Public Transport OMITFARES FILEI FACTORI subkeyword. general 46 PAO FILEO keyword. Public Transport 592 skimming. utility-based model 449 ODEMANDMW XCHOICE keyword. overview 267 727 727 688 689 Cube Voyager Reference Guide 969 . Generation 573 SETPA keyword. utility-based model 449 ODEMAND CHOICE keyword. Pilot 103 SYNCHIMP control statement 867 TPP2UB control statement 865 UB2TPP control statement 863 PARKINGMANEUVERS JUNCTION keyword. Cube Avenue 917 output files See also FILEO naming 45 Pilot program 76 Public Transport program 837 waiting for subprocess. Cube Avenue 916 PAGEHEIGHT GLOBAL keyword. Public Transport 606 network development. cost-based model 446 CHOICE keyword. cost-based model 453 XCHOICE keyword. cost-based model 446 OCOMPUTIL CHOICE keyword. general 46 PAGEWIDTH GLOBAL keyword. Public Transport 736 ONLINE CONSOLE subkeyword 44 ONOFFS FILEO LINKO subkeyword. Public Transport 594 P P COMP keyword. general 72 O OCOMPCOST CHOICE keyword. Cube Cluster 891 outputs loading process. Public Transport 711 LINE 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. Public Transport 728 NT keyword. utility-based model 456 OFF LINE NODES subkeyword. working matrix 69 NUMLINKS. Public Transport 589 route enumeration. selecting 612 fare model 649 transit line 728 ORIGIN FILEO PACKETLOG subkeyword. Generation 568 REPORT keyword. Public Transport 671 ON LINE NODES subkeyword. Public Transport ONEWAY GENERATE keyword.Index O numbers print format 63 print format. Highway 232 PERCENT select-link expression keyword. generating report 746 flow-metered volume 735 hours. Highway 232 PATHTRACE Highway function 137 PATTERN FILEI MATI subkeyword. Matrix 504 PC REPORT keyword. two-way stop 298 PEDESTRIANPHASE JUNCTION keyword. Highway 241 PENIFACTOR PATHLOAD keyword. example report 767 distance. Highway 232 REPORT keyword. two-way stop 298 penalty boarding. 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. example report 767 hours. skim function 600 PENI PATHLOAD keywords. Highway 206 FILET keyword. generating report of 746 statistics. Matrix 509 PATHLOAD keyword. Matrix 480 FILEO MATO subkeyword. Highway 188 970 Cube Voyager Reference Guide . Fratar 123 PDIFF convergence testing calculation 167 Highway variable 137 PARAMETERS keyword. perceived. improving with new service 801 volume.Index P passenger loadings analyses 617 assigning 605 example report 857 report example 768 passengers assigning to trips 605 denied boarding 773 distance. 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. Public Transport 646 transfer. Public Transport 643 FILEI JUNCTIONI subkeyword. geometric signals 288 PEDESTRIANSPEED JUNCTION keyword. Highway 231 PATHOGROUP PATHLOAD PATHO subkeyword. perceived. skim function 600 transfer. skimming 814 utility. actual. geometric signals 288 JUNCTION keyword. Highway 219 PEDESTRIANFLOW JUNCTION keyword. specifying for nontransit legs 736 PASSWORD SENDMAIL keyword. Pilot 107 PATH FILET keyword. skim function 600 boarding. Highway 200 impact on Cube Avenue 923 impact on Cube Cluster 886 PATHLOAD keyword. Generation 573 PCOMP REPORT keyword. Public Transport 616 PERIOD CROWDMODEL keyword. signals 283 PHASINGI FILEI keyword. general 69 Distribution control statement 521 Fratar control statement 521 Highway control statement 239 Matrix control statement 521 Public Transport control statement 746 Cube Voyager Reference Guide 971 . Generation 572 PROCESS keyword. general 62 Distribution control statement 521 FILEO PAO subkeyword. Cube Avenue 921 PLANID PARAMETERS keyword. Network program 381 Network program 379 NODEMERGE. Matrix 504 FILEO keyword. general 65 Public Transport control statement 746 REPORT MARGINREC subkeyword. geometric signals 289 JUNCTION keyword. Matrix 529 PRINTFILES WAIT4FILES keyword. general 65 PRINTROW control statement. SYNCHIMP utility 867 PILOT example. Pilot 107 POST PLOTTER POSTLINKVAR subkeyword. 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. Public Transport 694 PRINT keyword. Pilot 90 FILEO keyword. Cube Cluster 893 printing defining character formats 67 defining numeric formats 66 example listing links in 387 PRINTO FILEO keyword. general 51 PRINT control statement. JUNCTION keyword. 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. Pilot 104 PHASE JUNCTION keyword. Fratar 126 PGM RUN keyword. general 63 PRINT PRINTO subkeyword. Highway 201 FILEO keyword. Network 371 POSTLINKVAR PLOTTER keyword. Highway 240 PROCESS keyword. overview 267 JUNCTION keyword. Network program 380 NODEREAD. overview 267 JUNCTION keyword. Network 370 POSTNODEVAR PLOTTER keyword. Network program 381 PHASES. 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. Public Transport 623 Public Transport program 620 SUMMARY. SYNCHIMP 868 PLATESIZE PLOTTER keyword. Network 355 FILEO keyword.Index P PGF SETPA keyword. Network 374 phases defining in scripts 239 INPUT. Network 371 POW 33 PREFIX LOG keyword. Network program 380 LINKMERGE. signals 282 PROCESS keyword. details 760 reports. general 54 print format code. example 324 geometric. keywords 325 PRNFILE RUN keyword. 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. Highway variable 135 PROMPT Pilot control statement 100 public transport network developing. TPP2UB 865 Q QUESTION PROMPT keyword. keywords 320 keywords 319 overview 318 saturation-flow. Cube Cluster 894 PROCESSNUM DISTRIBUTEMULTISTEP keyword. common description 275 JUNCTION keyword. numeric items 67 print format code.Index Q priority junctions 318 geometric. example 327 saturation-flow. Pilot 100 R R LOOKUP keyword. Cube Cluster 894 DISTRIBUTEMULTISTEP keyword. example 849 loading trip matrix. string items 68 RAAD convergence testing calculation 167 Highway variable 137 PARAMETERS keyword. Cube Cluster 891 PROCESSLIST DISTRIBUTEINTRASTEP keyword. Public Transport 616 PROCESS Generation control statement 571 Highway control statement 239 Network control statement 374 PROCESSID DISTRIBUTEINTRASTEP keyword. overview 267 RANDSEED 33 972 Cube Voyager Reference Guide . 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. Cube Cluster 891 program features 4 PROJECTLINK. overview 584 routes. finding 582 skimming 583 system data input file 679 terminology 584 PURPOSE GRAVITY keyword. Pilot 104 PROBABILITY select-link expression keyword. Distribution 553 PARAMETERS keyword. Network 362 REPLACESTR 35 REPLACESTRIC 35 REPORT Distribution control statement 555 FILEO RECO subkeyword. Pilot 104 REDIRECTOUT RUN keyword. general 71 READNTLEGI GENERATE keyword. Matrix 504 WRITE keyword. general 65 Cube Voyager Reference Guide 973 . Matrix 512 REPORT VDTSPD 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. Highway 220 REMOVEFROMGROUP SETGROUP keyword. Matrix 506 Fratar control statement 123 FREQUENCY keyword. Public Transport 696 REPORTO FILEO keyword. 522 impact on Cube Cluster 886 REPL_DUP PARAMETERS keyword. Public Transport 712 REBESTPATHCOST FACTORS keyword. 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.NUMFIELD Matrix built-in variable 394 RECI. Matrix 482 impact on Cube Cluster 886 RECI processing Matrix program 402 RECI. Network 349 REVERSESTR 35 REWAITMAX FACTORS keyword. general 63 PRINT PRINTO subkeyword. Public Transport 655 REWAITMIN FACTORS keyword. Pilot 104 RELATIVEGAP PARAMETERS keyword. Highway 242 READ control statement. example 763 REPORTJ FILEI ROUTEI subkeyword. Public Transport 696 produced report. Public Transport 677 FILEO ROUTEO subkeyword. Network 359 RECOSTMAX FACTORS keyword. Network 339 MERGE keyword. Network 348 RENUMBER Fratar control statement 522. general 53 RESUME CLEARERROR keyword 84 REV FILEI LINKI subkeyword.RECNO Matrix built-in variable 394 RECO FILEO keyword. Public Transport 654 RECI FILEI keyword. Network 342 CROSSTAB ROW subkeyword.RECERR Matrix built-in variable 394 RECI. Public Transport 694 reports enumerated routes 761 evaluated routes 762 fare matrices 766 public transport network 749 Public Transport. Network 343 FREQUENCY keyword.NUMRECORDS Matrix built-in variable 394 RECI.Index R RANGE CROSSTAB COL subkeyword. Highway 244 RENAME FILEI LINKI subkeyword. Public Transport 654 REDIRECTIN RUN keyword. Public Transport 655 REWIND PRINT FILE subkeyword. Public Transport 677 FILEO ROUTEO subkeyword. Matrix 533 RECO processing Matrix program 402 RECORD COMPARE keyword. theory 797 maximum transfers in route 648 minimum-cost routes. empirical 314 example. Public Transport 695 ROW CROSSTAB keyword.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. Matrix 466 Highway function 136 Matrix built-in function 395 matrix function. not using 648 must-use mode. numeric function 33 roundabouts empirical. theory 798 overview 582 process overview. Public Transport 591 required transit modes 654 theory 799 route file format 743 ROUTEI FILEI keyword. finding 795 route evaluation fares. Public Transport 676 ROUTEO FILEO subkeyword. Network 342 ROWADD COMP function. gap-acceptance 317 keywords. finding 794 modes. Public Transport 590 required transit modes 654 theory 793 transit connectors. keywords 305 example. Highway 181 974 Cube Voyager Reference Guide . including in cost 739 initial wait time 651 overview 582 process overview. gap-acceptance 316 overview 303 route enumeration components generated 652 determining routes. 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. Network 349 FILEI ZDATI subkeyword. Highway 182 ROWFAC COMP function. Public Transport 729 S S print format code. Public Transport 699 SEATCAP LINE keyword. Public Transport 656 RUNTIME LINE NODES subkeyword. Public Transport 756 SEGMENTS PARAMETERS keyword. overview 267 JUNCTION keyword. Public Transport 727 RUN Pilot control statement 102 RUNFACTOR FACTORS keyword. 466 Highway function 136 Matrix built-in function 395 matrix function. converting output to Cube Voyager format 869 SAVE FREQUENCY keyword. Matrix 468 ROWSUM COMP function. Highway 182 ROWMAX COMP function. Matrix 488 select link process. Matrix 466 Highway function 136 Matrix built-in function 395 matrix function. 327 Saturn. numeric items 67 SAME FARESYSTEM STRUCTURE subkeyword. Matrix 467 Highway function 136 Matrix built-in function 395 matrix function. Highway 183 RT LINE NODES subkeyword. Cube Avenue 922 SELECT FILEI LINKI subkeyword. Highway 182 ROWDIV COMP function. Matrix 512 SAVEPRN DISTRIBUTEINTRASTEP keyword. Highway 183 ROWMPY COMP function. Matrix 468 Highway function 136 Matrix built-in function 395 matrix function. Public Transport 669 SATFLOWPERLANE JUNCTION keyword. Cube Cluster 894 SCREENLINE FILEO ESTMICPO subkeyword. 466 Highway function 136 Matrix built-in function 395 matrix function. signals 283 saturation flow 291. Public Transport 729 VEHICLETYPE keyword. Matrix 467 Highway function 136 Matrix built-in function 395 matrix function. Highway 195 FILEI ZDATI subkeyword. Highway 183 ROWMIN COMP function. Public Transport 698 SCREENVAR FILEO SCREENLINEO subkeyword.Index S ROWAVE COMP function. Matrix 466 Highway function 137 Matrix built-in function 395 matrix function. Highway 182 ROWFIX COMP function. Public Transport program 607 Cube Voyager Reference Guide 975 . Matrix 466. Public Transport 678 SCREENLINEO FILEO keyword. Highway 198 screenline file creating 836 SCREENLINEI FILEI keyword. Matrix 466 Highway function 136 Matrix built-in function 395 matrix function. Highway 183 ROWREAD COMP function. Matrix 467 Highway function 136 Matrix built-in function 395 matrix function. saturation-flow prioirty junctions 327 JUNCTION keyword. Highway 182 ROWCNT COMP function. Matrix 466. 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. Highway 228 SELECTIJ Public Transport phase 628 SELECTLINK FILEO PACKETLOG subkeyword. overview 267 JUNCTION keyword. Cube Avenue 917 PATHLOAD MW subkeyword. example 291 SIN 34 SINGLELANE JUNCTION keyword. Public Transport 748 SKIPBADLINES FILEI LINEI subkeyword. 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. example 289 keywords. Public Transport 696 SELECTGROUP FILEO PACKETLOG subkeyword. Cube Avenue 917 PATHLOAD MW subkeyword. example 291 geometric. Public Transport 683 SETUP phase Cube Avenue 902 Highway program 150 SETUPPER LOOKUP keyword. priority junctions 319 JUNCTION keyword. signals 284 JUNCTION keyword. Public Transport 690 REPORT LINES 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. Public Transport 741 SLACK GENERATE keyword. Public Transport 656 SET Distribution control statement 531 FILEI JUNCTIONI subkeyword. Public Transport 678 FILEO ROUTEO subkeyword. Highway 230 SENDMAIL Pilot control statement 106 service-frequency mode example 809 SERVICEMODEL FACTORS keyword. Public Transport 673 PARAMETERS keyword.Index S SELECTBYMAT FILEI ROUTEI subkeyword. geometric 285 overview 279 saturation flow. Public Transport 712 SMTPSERVER SENDMAIL keyword. Public Transport 593 quick reference 604 theory 812 SKIP0 FILEO LINKO subkeyword. Public Transport 747 REPORT LINEVOLS subkeyword. Pilot 107 976 Cube Voyager Reference Guide . two-way stop 298 SIZE LOOKUP keyword. general 54 signals fixed-time. generic 280 keywords. overview 267 JUNCTION keyword. Public Transport 748 STORAGE script variable. example in Cube Avenue 934 variable. See two-way stops. Public Transport 736 REPORT keyword. all-way stops STOPSONLY REPORT LINEVOLS subkeyword. utility-based model 457 SPLITCOMP XCHOICE SPLIT subkeyword. cost-based model 454 SPREAD definition 657 SPREADCONST FACTORS keyword. Network 376 setting. Public Transport 747 SPDCAP Highway control statement 245 Network control statement 378 SPEED Highway variable 135 LINE NODES subkeyword. Matrix 478 FILEI RECI subkeyword. Public Transport 669 STRUPPER 35 SUBAREAMAT PATHLOAD keyword. general 72 Cube Cluster impact 886 Distribution control statement 532 FILEI DBI subkeyword. Cube Avenue 929 setting. cost-based model 455 XCHOICE keyword. cost-based model 446 CHOICE SPLIT subkeyword. Highway 245 SPDCAP keyword. Network 349 STOP2STOPO FILEO keyword. cost-based model 447 XCHOICE DESTSPLIT subkeyword. utility-based model 451 XCHOICE keyword. Public Transport 656 SPREADFUNC FACTORS keyword. example in Cube Avenue 934 SPDCAP keyword. Public Transport 656 SPREADFACT FACTORS keyword. Highway 241 REPORT keyword. cost-based model 454 SPLITINTO CHOICE DESTSPLIT subkeyword. two-way stop 299 STR 35 strings maximum length 219 print format 62 STRLEN 35 STRLOWER 35 STRPOS 35 STRPOSEX 35 STRUCTURE FARESYSTEM keyword. Pilot 102 standing 723 START FILEI LINKI subkeyword.Index S SORT control statement. Public Transport 700 STOPGROUP FILEO STOP2STOPO subkeyword. Public Transport 727 NT keyword. Highway 233 Cube Voyager Reference Guide 977 . cost-based model 453 XCHOICE SPLIT 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. cost-based model 447 CHOICE keyword. cost-based model 454 XCHOICE keyword. utility-based model 458 statement tokens 21 STOP FILEI LINKI subkeyword. Public Transport 752 stops. Public Transport 703 STOPNODES REREPORT keyword. cost-based model 447 CHOICE keyword. Network 378 value computed. utility-based model 450 XCHOICE keyword. Cube Avenue 905 STORAGESPACE JUNCTION keyword. Cube Avenue 904 SPEEDFOR COMP function. Network 349 starting Cube Voyager 9 STARTMW CHOICE keyword. Public Transport 657 SQRT 33 STACK REPORT keyword. Highway LINKREAD phase 151 variable. Network 338 Highway function 137 Network function 333 SPLIT CHOICE keyword. Matrix 488 MERGE keyword. string items 68 TURNS keyword. Highway 233 TOLLMATI 146 FILEI keyword. example in Cube Avenue 934 value computed.Index T SUBAREAMATO FILEO keyword. Cube Avenue 905 T1 Highway variable 135 value set. Highway 247 T0 Highway variable 135 setting. Highway 190 PATHLOAD keyword. Highway 234 TOLLROUND FILEI TOLLMATI subkeyword. Network 359 SUMMARY phase Network program 381 variable referencing 382 SYMBOL PLOTTER LEGEND subkeyword. Highway 222 terminology. Highway LINKREAD phase 153 TIMEA skim function. numeric items 66 print format code. summary 605 TIMEFAC LINE keyword. Public Transport 679 T T print format code. Public Transport 728 value set. Highway 195 FILEI ZDATI subkeyword. summary 605 TIMINGI FILEI keyword. Network 368 SYNCHIMP 866 SYNCHIMP utility 866 SYSTEMI FILEI keyword. Highway 201 impact on Cube Avenue 915 impact on Cube Cluster 885 SUBAREANETI FILEI keyword. Public Transport 658 FACTORS XFERFACTOR subkeyword. general 54 TOLLFACTOR FILEI TOLLMATI subkeyword. Cube Avenue 905 TAN 34 TAPER PLOTTER BANDWIDTH subkeyword 365 TCCOEFF PARAMETERS keyword. Pilot 108 subkeywords 26 SUBSTR 35 SUM FILEI ZDATI subkeyword. SYNCHIMP utility 867 TITLE COMPARE keyword. Public Transport 729 TIMEP skim function. Highway 191 TONODE GENERATE keyword. Public Transport 660 SENDMAIL keyword. Public Transport 727 theory Cube Avenue 924 Network program 379 THISPROCESS Cube Cluster impact 887 Matrix built-in variable 395 THRUNODE PATHLOAD keyword. general 70 TO FACTORS XFERCONST subkeyword. Highway 191 PATHLOAD keyword. Highway 189 SUBJECT SENDMAIL keyword. Highway LINKREAD phase 152 variable. Public Transport 599 skim function. Network 339 FREQUENCY keyword. Public Transport 659 FACTORS XFERPEN subkeyword. Matrix 512 PRINTROW keyword. Highway 191 TOLLS FILEI TOLLMATI subkeyword. Public Transport 713 TPP2UB 864 978 Cube Voyager Reference Guide . Public Transport program 584 TF LINE NODES subkeyword. TPP2UB 865 TOLERANCE LOOKUP keyword. Public Transport 598 skim function. Highway 221 TCEXP PARAMETERS keyword. Highway LINKREAD phase 152 variable. Pilot 108 TOD PARAMETERS keyword. Highway 234 TIME Highway array 136 LINE NODES subkeyword. perceived. Highway 191 FILEI keyword. link 742 transposed matrix 395 TRANTIME PARAMETERS keyword. example 764 TRACEJ FILEI ROUTEI subkeyword. ignoring 741 excessive travel time. including data in 687 loadings. TPP2UB 865 TRNLEGS1 REREPORT keyword. Generation 573 REPORT keyword. Pilot 102 TRACEI FILEI ROUTEI subkeyword. skim function 598 report by line 751 transit lines attribute report 750 demand using. Public Transport 678 FILEO ROUTEO subkeyword. number computed 743 unsuccessful proportion. Public Transport 752 TRNLEGS2 REREPORT keyword. skim function 603 TRIPSIJ PARAMETERS keyword. message 738 links file. Public Transport 678 FILEO ROUTEO subkeyword. skim function 603 unsuccessful. Highway 202 TURNS Highway control statement 246 TURNVOLO FILEO keyword. exceeding control value. Matrix 520 transfers actual penalty. report 768 passenger boardings. Highway 202 two-way stop-controlled intersections 294 Cube Voyager Reference Guide 979 . skim function 600 actual wait time. Public Transport 680 TURNPENO FILEO keyword. overview 267 JUNCTION keyword. extending control values 739 TRIM 35 trip purposes 547 trip time best. Public Transport 753 TRNLEGS4 REREPORT keyword. skim function 598 crowded link. Highway 234 REPORT keyword. Matrix 530 REPORT keyword. skim function 599 perceived. Public Transport 742 travel time actual. skim function 600 perceived wait time. Public Transport 754 turn penalty files input. report 738 transit line. generating 747 travel demand on. Highway 241 REPORT keyword. computation of 730 travel time. including in 750 summary report. name of 680 turn times converting to costs 222 TURNCHANNELIZED JUNCTION keyword. Public Transport 697 TRAM PARAMETERS keyword. report 769 between operators. identifying 607 travel time. two-way stop 300 TURNCOSTFAC PARAMETERS keyword. Public Transport 697 report produced. constant to add 658 perceived penalty. Highway 222 TURNGAPWT PARAMETERS keyword. skim function 601 trips. Highway 222 TURNPENI FILEI keyword. skim function 599 transit line 742 transit line. skim function 597 banning between modes 660 between modes. Network 349 TRNCOEF PARAMETERS keyword. generating report 748 report summarizing 767 reports. selecting 610 errors in data. extending control value 739 travel time. Public Transport 753 TRNLEGS3 REREPORT keyword. Public Transport 743 TRIPSXY FILEI LINKI subkeyword.Index T TPP2UB utility 864 TRACE PATHLOAD keyword. report 770 maximum in route 648 method 738 penalty between modes 660 penalty weighting factor 659 penalty. Public Transport 625 MATI phase. Highway 179 COMP keyword. Highway program 250 USERCLASS REREPORT keyword. summary 605 value of choice skim function 603 VALUEMW FREQUENCY keyword. Matrix 462 COMP keyword. Network 353 VARI FILEI keyword. TPP2UB 864 variables COMP exrpession. Public Transport 615 U UB2TPP utility 862 UNCONNECTED REPORT keyword. Network 336 COMP keyword. overview 267 select-link expression keyword. Public Transport 626 Highway 135 LINKREAD phase. Network 376 UNITEXTENSION JUNCTION keyword. utility-based model 458 V V. Highway variable 135 V4ROUTEFORMAT PARAMETERS keyword. Public Transport 749 USERNAME SENDMAIL keyword. geometric signals 289 UNITFARE FARESYSTEM keyword. Matrix 512 VALUEOFTIME FACTORS keyword. Public Transport 658 VAR ARRAY keyword. Pilot 90 FILEI keyword. Public Transport 629 VARO FILEO keyword. Highway 198 LOG keyword. Public Transport 638 CROSSTAB keyword. Matrix 531 ValOfChoice skim function. Cube Cluster 893 URL DOWNLOAD keyword. Network 350 FILEO ESTMICPO subkeyword. Public Transport 631 matrix 179 Matrix program. Highway 176 ARRAY keyword. Public Transport 603 skim function. Network 343 FILEI LINKI subkeyword.Index U two-way stops example 301 keywords 295 overview 294 TXT FILEO TURNVOLO file format 204 TYP FILEI LINKI VAR subkeyword. UB2TPP 863 980 Cube Voyager Reference Guide . Highway 243 SET keyword. Pilot 89 user class example 857 list of 743 overview 744 passenger loading report by 749 trips loaded 743 user stacks. built-in 394 naming convention 39 Network program. Public Transport 754 USERCLASSES PARAMETERS keyword. Public Transport 743 VAL 35 SET keyword. Pilot 108 UTILITIES CHOICE keyword. referencing in 381 NODEREAD phase. Public Transport 628 MATO phase. Matrix 438 ARRAY keyword. Public Transport 743 REPORT LINEVOLS subkeyword. Public Transport 692 JUNCTION keyword. SYNCHIMP 868 UPDATEVARS WAIT4FILES keyword. Public Transport 624 output. general 51 VARFORM FILEO LINKO subkeyword. Highway program 137 DATAPREP phase. common description 276 JUNCTION keyword. utility-based model 451 UTILITIESMW XCHOICE keyword. Public Transport 670 UNITS junction file control statement 267 PARAMETERS keyword. Matrix 463 convergence. Network 350 TYPE FILEO MATO subkeyword. Network program 383 SELECTIJ phase. Pilot 101 wait curves defining 756 description 758 wait time crowding. skim function 598 wait curve 757 WAIT4FILES Cube Cluster control statement 891 WAITCRVDEF Public Transport control statement 756 WAITFACTOR FACTORS keyword. Public Transport 729 Public Transport control statement 755 VEHPERDIST PARAMETERS keyword. summary 605 XFERPENP skim function. geometric priority junctions 323 JUNCTION keyword. skim function 597 transfer. Highway 218 WIDTH JUNCTION keyword. Public Transport 754 XFERMETHOD GENERATE keyword. Cube Avenue 922 VISIBILITY JUNCTION keyword. skim function 597 initial. skim function 598 theory 773 transfer. Public Transport 659 XFERLEGS REREPORT keyword. PARAMETERS COMBINE keyword. actual. actual. Public Transport 658 XFERFACTOR FACTORS keyword. overview 267 VOL FILEO LINEO subkeyword. Public Transport 660 XFERPENA skim function. SYNCHIMP 868 VOLUMEI FILEI keyword. Highway 204 REPORT keyword. skim function 597 crowding. Public Transport 694 Highway array 136 LINE NODES subkeyword. Highway 243 SET keyword. SYNCHIMP 868 VOLFIELDS FILEO LINKO subkeyword.Index W VARS FILEO TURNVOLO keyword. perceived. Public Transport 713 XFERPEN FACTORS keyword. skim function 597 initial. Public Transport 736 PATHLOAD keyword. overview 267 Windows starting Cube Voyager from 10 work matrices maximum index. Public Transport 600 skim function. Highway 241 VEHICLETYPE LINE keyword. Matrix 519 maximum index. SYNCHIMP utility 867 W WAIT PROMPT keyword. Higwhay 235 REPORT VDTSPD keyword. Public Transport 658 walk choice portion of trips allocated to 652 walk time. Pilot 102 SET keyword. Public Transport 736 VOLTIME PARAMETERS keyword. perceived. geometric priority junctions 324 JUNCTION keyword. differences with 458 Matrix control statement 451 XFERCONST FACTORS keyword. summary 605 Cube Voyager Reference Guide 981 . Public Transport 728 NT keyword. 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. Highway 219 maximum index. Public Transport 690 VOLT NT keyword. Public Transport 685 FILEO NTLEGO subkeyword. perceived. Highway 243 VOLDATE PARAMETERS keyword. actual. Matrix 531 VDTSPD impact on Cube Cluster 886 REPORT keyword. Public Transport 600 skim function. theory 772 WEIGHTS. Public Transport 744 ZONEO RENUMBER keyword. Matrix 488 FILEO RECO subkeyword. Highway 195 FILEI ZDATI subkeyword. Highway 223 PARAMETERS keyword. Public Transport 728 XYSPEED LINE keyword. summary 605 XYSPD LINE NODES subkeyword. Matrix 506 Matrix built-in variable 395 ZDAT Report keyword. Public Transport 736 XWAITA skim function. Network 362 RENUMBER keyword. Public Transport 597 skim function. working with 398 substituting 400 ZONEMSG PARAMETERS keyword. keywords 325 Z Z FILEI ZDATI subkeyword. Matrix 525 982 Cube Voyager Reference Guide . Highway 222 PARAMETERS keyword. summary 605 XWAITCURVE FACTORS keyword. Matrix 520 PARAMETERS keyword. Public Transport 661 XWAITP skim function. Matrix 530 ZDATI FILEI keyword. Public Transport 598 skim function. Public Transport 729 Y Y Network variable 332 yield-controlled intersections geometric. Matrix 485 zonal timing messages Highway 222 Matrix 520 Public Transport 744 zone lacking valid routes 741 lists.Index Y XN FILEO NTLEGO subkeyword. keywords 320 keywords 319 overview 318 saturation flow. Matrix 520 PARAMETERS keyword. Distribution 555 PARAMETERS keyword. example 324 geometric. Highway 243 REPORT keyword. Public Transport 694 NT keyword. Highway 193 FILEI keyword. Fratar 123 PARAMETERS keyword. Matrix 525 ZONES Highway variable 135 Matrix built-in variable 395 PARAMETERS keyword. . Citilabs. 1040 Marina Village Parkway Alameda.com . Inc.citilabs. CA 94501 USA World Wide Web www.