You are on page 1of 1000

Cube Voyager Reference Guide Cube Voyager Reference Guide

Citilabs

Cube Voyager
Reference Guide
Version 5.0

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

Document Revision 50-006-1 December 12, 2008

Cube Voyager Reference Guide

Contents

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


Design concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Program features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Minimum system requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2

Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Starting Cube Voyager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Starting Cube Voyager from Cube Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Starting Cube Voyager from Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Starting Cube Voyager from the command prompt. . . . . . . . . . . . . . . . 14

Chapter 3

General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Introduction to Cube Voyager control statements . . . . . . . . . . . . . . . . . . . . . 20 Control statement syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Statement tokens (%...%) and (@...@) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Null blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Control blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Control fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Subkeywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Keyword values and documentation descriptions . . . . . . . . . . . . . . . . . 28 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Variable naming convention (general syntax) . . . . . . . . . . . . . . . . . . . . . 39

Cube Voyager Reference Guide iii

Contents

Standard control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Control statement introduction (general syntax) . . . . . . . . . . . . . . . . . . 41 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 CONSOLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 GLOBAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 LOG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 LOOKUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Chapter 4

Pilot Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Using Pilot program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Statement tokens (%...% and @...@) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 *command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 CLEARERROR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 COPY ... ENDCOPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 DOWNLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 NEWPAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 ONRUNERRORGOTO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 PROMPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 RUN ... ENDRUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

iv Cube Voyager Reference Guide

Contents

SENDMAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Pilot example 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Pilot example 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Pilot example 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Chapter 5

Fratar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Using Fratar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Specifying target values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Controlling target totals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Convergence Iteration control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Multiple purposes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 SETPA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Chapter 6

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


Using the Highway program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Highway introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Highway program control statement overview . . . . . . . . . . . . . . . . . . . 133 Functions and built-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Getting started with assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Path-based tolls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 SETUP and LINKREAD phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 ILOOP phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 ADJUST phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 CONVERGE phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 ARRAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 FILET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 FILLMW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Cube Voyager Reference Guide v

Contents

FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 JLOOP ... ENDJLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 LINKLOOP ... ENDLINKLOOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 PATHLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 PROCESS ... ENDPROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 SETGROUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 SPDCAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 TURNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Process overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 User stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Highway example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Highway example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Highway example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Highway example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Highway example 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Highway example 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Highway example 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 Highway example 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Chapter 7

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


Introduction to intersection modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Why use intersection modeling? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 How the intersection models work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Limitations of intersection modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Cube Voyager intersection modelling and other programs. . . . . . . . 263 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 JUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 UNITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

vi Cube Voyager Reference Guide

Contents

Common keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 APPROACH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 APPROACH1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 ENABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 ESTIMATEDDELAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 EXITONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 INITIALQUEUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 MINIMUMCAPACITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 MOVEMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 NODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 RANDOMNESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Signal-controlled intersections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Overview of signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Generic keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Geometric keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Geometric signals example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 Saturation flow signals example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Two-way stop-controlled intersections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 All-way-stop-controlled intersections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Roundabouts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 Overview of roundabouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 Empirical roundabouts: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 Empirical roundabouts: Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Gap acceptance roundabouts: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . 316 Gap-acceptance roundabouts: Example. . . . . . . . . . . . . . . . . . . . . . . . . . 317 Priority junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 Overview of priority junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 Geometric priority junctions: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 320 Geometric priority junctions: Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Saturation-flow priority junctions: Keywords . . . . . . . . . . . . . . . . . . . . . 325 Saturation-flow priority junctions: Example . . . . . . . . . . . . . . . . . . . . . . 327

Chapter 8

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


Introduction to the Network program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 Built-in variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 Built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Cube Voyager Reference Guide vii

Contents

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

viii Cube Voyager Reference Guide

Contents

Chapter 9

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


Using the Matrix program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 Introduction to the Matrix program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 Control statement types in Matrix program . . . . . . . . . . . . . . . . . . . . . . 396 Working with intrazonal cells of a matrix . . . . . . . . . . . . . . . . . . . . . . . . . 397 Working with lists of zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Working with RECI/RECO processing in v4.0 and beyond. . . . . . . . . . 402 Working with logit choice models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 ARRAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 BSEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 CALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 CHOICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 XCHOICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496 FILET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 FILLMW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 FREQUENCY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 JLOOP ... ENDJLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 RENUMBER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 WRITE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532

Cube Voyager Reference Guide ix

Contents

Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Example 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Example 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Example 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 Example 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 Example 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 Example 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539

Chapter 10

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


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

Chapter 11

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


Introduction to Generation program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 BALANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 PROCESS ... ENDPROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 Generation example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 Generation example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

x Cube Voyager Reference Guide

Contents

Chapter 12

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


Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Summary of facts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Preparing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Network development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 Route enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 Route evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 Skimming (level of service) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 Loading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 Select link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 Loading analyses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 Crowd modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618 Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 NODEREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 LINKREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 DATAPREP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 MATI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626 SELECTIJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628 SKIMIJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629 MATO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 CROWDCRVDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 CROWDMODEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 FACTORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 FARESYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684 GENERATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715 IF... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 JLOOP ... ENDJLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717 LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720 LINKLOOP ... ENDLINKLOOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731

Cube Voyager Reference Guide xi

Contents

LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731 MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734 OPERATOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746 REREPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749 VEHICLETYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755 WAITCRVDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756 Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760 Enumerated routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761 Evaluated routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762 Fare matrices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766 Transit line summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767 Transit line loadings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768 Transfers between modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769 Transfers between operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771 Generalized cost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771 Modeling approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777 Network simplification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782 Route-enumeration process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793 Route-evaluation process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799 SFM and SFCM examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809 Skimming process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812 Loading process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815 Fares. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818 Crowding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830 Using the Public Transport program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836 Estimating demand matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836 Defining input and output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837 Linking Highway and Public Transport models . . . . . . . . . . . . . . . . . . . 838 Coding network times/speeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839 Generating nontransit access and egress legs . . . . . . . . . . . . . . . . . . . . 842 Considering nontransit-only routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845

xii Cube Voyager Reference Guide

Contents

Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849 Public transport network development . . . . . . . . . . . . . . . . . . . . . . . . . . 849 Public transport skimming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854 Public transport loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856 Public transport user classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857

Chapter 13

Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
UB2TPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863 TPP2UB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865 SYNCHIMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867 Saturn conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869 Running from program window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869 Running from command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870

Chapter 14

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


Using Cube Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872 Cube Cluster introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872 Cube Cluster control statement summary . . . . . . . . . . . . . . . . . . . . . . . . 877 Working with Cube Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890 DISTRIBUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890 DISTRIBUTEMULTISTEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890 ENDDISTRIBUTEMULTISTEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891 WAIT4FILES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891 DISTRIBUTEINTRASTEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893 Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895 Cluster executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897

Cube Voyager Reference Guide xiii

Contents

Chapter 15

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


Using Cube Avenue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900 Cube Avenue introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900 Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909 DYNAMIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909 DYNAMICLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920 PATHLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924 Cube Avenue algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924 Cube Avenue calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926 Functions and built-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932 Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932 Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933 LINKREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934 Simplifying LINKREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935 Centroids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935 ILOOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936 ADJUST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937 Enhancing ADJUST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938 Packet logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939 Tuning parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940 Reducing segment and volume lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945

xiv Cube Voyager Reference Guide

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

Introduction

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

Cube Voyager Reference Guide 1

Introduction Design concepts

Design concepts
Cube Voyager is designed to be an integrated modeling system for transportation planning applications. At the heart of the Cube Voyager system is a flexible control language referred to as a scripting language. This provides a flexible environment and grants control over all aspects of the modeling process. The Cube Voyager system has four main assignment programs: Network, Matrix, Highway, and Public Transport. In addition, the system offers supplementary programs for common transportation planning tasks, such as the Generate program for trip generation and the Distribution program for trip distribution. These supplementary programs provide an easy-to-use interface to the basic four programs. Users may implement any model formulation desired in the scripting language. Cube Voyager has no hard coded mechanisms; users are free to change and modify runs as they progress. Cube Voyager is an excellent choice for model applications which require congestion feedback mechanisms. Typically, transportation planning software is run as a series of independent programs, any one of which could require a relatively large amount of input control data, and consume a considerably large amount of computer resources. Some programs could execute for hours, and operate most efficiently with large amounts of RAM. A user may want to use Scenario Manager in Cube to run many scenarios which could require running a large number of programs in successive order. Cube Voyager is a library of programs that employ a language that allows the user to write the script to provide instructions for performing all types of typical planning operations. The script is stored in a file and then read when the system is executed. The individual programs are activated according to the instructions in the script. Each program is designed to perform certain operations, but only as specified by the user. A typical application could involve

2 Cube Voyager Reference Guide

Introduction Design concepts

a very complicated set of instructions, or can be as simple as computing and/or printing a number from a file. It is the users responsibility to design the process that is to be run. The binary files generated by Cube Voyager are designed to reduce disk storage requirements and reduce the amount of time spent on input/output. They have a proprietary format that can not be used by other software, but they can be translated to other formats by the user.

Cube Voyager Reference Guide 3

Introduction Program features

Program features
Advanced features of the Cube Voyager software include: Integration with ESRIs ArcEngine allows reading and writing of supported file structures directly to and from a personal geodatabase Full multirouting transit system Intersection and link constrained traffic assignments Flexible scripting language for model run specifications True 32-bit system designed for operating systems such as Windows 95/98/NT/2000/XP All calculations are performed in 64-bit floating-point arithmetic Seamless file format compatibility with existing transportation planning packages such as TRANPLAN, MINUTP, TRIPS, TP+ and others. Database connectivity allowing data to be stored and edited in standard dBASE format Network calculator which can manipulate up to 10 network files concurrently Large problem sizes process efficiently (maximum zones=32,000, maximum nodes=999,999, maximum links=999,999) Flexible matrix calculator with no practical limit on the number of matrices (999 internal working matrices and up to 255 matrices on input and output files). Advanced plotting capabilities to create high quality plots for on-line printing or as plot file images that can be plotted at a later time All data is stored as floating point values (a proprietary data compression scheme is employed to save disk space)

4 Cube Voyager Reference Guide

Introduction Program features

Capability to link with user-generated native code

Cube Voyager Reference Guide 5

Introduction Minimum system requirements

Minimum system requirements


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

6 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Getting Started

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

Cube Voyager Reference Guide 7

Getting Started Installation

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

8 Cube Voyager Reference Guide

Getting Started Starting Cube Voyager

Starting Cube Voyager


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

Starting Cube Voyager from Cube Base


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

Cube Voyager Reference Guide 9

Getting Started Starting Cube Voyager

script file of the run to the Cube Voyager program to run and monitors and display status information about the run as shown in the figure below.

Starting Cube Voyager from Windows


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

10 Cube Voyager Reference Guide

Getting Started Starting Cube Voyager

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

Users can use either the Browse or the Favorite button to locate a job script file. Both buttons invoke an Open File dialog box. The only difference is that the Browse button points to the current directory, while the Favorite button points to the Windows Favorite directory. Users can add frequently run job script files to the Favorite directory (using Windows Explorer) to quickly locate them later in a Cube Voyager window, with the Favorite button. The Edit Input File button can be used to open the current job script file in Cube for editing or running directly from Cube. See Starting a model run on page 554 of the Cube Base Reference Guide.

Cube Voyager Reference Guide

11

Getting Started Starting Cube Voyager

The Work Directory is defaulted to the directory where the job script file resides when a new job script file is selected. When this data is completed and the Start button is pressed, Cube Voyager begins execution and the Start and the Cancel buttons become the Pause and the Abort buttons, respectively. The Pause button can be used to pause the execution, while the Abort button allows for pre-mature termination of the execution. During execution, periodic messages will be written to the window. The window can be minimized or left open as Cube Voyager is executing. When the application is finished, the View Print File button can be pushed to view the resulting run print file. The Notify When Done check box can be used to bring the Cube Voyager window back on top when its done, if it has been minimized during execution. The default behavior is to have the Cube Voyager window maintain its current status, minimized or maximized, after the execution is completed.

12 Cube Voyager Reference Guide

Getting Started Starting Cube Voyager

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

The Wait Start button can be used to place this instance of Cube Voyager in wait mode for use as a processing node for Cube Cluster. See Chapter 14, Cube Cluster, for a detailed description of this process.

Cube Voyager Reference Guide

13

Getting Started Starting Cube Voyager

The About Voyager button can be used to get License and maintenance information and the version and date of all Cube Voyager programs as well as some standard machine information as shown on the About Voyager dialog below.

Starting Cube Voyager from the command prompt


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

Command line parameters:

14 Cube Voyager Reference Guide

Getting Started Starting Cube Voyager

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

script control statements. The name may have a complete path in the typical operating system format. This file may be in a different subdirectory than the -Spath argument. In some operating environments (such as Windows), it may be necessary to provide a fully qualified file name (path\filename).
pppp is a prefix (or project) that is pertinent to this application. Some files will always contain these characters (maximum 4 characters) as part of their name. Most individual programs will allow the prefix to be substituted directly for the ? character in their file names. The characters must be those that are acceptable as part of filenames to the operating system, and are not a Cube Voyager operator ('",+-*/&|). The program will generate a print file and a var file with this prefix as its first characters. If the prefix is not designated, the program will assign one based upon the following criteria:

If there is a pppp.PRJ file in the working subdirectory: the prefix will be set to the last prefix in the file. If there is no pppp.PRJ, it will generate a file by that name. Warning: Be sure that any pppp.PRJ file that Cube Voyager reads is a valid Cube Voyager PRJ file. The program automatically associates a unique sequence number with the prefix. The pageht, pagewdth, and runid parameters can be reset dynamically by Cube Voyager control statements within individual Cube Voyager programs. When set within the individual programs, their effect may be valid for only that program.
pageht is the height (number of print lines) for a printed page

of output. This will default to 58, if the program can not find a height from the Cube Voyager PRJ file. The maximum value is 32767.
pagewdth is the maximum length a printed line can have. It

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

Cube Voyager Reference Guide

15

Getting Started Starting Cube Voyager

PRJ file, it will default to 132. Note that pagewdth will not cause longer length lines to be truncated or folded; they will be written with the appropriate length. The primary use of pagewdth is to assist in formatting messages and reports.
workdir is the subdirectory that the application is to be run

from. Normally, the user will log onto the desired subdirectory, and workdir will not need to be specified. But, in some operating environments, it may not be possible to log on to a subdirectory before starting the program. (Windows may cause some problems in this area.) When the program starts, it checks if workdir is specified, and if so, changes to that subdirectory before it processes the other arguments (excluding filename).
runid can be used to specify a starting ID for the application. If

ID is not specified, it will try to obtain a starting ID from the Cube Voyager PRJ file with matching prefix. Command line options: /Startfor example to auto start the run, also auto terminate when done unless /ViewPrint is on /StartTime:hhmm to auto start the run at certain time /EmailOn to set Email check box on /NotifyOn to set notify on check box /ViewPrint to automatically bring up print file /Hide to hide the run dialog box completely when starting if auto start on /High to set the high priority check box /Wait to auto start in Wait Start mode as a cluster node /WinLeft:xx to set the window location and width/height or to restore screen size and position when restart from Wait Start mode /WinTop:xx /WinWidth:xx

16 Cube Voyager Reference Guide

Getting Started Starting Cube Voyager

/WinHeight:xx

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

Cube Voyager Reference Guide

17

Getting Started Starting Cube Voyager

18 Cube Voyager Reference Guide

Cube Voyager Reference Guide

General Syntax

This chapter describes the general syntax found in Cube Voyager. Topics include: Introduction to Cube Voyager control statements Control statement syntax Standard control statements

Cube Voyager Reference Guide

19

General Syntax Introduction to Cube Voyager control statements

Introduction to Cube Voyager control statements


Cube Voyager operates by reading control statements from a script (job) file. All control statements have the same general format. Each statement begins with a control word to tell the program what type of statement it is. Following the control word and one, or more, spaces, are keywords and their values. A keyword is always followed by an equals (=) sign, and then the value(s) to be associated with the keyword. There may be as many keywords as are applicable to the control type. A statement can be continued onto the next line by breaking it after a valid operator for the statement. If the last character on the statement (prior to any comments) is a valid operator for the statement, the statement MUST continue onto the next line. Valid continuation characters are: comma and mathematical and logical operators: ( , + - / * ^ & | = ); the character must be one that is in proper context for the statement.
Example
COMP a = b + c = ; invalid: = is not in proper context COMP a = b + c + ; valid: + is logical at this point d + e / f ; continuation of previous line ZDATI=myfile, z=2-4, emp=21-30 pop=40- ; valid: - is logical here 48, ; valid: , is logical here sfdus = 51-55 & ; invalid: & doesnt fit here mfdus= 61-65

20 Cube Voyager Reference Guide

General Syntax Control statement syntax

Control statement syntax


This section describes the syntax, or components, of control statements. Topics include: Statement tokens (%...%) and (@...@) Comments Null blocks Control blocks Control fields Keywords Subkeywords Keyword values and documentation descriptions Expressions Variable naming convention (general syntax)

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


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

Cube Voyager Reference Guide

21

General Syntax Control statement syntax

Example
ijk = @ijk@ ; retrieve value from Cube Voyager xxx = @matrix.xxx@ ; retrieve value of xxx as set by prior matrix PRINT LIST=ijk from Cube Voyager PILOT=, ijk ; will be OK

Comments
There may be comments appended to any control statement/line. Comments must be preceded by a semi-colon (;). There may be any number of spaces before and/or after the semi-colon; they are ignored. If a statement is continued onto subsequent lines, each line may have comments. A semicolon (;) as the first character of a statement sets the entire statement as a comment.
Example
FILEI NETI=myfile.nam, ; I/P network ZDATI=zonal.dat ; Zonal data ; this entire line is a comment

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

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

Null blocks
The null block is a section of the input stream that is not processed by the program; it is skipped over when the program reads the control statement. The block begins with /* and ends with */, and

22 Cube Voyager Reference Guide

General Syntax Control statement syntax

blocks may be nested. Therefore, care must be exercised when null blocks are used; if another /* appears before the terminating */ is read, the program assumes that there is another null block within the current one. This nesting allows the user to block out a section of the control stream even if a section of the stream already contains a null block. The rule is that each /* must have a matching */. A null block can be used to block out stream terminators and even portions of a control stream specifying other programs to be run. If a matching */ is not found, the end of the block is set to the end of file on the control stream. Hint: to run only the first portion of an input stream, place an unmatched /* record after the last desired statement.
Examples
FILEI NETI=myfile.nam, /* I/P network */ ZDATI=zonal.dat ; Zonal data ; ** valid, but not recommend ** FILEI NETI=ipfile.net /* FILEO NETO=opfile.net */ FILEI NETI=myfile.nam, ; I/P network /* ZDATI=zonal.dat ; Zonal data */ FILEO ... ; will be an error, because FILEI is to be continued.

Control blocks
A control block can be used to block a control statement. The standard format for a control statement requires that the first word of the statement must be a valid control word, and must be followed by at least one key word. The statement can optionally be continued onto subsequent lines by use of a continuation character. Alternatively, a control block can be used. A control block begins with the control word, white space, and the {} character. All data up to the next {} character are considered as part of the statement. If multiple lines are used, they need not contain continuation characters. The statement will terminate with the {} character. Care must be taken: if there is no {}, the remainder of the input stream will be appended to the current statement. If the terminating {} is embedded within a literal string ('.. {} ..' or ".. {} .."), or it follows a semicolon (;) on a line, it will not be recognized. Currently a control block may be on one line, but planned revisions

Cube Voyager Reference Guide

23

General Syntax Control statement syntax

will probably preclude this capability. There is no reason to have a control block on a single line, so it is advisable to not code them that way.
FILEI { NETI = ... ; continuation character not required. ZDATI = ... } FILEI {NETI = ... MATI = ... } ; not recommended possible future change FILEI {NETI = ... ; input network } ; invalid: comment precedes the {}. FILEI {NETI = ... ; input network } ; valid: the {} is on a separate line.

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

24 Cube Voyager Reference Guide

General Syntax Control statement syntax

If the dash touches the second field, and there is another dash between the first field and the dash, it is a range with the second field being negative.
Examples of numbers specified as single or range values
Expression 1-5, 1- 5, 1 5 1 5 1 5, 1,5, 1 , 5 1,-5 1 , -5 135 -1-5 -1--5 -8--5 -8 - -5 Meaning three ways of specifying range: 1 through 5. value 1, and value -5. three ways of specifying: value 1 and value 5. error! value 1 and value -5 value 1 and range: 3 through 5. range: 1 through +5 range: -1 through -5; descending, and could be an error. range: -8 through -5, but doesnt look nice. range: -8 through -5, but less confusing.

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

Keywords
All control information is entered by coding a keyword followed by an equals sign (=) and then the value(s) to be entered for the keyword. Keywords may sometimes specify vector data (multiple values for successive entries in a curve or array). When a vector keyword is specified, the data is entered beginning at the first location in the array. Optionally, the vector keyword may be subscripted, so that the values are loaded into the array beginning at a specified location. A subscript is specified by inclosing it within

Cube Voyager Reference Guide

25

General Syntax Control statement syntax

square brackets []. When a keyword is subscripted, there may be no special characters prior to the right bracket (]); the subscript must fill the space between the []. Most keywords that are subscripted are specific to the program, and the subscript must be an integer constant. Some programs allow certain vectored keywords to have a variable as the subscript; this is usually only when the keyword is on a COMP (or similar type of statement). Some keywords allow double subscripts to indicate a matrix of rows and columns. In such cases, there are two sets of brackets [row][column]. For example: capacity stratified by lanes (row) and spdclass (column). The row index sets the row where the data is to load and the column index sets where in the row the data loading is to begin. If there is no column designation, it is assumed to be one. One is the minimum value for rows and columns. If there is more input data than is allowed in a row, the data spills into the next row (beginning at that rows column 1), but it will not fill beyond the end of the array. In certain cases, three-dimensional arrays are allowed, but they are rare, and will be more fully defined in the specific program documentation.
Examples
LINKI= LIINKI[3]= NOX[2][7]= NOX[3]= ; single value format VAL=10,20,30,35,40,50 ; VAL[1]=10, VAL[2]=20, , VAL[6]=50 VAL[55]=770, VAL[83]=1200,1250 ; VAL[83]=1200, VAL[84]=1250 VAL(2) ; invalid, the subscript must be [2]

Subkeywords
Some keywords (internal level 2) may have further descriptive keywords (level 3) associated with them, and each of those sub keywords may possibly have another sub keyword (level 4) associated with them. Level 4 is the maximum. A level 2 keyword may be used at any time, but a level 3 keyword may be used only following a level 2, 3, or 4, keyword. A level 4 keyword may be used

26 Cube Voyager Reference Guide

General Syntax Control statement syntax

only following a level 3 or 4 keyword. A sub level keyword applies only to the prior higher ranking keyword. An example is the Network program FILEI statement. The layering is as follows:
Example
(1) FILEI (2) LINKI= (3) EXCLUDE= ; These are same level (3), and can be (3) VAR= ; used only if LINKI has proceeded them. (4) TYP= ; These subkeywords (4) BEG= ; are all at (4) LEN= ; the same level, and (4) MIN= ; can not be specified (4) MAX= ; unless VAR= is LINKI=myfile, var=a, beg=1,len=5, var=dist, beg=14, len=3, var=street, beg=6,len=5,typ=c, LINKI[2]=myfile2.dbf, var=a,b,dist,name; DBF file

In this example, the comma following typ=c on the third line is not necessary, since LINKI is a valid FILEI invoking keyword. The typ=c applies only to street. With the comma, the four lines form a single FILEI statement. Without the comma, they form two FILEI statements.

Cube Voyager Reference Guide

27

General Syntax Control statement syntax

Keyword values and documentation descriptions


What may follow the = for a keyword depends upon the criteria for the keyword. In the documentation, each keyword description begins with a criteria list enclosed within |...|. Any of the following letters (case sensitive) within the criteria list indicate what type of data must be entered for the keyword.
Letter C D F Description Character -- any valid text string, but only the first character is used. Double Double-precision real numbers. Filename -- filenames in a format acceptable to the operating system. If the name is to contain any special characters that may be in conflict with the system delimiters, the name must be enclosed within double quotes. (Single quotes may be used, but if the operating system allows single quotes in the filename, double quotes are required). If a filename contains a question mark (?), the ? is immediately revised to PPPP, where PPPP is the Cube Voyager prefix that has been set by the user. In some cases, if the filename does not contain an extension (.ext), the program may want to append an appropriate extension (.NET, .MAT, .DBF, etc.). To preclude the program from appending an extension, the file name should end with a dot (.) (For example, MYFILE.) Integer -- numbers that are entered without decimal points. If a decimal point is entered, the value will be processed as the nearest integer. Real -- numbers that may contain decimal points. If the number is to be entered with a negative exponent (for example, 1.23E-2), the system reader doesnt know if the dash is an exponent sign or a field separator. With such values, the entire field must be enclosed within '...' (for example, '1.23E-2'). This same restriction does not apply to constants within an expression because ranges are not allowed. Real numbers are entered as single precision values: precision is restricted to the 6-7 most significant digits (system dependant). Boolean Response -- true/false character. Programs may accept various responses depending upon the native language of the user. In English, for example, a true response could possibly be any of (Yes ,1, True), and the negative response could be (No, 0, False); only the first character will be processed.

28 Cube Voyager Reference Guide

General Syntax Control statement syntax

Letter N s

Description Numeric expression -- expressions that will result in a number. See Numeric expressions on page 30 for details of expressions. selection expression -- a special form for establishing complex selection criteria; usually IF statements. The expression must be enclosed within (...). See Selection expressions on page 36 for details of expressions. String -- text string, usually used for naming or identifying something. If the string is to contain any of the delimiter characters (including space), it must be enclosed within '...'. If it is to contain a ', it must be within "...".

Other characters in the criteria list provide more information about the keyword. Possible characters and their meanings are:
Character a K Description Ascending order Values must be listed in ascending order. Trigger keyword -- The program recognizes the keyword directly without specification of the control statement. Therefore, you may specify trigger keywords as the first word on a statement; the program treats the entire statement as if the first word was the appropriate control statement. Pairs -- The values may be entered as single values or as pairs of numbers (two numbers separated by a dash.) Vector -- The keyword is vectored; multiple values may be entered. An index may be appended to the keyword to indicate the loading point in the keyword array. An index should not be appended if a number does not follow V, and any index may not exceed the value of the number. If a number follows V, it is the maximum index allowed for the keyword array. For example, V100 means the highest index may be 100. The repetition operator * may be used to enter the same value multiple times for a V keyword. The data are loaded into successive locations in the vector. If [n] follows n, the keyword is doubly dimensioned, and the [n] is the size of the second dimension. For example, V10[20] means the array referenced as the keyword has 10 rows with 20 columns each.

P V

[n]

Cube Voyager Reference Guide

29

General Syntax Control statement syntax

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

Numeric expressions
Numeric expressions are written as traditional formulas, and contain operands separated by operators. Standard hierarchy rules are followed; computation is performed from left to right, and expressions within () are evaluated to a single value. The hierarchy table for operators is as follows (with importance increasing in level):
Operator Addition Subtraction Multiplication Division Modular Exponentiation Symbol + * / % ^ Level 1 (in strings, "+" is a concatenator) 1 2 2 2 3

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

30 Cube Voyager Reference Guide

General Syntax Control statement syntax

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

Character constants are entered as strings enclosed in '...'. A program that deals with a variable number of matrices may have the work matrices referenced by using MW[] or MW[][]. Usually, matrices are referenced within a J loop (J refers to the destination, or column, cell in the matrix), but that is not always the case. At times, it may be beneficial to use a computed variable to indicate which work matrix to reference, and/or which cell in the matrix to reference. When that format is used, it is the users responsibility to ensure that the computed subscripts are within the correct ranges. Unpredictable results could be obtained, or the program could fatally terminate, if the subscripts are incorrect. A general rule is that when a MW is on the left side of an expression (the result) the subscripts must be constants or variables, and when MW is within an expression, the subscripts may be expressions, constants, and/or variables.
Function MW[#] MW[#][n] MW[#][X] MW[W] MW[W][X] Description The Jth cell in work matrix #. The nth cell in work matrix #. The Xth cell in work matrix #. The Jth cell in work matrix W. The Xth cell in work matrix W.

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

Cube Voyager Reference Guide

31

General Syntax Control statement syntax

Built-in functions are predefined processes that return a value to the expression; they must be followed by one, or more, expression arguments enclosed within parenthesis (). The number of arguments must match the requirements of the function. The standard functions include (this list may be expanded over time): Numeric functions Trig functions Character functions Lookup functions

Numeric functions
Function ABS(x) CmpNumRetNum(V1,OP,V2,R1,R2) Description Absolute value Compare number V1 to number V2 based on OP and return R1 if result is true and R2 if result is false. Valid operators OP are string and can have any of the following values: Equal to: '=' or '==' Not Equal to: '!=' or '<>' Less than or equal to: '<=' Greater than or equal to: '>=' Less than: '<' Greater than: '>' V1, V2, R1 and R2 can be numeric expressions or numeric values. This expression can be nested. NOTE: If the arguments are expressions, the expressions must be resolved before the function is called to determine which value is returned. EXP(x) Exponential e to the x (-103 < x < 88)

32 Cube Voyager Reference Guide

General Syntax Control statement syntax

Function INLIST(n,str)

Description Returns 1/0 to indicate if the value of n is found/not found in any normal paired list represented in str. If str contains illegal syntax, or non-numeric values, the function will try to ignore such errors, and perform the search on only valid values. Please note that the size of str may depend upon the specific program in which INLIST is used; the PARAMETERS MAXSTRING= might be required if str is long. Str can be dynamically modified in the program. Truncated integer value Natural logarithm (x > 0) Common logarithm (x > 0) Maximum value from the list Minimum value from the list Power (x=base, y=exponent) Return a random floating point number between 0 and < 1 Return a random integer between 0 and n-1, n is an integer between 1 and 2147483647 Initialize the random number generator with n, where n is an integer between 1 and 2147483647, so a repeatable series of random numbers can be generated from the rand() and random() functions Rounded integer value Square root (x > 0)

INT(x) LN(x) LOG(x) MAX(x,y,...) MIN(x,y,...) POW(x,y) RAND() RANDOM(n)

RANDSEED(n)

ROUND(x) SQRT(x)

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

convert radians to degrees:

Cube Voyager Reference Guide

33

General Syntax Control statement syntax

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

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

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

34 Cube Voyager Reference Guide

General Syntax Control statement syntax

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

Description Returns n characters from the left side of s1; if the length of s1 is less than n, or n is < 0, returns s1. Deletes leading spaces from str. Replaces n occurrences of s2 with s3 in s1, where n is the number of replacements, 0 means all; if n < 0, then no replacements, returns s1. Same as REPLACESTR but ignores case when searching for s2 within s1. Reverses s1. Returns n characters from the right side of s1; if the length of s1 is less than n, or n is < 0, return s1. Converts the variable v to a string that is w characters wide, with d decimal places. w must be less than 30, and d less than w - 2. Returns the length of str. Sets str to lowercase for immediate use; str is not permanently changed. Returns the position in str2 where str begins. If str does not exist in str2, returns 0. Both strings are case sensitive. Returns the position of s1 in s2, but starts the search from position n1 in s2 instead of from the beginning of s2. Returns 0 if not found; if n1 < 1 or n1 > length of s2, returns 0. Sets str to uppercase for immediate use; str is not permanently changed. Extracts a substring from str, beginning at position b, and continuing for n characters. b must be greater than 0. Deletes trailing spaces from str. Returns the numeric value contained in str.

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

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

STRPOSEX(s1,s2,n1)

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

TRIM(str) VAL(str)

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

Cube Voyager Reference Guide

35

General Syntax Control statement syntax

Lookup functions

Lookup functions are defined by a LOOKUP control statement. The statement must contain the source of the lookup data, the name to give the function, and optional parameters to control the actual lookup of data. See LOOKUP on page 51 for a details about the control statement. Each program may have a list of functions that are unique to the specific program. Those functions will be described with the specific program documentation. In some cases, the user will be allowed to define specific functions for use by the program. Functions that look up a value in an array or in a set of curves are examples of user functions.
Examples of valid expressions
x + 1 (1.5/distance) + (sqrt(AreaType)*abs(FacilityType]) ) Street + ',' + City + DUPSTR(' ',3) SUBSTR(street,4,6) FORMAT(volume,8,2,',') STRPOS('cd','abcde') INLIST(32, '10-15,25,31-35') CmpNumRetNum(V1,'>=',V2,V1-V2,V2-V1)

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

36 Cube Voyager Reference Guide

General Syntax Control statement syntax

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

Description A is greater than, or equal to, B. A is less than, or equal to, B. A is greater than B. A is less than B. A is not equal to B.

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

String comparison is based on the ASCII code value of each character and is done from the left to right until the right-hand side string is exhausted. In other words, the number of characters compared is the string length on the right-hand side. For example, ('abcde' = 'ab') is equivalent to ('ab' = 'ab'), which is true. On the other hand, ('ab' = 'abcde') is false. One should never use an empty or null string on the right-hand side of a comparison expression. It will always be true for equality comparison and false for other types of comparisons. Since a blank, ' ', is less than any printable character in ASCII code value, we can check if a text field is not empty using the following expression: (LTrim(TextFld) > ' ') Comparisons can be logically combined with other comparisons by using the AND operator (&&) or the OR operator (||). When logical combinations are made, it is wise to enclose them within (...); it is not always necessary, but it helps to eliminate ambiguity. A

Cube Voyager Reference Guide

37

General Syntax Control statement syntax

comparison enclosed within (...) can be preceded with the NOT operator (!) to cause the comparison result to be inverted. For example: !(i=5-10,12) means if I is not within the 5-10 range, nor is it equal to 12. AND and OR can currently be specified as single & and |, but this could change in the future.
Example of complex selection
( (i=1-10,37 && j=150,201-299) || (j=1-10,37 && i=150-201-299) || ( (I=j & !(i=87-100,203) ) || ((a+sqrt(5*j)) >= (j + sqrt(6/a)) ) ))

Examples of keyword variables


int = 1 float = 1.35, 1.23E2 name=abcde, 'this is a name' NETI=?2005.net, ; expands to PPPP2005.net (prefix = PPPP) "d:\test\alta\myfile.ext", ..\subd?\ALTA?.net ; expands to ..\SUBDPPPP\ALTAPPPP.NET

Examples of expressions
n + 1 (1.5/i) + (sqrt(MW[3])*abs(MW[m][j-1]) ) Street + ',' + City + DUPSTR(".-",3) SUBSTR(street,4,6) Inlist(I,1-5,99,888-993,5002,6,13) Inlist((k*2+j), CBD) ; CBD must be a string variable Randseed(12345) Rand() Random(I) ; if (I<2) will return 0.

38 Cube Voyager Reference Guide

General Syntax Control statement syntax

Variable naming convention (general syntax)


Variables used in expressions must have a valid name. There are some basic rules that must be followed in assigning a name to a variable. Some programs might relax the rules a bit, but to prevent any problems, the following rules should be adhered to.
Rule Length: Description Any reasonable length; network variables may not exceed 15 characters. If a database file (.dbf ) is to be written, the program will truncate the name to 10 characters (the maximum for the dbf ). A-Z, a-z, 0-9, _$#@ Insensitive. Any of the valid characters, except 0-9. Convention is to use underscore _ as the first character.

Valid Characters: Case: First Character: Temporary variables:

Variables are also used to reference items specific to a program. In a network-processing program, they could reference the variables associated with a network. In a matrix program, they could reference certain matrices. They also may reference variables defined specifically for the program (that is, I, J, M, etc.), or variables defined by the user in a prior assignment control statement. Usually, variable names can be most any length, but if the variable is to be associated with an input or output file, its length must be restricted to no more than 15 characters. If a file variable is to be referenced directly, it must be preceded with a prefix to indicate which file to use. Input file variable prefixes are always in the format 'TI.#.', where:
Prefix T I # Description File type (L=Link, N=Node, M=Matrix, Z=ZonalData). Indicates Input Index (explicit or implied) number of the file type named on a FILEI control statement.

Cube Voyager Reference Guide

39

General Syntax Control statement syntax

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


Filename format MI.3.varname Description refers to the matrix named varname found on the file designated by MATI[3]= on the FILEI control statement. If varname is a number, it refers to a relative matrix on the file refers to the variable named varname found in the node portion of the network file designated by NETI[3]= on the FILEI control statement. refers to the variable named varname found in the link portion of the network file designated by NETI[2]= on the FILEI control statement. refers to the array named varname generated by the file designated by ZDATI[5]= on the FILEI control statement. Zonal data are read into zonal arrays; each variable is an array with zones cells. Usually, the reference to a zonal value would also include a subscript; for example, ZI.5.POP[I].

NI.3.varname

LI.2.varname

ZI.5.varname

NOTE: LI.name and NI.name are used when there is only one NETI

allowed in the program (currently applies to only the Highway program).

40 Cube Voyager Reference Guide

General Syntax Standard control statements

Standard control statements


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

Control statement introduction (general syntax)


Many programs will share the same type of control statements; however, the data entered on them may vary between programs. This section briefly describes the common format of statements that are used in many of the Cube Voyager programs. All statements follow the format that the statement type is identified by the first word that appears on it. Usually, the first word is the ControlWord. However, in some cases it is more expedient (and/or convenient) for the user to start the statement with one of the special keywords that is acceptable for that type of statement.

Cube Voyager Reference Guide

41

General Syntax Standard control statements

Those keywords (termed trigger keywords) are identified in their respective program detailed descriptions. The general format for describing Control Statements in this document is:
ControlWord

Key1 Key1 Key1 (Key2 Key2 (Key3 Key3) ) Key1 (Key2) ... ControlWord is the statement type and must be the first keyword on each statement, unless the statement contains trigger keys, and the first keyword is a trigger keyword followed by an equals sign. See the keyword description below for details about trigger keys, denoted by K within the |...|.
Key Key1 Key2 Key3 Description A keyword that must be followed by an equals sign and appropriate value(s). A keyword that is valid only if it follows the values for its Key1, an equal level Key2, or any key3 or key4 (for the same Key1). A keyword that is valid only if it follows the values for its Key2, an equal level Key3, or a key4 (for the same Key2).

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

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

42 Cube Voyager Reference Guide

General Syntax Standard control statements

keywords, and may appear only following the values for GGG, HHH, or III. KKK is also a level 3 keyword and may appear only after the values for JJJ or KKK.
Keyword values AAA=3 BBB=5 DDD=2 EEE=25,FFF=Y AAA=3 DDD=2 BBB=5 KKK=27 FFF=Y HHH=5 BBB=5 CCC=6 DDD=7 CCC=8 BBB=9 Description Valid. Invalid: DDD must follow BBB or CCC Invalid: KKK must follow JJJ. Invalid: HHH must follow GGG Valid.

COMP
COMP statements are used to dynamically assign values to variables and/or matrices. COMP statements contains one, or more,

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

All numeric variables that are declared by the user in this manner are internally treated as double precision floating point variables. Some programs (mostly those involving zonal matrices) may allow the use of INCLUDE and EXCLUDE keywords on the COMP statement. When the statement contains either, or both, of these keywords, it means that the statement will be subjected to a zonal

Cube Voyager Reference Guide

43

General Syntax Standard control statements

filter before being processed. The zonal filter will refer to either I (origin zone) or J (destination zone); the program definition will clarify which. If an INCLUDE is present, the zone number will be checked against the zones in the INCLUDE list. If it fails the INCLUDE list specifications, the statement is bypassed. Then, if there is an EXCLUDE, the zone is checked with the EXCLUDE list. If it meets the EXCLUDE list specifications, the statement is bypassed.

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

FILEI
FILEI tells the program which input files to process. In most cases, if there is no FILEI statement, the program will assume a default

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

Some FILEI keywords may allow sublevel keywords that are associated with the file keyword. In some programs, all FILEI statements must be in the beginning of the control stream,

44 Cube Voyager Reference Guide

General Syntax Standard control statements

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

NOTE: Application Manager automatically writes all FILEI

statements to the script file when you define input file boxes. If you use Application Manager, do not manually edit the file path or file name elements of the FILEI statements, as both the script file and the applications .app file stores this information. Editing the file path or file name will result in a mismatch between the file that the script uses when it runs and the file Application Manager opens when you double-click an input file box. (See Chapter 14, Application Manager, in the Cube Base Reference Guide.)

FILEO
FILEO is the counterpart to FILEI; it names the output files to be written by the program. If there is no FILEO statement, some

program will simulate an appropriate statement. The exact format of the FILEO statement will vary between programs.
NOTE: Application Manager automatically writes all FILEO statements to the script file when you define content for output file boxes. If you use Application Manager, do not manually edit the file path or file name elements of the FILEO statements, as both the script file and the applications .app file stores this information. Editing the file path or file name will result in a mismatch between the file the script writes during runs and the file Application

Cube Voyager Reference Guide

45

General Syntax Standard control statements

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

GLOBAL
Alters the size of a page on the standard print media. The keywords are trigger keywords; you need not specify GLOBAL.
GLOBAL keywords
Keyword PAGEHEIGHT |KI| Description Resets the maximum number of lines on a page, so that the system knows when to start a new page with appropriate headers. The value must be in the range 1032767. Hint: If the print file is going to be viewed primarily on-line (instead of actually being printed), it is suggested that PAGEHEIGHT be set to a large number to reduce the number of interspersed page headers. The PAGExxxx values can also be set when Cube Voyager is initially launched from its menu. Resets the maximum number of characters to be printed on a single line. Usually this value is either 80 or 132 to accommodate most character printers. It only comes into play when certain reporting processes need to know the width of a print line, so it can form the report properly. The value must be in the range 50-250.

PAGEWIDTH

|KI|

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

ID
An ID statement is used to revise the page headings for each printed page. The length of the ID text will be truncated to 60 characters. The ID is specified as: ID=newid string. The ID is revised in one of two ways: with the ID statement, and (in some programs)

46 Cube Voyager Reference Guide

General Syntax Standard control statements

by a COMP ID=text expression. ID statements in Cube Voyager Pilot program are dynamic; they cause the ID to be revised when the statement is processed in the Cube Voyager operations stack. ID statements in the application programs cause the ID to be revised only when the statement is encountered in the statement reading and editing phase prior to actual program execution. This can cause the sign-on ID to be revised at a time different than what might be expected. Because of this situation, it is suggested that ID statements be used before a RUN statement. That way, the sign-on page for the application program will contain the desired ID.
Example of improper ID location
RUN PGM=MATRIX ID=this is the MATRIX ID ENDRUN RUN PGM=HIGHWAY ID=this is the HIGHWAY ID ENDRUN

In this situation, the first page (sign-on) for the Matrix application will not contain the this is the MATRIX ID as its header, but the first page of the Highway section would contain it. If the RUN and ID statements were reversed, the sign-on IDs would be correct. When ID is specified as the destination in a COMP statement, the ID can be computed, and it is revised at that time (but will not be reflected in the headers until a new page is required). In the COMP statement, parts of the ID can be computed. This would most likely be used in a Cube Voyager loop situation:
Example of Computing the ID
LOOP PASS=1,5 COMP ID=This is Pass+str(PASS,2,0) RUN PGM= ENDRUN ENDLOOP

Example
ID=This is the new Page Header

Cube Voyager Reference Guide

47

General Syntax Standard control statements

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


IF statements control the flow of user defined operations for those programs that provide for them. IF is followed by a selection

expression enclosed within (...). The expression is evaluated and will result in a true or false condition. For each IF statement, there must be a matching ENDIF later in the input stream. Between the IF and its matching ENDIF, optionally, there may be any number of ELSEIF statements, and one ELSE statement. The ELSEIF statement has the same format as the IF statement. Program flow is determined by the results of the condition evaluations of the IF and ELSEIF statements, and the ELSE statement. Flow is outlined as:
IF/ELSEIF expression is true The statements following the statement are executed until an ELSEIF, ELSE, or ENDIF is

encountered. The next statement executed is the one following the associated ENDIF statement.
IF/ELSEIF expression is false The next statement to be executed is the next associated ELSEIF, ELSE, or ENDIF

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

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


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

48 Cube Voyager Reference Guide

General Syntax Standard control statements

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

LOG
Writes values to the log file PREFIX VAR Cube Voyager maintains a file called the log file; it has a filename with an extension of .VAR. Whenever a RUN statement is encountered, Cube Voyager updates the values in the .VAR file with

Cube Voyager Reference Guide

49

General Syntax Standard control statements

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

50 Cube Voyager Reference Guide

General Syntax Standard control statements

The records that are written to the file are written as PREFIX.VAR=value. The current version of Cube Voyager truncates .VAR string values with embedded or trailing spaces at the first space when it reads the values. This is scheduled for revision in a subsequent release of the system.
LOG keywords
Keyword PREFIX |S| Description Sets the prefix of the logged variable(s). This string is added to the start of the names of all variables that follow PREFIX. If PREFIX is not specified, the program name will be used. This could be confusing if different applications of the same program log the same values. Indicates which variables will have their values written to the .VAR file.

VAR

|S|

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

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

A LOOKUP statement is used to define a lookup function and to enter data for the function. The statements are not dynamic, they are processed at the appropriate time by the program, prior to their actual use. Lookup functions are referenced from within numerical expressions. When the function is referenced in an expression, the correct number of arguments enclosed within parenthesis must follow it. The function returns a single value to the expression solver. A lookup array is allocated and initialized with the data referenced by the LOOKUPI, FILE or R keywords. In most cases, a lookup statement will define a single set of lookup data, but if a LOOKUP subkeyword follows the NAME, the function will be

Cube Voyager Reference Guide

51

General Syntax Standard control statements

defined as one that requires at least two arguments (curve number and the value to be searched for). This latter format is useful for entering friction factors for use in the Distribution program. Data referenced by LOOKUPI or FILE keywords can be either in DBF, MDB, or delimited ASCII format. A new wizard feature has been added to Cube to automate the coding of a LOOKUP function when linking a DBF file to a LOOKUPI file box in Application Manager. See Chapter 12, Job Script Editor Window, in the Cube Base Reference Guide for information about this wizard.
LOOKUP keywords
Keyword FAIL Subkeyword Type |RV3| Description Defines the results to be returned by the function if the lookup value is not contained within the data. By default, if the value is less than the lowest value in the table, the result for the lowest value in the table is returned, unless FAIL[1] is explicitly specified. If the value is greater than the highest value in the table, the result for the highest value in the table is returned, unless FAIL[2] is specified. If the value is not found within the data, FAIL[3] (default value is 0) is returned. If a call to the function has more arguments than is required, the argument following the required arguments is the value that will be returned if the lookup fails for any reason. Note that versions prior to 1.5.5 did not return the extreme results of the data for low and high failure; they returned FAIL[1] and FAIL[2], respectively. If FAIL[1-2] were not specified, they were set to 0. FILE |F| Name of the file that contains the data to be associated with the function. This keyword must be specified, unless R or LOOKUPI is specified. FILE, R, and LOOKUPI are mutually exclusive. Indicates if the returned function value is to be the result of interpolating between rows in the lookup table. The default value is false, meaning that there must be a direct match in the table. Indicates if the program is to format and list the lookup table.

INTERPOLATE

|?|

LIST

|?|

52 Cube Voyager Reference Guide

General Syntax Standard control statements

LOOKUP keywords (continued)


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

NAME NAME LOOKUP

|S| |S|

NAME

RESULT

|S|

NEAREST

|?|

Cube Voyager Reference Guide

53

General Syntax Standard control statements

LOOKUP keywords (continued)


Keyword R Subkeyword Type |SV| Description Used in place of the FILE or LOOKUPI keywords to enter data records for the function. If R is specified, FILE or LOOKUPI may not be specified. FILE, LOOKUPI and R are mutually exclusive. Any number of R records can be entered. The string values following R represent data records that are in the same format as the FILE records would be. Each R value must be enclosed within single quote marks '...'. A single R= may specify the entire file, or multiple R= records may be entered. See Example: Double value function Typical friction factor curves on page 58 for an example showing the use of LOOKUP to define friction factor curves for the usage of R= to read data directly from the body of the script file. Specifies that the function is to simulate an upper limit for a lookup row when only a single value is entered for the row. This option is useful when the data is input with single values, and the function can not find an exact match, and it is to return a value based upon the lower of two ranges. For example, a curve is entered with single values that begin at 1 and increment through 10 by 1. A lookup for 1.5 would fail. If INTERPOLATE were true, the return value would be computed, otherwise the return would be error. In such cases, if SETUPPER were true, the result for 1 would be returned. SETUPPER takes precedence over INTERPOLATE, and only comes into play for rows without both limits explicitly provided. Optional variable that specifies the total number of entries in a LOOKUP array. The value should be the number of resulting values to be searched for multiplied by the number of records. As of v4.1 of Cube Voyager and TP+ systems, this keyword is no longer required as the memory allocation process is now automated to optimize within the resources of the computer it is using. However, it is maintained to insure backward compatibility with previous versions of the software. Specifies a tolerance to be applied to the lookup value. This can be useful when the lookup value is the result of a computation and due to processor differences there may be differences in the level of precision associated with the result.

SETUPPER

|?|

SIZE

|I|

TOLERANCE

|R|

54 Cube Voyager Reference Guide

General Syntax Standard control statements

Lookup functions are referenced in numerical and selection expressions. When a function is referenced, it is supplied a lookup argument within parenthesis, and the function returns a value for the argument. The returned value is obtained by searching the lookup function data table for the lookup argument. The table is composed of rows of data. If the LOOKUP subkeyword is in effect, the call to the function requires at least two arguments: the lookup curve number and the lookup argument. Otherwise, the function requires only one argument: the lookup argument. If the function can not find a match for the lookup curve number, FAIL[3] is returned, regardless of the value of INTERPOLATE. If the argument is less than the lowest value for the lookup number the return value is set to FAIL[1]. If the argument is higher than the highest value, the return value is set to FAIL[2]. If the value is not found in any range, the return value is set to FAIL[3] unless INTERPOLATE is set to true. If interpolation is used, the return value is the result of interpolating between the high limit of the lower row and the low limit of the upper row. For either a single or double value function (functional call with 1 or 2 arguments) and additional argument value can be provided. If this optional argument is provided ANY failure will not return the FAIL value defined by the FAIL keyword or its default values but the value for this optional argument will be the returned value on any failure. This in effect gives you the ability to override the default FAIL values for specific situations. Possible data records include: Data records when LOOKUP subkeyword is NOT used and data source is ASCII: Each data record must have at least two fields delimited by white space, or commas or may be separate fields on a DBF file. The first field on a record is the lookup result, and the fields following it are the lookup values. If two numbers are separated by a dash, they form the low and high limits of a row. Numbers not separated by dashes are entered as both the low and high limits of a row. Ranges may not overlap, but the upper limit of a

Cube Voyager Reference Guide

55

General Syntax Standard control statements

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

56 Cube Voyager Reference Guide

General Syntax Standard control statements

There will be no data points for T=3,V2, T=4,V3, T=5,V1, and T=5,V2. The V1 curve will have points for T=1-4, the V2 curve will have points for T=1-2,4, and V3 will have points for T=1-3, 5. The result for a lookup of T=3 in V2, will depend upon the options of the LOOKUP statement (SETUPPER, INTERPOLATE, or none). Be aware that this situation exists only for comma delimited and dbf data; space delimited records dont have any way to designate null fields; the first empty field indicates the end of the record, and no more points appear on the record. With space delimited records, the T=3 record would appear as 3 103 303, which would be interpreted as points for V1 and V2; V3 would be blank.
Example: Single value function
COPY FILE=C:\LOOK1.DAT ; this is the data for the function 1 2 3 4-8 23 15 50 2 1 3 9-10 ENDCOPY LOOKUP NAME=DISTRICTS, FILE=C:\LOOK1.DAT LIST=Y

The lookup table will be represented as:


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

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

Cube Voyager Reference Guide

57

General Syntax Standard control statements

Example: Single value function using LOOKUPI


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

Example: Double value function Typical friction factor curves

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

58 Cube Voyager Reference Guide

General Syntax Standard control statements

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

INTERPOLATE=Y, R= '0.01 1200 1000 800', '1 1200 1000 800', '3 300 500', '4 100 100 100', '5 50', '120 50 100 100' FFX = FF(1,3) ; RESULT = 300 FFX = FF(3,150,888) ; RESULT = 888 since 150 > highest value in field 1 FFX = FF(2,2) ; RESULT = 750 /* to find 2 in field 1, you must interpolate between 1 and 3 then interpolate on same basis between 1000 and 500 in field 3 */

; ; ; ; ;

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

The lookup table will be represented as:


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

Cube Voyager Reference Guide

59

General Syntax Standard control statements

Example: Double value function LOOKUP with DBF LOOKUPI file


FILEI LOOKUPI[1] = "C:\CUBETOWN\TAZ\TAZ.DBF" LOOKUP LOOKUPI=1, ;references the input DBF file NAME=TAZ, ;name for this function LOOKUP[1]=TAZ, RESULT=ACRES, ;lookup a value in TAZ return ;a the value from ACRES LOOKUP[2]=TAZ, RESULT=POPULATION, LOOKUP[3]=TAZ, RESULT=AGE_5_14, LOOKUP[4]=TAZ, RESULT=AGE_15_17, LOOKUP[5]=TAZ, RESULT=ENROL_ELEM, LOOKUP[6]=TAZ, RESULT=ENROL_HS, LOOKUP[7]=TAZ, RESULT=TOTAL_JOBS, LOOKUP[8]=TAZ, RESULT=RET_JOBS, LOOKUP[9]=TAZ, RESULT=SERV_JOBS, LOOKUP[10]=TAZ, RESULT=OTH_JOBS, INTERPOLATE=F ; example of use: v=TAZ(10,25) ; look for 25 in the TAZ field and returns the OTH_JOBS value

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

60 Cube Voyager Reference Guide

General Syntax Standard control statements

*/

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

Where the FRICTIONFACTOR.DBF file contains:

Cube Voyager Reference Guide

61

General Syntax Standard control statements

PRINT
Formats data items and writes them as a single line to the standard printed output, a file, or both. The program prints one line for each PRINT statement. The length of the printed line is determined by the formatting of each listed item.
CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT)

PRINT keywords
Keyword CFORM Subkeyword |S| Description Optional. Default format for subsequently appearing character strings, except for literal values, specified with the LIST keyword. Explicit formats defined for particular items take precedence. This default format is effective until the program reads the next CFORM value. See Defining a character print format on page 67. Default value is 0. CSV |?| Optional. Flag indicating whether to print the output file in CSV format (with commas between the LIST items). Possible values: FILE |F| T Print in CSV format, with commas between each LIST item F Do not print in CSV format

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

62 Cube Voyager Reference Guide

General Syntax Standard control statements

PRINT keywords (continued)


Keyword FILE Subkeyword APPEND |?| Description Optional. Flag indicating whether to overwrite or append to the specified file. Possible values: T Append the formatted list to the specified file. F Overwrite the existing file when writing the formatted list.

NOTE: If set to T for a file at least once in a step, then all PRINT statements executed at that step will append to that file, even if other statements set APPEND to F. Default value is F. FILE PRINT |?| Optional. Flag indicating whether to write record to standard printed output in addition to specified file. Possible values: FILE REWIND |?| T Write the record to the standard printed output in addition to the specified file F Only write the record to the specified file

Default value is F. Optional. Flag indicating whether the program repositions to the start of the file before writing contents. Possible values: T Reposition to start of file before writing formatted list. Program overwrites previous contents. F Write to the current position in the file.

REWIND is dynamic; therefore, you can control the rewinding on each PRINT statement. Default value is F. FORM |S| Optional. Default format for subsequently appearing numbers specified with the LIST keyword. Explicit formats defined for particular items take precedence. This default format is effective until the program reads the next FORM value. See Defining a numeric print format on page 66. Default value is 10.2.

Cube Voyager Reference Guide

63

General Syntax Standard control statements

PRINT keywords (continued)


Keyword LIST Subkeyword |KS| Description Optional. List of items (variables, strings, and expressions) to format and write to a printed line. Enclose expressions in parentheses. Specify no more than 500 items. To assign an explicit format to a particular item in the list, place the format in parentheses next to the item. The format only applies to that item. See Defining a numeric print format on page 66 and Defining a character print format on page 67. For example:
I, J, ITEM1(6), 'abcde', (sqrt(4))(8C), 'i='(8R), I(L).

Append appropriate subscripts to any array and matrix variables in the list. If you do not specify a subscript, the program will supply one, depending on the variable, program, and phase. Subscripts may be constants, variables, or valid expressions. For example: P[i*3-1]. NOTE: MW[n] normally implies MW[n][J], where J is the current value of J. The PRINT statement recognizes four special character strings as special control characters: "\n" new line control "\f" new page control "\t" tab control "\\" ignore new line control

For example, a literal string may contain the newline character string ("\n" ; lowercase), to generate a new line at that location (the \n will not be printed). As long as a PRINT statement has at least one LIST item, the program automatically inserts a newline character prior to the first item. You can override the automatic newline character by making the first LIST item a literal string that begins with the \\ characters. The \\ will not be printed, and the printing will continue from the current line position. NOTE: Because special characters are treated as these special controls, problems can arise when printing strings for a system path due to the "\" character. For example, upon reading LIST="C:\n2020\output\" the program would treat the embedded \n as the new-line control and insert a new line at the location. Because the special control is case sensitive and directory folder names are not, you can avoid this issue by using LIST="C:\N2020\output".

64 Cube Voyager Reference Guide

General Syntax Standard control statements

PRINT keywords (continued)


Keyword LIST (continued) Subkeyword Description In some cases, you might prefer to form character variables using the string functions of a COMP character expression and include those variables in the list. The string functions might provide some flexibility that is better suited to the specific task. |I| PRINT |?| Optional. Index number of the FILEO PRINTO file where the program writes this output. Optional. Flag that indicates whether to write record to standard printed output in addition to specified PRINTO file. Possible values: PRINTO REWIND |?| T Write the record to the standard printed output in addition to the specified file F Only write the record to the specified file

PRINTO PRINTO

Default value is F. Optional. Flag indicating whether the program repositions to the start of the file before writing contents. Possible values: T Reposition to start of file before writing formatted list. Program overwrites previous contents. F Write to the current position in the file.

REWIND is dynamic; therefore, you can control the rewinding on each PRINT statement. Default value is F.

Examples

Report a mixture of numeric and character variables.


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

Use LIST keyword without the control statement name.


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

Output to file and rewind file at the end.


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

Interpret sqrt(6) as a variable sqrt with form=6

Cube Voyager Reference Guide

65

General Syntax Standard control statements

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

'

Output directly to CSV format

FILEO PRINTO[1]=c:\data\mydata.csv If (I=1) PRINT CSV=T LIST=I,J,TIME,COST,DISTANCE PRINTO=1 PRINT CSV=T LIST=I(6.0L),J(6.0L),MW[1](8.4L),MW[2](8.4L),MW[3](5.2L) PRINTO=1

Defining a numeric print format


Use FORM to format numeric items. For FORM or individual numeric LIST items, specify print format as:
w.dCDBTLRS

where: w Total field width. For strings, you might set w to 0, indicating that the field width depends on the string length.
NOTE: If the format specifies L, w must be wide enough to accommodate the number.

d For numbers, number of digits printed after the decimal point; for strings, number of leading spaces printed. The program sets d to 0 if the format begins with w, and you do not specify d. C Insert commas into numbers. D Display zero-value numbers as a pair of right-justified dashes. B Display zero-value numbers as blanks. B overrides D, if both are coded. T Truncate numbers on the left if they cannot fit the field width. Normally, the program formats such numbers with all asterisks.

66 Cube Voyager Reference Guide

General Syntax Standard control statements

L Trim numbers on the left and print the result beginning with the left-most digit. With L, w indicates the fields maximum width; the result will be left justified and only as long as required. However, the number must fit within the specified w. R For numbers, replace a numbers trailing 0s (right side of decimal point) with spaces. Program replaces zeros after normal formatting and removes decimal point if there is no trailing 0. For strings, right justify. S Insert a space before the digits of any numbers formatted with L.

All characters are optional. The CDBTLRS characters (case insensitive) may be in any order, but must follow w.d, if w and d are specified. Citilabs recommends using a varying length format unless you must align reported values. The program attempts to accommodate fixed formats. When values do not fit the specified field width, the program drops commas, and then reduces the number of decimal places. If necessary, the program reformats with scientific notation (1E+ppp), if possible, otherwise the program truncates. If printing an unknown range of values, FORM must have a width adequate to accommodate all possible ranges. For delimitedformat output, FORM=16.4LRS is probably adequate. When printing fixed fields, do not specify L, R, and S.

Defining a character print format


Use CFORM to format text items. For CFORM or individual string LIST items, specify print format as:
w.dCDBTLR

where:

Cube Voyager Reference Guide

67

General Syntax Standard control statements

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

accommodate the number. d Number of leading spaces printed (or periods, if D specified). Specify d anywhere in the format string; any digit preceded by a period specifies d. If a format string specifies multiple d values, the program uses the last value. Valid values range from 0 through 9. The default value is 0. C Center-justify text item. Program applies T first. C overrides L or R. D Print periods (.) in the d characters preceding the field. B Replace blanks with underscore characters (_). T Trim leading or trailing spaces from text item. If L is specified, delete leading spaces. If R is specified, delete trailing spaces. If both L and R are specified, delete leading and trailing spaces and center-justify text item. L Left-justify text item. R Right-justify text item (truncating beginning characters if length exceeds field width).

All characters are optional. The CDBTLR characters (case insensitive) may be in any order, but must follow w.d, if w and d are specified. Unlike FORM, order of w and d is not fixed with CFORM. Citilabs recommends using a varying length format unless you must align reported values. The program attempts to accommodate fixed formats. When text does not fit the specified field width, the program truncates.

68 Cube Voyager Reference Guide

General Syntax Standard control statements

PRINTROW
Formats and prints all cells or selected cells of a matrix row to the main print file. Row formatting can be quite voluminous; use this statement judiciously. None of the PRINTROW keywords are trigger keys. You must code all on a PRINTROW statement.
PRINTROW keywords
Keyword BASE1 |?| Description Optional. Flag indicating row format when using non-varying print format (that is, FORM does not contain L). Possible values: T Begin every printed line with a zone number ending in 1. F Begin each printed line with appropriate zone number based on FORM and page width.

MAXPERLINE takes precedence over BASE1: if MAXPERLINE is specified and is not modular ten, BASE1 has no effect. For example:
PRINTROW MW=1-2, 8 FORM=LRD TITLE='form=LRD' PRINTROW MW=1-21 FORM=8 BASE1=Y MAXPERLINE=10

FORM

|S|

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

Cube Voyager Reference Guide

69

General Syntax Standard control statements

PRINTROW keywords (continued)


Keyword J |IP| Description Optional. List of zone numbers formatted for printing. Program sets excluded zones (those not listed) to zero. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. Delimit each number or pair with a comma. For example J=1,3-5,10,12-20 selects zones 1,3 through 5, 10, and 12 through 20 for printing. Valid values range from 1 to the number of zones. Default value is all zones. MAXPERLINE |I| Optional. Maximum number of columns printed on a line. By default, program allows any number of values to be printed on a line, provided line length does not exceed the standard page width. If MAXPERLINE is specified, program ignores page width. MW |IP| Optional. List of work matrices to print. Program prints matrices in ascending order, regardless of specified order. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. Delimit each number or pair with a comma. For example MW=1, 3-10, 13 selects work matrices 1,3 through 10, and 13 for printing. Default value is no work matrices. TITLE |S| Optional. Title printed at the beginning of each MW. The program truncates titles longer than fourteen characters. Enclose the value within quotes ('...') or literal marks ("..."). You may specify only one title per PRINTROW statement, even if printing multiple MWs. By default, the program prints no title.

For neat-appearing reports, Citilabs suggests specifying FORM without the LD, setting BASE1 to true, and setting MAXPERLINE to some integral of 10.
Example
PRINTROW mw=1-2,8 form=LRD title='form=LRD' PRINTROW mw=1-21 form=6D base1=y maxperline=10

70 Cube Voyager Reference Guide

General Syntax Standard control statements

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

READ keywords
Keyword FILE Description File to be read. When the end of file is encountered on that file, reading of control statements will continue with the statement following this READ statement. Character string that will replace oldstring in the records in FILE that contain oldstring. Newstring is case sensitive; it will be replaced directly. Character string (not case sensitive) that is to be replaced by newstring. As each record is read from the file, it is scanned to see if oldstring exists in it. If it does, the string is replaced with newstring, and the scan is continued. If either oldstring or newstring contains any special characters it must be enclosed with '...'. It is suggested that strings always be enclosed within '...', but it is not mandatory.

newstring

oldstring

READ statements can be nested up to five levels. A nested READ

may not point to a file that is already in the nest. There is no specific limit to the length and number of replacement strings. The replacement process is designed to not allow a replacement string to replace an earlier replacement. Replacements are done in the left to right order as specified in the READ statement.
Example
READ FILE=BUSLINES, MODE=5 = MODE=3

Cube Voyager Reference Guide

71

General Syntax Standard control statements

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

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

Example 1
SORT ARRAY=A,B,C ; Sort on ascending values in A, carry B & C along with A SORT ARRAY=-A,B,C ; same as above, but sort order for A is descending SORT ARRAY=-A,'+B',-C,D,E ; sort on descending on A, ascending B, descending C SORT ARRAY=-A,B,'+C' ; *** ERROR *** signed name (+C) follows unsigned (B)

72 Cube Voyager Reference Guide

General Syntax Standard control statements

Example 2 (Matrix, Fratar, Distribution, Generation)


ARRAY ZONENO=ZONES, HH=ZONES, INCOME=ZONES . . ZONENO[I] = I HH[I] = ZI.1.HH[I] INCOME[I] = ZI.1.INCOME[I] . . SORT ARRAY=-INCOME,-HH,ZONENO LIST= Zone Income HHs JLOOP PRINT FORM=8, LIST=ZONENO[J], INCOME[J], HH[J] ENDJLOOP

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

Cube Voyager Reference Guide

73

General Syntax Standard control statements

74 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Pilot Program

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

Cube Voyager Reference Guide

75

Pilot Program Using Pilot program

Using Pilot program


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

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

indicates strange filenames or default parameters, most likely the pppp.PRJ file has been corrupted. In such cases, the remedy is to

76 Cube Voyager Reference Guide

Pilot Program Using Pilot program

delete the pppp.PRJ file and restart the process. Cube also uses .PRJ files, and it is possible for the user to confuse the two and store Viper configuration information into a Cube Voyager .PRJ, and vice versa.

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

intrazonal times).
2. Distribute trip ends according to the paths and user functions. 3. Adjust person trip matrices to account for non-model

characteristics, peak period factors, and auto occupancy.


4. Assign trips to the network.

After the application of a series of programs to accomplish this has been completed, you would have to verify the results, and decide if the process needs to be rerun with adjustments, or if the results are satisfactory. The decision process usually will include some type of numerical analysis. If the results of the analysis are not satisfactory, the process may be repeated with some adjustments in the input data, or parameters. Typically, the repeat process is just that: the input data and/or parameters are modified, and the process is resubmitted. Cube Voyager simplifies this process by allowing the user to program the process to adjust the data and/or parameters and automatically repeat the entire process, or just selected portions of it. In the simple case, if the final speeds are not acceptable, the process could be looped until speeds come into a reasonable

Cube Voyager Reference Guide

77

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

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

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

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

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

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

window. This prevents disruption of the display, allowing other tasks to be performed more comfortably while the script is running. If it is required that the command window appear on the display, use the alternate **command rather than *command; for example, '**pause' rather than '*pause'. The '**' approach will be appropriate if the command requires some interaction with the user, or perhaps if it displays some progress which the user always wants to be able to view.
Example
*DEL ABCD*.TMP *IF EXIST OLD.NET DEL OLD.NET

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

BREAK
BREAK can be used to break out of a LOOP ENDLOOP block. It must be within a LOOP block. When BREAK is encountered, flow

immediately branches to the statement following the appropriate


ENDLOOP statement. The contents of the LOOP variable are not

altered.

Cube Voyager Reference Guide

83

Pilot Program Control statements

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

CLEARERROR
CODE RESUME The CLEARERROR statement is used primarily in conjunction with the variable ONRUNERRORGOTO. When the statement is encountered, it automatically resets the internal error code value to 1 and the resume switch to false. It is then the users responsibility to set those values with the keywords.
CLEARERROR keywords
Keyword CODE RESUME |I| |?| Description Internal error code is reset to this value. Can be a value of 0,1. If the value is True (1), and the program detects that it is in an error recovery process set by ONRUNERRORGOTO, control will switch to the statement following the RUN statement that caused control to switch to the recovery process.

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

84 Cube Voyager Reference Guide

Pilot Program Control statements

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

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

Var is the variable that is to have a new value computed for it. If

the variable matches a name in the Vars array, the result will be updated after the COMP is completed. If it does not exist in the Vars array, it is added as a new variable that can be referenced in subsequent control statements.

Cube Voyager Reference Guide

85

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

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

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

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

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

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

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

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

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

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

Pilot Program Control statements

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

This code value is stored in a variable named RETURNCODE. If the RETURNCODE value is greater than 1, the run is automatically terminated. However, if the user has set the string variable named ONRUNERRORGOTO to point to a legitimate LABEL statement in the script, the run will continue at the labeled statement if the return code is 2. See GOTO on page 91 for a description of defining a LABEL. At the labeled statement, the user can provide additional statements to further control what is to happen with the run. Typically, the user will set up a PRINT statement to write a message to the run print file or use a PROMPT statement to issue a message, and possibly request a response from the user to continue the run. The user may now also send an e-mail or text message to report results based on a run error. See SENDMAIL on page 106 for an example of using these statements together. To continue the run, the user will have to clear the internal RETURNCODE variable, or subsequent tests of the run status may cause termination. The CLEARERROR statement is used to reset the internal return code; it can not be cleared by setting RETURNCODE=. The CLEARERROR statement also provides a keyword to allow the user to resume executing script at the point following the RUN statement that caused control to be switched to the label specified by ONRUNERRORGOTO.

96 Cube Voyager Reference Guide

Pilot Program Control statements

It is suggested that the script statements to be processed on the return of an error message be placed at the end of the run script and jumped to with the ONRUNERRORGOTO Statement. Note that an EXIT statement should be used just prior to the :label referenced by the ONRUNERRORGOTO. Placing an EXIT statement prior to the :label will allow the program to terminate without executing the statements for the error condition when the script runs successfully without any errors. Refer also to the CLEARERROR statement (see CLEARERROR on page 84).
Example 1
RUN PGM=MATRIX ENDRUN

At this point the job will terminate because there was an error in the Matrix program (no operations).
Example 2
ONRUNERRORGOTO = 'MYERROR' RUN PGM=MATRIX ENDRUN ;At this point control will transfer to :MYERROR if the MATRIX step fails RUN PGM=. ENDRUN EXIT ; if program gets to this point then exit, no errors were encountered :MYERROR PRINT LIST='Special Message' ; Run will terminate from here with a final completion code of 2

Example 3
ONRUNERRORGOTO = 'MYERROR :STEP1 RUN PGM=MATRIX ENDRUN ;At this point control will transfer to :MYERROR if the MATRIX step fails :STEP2 RUN PGM=. ENDRUN :STEP3 RUN PGM= ENDRUN

Cube Voyager Reference Guide

97

Pilot Program Control statements

EXIT ; if program gets to this point then exit, no errors were encountered ; or all errors cleared :MYERROR PRINT LIST='Special Message' CLEARERROR CODE=0 GOTO STEP3

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

PARAMETERS
Specifies basic parameter values for the Pilot run. MAXSTRING

98 Cube Voyager Reference Guide

Pilot Program Control statements

<> is the program default value.


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

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

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

Cube Voyager Reference Guide

99

Pilot Program Control statements

PROMPT
QUESTION= ANSWER= WAIT= Poses mid-run questions that can alter the flow of the job. When encountering a PROMPT statement, the program lists a question (defined by the QUESTION keyword) and the possible answers (defined by the ANSWER keyword) and waits for a response. The response must select one of the answers. The program will not continue until a proper selection is made. The ANSWER number is returned to Pilot in the variable named ReturnCode, which the user can test via an IF statement. The use of the keyword PRNFILE on the RUN statement allows the user to redirect the print file for any job steps. When the PROMPT dialog box opens, the user can peruse the output from any of the previous step(s) to decide how to respond to the question.
PROMPT keywords
Keyword ANSWER |S5| Description Possible answers. The same rules about quotes in QUESTION also apply here. There may be up to 5 ANSWERs. Question to prompt the user with. Enclose with quotes or ""; if it contains any delimiters, it must be within quotes.

QUESTION

|KS|

100 Cube Voyager Reference Guide

Pilot Program Control statements

PROMPT keywords (continued)


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

When Pilot is launched a Windows dialog box opens, and the user responds by selecting a button.
Example
QUESTION=What do you want to do?, ANSWER=Continue, ; 1 Break out of Loop, ; 2 ABORT ; 3 IF (ReturnCode==3) abort IF (ReturnCode==2) break RUN PGM=MATRIX PRNFILE=myfile.txt . . ENDRUN PROMPT QUESTION=Examine myfile.txt to determine response to, ANSWER=Sum Too High, Sum Too Low, Sum Acceptable Get Out of Loop IF (RETURNCODE==3) break PROMPT

Cube Voyager Reference Guide 101

Pilot Program Control statements

REPORT
VARS STACK TRACE
REPORT keywords
Keyword STACK |?| Description Writes the internal stack. This is mostly used for program debugging, but can be useful for relating TRACE information to internal notation. STACK is static; if set to true, writes occur at the beginning of stack processing. Controls the listing of the stack statements as they are processed. TRACE can be turned on and off at any time, thus controlling the amount of output as desired. Each statement will be listed with an internal number, the control statement name, and, in most cases, additional information. TRACE is a trigger key. When set to true, the program lists the current variables and their values from the VARS array.

TRACE

|K?|

VARS

|?|

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

RUN ... ENDRUN


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

102 Cube Voyager Reference Guide

Pilot Program Control statements

Pilot loads and executes the program specified by PGM. Pilot attaches any control statements between the RUN and ENDRUN command to the specified program. Only the specified program will read and edit these statements.
ENDRUN signals the end of the RUN statement. Though optional, Citilabs recommends always using ENDRUN. A system command (*....) or another RUN statement also signals the end of a RUN statement.

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

PARAMETERS

|SV|

Cube Voyager Reference Guide 103

Pilot Program Control statements

RUN keywords (continued)


Keyword PGM |S| Description Program to be run. Pilot determines if it is a Cube Voyager program by searching for both program.DLL and program.TDF in the directories discovered in the following order: Directory from which Pilot was loaded Current directory Windows system and then the Windows directories Directories that are listed in the PATH environment variable

If the program is not located that way, it assumes that it is a non-Cube Voyager program and tries to locate it by applying a somewhat different set of criteria to determine the full name for the program, and to locate the directory where it resides. If program has no file extension and the last character is not a dot (.), append .exe to program. If program contains path information (has a \ or :), use that path If program does not contain path information, locate the program by searching the directory from which Pilot was loaded, and then the directories as registered with the operating system If program*.exe is found, look in that directory for the latest version of the program by assuming program#.exe and use the highest # file. Thus, if name.exe, name1.exe, and name3.exe are all found, name3.exe will be assumed. PRNFILE |F| Optional. File where the program expects to write its standard system print output. PRNFILE will be ignored if it is determined that a TRIPS program is being run. Optional. Switch to indicate that CTLFILE is to be directed into the program. Optional. Switch to indicate that the program is to direct its output to PRNFILE, if PRNFILE is also specified.

REDIRECTIN REDIRECTOUT

|?| |?|

If it is determined that a TRIPS program is being run (by the presence of &FILES OPRN keyword in the CTLFILE), PRNFILE, REDIRECTIN, and REDIRECTOUT are ignored. The RUN statement is designed to allow easy integration of nonCube Voyager programs directly in line with a standard run and to have the printed output of the program directly incorporated into the standard Cube Voyager print file. There may be programs

104 Cube Voyager Reference Guide

Pilot Program Control statements

whose basic operations will not allow this type of integration. In those situations, it is possible that the use of the Pilot * statement will allow the direct running of the command. The RUN statement for non-Cube Voyager programs generates a system command that is structured and executed based upon the following decision table. If PGM is a TRIPS program (contains &FILES OPRN=):
pgm ctlfile parameters >tprn

If PGM is not a TRIPS program:


RDI F F F F T T T T RDO F F T T F F T T prnfile T F T F T F T F Generated command
pgm ctlfile prnfile parameters pgm ctlfile parameters pgm ctlfile parameters >prnfile pgm ctlfile parameters >tprn pgm prnfile parameters <ctlfile pgm parameters <ctlfile pgm parameters <ctlfile >prnfile pgm parameters <ctlfile >tprn

NOTE: 1. If ctlfile has no length, it is not placed on the command line 2. tprn is a temporary file which is copied to the Cube Voyager

print file.
3. DRI/RDO = redirectin/redirectout Examples
RUN PGM=program parameters=datain, dataout Command: Path\program.exe datain dataout RUN PGM=abc.exe ctlfile=datain prnfile=dataout parameters=abc Command: Path\abc.exe datain dataout abc RUN PGM=ME ctlfile=datain parameters="/m=20" "/demo"

Cube Voyager Reference Guide 105

Pilot Program Control statements

Command: Path\MVESTM70.EXE datain /m=20 /demo RUN PGM=ME ; ctlfile follows this statement; will be copied to tfile Command: Path\MVESTM70.EXE tfile RUN PGM="c:\util\pkzip.exe" parameters="junk.zip t*.", "-v c", prnfile=zip.txt, redirectout=t Command: c:\util\pkzip.exe junk.zip t*. -v c >zip.txt RUN PGM=MATRIX ; standard Cube Voyager run

SENDMAIL
SMTPSERVER FROM TO CC SUBJECT MESSAGE ATTACHMENTS USERNAME PASSWORD PORT

106 Cube Voyager Reference Guide

Pilot Program Control statements

Immediately sends an e-mail. Use to transmit the status of a job or job step to a recipient. The keywords SMTPSERVER, FROM, TO, and SUBJECT must be specified; the others are optional. E-mail messages can also be sent as text messages to a cell phone.
SENDMAIL keywords
Keyword ATTACHMENTS CC FROM MESSAGE |S| |S| |S| |S| Description List of file names sent as attachments. There is a maximum of 1000 attachments. E-mail address(es) for copied recipient(s). E-mail address to be sent as the return List of individual lines to send in the message area of the e-mail. Each string is a separate line. There is a maximum of 1000 messages. Password for the account specified in USERNAME, if the SMTP server requires secure logon. If coding your script in Cube, you can insert the password value with the Insert menu command then selecting Password for email. Cube opens a Password Entry dialog box, which t allows you to mask the password for security.

PASSWORD

|S|

PORT SMTPSERVER

|I| |S|

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

Cube Voyager Reference Guide 107

Pilot Program Control statements

SENDMAIL keywords (continued)


Keyword SUBJECT TO |S| |S| Description Subject of e-mail. E-mail address(es) of the recipient(s). Separate multiple recipient addresses with a comma. You can also send mail as a text message to a phone and account that supports text messaging. Examples of cell phone provider messaging e-mail addresses are: T-Mobile: {phone#}@tmomail.net Sprint:
{phone#}@messaging.sprintpcs.com

Verizon: {phone#}@vtext.com

Check with his/her cell phone service provider to verify the appropriate address. USERNAME |S| User name for mail account, if the mail SMTP server requires logon.

Example

Using SENDMAIL with ONRUNERRORGOTO, RETURNCODE, and CLEARERROR to generate e-mail with attachments for various conditions
;======================================================================== ONRUNERRORGOTO='ONERROR' ; set LABEL to jump to if an error occurs StepName='Step 1 - Network' RUN PGM=NETWORK NODEI=DTWNNOD.DBF, LINKI=DTWNLNK.DBF NETO=DTWNTPP1.NET ZONES=24 ENDRUN StepName='Step 2 - Network' RUN PGM=NETWORK NODEI=xDTWNNOD.DBF, LINKI=DTWNLNK.DBF NETO=DTWNTPP1.NET ENDRUN SENDMAIL SMTPSERVER='smtp.yourname.com', FROM='ken@yourname.com',

108 Cube Voyager Reference Guide

Pilot Program Control statements

TO='ken@yourname.com,jill@yourname.com', CC='The Boss<boss@yourname.com>', Subject='Email from Voyager, Run Completed, No Error', Message='Voyager Run Completed', 'There is no run error', ATTACHMENTS='DTWNTPP1.NET' Exit ; if no errors then this step gets executed and terminates the run :ONERROR ; if an error occurs the processing jumps to this location rcode=str(returncode,2,0) ; returncode will have value=0,1,2,3 SENDMAIL SMTPSERVER='smtp.yourname.com', FROM='ken@yourname.com', TO='ken@yourname.com', Subject='Email from Voyager, Run Error', Message='There is a run error, returncode:',rcode, 'On Step ',StepName ; Also text message a cell phone SENDMAIL SMTPSERVER='smtp.yourname.com', FROM='ken@yourname.com', TO='5106635200@messaging.sprintpcs.com', Subject='Email from Voyager, Run Error', Message='There is a run error, returncode:',rcode, 'On Step ',StepName ; If the error happens on step 2, ignore the error, resume the run if (StepName='Step 2 - Network') CLEARERROR resume=t code=0 endif

Cube Voyager Reference Guide 109

Pilot Program Examples

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

Pilot example 1
/* Example 1: Typical application, with no logic. */ RUN PGM=NETWORK . data for NETWORK to build a network ENDRUN RUN PGM=HIGHWAY . data for HIGHWAY to build LOS files ENDRUN RUN PGM=DISTRIBUTION . data for DISTRIBUTION to distribute trip ends ENDRUN RUN PGM=MATRIX . data for MATRIX to combine and factor matrices ENDRUN RUN PGM=HIGHWAY . data for HIGHWAY to load trips to highway network ENDRUN RUN PGM=NETWORK . data for NETWORK to analyze assignment ENDRUN

Pilot example 2
/* Example 2: A little more complicated. All the RUN statements would have statements following them (including an ENDRUN statement). They are excluded, so that process can be presented more briefly. */ LOOP iter=1,5 COMP ID='This is iteration' + str(iter,2,0) RUN PGM=NETWORK

110 Cube Voyager Reference Guide

Pilot Program Examples

RUN PGM=HIGHWAY RUN PGM=DISTTRIBUTION RUN PGM=MATRIX RUN PGM=HIGHWAY RUN PGM=NETWORK ENDRUN IF ( NETWORK.RESULT <= 0.02) BREAK ; criteria already satisfied ENDLOOP

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

Cube Voyager Reference Guide 111

Pilot Program Examples

112 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Fratar

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

Cube Voyager Reference Guide 113

Fratar Using Fratar

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

114 Cube Voyager Reference Guide

Fratar Using Fratar

Specifying target values


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

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

Cube Voyager Reference Guide 115

Fratar Using Fratar

In this example, the values for zones 1-500 would be the direct values obtained directly from the ZI.1.HBWP2000 array, and the values for zones 501-550 would be the growth factors obtained from the ZI.2.EXTW array (divided by 2). In most cases the values will be obtained from ZDATI (zonal data) files, or LOOKUP functions, but that is not an absolute requirement. Standard numerical expressions (J being the only viable variable that could be included) are used to compute the values. Sometimes, it is desirable to input specific values.
Example 2
SETPA P[1]=5000 INCLUDE=255 ;input a specific value SETPA A[1]=sqrt(J/2+25**3.5) ;would be possible, but weird.

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

Controlling target totals


After processing the input matrix, the target totals for any growth factor values can be fully determined (value = gf * input). Next, the program adjusts the values to insure that the P and A totals match for each purpose. There are several options for adjustment; they are specified by the use of the CONTROL keywords on the SETPA statement. There may be a CONTROL specification for each purpose, and if the CONTROL for any purpose is specified more

116 Cube Voyager Reference Guide

Fratar Using Fratar

than one time, the latest value prevails. If no CONTROL is specified it defaults to PA. The valid values for CONTROL are: P, A, PA, PL, AL, and PAL. The meanings are:
Value P A PA Description The P totals control; all values in the A array will be factored so that the A totals will match the P totals. The A totals control; all values in the P array will be factored so that the P totals will match the A totals. All values in both the P and A arrays will be factored so that their totals will match the average of the initial totals.

Sometimes only certain zones are to be modified, and the remainder of the zones are to be kept constant. The program keeps track of the zones that are eligible for modification by noting which zones have target values that differ from the input value by more than one. If the letter L is appended to any of the CONTROL values, it indicates that the modifications are Limited to only the zones that have change. Use of the this feature can, in some cases, lead to a situation where a matrix grand total can not be properly computed. If that is the case, the program will fatally terminate.
Value PL AL PAL Description The P totals control. The changed zones in the A array will be factored so that the final A total will match the P total. The A totals control. The changed zones in the P array will be factored so that the final P total will match the A total. The values in P array for zones that have P changes, and the values in the A array for zones that have A changes will be factored in such a manner that the final P and A totals match the average of the initial P and A totals.

It is impossible to modify any cell, column, or row, that has zero to begin with. If a target value is specified for a zone that initially had no total, a warning message is issued. Traditionally, some modelers would scale a matrix by a value (usually 10, or 100), and then fill in all empty cells with one. This is not necessarily a good, or bad, solution. But, because of the potential problems associated with this approach, zero accountability is not included in this program

Cube Voyager Reference Guide 117

Fratar Using Fratar

directly. If the scaling scheme is to be applied, a prior application of the Matrix program can be used to scale and fill in a matrix in any desired manner. It could also be achieved by setting the SETPA MW expression to: max(1,mi.n.n*10).

Convergence Iteration control


A concern is when to stop the iterating process; there are several ways to control it. The user can specify a maximum number of iterations, so that no matter how the convergence is progressing, the process will not exceed that number. After each iteration, the program computes an RMS error value based upon the integer differences between the computed and target row or column totals. After odd iterations, column total differences are checked, and after even iterations, row differences are checked. If the RMSE value is less than the MAXRMSE parameter value, the solution is achieved. It is believed that this process will eventually reach convergence. But if, due to some unforeseen conditions, the RMSE value begins to oscillate, the program detects the oscillation, and terminates the process at the minimum RMSE. If there are multiple matrices being factored, they may reach optimum solutions at different times. If this happens, the solved matrices are held steady, and the others continue to be processed. A small example of this process:
After Iteration 1: RMSE = 22.87
Zone 1 2 3 Total Target 1 57 64 102 223 240 2 24 106 61 191 200 3 19 30 137 186 160 Total 100 200 300 600 600

118 Cube Voyager Reference Guide

Fratar Using Fratar

As dictated by row factoring, the row totals are correct. But, the column totals do not quite match the target. Another iteration is performed, and the results appear as:
After Iteration 2: RMSE = 7.94
Zone 1 2 3 Total 1 61 69 110 240 2 25 111 64 200 3 16 26 118 160 Total 102 206 292 600

The column totals are now on target, but the row totals are not quite on target. This process goes on, back and forth, until either the RMSE drops to the MAXRMSE level, or the number of iterations reaches the MAXITERS value. In this example, the final solution is reached after 5 iterations (MAXRMSE=0.01 and MAXITERS=10).
After Iteration 5: RMSE = 0
Zone 1 2 3 Total 1 60 70 113 240 2 25 190 64 200 3 16 26 118 160 Total 102 206 292 600

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

Multiple purposes
The number of purposes is determined by the highest P, A, PGF, AGF, or MW index found on any SETPA control statement. The program assumes that there will be purposes from one, monotonically, through that highest index. The distribution is performed prior to entering the main Matrix program I loop. When the main I loop is processed, MW[1] through MW[highest purpose]

Cube Voyager Reference Guide 119

Fratar Using Fratar

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

120 Cube Voyager Reference Guide

Fratar Control statements

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

Fratar keywords not in Matrix:


PARAMETERS MAXITERS= MAXRMSE= REPORT ACOMP= PCOMP=

This section describes: PARAMETERS REPORT SETPA

PARAMETERS
Sets general parameters. MATOEVERY MAXITERS MAXPURPS MAXRMSE ZONES

Cube Voyager Reference Guide 121

Fratar Control statements

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

122 Cube Voyager Reference Guide

Fratar Control statements

PARAMETERS keywords (continued)


Parameter MAXPURPS |KI| Description Number of purposes to process in this application. The keyword is not required, because the program will determine the value from the detection of the values on the SETPA statements. But, if this value is provided, and it conflicts with the SETPA statements, a fatal message will be issued. Cutoff criteria. If the RMSE for a purpose does not exceed this value, a solution is assumed for the purpose. The default is 10, and the minimum is 0. ZONES |KI| Highest zone number to process. If the number of zones cannot be ascertained from the project file or from any binary input matrices, ZONES must be provided, or the value will default to 100. If present, this value controls the application. Normally, there will be an input matrix file, so this keyword should not be required.

MAXRMSE

|KR|

REPORT
PCOMP ACOMP In addition to the REPORT keywords available for Matrix, the following are also available for Fratar:
REPORT keywords
Keyword ACOMP |KIP| Description Requests report comparing computed to target attractions for specified purposes. The report is in a format that is similar to the MARGINS report. The values are reported as nearest integers (without decimal places). Only the purposes specified by the keyword are reported, but they are reported for all odd iterations. Same as ACOMP, but refers to productions, and refers to only even iterations.

PCOMP

|KIP|

Cube Voyager Reference Guide 123

Fratar Control statements

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

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

124 Cube Voyager Reference Guide

Fratar Control statements

purpose are to be obtained from different sources, or if different INCLUDE/EXCLUDE filters are to be used (different SETPA statements must be used for different filters).
SETPA keywords
Keyword A AGF |NV| |NV| Description Expression solved to set the target attraction totals for the indexed purpose. Expression solved to set the target attraction growth factors for the indexed purpose. The final totals are obtained by multiplying the growth factors by the initial input matrix totals. String indicating how to adjust final target totals to enable convergence. The possible values are: P A PA PL Production totals control; As will be adjusted Attraction totals control; Ps will be adjusted Both Ps and As will be adjusted to the average of the P and A totals. Same as P, but only As in adjustable zones will be adjusted

CONTROL

|SV*|

AL Same as A, but only Ps in adjustable zones will be adjusted PAL Same as PA, but only adjustable zones will be adjusted EXCLUDE |IP| Processed the same as EXCLUDE on COMP statements (see COMP on page 43). If it is used, the loop will not be processed for any zones in the list. EXCLUDE filtering follows any INCLUDE filtering. Processed the same as INCLUDE on COMP statements (see COMP on page 43). If it is used, the loop will not be processed for any zones not in the list. INCLUDE filtering precedes any EXCLUDE zones.

INCLUDE

|IP|

Cube Voyager Reference Guide 125

Fratar Control statements

SETPA keywords (continued)


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

P PGF

|NV| |NV|

Example

Using single CONTROL keyword:


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

Using multiple CONTROL keywords:


SETPA P[1]=(ZI.1.P1) A1=(ZI.1.A1) MW1=1 CONTROL[1]=A SETPA P[2]=(ZI.1.P1) A2=(ZI.1.A1) MW2=1 CONTROL[2]=P SETPA P[3]=(ZI.1.P1) A3=(ZI.1.A1) MW3=1 CONTROL[3]=PA

126 Cube Voyager Reference Guide

Fratar Examples

Examples
/* The following two steps (MATRIX and FRATAR) setup and run the small example used in the Introduction to illustrate convergence. It is a good example of different ways to play with MATRIX. The MATRIX step generates a 3 zone matrix, and the FRATAR step modifies it. */ RUN PGM=MATRIX ZONES=3 MATO=3ZONE.MAT,MO=1 IF (I==1) MW[1][1]= 57 MW[1][2]= 24 MW[1][3]= 19 IF (I==2) MW[1][1]= 64 MW[1][2]=106 MW[1][3]= 30 IF (I==3) MW[1][1]=102 MW[1][2]= 61 MW[1][3]=137 ENDRUN RUN PGM=FRATAR MATI=3ZONE.MAT MATO=3ZONEF.MAT,MO=1 LOOKUP NAME=TOT,LOOKUP[1]=1,RESULT=2,LOOKUP[2]=1,RESULT=3, R='1 100 240', '2 200 200', '3 300 160' MAXRMSE=0.01 MAXITERS=10 SETPA P[1]=TOT(1,J) A[1]=TOT(2,J) MW[1]=MI.1.1 ACOMP=1,PCOMP=1 MARGINS=1 ENDRUN

Cube Voyager Reference Guide 127

Fratar Examples

128 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Highway Program

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

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

Cube Voyager Reference Guide 129

Highway Program Using the Highway program

Using the Highway program


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

Highway introduction
The Highway program now supports junction or intersection constrained assignment as well as the typically link based capacity constrained assignment. Junction-constrained assignment requires the coding of the junction or intersection movements and controls. The descriptions below refer to link based traffic assignment. Refer to Chapter 7, Intersection Modeling, for a detailed description of intersection modeling and the data requirements. The Highway program now can write the full path file from an assignment run including full results from every iteration. This makes many forms of path based analysis directly accessible in Cube without having to rerun the assignments with specific commands in the scripts. See the description of PATHO in FILEO on page 196 and PATHLOAD on page 223; also refer to Highway path display on page 278 of the Cube Base Reference Guide for information about path-based analysis in Cube. The Highway programs primary function is to assign trips to highway network links. A highway network, zonal matrices, zonal data, junction data and turn penalties can be input, and a loaded network, new matrices, turning volumes, final junction delay and reports can be output. There are basic default operations, but the user can control much of the process

130 Cube Voyager Reference Guide

Highway Program Using the Highway program

A typical assignment program builds paths based upon link costs (impedances) and assigns trips to those paths for each origin zone. After all origin zones have been processed, link costs are updated based upon the level of congestion on each link. Then the entire path and assignment process is repeated. This process continues until some criteria for termination is reached. The volumes from each iteration are combined to form a weighted assignment. Different criteria are used to determine when enough iterations have been performed. Almost all of the operations follow a fixed pattern, and are driven by basic parameters. Various options are usually available to provide the user with additional outputs. Select link analysis is a major tool for most users. This process traps the trips that meet the select link criteria, and usually writes them to output matrices. The Highway program provides the same capabilities as a traditional assignment program, but functions somewhat differently. There are only a few automatic operations, and global parameters are used sparingly. The program operates by processing in various phases. In each phase the program performs certain specific operations, and optionally processes a stack of operations provided by the user for that phase. In addition to phase operations, the user can enter FUNCTION statements (in the form of numerical expressions) that are to be performed in place of default functions at certain times by the program. For normal processing, there must be a way of computing certain required values for each link. If there is no automatic way for the program to determine these values, the user must supply the process to obtain them. Normally, the values are computed directly from the variables in the input network, but since there is no fixed format of the network, the required variables may not be present. In that case, the LINKREAD phase can be used and formulated to provide these values. The underlying assumption is that path building and capacity restraint are based upon a generalized cost on each link. In most cases, the cost is time. There are several ways to obtain the free flow time (T0), and the initial path time (T1). The hierarchy of the processes to obtain T0 and T1 is outlined below, in the description of the LINKREAD phase.

Cube Voyager Reference Guide 131

Highway Program Using the Highway program

The best advice is that the network should contain a variable that can be used directly for T0, or that it contains variables so that DISTANCE and SPEED information can be easily obtained. If the variables DISTANCE, LANES, and SPDCLASS are in the network, T0 can be computed from the DISTANCE and the values from the SPDTAB speed table. If the network is the result of conversion from a TRANPLAN network, it will usually contain variables named DISTANCE, TIME1, and CAPACITY. DISTANCE and TIME1 are usually in hundredths of miles and hundredths of minutes, respectively. CAPACITY is normally the total capacity for the link. TIME1 is the starting time for assignment, and is not necessarily a true T0 (free flow time). If such a network is used directly, the LINKREAD stack should contain the following statements:
DISTANCE=LI.DISTANCE/100 ; not absolutely necessary T0 = LI.TIME1/100 C = LI.CAPACITY * CAPFAC ; factor to get on same scale with trips

In reality, it would be better to rename and scale the variables appropriately during the network conversion process, so that it is not necessary to remember to deal with them in the Highway program. ProductName converted networks will be in nearly the correct format, but the user should also be aware to scale the variables to the correct values. If the network distance is properly scaled, T0 will be computed from the DISTANCE, SPDCLASS, LANES, and the SPEED portion of the SPDCAP tables. The major phases in the process are: SETUP Optionally, initialize basic user arrays and processes LINKREAD Obtain required values for each link ILOOP Build paths and assign trips from each origin zone ADJUST Examine iteration results, test for convergence and adjust link values for next iteration

132 Cube Voyager Reference Guide

Highway Program Using the Highway program

CONVERGE Optional phase where user can specify their own convergence rules and stopping criteria

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

Highway program control statement overview


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

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

include: COMP PATHLOAD SET


Reporting statements Accumulate or dynamically display

values. Examples include:

Cube Voyager Reference Guide 133

Highway Program Using the Highway program

PRINT PRINTROW REPORT


Flow control statements Set statement order. Examples

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

Functions and built-ins


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

NOTE: The names are not case sensitive, but capitalization may

make them a bit more meaningful. You can also use FUNCTION statements to enter single expressions for computing certain values. See FUNCTION on page 206.

134 Cube Voyager Reference Guide

Highway Program Using the Highway program

Built-in variables
Only the variables with a * may be stored into by the user; the others are reserved.
Variable _SKIPTOI Description In the ILOOP phase, jump to the specified zone immediately. Its value is checked at the end of the current I. If specified, Cube Voyager sets I to that value. The specified value must be greater than the current I. See Example of _SKIPTOI on page 141. Capacity used in congestion expressions; Link distance expressed in miles or kilometers. Current rows zone (ILOOP). Current iteration number. Column index, usually 1, and varies (1-Zones) for MW[] and JLOOPs. Lambda value computed for this iteration; do not be reset. Last iteration indicator, usually set to the MAXITERS parameter Class of the current link; you can modify in LINKREAD. Link number (available during any implied link loops) Result of LOWEST(). Number of nodes. Number of links. Zero value means do not include in equilibrium; you can modify in LINKREAD. Link speed. Link free flow time. Initial iteration time. Total link volume used in ADJUST; by default, it is the sum of all VOL[] sets. Number of zones.

C* DISTANCE*

I
ITERATION

J
LAMBDA LASTITERATION LINKCLASS* LINKNO LOWCNT NODES NUMLINKS PROJECTLINK

SPEED*
T0* T1* V* ZONES

Cube Voyager Reference Guide 135

Highway Program Using the Highway program

Built-in arrays
There are arrays that can be referenced with [] to indicate a specific value from the array. Most times, the link-oriented arrays need not be referenced with an index; the default [linkno] is supplied by the program. The names with a * can be stored into, the others are reserved.
Array A B COST DIST* LI.name LW.name* MW[]* TIME* VOL[]* Description A-nodes for each link. B-nodes for each link. Link cost values. Link distances. Link values from the network. User generated values for links (currently accepts numeric values only). A work matrix; see COMP on page 177 for more details. Link times. Link volumes.

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

136 Cube Voyager Reference Guide

Highway Program Using the Highway program

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

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

Built-in variables available in the CONVERGE phase


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

Cube Voyager Reference Guide 137

Highway Program Using the Highway program

Converge phase variables (continued)


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

Built-in functions available in the CONVERGE phase


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

GAPCHANGEMIN

138 Cube Voyager Reference Guide

Highway Program Using the Highway program

Converge phase functions (continued)


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

Cube Voyager Reference Guide 139

Highway Program Using the Highway program

Converge phase functions (continued)


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

In many applications, only a few ILOOP statements will be required. For example, an assignment would require only the following statements:

140 Cube Voyager Reference Guide

Highway Program Using the Highway program

Example of most simple assignment

Assume NETI contains values to obtain T0.


RUN PGM=HIGHWAY FILEI NETI=..., MATI=... FILEO NETO=... PHASE=ILOOP PATHLOAD VOL=MI.1.1, PATH=TIME ENDRUN

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

Getting started with assignment


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

Cube Voyager Reference Guide 141

Highway Program Using the Highway program

we will assume that time is the basis for the process, we wish to do a peak-hour assignment, and the network has the following variables.
Variable T0 DISTANCE C Description Link free flow time Optional, but useful for certain statistics Link capacity in veh/hr

Base case is therefore:


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

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

Examples show: Daily assignment Add select link loading Add truck assignment on same paths Add truck assignment on separate paths Use preloaded truck volumes

142 Cube Voyager Reference Guide

Highway Program Using the Highway program

Separate trips on separate paths Assignment of trips to HOV facilities

Daily assignment
Now lets add a few complications: The trip matrix contains daily trips, and we wish to do a daily assignment. The only thing that we need to do is to get the capacity into the correct units (well assume that daily capacity is 10 times the hourly capacity). We can do this in one of several ways, but lets just do the simplest, by adding a capacity factor.
PARAMETERS CAPFAC=10; factor NETI capacity by 10 to get daily capacity PHASE = ILOOP PATH=TIME, VOL[1]=mi.1.1

Add select link loading


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

In this case, work matrix 1 (MW[1]) is computed to be only the trips from MATI whose paths use the selected link. That matrix is then assigned to volume set 2 (VOL[2]). Because we supplied the V function, capacity restraint will only involve VOL[1].

Cube Voyager Reference Guide 143

Highway Program Using the Highway program

Add truck assignment on same paths


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

Add truck assignment on separate paths


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

Use preloaded truck volumes


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

Separate trips on separate paths


This involves more planning and a bit more script to set up the process. In this scenario, we will assume that one matrix will be assigned to the minimum time paths, but when the paths for the other matrix are developed, the link times are different then the times used for the first matrix. A typical situation occurs when

144 Cube Voyager Reference Guide

Highway Program Using the Highway program

trucks basically operate at a lower speed than cars. In this example, we will establish a time factor to adjust the time on all links. The LINKREAD phase will establish an array (LW.TRKTIME) of times to be used in assignment of the truck trips. After the first iteration, the program would automatically adjust the car times, but there is no automatic way to adjust the truck times. So, we have to introduce an ADJUST phase, in which we do the truck time adjustment for the next iteration.
PHASE = LINKREAD T0 = LI.DISTANCE * 60 / LI.SPEED TRKFAC = 1.0 IF (LI.FUNCTYPE == 15, 25,35,45,55,65,75) TRKFAC = 1.2 LW.TRKTIME = T0 * TRKFAC ENDPHASE FUNCTION V = VOL[1] + VOL[2]*1.3 PHASE = ILOOP PATH = TIME, VOL[1] = mi.1.1 PATH = LW.TRKTIME, VOL[2] = mi.1.2 ENDPHASE PHASE = ADJUST LW.TRKTIME = TIME * TRKFAC ENDPHASE

Assignment of trips to HOV facilities


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

Cube Voyager Reference Guide 145

Highway Program Using the Highway program

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

Network development
To use the path-based tolling TOLLMATI function, you must follow several rules when coding closed toll systems. Violating any of these rules causes Cube Voyager to terminate. Each toll facility must operate as a completely closed system where users can access and egress the facility only by crossing specified toll gates. Every on-gate must have a unique number (1-999). Every off-gate must have a unique number (1-999). Every toll-road link must be identified as such (that is, value is not 0). Each network link must have three attributes, which designate the links role in the toll system. You specify the attribute names in a FILEI TOLLMATI statement. A link can have a non-zero value for at most one of these attributes. The attributes store: On-gate number Off-gate number Toll-road indication A toll record must specify the toll for every possible on-off combination of toll gates. You specify toll records in a FILEI TOLLMATI file. Toll access rules: Toll on-ramps:

146 Cube Voyager Reference Guide

Highway Program Using the Highway program

Inbound link must be a non-toll-road link or a toll offlink. Outbound link must be a toll-road link or a toll off-link. Inbound link must be a toll-road link or a toll on-link. Outbound link must be a non-toll- road link or a toll onlink. Inbound link must be a toll-road link or a toll on-ramp. Outbound link must be a toll-road link or a toll off-link.
Inbound link must be Non-toll-road off-ramp Toll-road onramp Toll-road onramp Outbound link must be Toll-road offramp Non-toll-road on-ramp Toll-road offramp Inbound link may not be Toll-road onramp Non-toll road Non-toll-road off-ramp Outbound link may not be Non-toll-road on-ramp Toll-road offramp Non-toll-road on-ramp

Toll off-ramps:

Toll-road links:

Toll type On-ramp Off-ramp Toll road

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

The file may be a DBF, an MDB-element, or a delimited text file. For DBF or MDB files, you must name ENTRYGATE and EXITGATE to indicate which fields on the record contain the on- and off-gate numbers, and TOLLS must name the fields containing the toll values. The first value for TOLLS is toll set 1, the second value is set 2, and so forth. For delimited text files, the values are field numbers

Cube Voyager Reference Guide 147

Highway Program Using the Highway program

instead of names. There may be up to ten TOLLMATI record numbers, and up to ten toll sets. If any of these values is not specified, the default is the relative field on the record (ENTRYGATE is 1, EXITGATE is 2, and TOLL is 3).
NOTE: If a record exists for a gate-to-gate combination (for the

TOLLMATI#), but does not contain a specific toll (value missing or blank), Cube Voyager assumes a toll value of zero. The NETI... keywords indicate the NETI link attributes that contain the values for the ramp and road links. You can use these keywords on any FILEI TOLLMATI statement. If you use the keywords on more than one such statement, they must have the same values. If any are unnamed, the defaults names are: TOLLENTRY, TOLLEXIT, TOLLROAD. The program will fatally terminate if: A link has a nonzero value on more than one of the required toll attributes. More than one link has the same on-ramp value. More than one link has the same off-ramp value. A possible on-to-off route does not have a toll specified. Zero is an acceptable value. There is a violation of the above access rules.

At the beginning of each iteration, the program determines the onoff combinations that are possible for each PATHLOAD statement. It checks if there is a toll for each of those combinations, and if not, it fatally terminates. It saves those on-off combinations and uses them during the PATHLOAD statement; therefore, do not revise the PATH=array within the iteration. With most toll systems, altering the array would probably not cause a different routing between on-off ramps, but, the on-off travel costs could become incompatible with the array costs. In some systems, changes in the path array might cause a different on-off routing, but since the toll routings and costs are fixed for the iteration, the application does not consider

148 Cube Voyager Reference Guide

Highway Program Using the Highway program

such changes. The PATHLOAD path-building process does not directly use the toll facility links; instead, the process uses the predetermined combinations. During path building, the new PATHTOLL keyword value can be used to skim the toll values for the paths (MW[1]=PATHTOLL). Any I-J path that traversed one or more combinations of entry and exit gates will have the accumulated toll along the path placed in the matrix. For an example of a script using TOLLMATI, see Highway example 8 on page 259.

Cube Voyager Reference Guide 149

Highway Program Phases

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

SETUP and LINKREAD phases


This section describes the SETUP and LINKREAD phases: SETUP phase LINKREAD phase

SETUP phase
The stack for this phase is processed after all control statements have been read and edited. The only operational statements allowed in this stack are COMP and SET. There is no specific header for SETUP; it is the phase that precedes the first actual PHASE= statement. It is used to initialize certain variables and/or arrays.

LINKREAD phase
This phase follows the SETUP phase. The primary purpose is to obtain the initial values that are required from the input network, and to compute link values that the user can reference in other phases. The values obtained directly from the network are referenced using the network name prefixed by LI. Any variables, other than those obtained directly from the network, that the user wishes to reference later in any phase must be named as LinkWork variables. LinkWork variables must be given names that begin with LW. The statement: LW.TOLLTIME = LI.TOLLTIME / 100 would generate a value that is available for every link at any stage in the

150 Cube Voyager Reference Guide

Highway Program Phases

application. On the other hand, the statement: TOLLTIME = LI.TOLLTIME / 100 would generate a variable that has no meaning beyond the current link. The LinkWork variables are stored as LinkWork arrays (see Built-in arrays on page 136). An internal loop is processed based upon the Linkno variable which loops from the first link through the last link (Linkno=1, NumLinks). For each value of Linkno, the program obtains a link data record from the input network (NETI), and processes the LINKREAD phase stack, if present. After the LINKREAD stack is finished, it ensures that certain link variables (T0, T1, and C) are set and fills in the link TIME and COST values. There are different ways that these variables can be set. The logic that the program uses is described below. Note that while DISTANCE and SPEED are examined, they need not be specified by the user. Usually, T0 is computed by dividing DISTANCE by SPEED. Therefore, the program will try to obtain DISTANCE and SPEED values. If they are not set by the user stack statements, the program will try to set them, and then compute T0 from them. On the other hand, if the user has set T0 directly, the values of DISTANCE and SPEED are merely academic. The logic that is applied to get the required values (after the user LINKREAD stack is processed) is as follows: DISTANCE (possibly used to compute T0): If set by LINKREAD, use that value, Else if there is a LI.DISTANCE, DISTANCE = LI.DISTANCE, Else DISTANCE = 0. If DISTANCE < 0, set DISTANCE = 0. LINKCLASS (essential for selecting appropriate Functions): If set by LINKREAD, use that value, Else if there is a LI.LINKCLASS, LINKCLASS = LI.LINKCLASS, Else LINKCLASS = 1. If LINKCLASS < 1, set LINKCLASS = 1. SPEED (possibly used to compute T0): If set by LINKREAD, use that value,

Cube Voyager Reference Guide 151

Highway Program Phases

Else if there is a LI.SPEED, SPEED = LI.SPEED, Else If there are LI.LANES and LI.SPDCLASS and their values are valid (1-9, and 1-99), SPEED = SPEEDFOR(LI.LANES,LI.SPDCLASS). Else SPEED = 0. C (capacity, used later in restraining process in the ADJUST phase): If set by LINKREAD, use that value. Else if there is a LI.CAPACITY, C = LI.CAPACITY* CAPFAC, Else If there are LI.LANES and LI.CAPCLASS and their values are valid (1-9, and 1-99), C = CAPACITYFOR(LI.LANES,LI.CAPCLASS) * CAPFAC. Else C = 0. If C < 0, set C = 0. Note: the program treats a link capacity of 0 (zero) as infinite capacity. T0 (free flow time): If set by LINKREAD, use that value. Else if there is a LI.T0, T0=LI.T0 Else if there is a LI.TIME, T0 = LI.TIME Else if there is a LI.TIME1, T0 = LI.TIME1 Else if SPEED > 0, T0 = DISTANCE*60/SPEED If T0 < 0, T0 = 0. T1 (initial iteration time): If set by LINKREAD, use that value. Else T1 = T0;

152 Cube Voyager Reference Guide

Highway Program Phases

TIME (a LinkWork variable, without the required LW. prefix, of T1 values): TIME is set equal to T1 after the LINKREAD stack is processed; the user may not reference TIME in LINKREAD because its value is unpredictable at that time. COST (a LinkWork variable, without the required LW. Prefix, of cost values): COST is ALWAYS computed by the COST function for the LINKCLASS after the user LINKREAD statements are exhausted. The user may not reference COST in LINKREAD. DIST (a LinkWork variable, without the required LW. prefix, of DISTANCE values): DIST is set equal to DISTANCE after the LINKREAD stack is processed; the user may not reference DIST in LINKREAD. When the LINKREAD stack is processed for each link in the capacity restraint process, the TIME, COST and DIST values are not touched following the stack operations. Another important function of LINKREAD is to allow the user to specify GROUP codes for links. Group codes can be used in various applications. Links with certain GROUP code values can be disabled during path building to preclude those links from being included in the path. (See PATHLOAD on page 223 for more details.) For example, it is possible to build low occupancy vehicle paths by precluding the use of HOV links. There are additional types of applications that can take advantage or this capability. GROUP codes can be very useful in select link processing. Paths which use links with certain GROUP codes can be easily identified and used for extracting matrices. It is even possible to identify the paths that have a certain level, or combination of levels, of GROUP coded links. See SETGROUP on page 244 for more details about this capability. COMP statements can be used to alter, or set, link values in LINKREAD.

Cube Voyager Reference Guide 153

Highway Program Phases

PRINT statements can be useful for listing information about individual links. It should be noted that listing TIME, COST and DIST will display meaningless values during LINKREAD.
NOTE: It is important to note that the entire LINKREAD stack is

processed for each link every time a network link data record is read. In order to ensure consistency, the LINKREAD stack is also processed for each link as it is read and processed in the ADJUST (capacity restraint) phase also. That is primarily why the user may not reference TIME, COST and DIST in LINKREAD; it could alter the internal arrays that are being used and dynamically altered by the capacity restraint process. If there are no special LINKREAD operations to be performed, there need not be any stack statements in this PHASE.

ILOOP phase
This phase performs a zonal loop (I = 1, Zones). Almost all control statements are valid within this stack. There MUST be a PHASE=ILOOP statement, and the stack MUST have at least one PATHLOAD statement. The ILOOP stack is executed one time for each value of I. Almost all the functions of the Matrix program can be performed within this stack. MW[#]= statements are performed for all Js (J=1,Zones), unless the statement occurs within a JLOOP block, or both indices (MW[][]) are specified. For assignment, the PATHLOAD statement is the most important. It specifies a set of values that are to be assigned to the links in a specified path set. The following examples illustrate the PATHLOAD statement: Volume sets Stratifying vehicle distance traveled by average trip speed Select link Selected zone loading

154 Cube Voyager Reference Guide

Highway Program Phases

Subarea trip extraction

Volume sets
A volume set is an array in which assignments for each link are accumulated. There may be up to twenty volume sets; the highest set number is 20, but set numbering need not be monotonic. The volume sets are addressed as VOL[#], and each of these is cleared at the beginning of each iteration. Values are entered into the VOL sets by using PATHLOAD VOL[] = expressions. In example 1, VOL[1]=MI.1.6 instructs the program to route the values from the expression MI.1.6 along the paths from the origin zone (I) to each of the destination zones (J). A VOL[] = expression implies an internal loop of J=1,Zones. In the example, as J loops, the value (normally trips) for I to J from MI.1.6 will be routed along the path from I to J.
Example 1
PATHLOAD VOL[1]=MI.1.6, PATH=TIME

Example 1 establishes that the set of link volumes (VOL[1]) is to have values added to it by assigning the values from matrix 6 from the MATI[1] file to the links in the paths based upon the link values of TIME.
Example 2
PATHLOAD PATH=LI.DISTANCE, VOL[3]=I*10+J

Example 2 establishes that the set of link volumes (VOL[3]) is to be have values added to it by assigning the values computed from the I*10+J expression to the links in the paths based upon the link values for LI.DISTANCE. (A value will be assigned for each J in: J=1,zones.)
Example 3
PATHLOAD VOL[4]=MW[5]+MW[6]+MI.2.8, PATH=LW.TOLLTIME

Cube Voyager Reference Guide 155

Highway Program Phases

Example 3 specifies that a PATH is to be built based on the link values from LW.TOLLTIME, and the values to be assigned to those paths are obtained by solving the expression: MW[5] + MW[6] + MI.2.8.

Stratifying vehicle distance traveled by average trip speed


During a multiple iteration assignment, the trips from any I to J may use various paths. The paths are based upon the times on each link in effect in that iteration. After all iterations, the final link volumes, along with the travel times associated with those volumes are used to obtain vehicle time. There are those who believe that emission estimation based upon individual link volumes, distances, and times is not as useful as vehicle distance based upon the average trip speed. To allow vehicle distance to be obtained based upon average trip speed, the REPORT VDTSPD must be requested. With this option, considerably more processing must be undertaken, and a considerable amount of disk space might be required. The program saves the paths for each I-J movement during normal assignment. Following the assignment, the paths are retrieved and the all the assigned trips are retraced along the paths they used in assignment. However, the final link times are used to obtain the individual trip time and distance. The average speed for the trip can then be calculated. The speed is used to stratify the vehicle distance of travel. The user can specify multiple stratification schemes; additional schemes do not require additional resources.

Select link
There are several ways in which select link processing can be undertaken, and they are all initiated via the PATHLOAD statement. A PATH keyword specifies the link values that are to be used to develop the paths. Any MW[]= expressions that are followed by SELECTLINK=, SELECTGROUP=, or SELECTLINKGROUP= will solve the MW= expression for only those destination zones (J) where any

156 Cube Voyager Reference Guide

Highway Program Phases

of the SELECT expressions results in a true condition. If a subsequent VOL= is used, any of the select link matrices can be assigned at that point.
Example (simple code inefficient)
MW[1]=0 JLOOP ; this illustrates selective gathering IF ((I=... & J=...) || (I=... & J=...) ) MW[1] = MI.1.1 ENDJLOOP VOL[1]=MW[1],path=...

Since solving complicated selections can be somewhat time consuming, the IF process would probably be faster if the zonal ranges are not too complicated.
Example (most efficient)
IF (I=...) PATH=..., VOL[1]=MI.1.1, INCLUDEJ=...

Example (using SelectLink)


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

Selected zone loading


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

Subarea trip extraction


To obtain matrices of trips that have some portion of travel in a selected region (subarea network polygon) of the network, the following keywords must be used:

Cube Voyager Reference Guide 157

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 values computed from the SUBAREAMAT expression for each J zone are traced along the path from I to J. If the path uses any links that are in the subarea network, the value for J is placed into the subarea matrix. In this process, there are several types of records that can be extracted:
Description X-X X-I I-X I-I path begins and ends outside subarea, crossing the cordon line only 2 times. path has origin outside the subarea and destination inside the subarea. path has origin inside the subarea and destination outside the subarea. both ends of the path are inside the subarea.

When a path enters the subarea by crossing a cordon link, the A node of that link becomes the origin zone of the extracted record, and the B node of the cordon link used to exit the subarea becomes the destination zone. If the path terminates at an internal zone, the internal zone becomes the destination zone. When a path exits the subarea, the internal zone where the path began, or the A node of the cordon link that was used to enter the subarea, becomes the origin zone of the extracted record, and the B node of the exit cordon link becomes the destination zone. If a path begins and ends inside the subarea, but never crosses the cordon line, a single I-I record is extracted. The A node of the origin zone becomes the origin, and the destination zone becomes the destination. The intrazonal value for an internal zone will be extracted even though there is no path.

158 Cube Voyager Reference Guide

Highway Program Phases

Multiple records can be extracted for a path. (For example, a path begins outside, enters, exits, enters, and either exits again, or terminates an internal zone.) The final matrices are combined values from all iterations of assignment, but if requested during a non-assignment application, only 1 iteration is processed. The subarea network is obtained from the Viper software, using the Polygon Subarea network extraction process.
Example (subarea trip extraction)
PATHLOAD PATH=TIME, SUBAREAMAT[1]=MI.1.1, SUBAREAMAT[2]=1

ADJUST phase
This phase is automatic, and follows the ILOOP phase in each iteration. A major purpose is to compute the congested time (Tc) on each link and to revise the link TIME values for use in the next iteration. If some special processing on each link is to be performed following the normal adjustment process, the Phase=ADJUST control must be input and followed by a stack of control statements that are to be performed. A common application for user supplied ADJUST statements is to list the effect of the normal process on each link and to make adjustments to LW. values. If an LW.value is based upon any values that are revised by the ADJUST process (most likely Time and/or Cost), LW.value should be re-calculated by the user at this time. For example, assume that there is a set of LW.TOLLTIME values, and those values need to be updated to reflect the change that were made in TIME. It is the users responsibility to make the changes in LW.TOLLTIME; the program does not know the intention of the user, so it can not make any adjustments automatically. It is permissible to alter TIME values with ADJUST statements, but it is not advised. After the user ADJUST statements are completed, the program recalculates the COST values using the Cost Function. (See Functions and built-ins on page 134 for a description of the built in functions, variables and arrays the program uses.

Cube Voyager Reference Guide 159

Highway Program Phases

The ADJUST phase runs an automatic LINKLOOP across all links on the input network. All control statements coded in this phase are executed once per link. If summary values are to be accumulated during the link loop, it is the users responsibility to properly initialize them at the beginning of the link loop. This can be done by testing for the value of Linkno: IF (Linkno=1)... (Hint: Iteration and LastIteration can also be tested by the user). Congestion is based upon the variable V, which is computed for each link. By default, V is the sum of all VOL[]s that appear on any PATHLOAD statements. This may not be exactly what is desired, so a FUNCTION V= statement can be used to override the default computation of V. The default Function for V should not be used if a standard assignment is being made along with a select link assignment; some volumes would be duplicated. In most cases, multiple iterations are performed, and the final volumes are obtained by combining the volumes from each iteration. The maximum number of iterations can be specified, but it is usually better to let the program determine when more iterations will not result in any assignment improvements. Various combination processes can be specified; the PARAMETERS COMBINE value is used to specify the method to be used: Equilibrium (the default) Average Weighted average Iterative Summation (often referred to as incremental)

Equilibrium assignment is performed within the ADJUST phase. If the term assignment is used to indicate the actual accumulation of trips on link volumes, the term equilibrium assignment is somewhat of a misnomer. Most users tend to think of equilibrium assignment as the process of determining a weight factor for an iteration, and then applying that factor to the current iteration volumes and a complementary factor to the previously weighted volumes to obtain new weighted volumes. If the network is well

160 Cube Voyager Reference Guide

Highway Program Phases

behaved, and the appropriate processes are included, eventually a state of equilibrium is reached. That state is reached when further adjustments in the link costs used for routing, will not produce significant differences in the system as a whole. In theory, equilibrium is reached when there is no ability for individual I-J path costs to improve, without causing degradation in other parts of the network. If a system has a significant degree of congestion, it may be difficult (practically impossible) to reach a true state of equilibrium. The basic measure of equilibrium is total system user cost, and in most situations, cost involves some measure of time. Time is generally the measurable quantity that can be directly related to congestion. Thus, most equilibrium formulations are based upon time. To determine the weight to apply to each iterations volume in the volume combining process, a factor (generally referred to as Lambda) is estimated for the iteration. Lambda is a factor between 0 and 1. It is impossible to solve directly for Lambda, so it is estimated using a linear approximation method. The user can select one of two Lambda search processes using the PARAMETERS COMBINE LAMBDASEARCH = AREA/EQUATION. Note that both processes estimate Lambda so the results might be slightly different. In most cases, the results will be quite similar, but the EQUATION method can save considerable computation and I/O time. If the AREA search process is used, the program minimizes the area under all the V vs. Cost curves computed for incremental estimates of lambda for every link. This process provides a Lambda calculation that is up to 6 digits in precision. If a standard function for computing TC is used, the estimation process could be considerably more efficient.

Cube Voyager Reference Guide 161

Highway Program Phases

If the EQUATION search process is used, the program solves the expression for only a limited number of Lambdas, using the following expression if the default BPR form is used for the TC functions or no TC functions are coded (default TC function is BPR form with default BPR constant and exponent): Y() = (VOLk Vk-1) * T0(1 + TCCOEFF * ((Vk-1 + * (VOLk - Vk-1))/C) ^ TCEXP) where:
VOLk Vk-1 T0 = the summation over the links in the input network = the AON volume assigned in iteration k to COSTk-1 paths based on Vk-1 = the equilibrium weighted volume from the prior iteration = the free flow time

TCCOEFF = value of the TC functions coefficient term defined on the PARAMETERS statement C TCEXP = the link capacity = value of the TC functions exponent term defined on the PARMETERS statement

If the user has specified his own alternate form for the TC functions using the new PARAMETERS TCCOEFF and TCEXP and requests the EQUATION search process then the program uses the following expression to solve for Lambda: Y() = (VOLk Vk-1) * TC(V,TCCOEFF,TCEXP) Where TC(V,TCCOEFF,TCEXP) is the TC functions evaluated for link volumes V, and the appropriate values of TCCOEFF and TCEXP, where V= Vk-1 + * (VOLk - Vk-1). The resulting curve is examined, and the Lambda which provides Y=0 is obtained by interpolation. This value is then used to weight the current volumes: Vk = * VOLk + (1- )*Vk-1.

162 Cube Voyager Reference Guide

Highway Program Phases

There are several iteration volume combination processes available; the PARAMETERS COMBINE= specifies the one to use. EQUI is the default. The available processes are:
Process EQUI AVE WTD ITE SUM Description Equilibrium assignment. Iteration volumes are factored by the equilibrium weights computed for each iteration. Average assignment simply keeps a running average of the volumes on each link. Weighted Average assignment is the same as Average, but the user can specify a specific weight for each iteration. Iterative assignment keeps only last iteration volumes are output; prior iteration volumes are not considered. Sum assignment is one in which the final volumes are the result of adding the volumes from each iteration. This is traditionally known as incremental loading.

Convergence tests

If the optional CONVERGE phase has not been specified then default convergence testing is performed at the end of the ADJUST phase to determine if more iterations are necessary.

Cube Voyager Reference Guide 163

Highway Program Phases

Convergence testing is not performed for Combine=Sum assignment. There are several tests that can be made to determine if more iterations are necessary. The items that are used in the tests are Keywords set with the PARAMETERS statement and include:
Keywords GAPk Description ABS(SUML(VEk*COSTEk) SUML(Vk-1*COSTEk-1))/ SUML(Vk-1*COSTEk-1) Where k is the current iteration and SUML denotes summation over the links and, if appropriate, the turning movements in the network, VEk is the equilibrium weighted volumes for iteration k and COSTEk is the cost based on the equilibrium volumes VEk. RGAPk (SUML(VEk-1*COSTEk-1) - SUML(VAk*COSTEk-1) )/ SUML(VEk-1*COSTEk-1) Where VAk is the link volume from an all or nothing assignment to the minimum cost paths based on COSTEk-1. AAD RAAD Pdiff RMSE MAXITERS Average absolute volume difference: based upon successive iterations Relative AAD: DiffV/V Percent of links whose change in V between iterations is less than a set value. Root mean squared error of the differences in V between iterations. Sets a fixed maximum number of iterations for convergence

The ADJUST phase process is as follows: Major Link loop: Linkno = 1, NumLinks (multiple passes if equilibrium is specified): Obtain link values (as in LINKREAD and LINKREAD stack, except TIME is not altered). If Iteration > 1, obtain prior combined iteration volumes (CVOL is prior V). Apply the appropriate TC and Cost Functions (based on LinkClass) to compute revised Time and Cost.

164 Cube Voyager Reference Guide

Highway Program Phases

If this is an Equilibrium pass, compute link contribution (Y) to Lambda estimations. Else if Iteration > 1, combine V with prior combined Vs Process LinkAdjust stack (if present), and recompute Cost. End Major Link Loop. Determine if this is to be the last iteration: If Iteration = MaxIters: LastIteration = 1, go to write Neto Test for Convergence if CONVERGE phase not specified (true if any of following conditions met minimum values are those set with the PARAMETERS statement): GAP RGAP AAD RAAD PDIFF RMSE < MinGap < MinRGAP < MinAAD < MinRAAD > MaxPdiff < MinRMSE

NOTE: Under the default convergence criteria, convergence is

considered to be achieved if ANY of the above PARAMETERS minimum values are obtained. Note that all of these PARAMETERS have default values so they do have minimum targets even though the user has not explicitly coded them. For example if you have specified PARAMETERS GAP=0.001 in order to stop further iterations beyond this value of GAP but have set no other controls, the assignment may stop after 10 iterations because the default value of MAXITERS=10 is reached before reaching a GAP<0.001. Or, the assignment may stop in less then 10 iterations and before GAP<0.001 because one of the other PARAMETERS has reached its default minimum. In order to insure that a specific GAP value is achieved (if that is your goal) you must set all of the other convergence PARAMETERS to zero. For example:

Cube Voyager Reference Guide 165

Highway Program Phases

PARAMETERS MAXITERS=99, GAP=0.001, RELATIVEGAP=0, AAD=0, RAAD=0, RMSE=0

Would continue performing iterations until GAP<=0.001 or 99 iterations were preformed. If you would like to specify alternate rules for when the program determines convergence is reached, this can now be achieved by using the CONVERGE phase. See CONVERGE phase for examples of specifying alternate convergence rules. If PHASE=CONVERGE is present, process the stack statements in the CONVERGE Phase until BALANCE=1 or MAXITERS is reached. If Convergence satisfied by BALANCE=1 (LastIteration set to Iteration, if true), or LastIteration: Write Neto.

CONVERGE phase
This phase, if specified, follows the ADJUST phase in each iteration. At the end of the ADJUST phase, the program checks if additional iterations are necessary. Convergence testing is not performed for Combine=Sum assignment or for Iteration=1. There are several tests that can be made to determine if more iterations are necessary. The default items that are used in the convergence tests are: GAPk ABS(SUML(VEk*COSTEk) SUML(Vk-1*COSTEk-1))/ SUML(Vk-1*COSTEk-1) Where k is the current iteration and SUML denotes summation over the links and, if appropriate, the turning movements in the network, VEk is the equilibrium weighted volumes for iteration k and COSTEk is the cost based on the equilibrium volumes VEk.

166 Cube Voyager Reference Guide

Highway Program Phases

RGAPk

(SUML(VEk-1*COSTEk-1) - SUML(VAk*COSTEk-1) )/ SUML(VEk-1*COSTEk-1) Where VAk is the link volume from an all or nothing assignment to the minimum cost paths based on COSTEk-1.

AAD RAAD Pdiff RMSE

Average absolute volume difference: based upon successive iterations Relative AAD: DiffVE/VE Percent of links whose change in VE between iterations is less than a set value. Root mean squared error of the differences in VE between iterations.

MAXITERS Sets a fixed maximum number of iterations for convergence There are different philosophies as to what measures are best to determine if convergence has been reached, or if further assignment iterations will improve the assignment depending on the assignment method used. Some networks may never be able to reach a true balance because there is too much congestion, or there is insufficient capacity in certain parts of the network. Things can not be completely smooth because a slight adjustment in a few links may cause a large shift in a slug of traffic. Sometimes, the test statistics will begin to oscillate near the desired test limit, and may never reach a desired result. The CONVERGE phase process is provided to allow the user to program his/her own method of setting convergence. The user can write script to determine if the desired measure has been met. When the results are satisfactory, the script should set the variable BALANCE to 1. That will indicate to the program that further iterations are not to be undertaken.

Cube Voyager Reference Guide 167

Highway Program Phases

Note that if PHASE=CONVERGE is detected within the script, the standard tests are not performed; termination will be determined by the value of BALANCE after the phase is completed. If BALANCE is never set to 1, the program will continue until MAXITERS is satisfied. BALANCE is automatically set to 0 when the phase begins. To help the user set BALANCE, various variables and functions are available.
Variables available for BALANCE
Variable GAP RGAP AAD RAAD PDIFF RMSE Description The GAP for the current iteration, Must be indexed GAP[] for previous iterations The RELATIVEGAP for the current iteration, Must be indexed for previous iterations The AAD for the current iteration, Must be indexed for previous iterations The RAAD for the current iteration, Must be indexed for previous iterations The PDIFF for the current iteration, Must be indexed for previous iterations The RMSE for the current iteration, Must be indexed for previous iterations A variable initialized to the value Parameters GAP, may be reset anytime A variable initialized to the value Parameters RELATIVEGAP, may be reset anytime A variable initialized to the value Parameters AAD, may be reset anytime A variable initialized to the value Parameters RAAD, may be reset anytime A variable initialized to the value Parameters PDIFF, may be reset anytime A variable initialized to the value Parameters RMSE, may be reset anytime

GAPCUTOFF RGAPCUTOFF AADCUTOFF RAADCUTOFF PDIFFCUTOFF RMSECUTOFF

168 Cube Voyager Reference Guide

Highway Program Phases

Functions available for BALANCE


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

RGAPCHANGE

AADCHANGE

RAADCHANGE

PDIFFCHANGE

RMSECHANGE

GAPMIN

GAPMAX

GAPAVE

GAPCHANGEMIN

GAPCHANGEMAX

GAPCHANGEAVE

Cube Voyager Reference Guide 169

Highway Program Phases

Functions available for BALANCE (continued)


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

RGAPMAX

RGAPAVE

RGAPCHANGEMIN

RGAPCHANGEMAX

RGAPCHANGEAVE

AADMIN

AADMAX

AADAVE

AADCHANGEMIN

AADCHANGEMAX

AADCHANGEAVE

170 Cube Voyager Reference Guide

Highway Program Phases

Functions available for BALANCE (continued)


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

RAADMAX

RAADAVE

RAADCHANGEMIN

RAADCHANGEMAX

RAADCHANGEAVE

PDIFFMIN

PDIFFMAX

PDIFFAVE

PDIFFCHANGEMIN

PDIFFCHANGEMAX

PDIFFCHANGEAVE

Cube Voyager Reference Guide 171

Highway Program Phases

Functions available for BALANCE (continued)


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

RMSEMAX

RMSEAVE

RMSECHANGEMIN

RMSECHANGEMAX

RMSECHANGEAVE

Example
PHASE=CONVERGE IF (ITERATION < 6) BREAK; Do not even test for Iterations 2-5 IF (GAP < GAPCUTOFF) BALANCE = 1 BREAK ENDIF IF (GAPCHANGEAVE(3) < 0.006 && GAPCHANGEMAX(3) < 0.009 && ABS(GAPCHANGEMIN) < 0.009) BALANCE = 1 ENDPHASE

Example
; This example implements the opposite of the default stopping criteria which is to stop if ANY of the convergence measures go below the values specified on the PARAMETERS statement. In this example the assignment would stop only when ALL criteria fall below their specified values. PHASE=CONVERGE IF (GAP<GAPCUTOFF & RGAP<RGAPCUTOFF & AAD<AADCUTOFF &

172 Cube Voyager Reference Guide

Highway Program Phases

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

Cube Voyager Reference Guide 173

Highway Program Control statements

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

174 Cube Voyager Reference Guide

Highway Program Control statements

Control statement SORT SPDCAP TURNS

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

ABORT
Aborts the entire run. MSG Use ABORT to terminate the program and return a fatal code to Cube Voyager. It normally is not used, but allows for termination due to some conditions that can be detected in the process. For example: if it is discovered that an LOS matrix is empty when it should have data, the run should be aborted.
ABORT keyword
Keyword Description |S| Optional message that can be printed when the program terminates.

MSG Example

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

ARRAY
Declares user single dimension arrays. VAR=size, VAR=size Use ARRAY to allocate user arrays that are to be used in the process. An array is different than a variable in that it represents vectored data. Values stored to arrays must be numeric. String values cannot currently be stored in an array. When an array is referenced, it should include an index [], and if the index exceeds the size, the program may fatally terminate. Arrays can be useful for different processes. ARRAY statements are not dynamic (stack oriented); they

Cube Voyager Reference Guide 175

Highway Program Control statements

are allocated prior to any stack operations. When an array variable appears in a SET statement, all the cells in the array are set to the same value.
ARRAY keyword
Keyword Description |I| Name of the variable that is to be allocated according to the specified size. VAR must be a unique name. The size following the keyword is the highest index possible for VAR. Size may be either a numeric constant, or a special name. Special names are: ZONES, NODES, LINKS (or NUMLINKS).

VAR

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

BREAK
Breaks out of a loop. Upon encountering BREAK, the script immediately passes control to the statement after the associated loop. If BREAK is within a LOOP ... ENDLOOP or JLOOP ... ENDJLOOP block, control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J is reset to 1). If BREAK is not within a LOOP or JLOOP block, the script terminates processing for the I zone but does not bypass output and zonal reporting statistics.
Example
LOOP L1=1,3 IF (condition) statements ELSE BREAK ENDIF

; jump to IF statement

176 Cube Voyager Reference Guide

Highway Program Control statements

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

COMP
Computes a variable, matrix, or matrix element from an expression.
VAR=expression MW[n]=expression, INCLUDE=list of J zones, EXCLUDE=list of J zones

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

Cube Voyager Reference Guide 177

Highway Program Control statements

COMP keywords (continued)


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

178 Cube Voyager Reference Guide

Highway Program Control statements

COMP keywords (continued)


Keyword VAR Subkeyword |KN| Description Name of a variable where the result of expression is to be stored. The name may be as long as desired (within reason). The expression is solved one time for each encounter, with J being either one (not in JLOOP), or the value of the JLOOP J. If expression results in a character string, the variable must be a character string variable. All variables are assumed to be numeric variables, unless their first appearance as a result in a COMP statement is with an expression that results in a character string. Examples: abc = '123' def = 123 abc = def ; invalid: abc has been declared a string abc = abc + '456' ; valid abc = abc + def ; messy -- dont mix jkl = 1 jkl = xyz xyz = 'xyz' ; jkl is declared numeric ; invalid: xyz is declared a string (later) ; xyz is declared a string

If a COMP statement includes any INCLUDE or EXCLUDE filters, the filters apply to all MW[]= values, and special matrix functions on the statement, no matter where they appear on the statement. EXCLUDE is processed after INCLUDE. INCLUDE and EXCLUDE may not be specified within a JLOOP.
Special matrix variables MW[] MI.n.name MI.n.matnum

Cube Voyager Reference Guide 179

Highway Program Control statements

The expression is a standard Cube Voyager numeric expression, but there are some special variables that may be used within it:
Matrix variables
Variable MW[Rexpression] Description Value from any work matrix; the column index (not explicitly expressed) will be supplied as J. Rexpression may contain nested MW[]; be careful! MW[Rexpression][Cexpression] is the value from any work matrix for zone Cexpression. Value from the MATI[n].name matrix; the column index (not explicitly expressed) will be supplied as J. The row index [n], must be a constant. MI.n.name[Cexpression] is a variation; the column index is computed. Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). If matrix names have spaces, then you must include the entire MI matrix reference in double quotes to recognize the name. For example:
MW[1]="MI.1HBW TRIPS"

MI.n.name

MI.n.matnum

Value from the MI[n].matnum matrix; the column index (not explicitly expressed) will be supplied as J. The row index [n] and the matnum must be constants. MI.n.matnum[Cexpression] is a variation; the column index is computed. Value from the ZDATI[n].name matrix; the zone index (not explicitly expressed) will be supplied as I. ZI.n.name[Cexpression] is a variation; the zone index is computed.

ZI.n.name

Special matrix functions

ROWSUM ROWCNT ROWMIN ROWMAX ROWAVE ROWFIX ROWFAC LOWEST LOWCNT ROWADD ROWMPY ROWDIV In addition to the standard numeric expression functions (abs, exp, int, ln, log, max, min, round, sqrt see Chapter 3, General Syntax, for more details), some special purpose functions are available. The matrix-oriented functions process all cells in a matrix (subject to the restrictions of any INCLUDE and EXCLUDE lists), and should not be used within JLOOP blocks and MW[]= expressions. Normally, they should be used only as VAR = ROWFUNC(#).

180 Cube Voyager Reference Guide

Highway Program Control statements

Most of these functions could be duplicated with a combination of MW[]= statements. The function format has two advantages: coding is much easier, and processing is more efficient. Combining functions on a single statement is permissible; they will be processed in appropriate order. Example: DUMMY = ROWFAC(3,1.5) + ROWFIX(3) will factor matrix 3 and then convert it to integer. In the following matrix function descriptions, the first argument (mw) indicates the work matrix to process, and must be specified. If lo,hi is allowed, and lo is supplied, and hi is not, hi will be set to lo. Lo and hi are inclusive values. If an invalid argument is detected by a function, the function will return a zero, without any diagnostics.
Matrix functions
Function LOWCNT Description The actual number of cells that was used in the summary is stored in the variable LOWCNT. Warning: Dividing by LOWCNT if it is 0, will cause a program error message (too many will be fatal). Sum of lowest n cells. Sum of lowest n cells, including only cells with values greater than or equal to lo, and less than or equal to hi. Sum of lowest n cells, including only cells with values greater than or equal to lo, and less than or equal to hi, and exclude the values for J=z,z,... LOWEST is quite useful for computing an intrazonal value based upon the proximity to the nearest zones. The range of arguments is to provide for most types of situations. With lo and hi, it is possible to exclude possible dummy zones that may appear as zero in the row. With z, specific zones can be excluded; normally, the intrazonal cell (I) would be excluded. This exclusion is in addition to any that may be on an EXCLUDE list. NOTE: Zeros are treated as regular numbers in LOWEST function. Since all MWs are initialized to zeros, caution should be exercised when applying LOWEST function with no range specified. ROWADD(d,s1...sn) Add matrix mw[1] + mw[sn] into mw[d] Same as:
MW[d] = MW[s1] + MW[s2] + MW[sn]

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

Cube Voyager Reference Guide 181

Highway Program Control statements

Matrix functions (continued)


Function ROWAVE(mw) ROWAVE(mw,lo,hi) ROWCNT(mw) ROWCNT(mw,lo,hi) ROWDIV(d,s) Description Average cell value, including only cells with values not equal to 0. Average cell value, but include only cells with values greater than or equal to lo, and less than or equal to hi. Number of cells with values not equal to 0 Number of cells with values greater than or equal to lo, and less than or equal to hi; can include 0. Divide MW[d] by MW[s] making all divided-by-zero cells equal to 0. Same as:
JLOOP IF (MW[s] == 0) MW[d] = 0 ELSE MW[d] = MW[d] / MW[s] ENDIF ENDJLOOP

ROWFAC(mw,fac) ROWFIX(mw) ROWFIX(mw,n) ROWFIX(mw,n,rnd)

Factors the row by fac. Same as MW[mw] = MW[mw] * fac Convert mw to integer values (start at column intrazonal + 1, with rounding factor = 0). Convert mw to integer values (start at column n, with rounding factor = 0). Convert mw to integer values (start at column n, using specified rounding factor). ROWFIX converts the values in each cell of the matrix to integers (that is, drops all fractional portions of the number) in such a manner to ensure the integer total is consistent with the original total. It converts each cell to an integer value after adding the rounding factor and the accumulated fractional portions from the previously treated cells. With a rounding factor of 0 each cell is truncated and its fractional remainder is carried to the next cell. With a rounding factor of 0.5, each cell is rounded to the nearest integer and the difference (original rounded) is carried to the next cell.

182 Cube Voyager Reference Guide

Highway Program Control statements

Matrix functions (continued)


Function Description If the process always began at zone 1, the lowest numbered zones would never get their fair share of the fractions. To eliminate this bias, the default condition is to start at the cell after the intrazonal cell and wrap around until the intrazonal cell is the last cell processed. The optional second argument specifies which cell the process is to end with. ROWMAX(mw) ROWMIN(mw) ROWMPY(d,s) Maximum value in the row. Minimum value in the row. Multiply MW[d] by MW[s] Same as:
MW[d] = MW[d] * MW[s]

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

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

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

Example 2
MW[2]=J MW[K]=MW[2] * MW[5]) / SQRT(A*MW[3][MW[22]]) A=1, B=2, MW[A]=A+B INCLUDE=1-5,8,47-93 MW[3]=5*A, MW[4]=MW[3]*2, MW[K][I%10+1]=ODD, INCLUDE=1-100,401-500, EXCLUDE=90,93,452 ; applies to the MW[]s= ABC=LOOKUP(DEF)*3 /* move input matrices to work areas */ MW[11]=MI.1.1, MW[12]=MI.1.2, MW[13]=MI.1.3 MW[21]=MI.2.1, MW[22]=MI.2.2, MW[23]=MI.1.3

CONTINUE
Jumps to the end of a loop, bypassing all intermediate statements.

Cube Voyager Reference Guide 183

Highway Program Control statements

If CONTINUE is within a LOOP ... ENDLOOP or JLOOP ... ENDJLOOP block, control passes to the appropriate ENDLOOP or ENDJLOOP statement. Otherwise, processing for the I zone is terminated, but output statistics will not be bypassed.
Example
LOOP L1=1,3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE ; no more processing for this origin zone LOOP L2=K1,K2,KINC LOOP L3=L2,L2+5 IF (condition) CONTINUE ; jump to ENDLOOP for L3 ENDLOOP ENDLOOP

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

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

and for important limitations when using Application Manager. Input data files MATI NETI SUBAREANETI TURNPENI (MISSINGLINK LIST)

184 Cube Voyager Reference Guide

Highway Program Control statements

ZDATI (Z SELECT NAME (DEFAULT) AVE AVEX0 CNT FIRST LAST MAX MIN SUM) JUNCTIONI (PERIOD N SET) LOOKUPI TOLLMATI (ENTRYGATE EXITGATE TOLLS NETIENTRY NETIEXIT NETITOLLROAD TOLLFACTOR TOLLROUND) Matrix data is read dynamically (at the start of each I loop), and must be in origin zone (I) order, whereas zonal data is read prior to the initiation of the I loop, and need not be in any specified order. Data from MATI and ZDATI files are accessed via stack statements, and are identified as MI.n.name and ZI.n.name. The n designates subscript of the file, name designates the matrix name or number. Cube Voyager matrices can have names and/or numbers, other matrices have only numbers, and zonal data files have names only. Example: MI.1.3 indicates matrix number 3 on the MATI[1] file. ZI.6.POP indicates the POP variable from ZDATI[6] file. Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). If matrix names have spaces, then you must include the entire MI matrix reference in double quotes to recognize the name. For example:
MW[1]="MI.1HBW TRIPS"

On the FILEI statement the subscript is either explicitly, or implicitly, specified. MATI=... defaults to MATI[1], and MATI[3]=name3,name4,name5 sets up MATI[3], MATI[4], and MATI[5]. Since it is required that ZDATI files have variables explicitly defined for them, the vector form of ZDATI (ZDATI=file1, file2...) will be treated as an error. When an input file is used in an expression, it may have an additional subscript appended to it to specify a zone number. For matrices, the subscript references the column within a row, and for zonal data, it references the nth item in the vector. Zonal data can be viewed as having zones rows with one column per zone, or as one row having zones columns (users choice, it doesnt matter). If there is no subscript specified, the current value of J is used. J will

Cube Voyager Reference Guide 185

Highway Program Control statements

always be in the range 1-zones. Example: MI.6.3[I] accesses the intrazonal cell. ZI.1.TRMTIME[I] and ZI.1.TRMTIME[J] reference the origin and destination terminal times, respectively.
TURNPENI designates a file that contains intersection movement

functions and penalties. This file may be read and kept in memory for use during any path development processes (specified with PATH on PATHLOAD statements). Even if the file is designated on a FILEI statement, the penalties will not automatically be applied during path development; the user must specify which penalties are to be applied on each PATH selection. The file has two sections: functions and movements. The function section is optional, but allows the user to specify that a penalty is to be computed from an expression. If a function contains a C variable (movement capacity), the penalty will be revised between iterations in the ADJUST phase. Each record in the movement section designates a specific movement (a-b-c), a set identifier for the movement, and the penalty to be assessed. For example,
a b c -------11 23 15 1 12 13 15 58 36 set # -----1 3 8 turnpen ---------1 2 FUNC1(500)

(Prohibitor) (Constant) (Function)

The penalty may be a prohibition, a fixed unit penalty, or a reference to a function in the function section. A prohibition is designated as the constant -1. It is the users responsibility to make sure that the penalty values are in the proper scale and units as the paths to which they are being applied. Turn functions are designated as numeric expressions that may contain constants and the variables: T, C, PrevPen. T is the turn volume at the intersection (it may alternatively be named TURN); C is the capacity of the movement, and PrevPen is the penalty that was used in the previous iteration. T is vectored (that is, it may contain an index []). T is the total volume for the movement; it is 0 at the first iteration, but is the result of the T=expression on the

186 Cube Voyager Reference Guide

Highway Program Control statements

TURNS statement after the first iteration. If there is no TURNS

statement, T will automatically be the sum of all loadings. T[1] would indicate the turning volume associated with any PATHLOAD VOL[1] statements. T[0] and T are the same variable. If a T is specified with an index for which there is no PATHLOAD VOL[index], the value of T[] in the expressions will be 0. Care must be taken if a fixed penalty is to be established for the first iteration, and then dynamic values are to be used after the first iteration. This is usually done by using the MAX function in the expression. For example: Func1=MAX(2.00,T/C*5.00). In this example, since T would be 0 on the first iteration, the initial penalty would be 2, and it would vary after the first iteration. If the 2 unit penalty was to remain in effect for all iterations, and be increased according to the T/C ratio, the expression would be: Func1=2+ T/C *5. C is obtained from the record in the movement section as an argument of the function. To apply the above Func1 (2+T/C*5), with C=500, the movement record would be coded as: 100 200 201 0 Func1(500). This designates that the movement 100-200-201 is to be penalized 2 units on the first iteration and then the penalty will be increased according to a T/C ratio (with C being 500) after the first iteration. If there were no C affixed to the Func1 on the movement record, the C would be considered as 0 in the computations. (Warning: Be careful not to create divided-by-zero errors when applying functions with C=0.) TURNPENI function records are structured as: FuncName=expression. The name is what the user desires, and the expression is any valid numeric expression that may contain numbers, standard functions, T, C, PrevPen. TURNPENI movement records are structured as: A B C Set Penalty (one set per record). The records are white space delimited (space, comma). A is the entry node to the intersection, B is the intersection node, and C is the exit node. Set is a number in the range of 0-8. If the set number is 0, it is applied any time that penalties are in effect, no matter what the designated sets are. There may be up to 9 records (sets 0-8) for the same movement. During path building, when the movement is detected and PENI= is

Cube Voyager Reference Guide 187

Highway Program Control statements

specified in the PATHLOAD statement, the penalty process will automatically apply set 0, if there is a set 0 for the movement. If there is no set 0, the penalty is assumed to be 0. Then it will check all the other possible sets for the movements; it there are additional sets, the penalty for the highest set number that matches the highest PENI designation for the PATH process will be used. NOTE that any movements that have functions specified will cause the B node to be included as a node for which TURNS are to be kept, and will be reported on the TURNVOLO file. JUNCTIONI designates a file containing descriptions of junction models. The format of the file is discussed in Chapter 7, Intersection Modeling. N specifies a list of nodes where the intersection modeling is to be invoked during the ADJUST phase. However, invoking intersection modeling for a node where there is no model description has no effect. PERIOD is the model period in minutes. It is used to convert the assigned volumes into units of per hour, and it is one of parameters of the queuing delay equation. Executing a junction model produces turning delays that may be applied during the next iteration of capacity restraint. This form of output is similar to a set of turn penalties, and the turn penalty set numbering system applies. The SET keyword designate the turn penalty set to contain the model results. Turn penalty records may be applied with higher or lower priority (that is, set number) than the calculated delays.
FILEI keywords
Keyword JUNCTIONI JUNCTIONI N Subkeyword |KF| |IP| Description Specifies the input junction file. Specifies the nodes where intersection modeling is to be invoked. A junction model that is not invoked has no effect. Invoking intersection modeling where there is no junction described has no effect. Only those nodes that both have a model description and are listed in this list are actually modeled. Duration of the model period in minutes. The input demand matrix should be in units of vehicles (or PCU) per model period.

JUNCTIONI

PERIOD

|R|

188 Cube Voyager Reference Guide

Highway Program Control statements

FILEI keywords (continued)


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

SUBAREANETI

|KF|

If these values are altered from those that Viper or Cube Base wrote, the results will be unpredictable.

Cube Voyager Reference Guide 189

Highway Program Control statements

FILEI keywords (continued)


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

TOLLMATI

EXITGATE

|S|

TOLLMATI

NETIENTRY

|S|

TOLLMATI

NETIEXIT

|S|

190 Cube Voyager Reference Guide

Highway Program Control statements

FILEI keywords (continued)


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

TOLLMATI

TOLLFACTOR

|R10|

TOLLMATI

TOLLROUND

|R|

TOLLMATI

TOLLS

|S10|

TURNPENI TURNPENI LIST

|KF| |?|

Cube Voyager Reference Guide 191

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

Highway Program Control statements

FILEI keywords (continued)


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

Cube Voyager Reference Guide 193

Highway Program Control statements

FILEI keywords (continued)


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

ZDATI ZDATI ZDATI ZDATI ZDATI

FIRST1 LAST1 MAX1 MIN1 NAME

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

194 Cube Voyager Reference Guide

Highway Program Control statements

FILEI keywords (continued)


Keyword ZDATI Subkeyword SELECT |S3| Description Used to cause selective reading of zonal data records from ASCII files. The program will compare a field from each record with the string specified in SELECT[1], and if the comparison fails, the record is bypassed. This selection is not used if SELECT is not specified. The second SELECT value specifies the field to be compared with. If the value is a number, it designates the beginning column of the comparison field on the input record, and an optional third value can be specified to designate the ending column. The second and third values must both be numeric and should be separated by a dash. If the second field is not numeric, but ends with a number (Example: #1), it is assumed that the value indicates a relative field number on the data record; that field is the comparison string. The third value is ignored if the second value is a free field definition. Sum of all the records. Identifies where the zone number identifier is found on each data record; Z MUST be specified, even if the file is a dbf. Z is a special case for name= (below).

ZDATI ZDATI

SUM1 Z

|SV| |S|

1. Indicates a process to use in obtaining the value for the variables that are listed following the keyword. The values for the variables will be obtained only from file records that contain the variable. A variable may appear in only one keyword list; any variables that are not in any list will be set to LAST.

Caveat: The program establishes a buffer to read file records into. It has to know how long a buffer is required. With DBFs and fixed format records, the required length is known, but with delimited format, the required length can not be estimated exactly. For delimited files, the record length is estimated by multiplying the highest field number by 10. If the estimated length is inadequate, a dummy variable with a high field number can be specified to generate a larger record length.
Example
NETI=network.net ; TPP binary network file MATI=test11.dat, test12.dat ; MINUTP binary matrix files

Cube Voyager Reference Guide 195

Highway Program Control statements

MATI[4]=tppltrips.mat ; TPP or MINUTP matrix file TURNPENI=time.pen, MISSINGLINK=1 ZDATI[1]=housing.txt, Z=#1,DU1=#2,DUPLEX=3,MULTI_FAMILY=4, CONDO=5,RETIREMENT=6 ZDAT[4]=pop.txt,Z=1-5,poptotal=6-15,popmale=16-25,popfemale=26-35, popyouth=36-45,pop19-65=46-55,popsr=56-65, poptotal=sum, popmale=cnt

FILEO
Specifies files that the Highway program outputs. ESTMDATO NAME ESTMICPO (CONFVAR COUNTVAR DEFAULTCONF SCREENLINE VAR) JUNCTIONO MATO (FORMAT MO NAME DEC COMBINE) NETO (INCLUDE EXCLUDE APPEND DEC) PATHO (COSTDEC ITERS) PRINTO (APPEND) SUBAREAMATO (FORMAT DEC NAME) TURNPENO TURNVOLO (FORMAT (DELIMITER) DEC INCLUDE0 VARS NAMES) Use FILEO to specify the number and types of files that are to be written by the program. Requested matrices are written for every origin zone for every iteration, but are combined into a single combined matrix at the end of the application. A single network with appended volumes and associated variables is written at the end of the application. A turning volume file must be requested if a TURNS statement is used. There MUST be a NETO specified if assignment is to be made; there would be no use in running the program if there was no way to obtain the results. By default the NETO file will contain all the input variables from NETI plus the variables V, VT, VC, TIME, CSPD

196 Cube Voyager Reference Guide

Highway Program Control statements

(congested speed), VDT (vehicle distance traveled), VHT (vehicle hours traveled) and a Vn, and VnT for every VOL[n] specified on any PATHLOAD statements. VT and VnT are the non-directional (twoway) counterparts of V and Vn. (Non-directional volumes can be turned off using NETO EXCLUDE=T_.) These appended variables will have an assignment number appended to their names. If there were no prior assignment result variables appended to the link records, the assignment number will be 1. Thus, the first assignment variables will be named V_1, VT_1, VC_1, TIME_1, V1_1, V1T_1 etc. If the NETI file contains any variable whose name ends in _#, the NETO appended variables will have an appended number that is one greater than the highest _# from NETI. If the NETO file is being written to a Cube geodatabase network in an MDB file, the source geometry for links in the output network will come from the geometry of the input network. If the input network is a binary network, then the output NETO file will have no associated geometry and will be displayed as straight-line links when opened in the Cube GIS window.
FILEO keywords
Keyword ESTMDATO ESTMDATO NAME Subkeyword |F| |SV| Description Specifies the file name for the output screenline data file (*.DAT) that is required by Cube Analyst. Specifies the names for the screenlines in the ESTMDATO file. There need not be a name for each screenline, but it is suggested that they be included to help in documentation of the file. A default name of SL A-B will be supplied by Cube Voyager if no NAME is provided for a screenline. Specifies the file name for the output intercept file (*.ICP) that is required by Cube Analyst. Specifies the link array that contains the count confidence values. The value may be an lw.array or li.array. Alternate to using VAR. Specifies the link array that contains the counts. Links that have values in this array will be trapped for inclusion in the matrix estimation. The value may be an lw.array or an li.array. If using COUNTVAR, then do specify VAR.

ESTMICPO ESTMICPO ESTMICPO CONFVAR COUNTVAR

|F| |S20| |S20|

Cube Voyager Reference Guide 197

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

ESTMICPO

VAR

|S20|

198 Cube Voyager Reference Guide

Highway Program Control statements

FILEO keywords (continued)


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

MATO

FORMAT

|S|

MATO

NAME

|SV|

Cube Voyager Reference Guide 199

Highway Program Control statements

FILEO keywords (continued)


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

NETO

APPEND

|I|

NETO NETO

DEC EXCLUDE

|I| |S20|

NETO

INCLUDE

|S20|

PATHO PATHO COSTDEC

|F10| |I|

200 Cube Voyager Reference Guide

Highway Program Control statements

FILEO keywords (continued)


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

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

PRINTO SUBAREAMATO

APPEND

|?| |KF|

SUBAREAMATO

DEC

|SV20|

SUBAREAMATO

FORMAT

|C|

SUBAREAMATO

NAME

|SV20|

Cube Voyager Reference Guide 201

Highway Program Control statements

FILEO keywords (continued)


Keyword TURNPENO Subkeyword |F| Description Specifies the file name where the movement delays from the junction model and/or the turn penalties from the turn penalty file will be written. In order to get the final travel time and cost skims from an assigned network it is necessary to pass the loaded network back through the Highway program and build and skim the paths from the loaded network. The TURNPENO file allows the movement delays computed by the Junction Model to be included in the path skims by using the TURNPENO file from the assignment as the TURNPENI file for the skims. The data structure is the same as that of the TURNPENI file but a comment field is added to indicate the movement is delay is from the junction model in lieu of a turn penalty or restriction. An example of the output is show below.
2606 2635 2635 2635 2635 2621 2621 2621 2621 2621 2773 2606 2615 2615 2773 1 1 1 2 1 0.08 ;junct 0.15 ;junct 0.15 ;junct -1.00 0.15 ;junct

TURNVOLO

|F|

Specifies the filename where the turning volumes are to be written. There may be more than one TURNVOLO specified; each may have a different format. Users must also specify TURNS to instruct program to accumulate turning volumes, otherwise, the TURNVOLO will be empty. The default format for this file is binary so that Cube can display it directly. Please note that the presence of the VARS keyword may alter the overall application of this statement. See Example using TURNVOLO on page 205. Specifies the number of decimal places to preserve when the file is either DBF of TXT. Character that is written in a TXT file. If this keyword is specified, the file will be delimited with this character. If it is not specified, the file will be fixed-field format. If the value is a character, it should be enclosed within quotes; but it may also be specified as a number that represents the desired character (for example, 9=TAB).

TURNVOLO TURNVOLO

DEC DELIMITER

|I| |c|

202 Cube Voyager Reference Guide

Highway Program Control statements

FILEO keywords (continued)


Keyword TURNVOLO Subkeyword FORMAT |S| Description Specifies the format for the file (must be BIN, DBF, or TXT). NOTE: FORMAT=BIN will automatically be reset to TXT if VARS= is specified on the statement. BIN Binary format that is usable only by Cube. The structure is: One header record (at least 64 bytes long): 0-1 total length of this record (bytes) 2-3 length of each turn record 3-6 bits whose position represents the presence of a turn volume 0: 1: 2: 1 always on for T0 1 if T[1] in the data records, 0 if not in data record 1 if T[2] present, o if not

3-31 same for T[3]... 7-64 Cube Voyager TURNVOL pppp.nnnn HIGHWAY date... pppp is the Cube Voyager project prefix nnnn is the Cube Voyager sequence number Individual records (length set in header): 0-1 Anode 2-3 Bnode 3-4 Exit Node 5-12 T[total] All Ts are double precision 13-201st T (T1) 21-282nd T DBF A standard DBF file will be written with each record containing the Anode, Bnode, ExitNode, T[0], and any appropriate T# values. The DBF header will name the variables that are in the data records.

Cube Voyager Reference Guide 203

Highway Program Control statements

FILEO keywords (continued)


Keyword TURNVOLO Subkeyword FORMAT (continued) Description TXT ASCII format either in fixed format or delimited. There is no header for this file; the structure of each record is: Anode, Bnode, ExitNode, T,T# (The user has to know which individual Ts are written to the file). The T values will be determined either by the DEC keyword, or internally by the program. Each volume will be formatted appropriately. If DELIMITER is specified, the fields will be written with only the delimiter separating them. If no DELIMITER, the fields will be in fixed width format; the program will determine the size. Note that VARS= will cause this format to change. TURNVOLO INCLUDE0 |?| Flag that when set false indicates that a turn movement with T values all equal to 0, is to not be written to the file. The default value is true. May be used if both VARS= and FORMAT=DBF are specified. The names are aligned with the VARS fields and then placed into the created dbf file. Optionally, the NAMES may be indexed [] to set the alignment for renaming only specific variables. Specifies which variables are to be written to the file. Note that if VARS is specified, FORMAT=BIN will be reset to FORMAT=TXT, or if there is no FORMAT specified, that it will default to TXT. Any of the following variables may be specified (in any order, and may even be repeated): A B C T T1 T2Tn, where n is the highest VOL in the application. Optionally, the variable name may have a standard PRINT form appended to it (enclosed within parenthesis). If decimals are to be printed with the values, it is suggested that an appended format be specified instead of DEC=. If a delimiter is desired, FORMAT=TXT, DELIMITER= must be specified.

TURNVOLO

NAMES

|S25|

TURNVOLO

VARS

|S25|

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

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

204 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD statement that does not have VOL[]= on it. PATHLOAD must have the keyword PATHO=# in order to output the path file specified with FILEO PATHO= Example using TURNVOLO
MATO=TPPTEST.MAT, MO=1-2, DEC=2*2 NAME=SLINK1,TOLL1,COMBINE=Y MATO[3]=DEMO12.DAT, FORMAT=MINUTP, MO=1,3,5-7 NETO=ALTERNATE.NET, EXCLUDE=_#1, _#2 TURNVOLO=AlternateA.Trn.Bin, format=BIN TURNVOLO=AlternateA.Trn.DBF, format=DBF, DEC=0 TURNVOLO=AlternateA.Trn.TXT, format=TXT, DELIMITER=',', DEC=0 TURNVOLO=AlternateA.Trn.TXT, VARS=b(5) a(6) c(6) t(10.2) t1(10.2) t2(8.2) TURNVOLO=AlternateA.Trn.TXT, format=dbf, vars=a(5),b(5),c(5),t(8.2), t1(8.2),t2(8.2), names= Enter thru exit Total Cars Trucks

Example
MATO=TPPTEST.MAT, MO=1-2, DEC=2*2 NAME=SLINK1,TOLL1,COMBINE=Y MATO[3]=DEMO12.DAT, FORMAT=MINUTP, MO=1,3,5-7 NETO=ALTERNATE.NET, EXCLUDE=_#1, _#2 TURNVOLO=AlternateA.Trn.Bin, format=BIN TURNVOLO=AlternateA.Trn.DBF, format=DBF, DEC=0 TURNVOLO=AlternateA.Trn.TXT, format=TXT, DELIMITER=',', DEC=0 ESTMICPO=ESTMO.ICP, VAR=LI.COUNT, SCREENLINE=LW.SCREENLINE ESTMDATO=ESTMO.DAT, NAME='SL#1','SL#2','SL#3', NAME[5]='SL#5'

Example
/* Commands to generate a path file. */ FILEO PATHO[1]=myfile.pth, costdec=2, iters=0 . . . PATHLOAD PATH=TIME, PATHO=1, INCLUDECOST=F, NAME=TIME_PATH, ALLJ=T

FILET
Specifies where the Highway program writes various temporary files.

Cube Voyager Reference Guide 205

Highway Program Control statements

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

PATH

The value for PATH is entered as a standard operating system path. If not specified, it will default to the path in the environment variable named TMP, or TEMP. The logic for determining the appropriate path, and opening the files is: If the PATH=' ', use current directory. If the PATH is specified, use it. If not specified, and TMP is, use TMP. If the operation fails, Fatal.

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

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

FUNCTION
Defines special functions. V TC COST Use FUNCTION statements to enter single expressions for computing certain values. The statements are inoperable by themselves, and can be anywhere in the input stream, the program dictates when they will be processed. It is recommended that they

206 Cube Voyager Reference Guide

Highway Program Control statements

be placed prior to the first PHASE statement or within the major phase in which they will be processed. If there is no function for a type, a default function will be used. The V function may be defined one time only. Each of the other functions is entered with an index [] to indicate which LinkClass it is to be applied to. All the functions can be on one FUNCTION statement, or they can be on individual statements, or some combination of both. To reduce confusion, some users may wish to code the functions on a single FUNCTION statement with a block control.
FUNCTION keywords
Keyword COST |NV999| Description Computes the cost for a link. COST is processed in LINKREAD and ADJUST to compute the cost. In LINKREAD, it is applied after the stack statements. In ADJUST, it is applied during capacity restraint, usually following a TC application, and after the user stack statements are completed. This is the only way to alter the cost values. Computes the congested time on a link by LINKCLASS. TC functions are the labels in the software given to volume delay functions (commonly referred to as VDFs). TC stands for congested time. The LINKREAD Phase of this program allows the user to associate every link in the network with an internal LINKCLASS variable. The TC functions can be indexed by LINKCLASS to specify different volume delay relationships for different classes of facility. If no LINKCLASS is defined for a link it defaults to LINKCLASS=1. If no TC functions are defined then a default TC function is applied. The default TC function is the standard BPR with the form: TC[1] = T0 *(1 + TCCOEFF * (V/C) ^ TCEXP) where TCCOEFF defaults to 0.15 and TCEXP defaults to 4 if values are not specified with PARAMETERS. Specifying TC[1] alters the function. The user can also code their own functional form if the BPR form is not what is desired. In general, TC[#]=f(T0, V/C, TCCOEFF, TCEXP) but the user is free to experiment with any forms that make sense to them for their application.

TC

|NV999|

Cube Voyager Reference Guide 207

Highway Program Control statements

FUNCTION keywords (continued)


Keyword V |N| Description Computes the total volume on a link after an iteration. It is applied in the ADJUST phase. If there is no V function, V is assumed to be the sum of all the VOL sets (V[1] + V[2] + ... + V[n]). Some times the total volume should not be the sum of all the VOLs. For example: if a separate select link VOL set is being accumulated in addition to the total VOL set, that VOL set should be excluded from the total volume. Another example would be if one of the VOL sets is for a vehicle type for which it is desired to equate to a passenger car equivalent.

Example
FUNCTION { V = VOL[1] + VOL[3] + VOL[10]*1.3 TC[1] = T0 * (1 + 0.20 * (V/C) ^ 6) TC[201] = MIN(T0*5, T0 * (1.5 + 0.18 * (V/C) ^ 4)) COST[255] = TIME * 2 }

GOTO
Jumps immediately to a named statement.
GOTO label

When GOTO is processed, flow immediately branches to the target statement, named :label. Each GOTO statement must have an associated :label statement. Use care when the :label statement is within a different IF or LOOP block. The target statement must begin with a semicolon (:).
NOTE: GOTO is not valid in the SETUP phase. You cannot place a :label statement inside a JLOOP statement. However, you can use a GOTO statement inside a JLOOP to jump to a :label statement outside the JLOOP. Example
GOTO buildhwy GOTO :buildhwy

208 Cube Voyager Reference Guide

Highway Program Control statements

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

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


Performs certain operations based on conditions.
IF expression ELSEIF expression ELSE expression ENDIF

Use IF/ENDIF blocks to determine if certain operations are to be performed. IF blocks may be nested, but they may not overlap LOOP, JLOOP, or other IF blocks. If a variable in the expression is MI.n.name, ZI.n.name, or MW[], the same rules for indexing in a COMP statement are applied. MI.n.name or MW[] should realistically only be used within a JLOOP. Lengthy IF expression solutions could be time consuming; use them judiciously. Although IF expressions can be quite powerful for zonal selection, sometimes INCLUDE and EXCLUDE filters may provide a much more efficient selection process (see the examples below). You may append the following control statements to a single IF statement:
BREAK COMP CONTINUE EXIT GOTO PRINT

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

Cube Voyager Reference Guide 209

Highway Program Control statements

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

JLOOP ... ENDJLOOP


Controls a loop through the columns of a matrix row. Each row represents an origin zone and each column represents a destination zone. Typically, you use JLOOP ... ENDJLOOP blocks for matrix computations that you cannot complete with a single COMP MW control statement.
JLOOP blocks may not be nested, and may not overlap other JLOOP, LOOP, or IF blocks. JLOOP keywords
Keyword J |I| Description Optional. List of up to three integers that define the value of the loop control variable. You may define each integer with an expression. Specify as:
J=Jbeg, Jend, Jinc

where: Jbeg defines the initial value of the loops control variable, J. Default value is 1. If you do not define Jbeg, you cannot define Jend or Jinc. In that case, Jend defaults to the number of zones in the network, and Jinc defaults to 1. Jend defines the terminal value of the loops control variable, J. Valid values range from 1 to the networks maximum number of zones. If not specified, Jend defaults to Jbeg, and Jinc defaults to 1. Jinc defines the increment for the loops control variable, J. If not specified, set to 1 or -1, depending on the direction from Jbeg to Jend.

Because the list of values for J can be expressions, you must separate the values with commas. Enclose expressions containing commas in parentheses. INCLUDE |I| Optional. List of origin zones that the program will process. If you include this keyword, the program will only process statements for these zones.

210 Cube Voyager Reference Guide

Highway Program Control statements

JLOOP keywords (continued)


Keyword EXCLUDE |I| Description Optional. List of origin zones that the program will not process. If you include this keyword, the program will not process statements for these zones, and instead skip to the next zone.

A JLOOP block causes the program to loop between the JLOOP statement and its ENDJLOOP statement, moving J from Jbeg to Jend in increments of Jinc. The logic for JLOOP and ENDJLOOP processing is: At JLOOP: If J is specified, establish values for Jend and Jinc, else set J=1, Jend=Zones, Jinc=1. If (J < 1 or J > Zones or Jend <1 or Jend > Zones), terminate fatally. If (statement contains INCLUDE keyword and J is not listed among INCLUDE keyword values) go to ENDJLOOP. If (statement contains EXCLUDE keyword and J is among listed EXCLUDE keyword values) go to ENDJLOOP. Process statements within JLOOP. At ENDJLOOP: Add Jinc to J. If (Jinc > 0 and J <= Jend) go to statement following JLOOP. If (Jinc < 0 and J >= Jend) go to statement following JLOOP. Control passes to statement following ENDJLOOP. The program processes all statements between the JLOOP and ENDJLOOP statements, including COMP MW statements, with the current value of J. The following statements are valid within a JLOOP block:
BREAK COMP

Cube Voyager Reference Guide 211

Highway Program Control statements

CONTINUE EXIT GOTO IF ... ELSEIF ... ELSE ... ENDIF PRINT REPORT SET

NOTE: You cannot place a :label statement inside a JLOOP; a GOTO statement cannot jump into a JLOOP. However, you can place a GOTO statement inside a JLOOP to jump to a :label statement outside the JLOOP. Example
;process only intra zonal values, but exclude externals JLOOP J=I EXCLUDE 500-535 ... ENDJLOOP ROWSUM1 = 0 ROWSUM3=0 JLOOP ; get rowsums for matrices ROWSUM1 = ROWSUM1 + MW[1] ROWSUM3 = ROWSUM3 + MW[3] ENDJLOOP

LINKLOOP ... ENDLINKLOOP


Controls a link loop for processing link records in the ILOOP phase. You can nest LINKLOOP blocks, but you cannot overlap them with IF blocks. By default, the link loop processes through all link records at an increment of one. You can use LINKNO, the default loop index, to reference the current link number. The program supplies all link arrays the default [LINKNO] in a LINKLOOP block.
Example
; double LW.VAR for even number zones

212 Cube Voyager Reference Guide

Highway Program Control statements

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

LOOP ... ENDLOOP


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

where: Lvar Name of the loop control variable. Lvar is not protected during the loop; computational, program, and other LOOP statements can alter its value. Lvar must be followed by Lbeg, and optionally, Lend and Linc. Lbeg Numeric expression that initializes Lvar. Lend Optional. Numeric expression that Lvar is compared to when processing the ENDLOOP statement. If not specified, no comparison is made and loop ends at ENDLOOP statement. Linc Optional. Numeric expression added to Lvar before making the ENDLOOP comparison. If not specified, Linc is set to 1 (or -1 if Lbeg and Lend are both constants and Lbeg < Lend; a backwards loop).

Use LOOPENDLOOP blocks to repeat a series of statements. LOOP initializes a variable; ENDLOOP compares the contents of the variable to another value, and branches back to the statement following the LOOP statement if the comparison fails. You can nest LOOP blocks, but you can overlap them with IF blocks. The process differs considerably from JLOOP. The logic is as follows: At LOOP: Initialize Lvar to Lbeg. Drop through to next statement.

Cube Voyager Reference Guide 213

Highway Program Control statements

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

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

If (Linc < 0 and Lvar >= Lend) jump to statement after LOOP This logic offers considerable flexibility, but can result in unpredictable results or endless loops. Endless loops could happen if the Lend and/or Linc values are expressions that contain variables that could change during the loop. On the other hand, the flexibility provides for powerful control. The loop will be processed at least one time regardless of Lend and Linc values. Most uses will involve constants. Because Lvar values can be expressions, Lbeg, Lend, and Linc must be separated by commas (standard white space delimiting cannot be interpreted properly).
Example
LOOP pass=1,10 ; perform 10 passes ... ENDLOOP LOOP xyz=abc*def,ghi+jkl,mno/pqr LOOP abc=xyz,xyz+2,2 ; nested LOOP ... ENDLOOP ENDLOOP LOOP jj=10,3,-2.5 ; 10, 7.5, 5.0 ... ENDLOOP

214 Cube Voyager Reference Guide

Highway Program Control statements

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

Cube Voyager Reference Guide 215

Highway Program Control statements

PARAMETERS keywords (continued)


Keyword CAPFAC Subkeyword |KR| Description Specifies a value to convert input capacity to the same unit as V. It is not used if C is specified in the LINKREAD phase. When C is not specified in the LINKREAD stack and is obtained directly from the input network, C = CAPFAC * input capacity. (See SETUP and LINKREAD phases on page 150 for details on how Cube Voyager obtains capacity from input network.) Default value is 1. COMBINE |KS| Specifies the method to combine the results of iteration volumes. Default value is EQUI. Possible values include: EQUI Standard equilibrium processing: compute a Lambda for each iteration to be applied to obtain the factor to combine the current volume (V) with the previous combined volume (CVOL): V = V * Lambda + CVOL * (1-Lambda) With this method, there are several options that can be specified by the subkeyword LAMBDASEARCH (seeLAMBDASEARCH on page 218). When intersection modeling is being undertaken (triggered by the presence of a FILEI JUNCTIONI statement), standard Lambda estimation processes are used for the link volume evaluations, but there is no equivalent process for including turning volumes. Intersection delays are not directly dependent upon the volumes on them; they are influenced by the total intersection traffic. But, the delays might have an important impact upon the assignment convergence. The vehicle delay costs for the turn movement can be included with the link costs by providing a value for the EQUITURNCOSTFAC keyword. If specified, Lambda estimation includes the turning delays multiplied by this value.

216 Cube Voyager Reference Guide

Highway Program Control statements

PARAMETERS keywords (continued)


Keyword COMBINE (continued) Subkeyword Description AVE WTD Average all the iteration loadings. Weighted average. MAXITERS will be set according to the number of weights specified in WEIGHTS. This is similar to AVE, but the required weights are used to favor specific iterations. Only the last iteration volumes are used for output to NETO. All the Iteration volumes are summed to form the final volume. This process can be used to perform traditional incremental loading. When SUM is specified, it must be followed by the FRACTIONS subkeyword. The V at the end of each iteration is the accumulated V for all the iterations to that point. Thus, the V/C ratio used in adjustment is based upon a partial assignment; it is true only on the last iteration. If it is desired to use a projected full V/C, then C must be computed differently depending upon which iteration it is. This can be accomplished in the LINKREAD phase, by use of IF (ITERATION=...) processes or by using an array of C scales.

ITER SUM

COMBINE

FRACTIONS

|RV*|

Specifies the fractions to be when COMBINE is set to SUM. The number of fractions sets the value for MAXITERS. The sum of all the values should be 1.00; if the sum is not 1.00, a warning message will be issued. That will not preclude the program from executing. During the ADJUST phase for each iteration, V will be factored according to the FRACTIONS for that iteration, and added to the V accumulated for the prior iterations.

Cube Voyager Reference Guide 217

Highway Program Control statements

PARAMETERS keywords (continued)


Keyword COMBINE Subkeyword LAMBDASEARCH |S| Description Specifies alternate methods for computing Lambda in EQUI processing. You can select one of two Lambda search processes: AREA Indicates to minimize the area under all the V vs. Cost curves computed for incremental estimates of lambda for every link. Estimates lambda by solving an expression based on the TC functions.

EQUATION

Default value is AREA. NOTE: Both processes estimate Lambda so the results might be slightly different. See the description of these two processes in ADJUST phase on page 159. COMBINE WEIGHTS |RV*| Specifies the weights to be used when COMBINE is set to WTD. The number of weights sets the value for MAXITERS. Specifies minimum string length for link consolidation, if CONSOLIDATE=T is specified on the PATHLOAD statement. Default value is 2. If the default is used (2), then links of two or more strings will be consolidated. If CONSOLIDATE is set to 3 then links of three or more strings will be consolidated, and so on. EQUITURNCOSTFAC |KR| Factor used to convert turn delays from minutes to cost for estimating Lambda in the equilibrium process. Default value is 0. If the default value (0) is used, turning volumes and delays from JUNCTIONI processing are not included in the estimation. This value is used only if: there are turning volumes and COMBINE is set to EQUI. When use, this value typically specifies the same value as TURNCOSTFAC. GAP1 |KR| Specifies the cutoff point based upon the relative difference in system cost (volume * cost) between two iterations. Default value is 0.005.

CONSOLIDATE

|I|

218 Cube Voyager Reference Guide

Highway Program Control statements

PARAMETERS keywords (continued)


Keyword MATOADJUST Subkeyword |KI| Description Specifies how often MATO matrices are combined during assignment. Enter number of iterations to combine at once, using the same factors used to combine volumes. Default value is 5 (the matrices are combined every five iterations). A lower number requires less disk space but more processing time. A higher number results in faster processing, but requires more disk space to store intermediate matrices. With a high number and numerous iterations, you could exhaust disk space. If disk space is scarce or you are not concerned about run times, Citilabs recommends setting this value to 1 (matrices will be combined after each iteration). Otherwise, Citilabs recommends using the default value. MAXITERS1 MAXMW |KI| |KI| Specifies maximum number of assignment iterations to be performed. Default value is 10. Optional. Maximum index for work matrices (MWs). Valid values range from 1 to 999. Default value is 999. Normally, you do not specify this keyword and override default value. Specifies the maximum length for a string variable. Default is 100. If you expect to compute longer strings, you must define a larger number. All string variables will have this possible length. Duration of the model period in minutes. The input demand matrix should be in units of vehicles (or PCU) per model period. This value is only used if junctions are being modelled, or in an AVENUE run. If no value is specified, a default of sixty minutes (one hour) will be used. Specifies the cutoff point based upon the fractional portion of links that have a change in volume (between two iterations) less than the value of PDIFFVALUE. Default value is 1.00. Specifies the value to be used with PDIFF. Default value is 0.0.

MAXSTRING

|KI|

MODELPERIOD

|KR|

PDIFF1

|KR|

PDIFFVALUE1

|KR|

Cube Voyager Reference Guide 219

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. Default value is 0.005. Specifies an alternative GAP measure as the cutoff point. Default value is 0.005. Specifies the cutoff point based upon the root mean squared error of the differences in volumes between two iterations. Default value is 0.1.

RELATIVEGAP1 RMSE1

|KR| |KR|

220 Cube Voyager Reference Guide

Highway Program Control statements

PARAMETERS keywords (continued)


Keyword TCCOEFF Subkeyword |RV*| Description Represents the coefficient term in a LINKCLASSspecific TC function relating congested volumes from the assignment to congested travel times on the links. Default value is 0.15. TC functions are the labels in the software given to volume delay functions (commonly referred to as VDFs). TC stands for Congested Time or TC. The LINKREAD Phase of this program allows the user to associate every link in the network with an internal LINKCLASS variable. The TC functions can be indexed by LINKCLASS to specify different volume delay relationships for different classes of facility. If no LINKCLASS is defined for a link it defaults to LINKCLASS=1. If no TC functions are defined then a default TC function is applied. The default TC function is the standard BPR with the form: TC[1] = T0 *(1 + TCCOEFF * (V/C) ^ TCEXP) The default values for TCCOEF and TCEXP result in the Standard BPR formula. If you code LINKCLASS values but do not code alternative TC functions by LINKCLASS, the default BPR form will be used but the LINKCLASS-specific values of TCCOEFF and TCEXP (if coded) will be substituted into the formula for the LINKCLASS. For example, if four LINKCLASSes are defined in the LINKREAD phase, and no TC functions are specified then TC[1] as specified above is in effect for all links. If the user codes:
PARAMETERS TCCOEFF[1]=0.15, TCEXP[1]=4, TCCOEFF[2]=0.16, TCEXP[1]=4.5, TCCOEFF[3]=0.17, TCEXP[1]=6, TCCOEFF[4]=0.18, TCEXP[1]=8,

Then these LINKCLASS-specific values of TCCOEFF and TCEXP are substituted into TC[1] for the appropriate LINKCLASS of a given link. This allows you to have one common functional form but apply different coefficient and exponent values by LINKCLASS. You can also code your own functional form if the BPR form is not what is desired. In general, TC[#]=f(T0, V/C, TCCOEFF, TCEXP) but the user is free to experiment with any forms that make sense to them for their application.

Cube Voyager Reference Guide 221

Highway Program Control statements

PARAMETERS keywords (continued)


Keyword TCEXP Subkeyword |RV*| Description Represents the exponential term in a LINKCLASSspecific TC function relating congested volumes from the assignment to congested travel times on the links. See the discussion for TCCOEFF above for usage. Default value is 4.0. Factor to convert turn times to equivalent costs for use in summary statistics and GAP calculations. If the value is 0, the summary report will not include turn volume costs. Default value is 1. Constant that indicates how much weight each turn movement should have when turn cost is used in GAP calculations. Default value is 1. A value of 1 indicates that each movement is to be considered with the same weight as a link. A value of 2 indicates that the turn cost should be multiplied by 2 (each turn movement is to be considered equal to 2 links during testing). ZONEMSG |KI| Optional. Frequency with which the program writes zonal timing messages to the run monitor or console. Value corresponds to number of zones. For example, with a value of 1, the program writes a message for every zone. With a value of 10, the program writes a message for every 10 zones. With a value of 0, the program writes no zonal messages. Specify a larger value to reduce run times. Program writes to the run monitor when initiated through Application Manager or voyager.exe. The program writes to the console when initiated through runtpp.exe. Valid values are greater than or equal to zero. Default value is 1.

TURNCOSTFAC

|KR|

TURNGAPWT

|R|

222 Cube Voyager Reference Guide

Highway Program Control statements

PARAMETERS keywords (continued)


Keyword ZONES Subkeyword |KI| Description Establishes the number of zones to process. Default value is taken from NETI. If ZONES is not specified, and the program has no other way to identify the appropriate number of zones, it will be set to 100. Normally, the NETI or MATI matrices will establish the number of zones, but there could be cases where the user wishes to use a different value. 1. These keywords are used to control when to not do any more assignment iterations. In the USA, GAP is a commonly used criteria. Thus, if GAP=0.01, this implies that when the system costs do not change by more than one percent, the process is to terminate. The first of these criteria that is satisfied controls the process. It is suggested that MAXITERS always be used to preclude endless processing. Some networks may never converge, and oscillations may start. Using MAXITERS can prevent useless processing. If MAXITERS ends up being the controlling value, the results printed at the end of the program should be examined to determine if oscillation has occurred, or if more iterations are really needed.

Example
ZONES=3000 COMBINE=WTD, WEIGHTS=1,1,2,3*3,5; 7 iterations COMBINE=EQUI, MAXITERS=30 PARAMETERS COMBINE=SUM, FRACTIONS=.30,.20,5*.10 ; 7 Iterations - Incremental ; SAMPLE INCREMENTAL ASSIGNMENT WITH PROJECTED RESTRAINT PARAMETERS COMBINE=SUM, FRACTIONS=.5,.2,.2,.1 ARRAY CSCALE=4 CSCALE[1]=.5, CSCALE[2]=.7, CSCALE[3]=.9, CSCALE[4]=1 PHASE=LINKREAD C = LI.CAPACITY * CSCALE[ITERATION]

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

Cube Voyager Reference Guide 223

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, and then complete other processes based on that path. Selected I-J path traces can be written to the standard output print file, matrices can be generated based upon path criteria, link volumes can be obtained by routing matrix values along the path. Although any of the keywords on the statement can be in any order, the statement is processed in the following specific order:
1. PATH Built using any EXCLUDEGROUP and PENI values

specified
2. TRACE 3. LINKIDARRAY 4. MW Processed in the input order

224 Cube Voyager Reference Guide

Highway Program Control statements

5. VOL Loaded in input order PATHLOAD keywords


Keyword CONSOLIDATE Subkeyword |?| Description Flag that specifies whether to consolidate links that are part of the same road segments prior to path building. Default value is F, no link consolidation. Consolidating the links reduces the size of the link table and the thus reduces pathbuilding time. Depending on the level of inefficiency in the input network, reductions in runtime could be significant. Also see PARAMETERS keyword CONSOLIDATE on page 218 for information on controlling the effective level of consolidation. ESTMO |?| Flag that specifies whether the assigned volumes on screenline links are to be trapped and output to the ICP file specified by FILEO ESTMICPO. Default value is F. Flag that indicates if ESTMO processing is used for all I-J paths, or for only the I-J paths where an actual assignment is performed. Default value is FALSE. If the value is TRUE, all potential paths are considered, mostly likely resulting in longer processing times and larger output files. EXCLUDEGROUP |IP| Specifies that links that have any of the designated group codes will be excluded from the path building process. For example, if HOV links were assigned to group 4, and 4 were one of the excluded values, then none of the paths would contain HOV links. EXCLUDEJ INCLUDEJ |IVP| |IVP| Specifies that the processes for the named keywords will exclude the specified destination zones. Specifies that the process for the named keywords will include only the specified destination zones

ESTMO

ALLJ

|?|

NOTE: INCLUDEJ and EXCLUDEJ should really be mutually exclusive, but they can be combined. When both are used, The INCLUDEJ is processed first, and than the EXCLUDEJ follows. Thus, if INCLUDEJ=100-200 and EXCLUDEJ=140-150, zones 100-139 and 151-200 would be the only destination zones processed. LINKIDARRAY LINKIDARRAY LINKIDCNTMW |S| |I| Specifies an array of link attributes; it must be either an LI.array or an LW.array. Specifies the MW[] in which to store the number of links in the list.

Cube Voyager Reference Guide 225

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

226 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD keywords (continued)


Keyword MW[] (continued) Subkeyword Description In some cases, a big number is acceptable, and in other cases, it is not. To solve this dilemma, you can use the subkeyword NOACCESS to specify a value to be returned from the PATHTRACE function when there is no path. The keyword PATHCOST may be used to obtain the value directly from the path tables. This is different than PATHTRACE, because PATHTRACE actually traces the path and sums the value from the network links that are in the path. PATHCOST is much faster, because it obtains the values without tracing paths; it also contains any penalty values that were included in building the paths. To provide similar capabilities with PATHTRACE, the argument list to PATHTRACE may include the penalty set numbers that should be added to the values for the first argument to PATHTRACE. Warning: The program determines when the last iteration has been performed, and no paths or matrices are built from the final network link values. Following the last iteration, MATOs written during normal iteration processing are combined according to the COMBINE option on the MATO statement. Thus, if skims had been written in each iteration, and COMBINE=T, the final skim mato will be the weighted values from all the iterations. This is normally done for trip matrices, but it may be useful for specific travel cost matrices. If COMBINE=F, the MATO will contain the values obtained during the last iteration -- not after the iteration. To obtain the true equilibrium zonal travel time and/or distance, one should run another Highway step using the loaded network as input and skim the shortest path time/distance.

Cube Voyager Reference Guide 227

Highway Program Control statements

PATHLOAD keywords (continued)


Keyword MW[] (continued) Subkeyword Description Example of PATHTRACE
PATH=TIME, MW[1]=PATHTRACE(TIME), ; zone-to-zones times MW[2]=PATHTRACE(LI.DISTSNCE), ; zone-to-zone distances MW[3]=PATHTRACE(TIME,2), ; same as MW[1], penalties added MW[4]=PATHCOST ; same as MW[3]

Select-link matrix A matrix of values for the zones that meet select link criteria. There are several different subkeywords that can be used to specify the select-link criteria: SELECTLINK, SELECTGROUP, and SELECTLINKGROUP. Their detailed descriptions are below. All the SELECT... keywords are combined for the MW that they directly follow. Each results in a true or false condition, and if any of them is true, the MW= expression is computed. In the following example, if any of the SELECT criteria is satisfied for a given J, MW[3] for that J will be computed to be the value from MI.1.TRIPS. Example of Select Link
PATH=COST, MW[3]=MI.1.TRIPS, SELECTLINK=(L=1000-1001 && L=20002001), SELECTGROUP=1-3,5, SELECTLINKGROUP=((GRP[1]=1 && GRP[2]=2) || (GRP[3]=1))

MW[]

NOACCESS

|R|

Specifies a number to be returned from the PATHTRACE function when there is no path from the current I to the destination (J) zone. Default value is 1,000,000. Specifies the group codes for selection. A path has to include at least one link that has any of the specified group codes. If the selection is 1-3, 7, then at least one link in the path has to have a group code of either 1, 2, 3, or 7.

MW[]

SELECTGROUP

|s|

228 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD keywords (continued)


Keyword MW[] Subkeyword SELECTLINK |s| Description Expression used to determine if the I-J path uses certain facilities. The expression must be enclosed within parenthesis, and can contain any of the following variables: A B N L The A-node of a link; only useful to select links with a path begins at A. The B-node of a link; only useful to select links with a path ends at B. A node that must be used in the path. A link that must be used in the path. Links are coded as A-B (directional) or A-B* (non-directional link may be traversed in either direction).

Any of these variables can have multiple values specified for them. Nodes (A, B, N) can be specified as single values and/or as ranges; L can have multiple links specified. When the multiple value specification is used, the implication is a logical OR amongst the values. Example: N=100,105,200-205 means if N is 100, or if N is 105, or if N is a value between 200 and 205, inclusive. The selection is processed by examining each link/node in the path, on both an individual link and a total path basis. The process is from left to right. Each link/node is processed, and as long as it does not fail any conditions, it is considered as a candidate for processing in the total path. In the total path basis, the link/node is considered in conjunction with other links/nodes in the path. Examples may better illustrate the process.

Cube Voyager Reference Guide 229

Highway Program Control statements

PATHLOAD keywords (continued)


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

230 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD keywords (continued)


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

PATHO

ALLJ

|?|

PATHO PATHO

FULLPATH INCLUDECOST

|?| |?|

PATHO

NAME

|S|

Cube Voyager Reference Guide 231

Highway Program Control statements

PATHLOAD keywords (continued)


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

PENIFACTOR

|N|

232 Cube Voyager Reference Guide

Highway Program Control statements

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. For example: SUBAREAMAT[1] = MW[3] specifies that for every J of the current I path set, if the path from I-J has some portion within the subarea, a value is to be inserted to the subarea matrix. There must be an index for the keyword. The highest index is used to set the number of matrices on the SUBAREAMAT file. This process is described in ILOOP phase on page 154. SUBAREAMAT MAXMSG |I2| Specifies how many messages to print about improper cordon crossings and the error level to assign to the messages. Two values are allowed: The first value specifies how many messages are printed for the SUBAREAMAT. The second value specifies the error level to assign to the message when the number of messages reaches the first value.

The printed messages will be assigned an error level of 1 less than the second value for all messages except the last one. For example: MAXMSG=50,2 indicates that the first 50 improper crossings are to be printed at error level 1, but the program will terminate with error level 2, at the 50th message. TOLLFACTOR |N| Expression that specifies a factor for converting tolls to COST units. Generally paths are built on TIME and TIME is in the units of minutes. If a generalized COST function is used for path building, all components of this function are typically appropriately factored to be in generalized minutes. Units must be (path cost units)/(toll cost units). For example, if tolls are coded in $US and path costs in minutes, then the TOLLFACTOR expression must specify a value in minutes/$US. An assumed traveler value of time of US$15/Hour would be implemented by setting TOLLFACTOR to 4 (60/VOT).

Cube Voyager Reference Guide 233

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. Specifying TOLLMATI=1,2 indicates to use toll set 2 on TOLLMATI file 1. See Path-based tolls on page 146. THRUNODE |I| Sets the minimum node number allowed to be included in the path building process. The value has to be a positive integer. The default value is ZONES+1. The default value excludes centroids as intermediate points of a path. Specifies if any paths from I to the selected destinations are to be formatted and reported for this path. The select expression must be enclosed within parenthesis. Most likely, the variables used in the expression would be I, J, and Iteration, but any valid variable can be used. The TRACE expression is evaluated for J=1,Zones. Example:
PATHLOAD PATH=TIME TRACE=(I=1-10 & J=100150)

TRACE

|S|

The selected path traces will be listed in the run print file. The TRACE keyword can now use the PRINT statement keywords as subkeywords to format and direct the print of the path trace(s) to an external PRINTO file. The following additional subkeywords can be used: PRINTO (REWIND PRINT) CSV CFORM FORM LIST See PRINT on page 238 for details on these subkeywords. The LIST subkeyword may be any valid input (li.) or work (lw.) array or it can be set to _pathcost to list the accumulated value of the COST function along the path trace. See TRACE example on page 236.

234 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD keywords (continued)


Keyword VOL[] Subkeyword |N| Description Specifies an expression to be solved for J, and that the result of the expression is to be assigned to the links in the path generated by the PATH keyword. VOL should be indexed [], but if it is not, the index is implied to be 1. The index range is 1-20; there may be up to 20 volume sets in a single application of Highway. The values are added to the volumes. In most cases, there will be a single VOL for a PATHLOAD statement, but there are many cases, where it will be advantageous to have more than one VOL. For example, if a standard assignment is to be performed, and it is desired to have another assignment made of just the trips that meet select link criteria, that is easily accomplished. Or, perhaps it is desired to assign all vehicles, and to determine what types of trips make up the volumes on each link. The examples below illustrate these capabilities. It should be noted that when specifying multiple VOL keywords, you must specify the FUNCTION V so the program knows which VOL combinations are to be used for capacity analysis. Specifies the name of a link value that should be used in restricting the links that should be included in the VOL assignment. The primary use of this keyword is for air quality analysis. An example would be to obtain what portion of the volume on a link is in cold start mode. In that case, VOL[2]=MI.1.TRIPS, TIME=0-7.5 would mean to assign only to the links that are within 7.5 minutes from the origin zone. A single range of numbers is required for this keyword. In the example, if a 3 minute links A node were 6 minutes from I, only 50% of the trip value would be added to the link volume (7.5 is 50% of the way from 6 minutes to 9 minutes). Normally, the range would be 0-some number, but if the range were say, 7.5-99999, only the hot running portion of the trip would be assigned.

VOL[]

Valuename

|S|

Cube Voyager Reference Guide 235

Highway Program Control statements

TRACE example
RUN PGM=HIGHWAY FILEO PRINTO[1] = PATH.CSV FILEO PRINTO[2] = PATH_TRACE_RPT.DAT FILEI NETI = TEST.NET PHASE = LINKREAD FromNode=1500 ToNode=1875 lw.fac_dist=10*li.DISTANCE lw.flag1=1 ENDPHASE PROCESS PHASE=ILOOP if (I < FromNode) _skiptoI=FromNode ; speeds up process IF (I=FromNode) ; build paths for select I PATHLOAD PATH=li.TIME mw[1]=PATHTRACE(li.TIME), mw[2]=PATHTRACE(li.DISTANCE), TRACE=(I=FromNode & J=ToNode) PRINTO=2 PRINT=T F=6.0, LIST=I,J,A,B,li.TIME(8.3),_pathcost(8.3), li.DISTANCE(8.4),lw.flag1(3.0), lw.fac_dist(10.2) ;Print results to formatted file to check against TRACE JLOOP IF (J=ToNode) ; FROM, TO, TIME, DISTANCE PRINT CSV=T, PRINTO=1, LIST='FromNode','ToNode','TIME','DISTANCE' PRINT CSV=T, PRINTO=1, LIST=FromNode(5.0),ToNode(5.0),mw[1](10.2),mw[2](10.2) ENDIF ENDJLOOP EXIT ENDIF ENDPROCESS ENDRUN

An example of getting toll costs would entail having a LOOKUP function where the lookup value is the gate-gate combination traversed on the path and the result of the function is the toll value associated with gate-gate movement.
LINKIDMW=1-2 Cost = tolllook(MW[1]*1000+MW[2])

See Highway example 7 on page 258 for an example of using the LINKIDARRAY keyword and its subkeywords in a script.

236 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD example
PATHLOAD PATH=COST, VOL[1]=MI.1.ODTRIPS PATHLOAD PATH=COST, MW[6]=MW[3], SELECTLINK=(L=2001-2004), VOL[1]=MW[3], VOL[2]=MW[6],VOL[3]=MW[3],TIME=0-7.5

This first PATHLOAD statement causes the COST paths to be built, and then the values from MI.1.ODTRIPS are assigned and added to VOL[1]. The second PATHLOAD statement causes the following sequence of events:
1. COST paths are built. 2. MW[6] is set equal to the values in MW[3] for the Js whose path

from I crosses link 2001-2004. Note that MW[6] was cleared at the beginning of the ILOOP for I, but if the user caused any values to be set into MW[6] prior to this statement, the MW[6] values could be incorrect.
3. The values from MW[3] are assigned to the COST paths and

added into VOL[1] volumes.


4. The values from MW[6] (the selected link trips) are assigned to

the COST paths and added into VOL[2].


5. The values from MW[3] are assigned to only the links that are

within 7.5 minutes from I and added into VOL[3] (these are the cold start volumes).
Example
/* The first PATHLOAD statement below (PATH is a trigger keyword PATHLOAD is not required) builds the DISTANCE paths and illustrates two different ways to extract a LOS matrix for the path. The second PATHLOAD statement builds the COST path using penalties and shows that the two extracted matrices are not necessarily the same because of the penalties. The comments illustrate how to properly skim a path when penalties should be incorporated. */ PATH=LI.DISTANCE,MW[1]=PATHTRACE(LI.DISTANCE),MW[2]=PATHCOST ; MW[1] and MW[2] are the same in this case PATH=TIME, PENI=1,3 MW[1]=PATHTRACE(COST),MW[2]=PATHCOST

Cube Voyager Reference Guide 237

Highway Program Control statements

; MW[1]and MW[2] could be different because penalties are used ; in the path. If MW[1]=PATHTRACE(TIME,1,3),they would be the same. /* Following is an example of trip splitting based upon the relative difference of time if a link (say, a bridge) is added to the network. In this example the link is already in the network, and it can be unavailable to the path builder by excluding links with group code 1. The steps are: 1. Compute the time path with the bridge included and extract the times along the path into MW[1]. 2. Compute another path with the bridge excluded (group=1)and extract the times along the path into MW[2] 3. Compute a path split based upon the total times for the two sets of paths. The portion of trips that would use the bridge path is computed based upon the values in the two time LOS matrices [1] and [2]. If the time saved exceeds 10 minutes and the relative saving (time saved / total trip time) is greater than 15 percent, the portion of trips that will use the bridge path is set equal to the relative saving. (This is to illustrate a method of application, and is not meant to imply any type of realistic diversion.) 4. Assign a portion of the trips to the one path set, and the remaining trips to the other path set. The two assignments are made to the same volume set, but, they could have just as easily be kept separate. */ PHASE=LINKREAD If ((A=1001 & B=1002) | (A=1002 & B=1001)) ADDTOGROUP=1 PHASE=ILOOP PATHLOAD PATH=TIME, MW[1]=PATHTRACE(TIME) ;w bridge PATHLOAD PATH=TIME, EXCLUDEGROUP=1 MW[2]=PATHTRACE(TIME) ;wo bridge JLOOP; MW[3] = the fraction of trips diverted to the bridge path TimeSaved = MW[2] - MW[1]; 2 is always >= 1. Divert = 0 RelativeSaving = TimeSaved / MW[2] IF (TimeSaved > 10 && RelativeSaving >.15)Divert = RelativeSaving MW[3] = Divert ENDJLOOP ;assign bridge trips PATHLOAD PATH=TIME, VOL[1]=MI.1.TRIPS*MW[3] PATHLOAD PATH=TIME, EXCLUDEGROUP=1, VOL[1]=MI.1.TRIPS*(1-MW[3])

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

238 Cube Voyager Reference Guide

Highway Program Control statements

See PRINT on page 62 for details.


Example
IF (ITERATION = 0) ; LIST INPUT LINKS LIST= A(5), B(5), NI.DIST(6), T0(6.2) ENDIF IF (ADJUST=1 && ITERATION >5 && VC >2.0) LIST='BIGVC for: ',A,B,VC(5.2)

PRINTROW
Formats and prints row(s) of matrices. MW J TITLE FORM MAXPERLINE BASE1 See PRINTROW on page 69 for details.
Example
PRINTROW mw=1-2,1 form=LRD title='form=LRD' PRINTROW mw=1-21 form=6D base1=y maxperline=10 form=6D, base1=y maxperline=10

PROCESS ... ENDPROCESS


Establishes phase blocks. PHASE ENDPHASE A user process phase stack is defined by a PROCESS statement that names it and an ENDPROCESS statement that ends it. To simplify coding, the PROCESS control word is not necessary; PHASE=name may be used directly. And, to further simplify coding, the ENDPROCESS statement is not necessary; the occurrence of another

Cube Voyager Reference Guide 239

Highway Program Control statements

PROCESS statement acts as the ENDPROCESS statement. If ENDPROCESS is used, it may be coded as either ENDPROCESS or ENDPHASE. PROCESS keywords
Keyword PHASE |KS| Description Names the phase stack. The control statements that follow it, until an ENDPROCESS statement or another PROCESS statement is encountered, will be executed when the phase is internally executed. Exception: Static statements, such as PARAMETERS, FILEI, FILEO, and LOOKUP, are not processed within the stack, even if that is where they are coded. The following names may be specified: ENDPHASE |K| SETUP LINKREAD ILOOP ADJUST

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

Example
PHASE=LINKREAD T0 = LI.DISTANCE*60 / SPEED ENDPHASE PHASE=ILOOP PATH=TIME, VOL[1]=MI.1.ODTRIPS ENDPHASE PHASE=ADJUST LW.TIME = TIME * LW.FLAGCODE ENDPHASE

REPORT
Requests reports and establishes tracing. CAPACITY PENI

240 Cube Voyager Reference Guide

Highway Program Control statements

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


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

SPEED TRACE

|?| |K?|

VDTSPD

|?|

VDTSPD

|IV|

VDTSPD

|IV|

Cube Voyager Reference Guide 241

Highway Program Control statements

REPORT keywords (continued)


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

VDTSPD

RANGE

|IP|

have only one number reported.


RANGE=0-100-1 specifies that the report is

to have 100 values reported.


RANGE=0-7.5, 7.5-100-5 specifies that two different schemes are to be obtained.

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

242 Cube Voyager Reference Guide

Highway Program Control statements

REPORT keywords (continued)


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

ZDAT ZDAT DEC

|?| |I|

Example
TRACE=y ; turn stack tracing on REPORT CAPACITY=yes ; report the capacities by lane by CAPCLASS REPORT VDTSPD=T, VOL=1, I=1-933, J=1-933, RANGES=0-7.5, 7.5-100-5, FILE=VDTSPD.TXT

SET
Sets multiple variables or arrays to the same value. VAL VARS Use SET to set any number of variables to some value. All variables are set to zero when they are first allocated. COMP statements produce most changes. A COMP statement is not as efficient as a SET statement.
SET keywords
Keyword VAL |R| Description Value that the VARS that follow will be set to. It must be a numeric constant. VAL is initialized to zero when the statement is encountered. List of variables that are to be set to the more recent value of VAL obtained from this statement. If a VARS is the name of an array established on an ARRAY statement, the entire array will be set to VAL.

VARS

|S|

Cube Voyager Reference Guide 243

Highway Program Control statements

Example
SET VAL=0, VARS=TOT1,TOT2,COUNTER TOT1=0 TOT2=0 COUNTER=0 ; is a COMP statement to do the same thing SET VARS=TOT1 TOT2 COUNTER ; is also the same (VAL is 0) SET VAL=123 VARS=C123, VARS=TOT1, TOT2, TOT3 ; sets all to 123 SET VAL=0, VARS=VA1,VA2,VA3, VAL=100, VARS=VX, VY

SETGROUP
Sets group codes for a link. ADDTOGROUP REMOVEFROMGROUP Use SETGROUP to set group codes for a link; it is applicable during only the LINKREAD phase. Group codes are used primarily for designating links that are to be excluded in path-building, and for inclusion in select link analysis. Each link can have up to 32 different group codes assigned to it. The codes are numbered 1-32. There are no preconceived definitions for the codes; that is the users responsibility. Group codes can be quite helpful in project analysis or for determining specific interchange to interchange movements.
SETGROUP keywords
Keyword ADDTOGROUP |KIP| Description Specifies that the current link is to be assigned the codes that are in the value list. Specifies that the current link is to have the designated values removed from its codes. This keyword normally should not be used.

REMOVEFROMGROUP

|KIP|

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

244 Cube Voyager Reference Guide

Highway Program Control statements

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

SPDCAP
Revises speed and capacity tables. CAPACITY LANES SPEED The SPDCAP statement is the same as that used in the Network program to revise the SPEED and CAPACITY tables attached to the network. If this statement is used in the control file for the Highway program, the values from the NETI are updated when NETI is opened. This capability allows you to test various scenarios without having to modify the network. The revised tables will be written to the NETO file.
SPDCAP keywords
Keyword CAPACITY |RV*99| Description Capacity in vehicles per lane per hour. Actual link capacity is obtained by multiplying the link capacity based upon its capacity classification (CAPCLASS) value by the number of LANES. All values must be 09999, inclusive. The capacity array is initialized to 20 times the index number, for all lane stratification (CAPACITY[1]=20, CAPACITY[2]=40...). Lane stratification that any following CAPACITY and/or SPEED values are to apply to. LANES may be interspersed with other keywords and values on the statement. All values must be 1-9, inclusive. Speed to be applied to the link. All values must be 03276.7, inclusive. The speed array is initialized to the index number, for all lane stratification (SPEED[1...99]=1,2,...99). Speed is maintained with one decimal place.

LANES

|IV|

SPEED

|RV*99|

Cube Voyager Reference Guide 245

Highway Program Control statements

A network contains an array of capacity and speed data. Each array is dimensioned with ninety-nine values for each of nine lane stratification, and contains 891 values. When an array is accessed, the program uses the number of lanes (LANES) as the row index, and the capacity and/or speed classification (CAPCLASS, SPDCLASS) as the column index to obtain a value for a link. If CAPACITY or SPEED is encountered prior to a LANES keyword on the statement, LANES will be preset to 1-9. CAPACITY and SPEED are entered as vector data, and may be indexed to set a specific loading place, and may have null fields to skip the revision of certain columns. The SPEEDFOR and CAPACITYFOR functions can be used to obtain values for these tables.
Example
;Set entire table to 50, ; then revise the values for 20,21, and 24 for lanes 1,3,8 SPDCAP CAPACITY=99*50, LANES=1,3,8, CAPACITY[20]=300,400,,,700 SPDCAP LANES=2,4-9, SPEED=20.5,30.3,50.6,,,88.2, LANES=5,SPEED[15]=15 SPDCAP SPEED=30, LANES=2-8; Inappropriate; the LANES will not be used.

TURNS
Requests turning movement volumes. NT Use TURNS to request that the volumes at specific interchanges (nodes) be accumulated. If there is at least one TURNS statement, the program will accumulate turns for every PATHLOAD VOL[]= statement that is present. At the end of each iteration (in the Adjust phase), a single total turn volume will be computed for each movement at the nodes where turns are requested. By default, the single volume is computed by adding all the individual turn volume sets together (T = TURN[1] + TURN [2] + TURN [..] ...). This default accumulation process can be overridden by using the T= capabilities on this statement. Usually, the T= expression should be parallel to the V= expression that is specified on a FUNCTION statement. The value of T for each movement will be computed in the Adjust phase, and then combined with other iteration values to form the combined volume.

246 Cube Voyager Reference Guide

Highway Program Control statements

To accumulate turn volumes, you must specify a FILEO TURNVOLO statement. The turn volumes will be written to the file(s) specified on that statement.
TURNS keywords
Keyword N T |IP| |N| Description List of nodes at which turning volumes are to be accumulated. Expression used to compute the total volume at each of the nodes.

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

Cube Voyager Reference Guide 247

Highway Program Theory

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

Process overview
It is important to have a basic understanding of the logic of the program, so that when certain special operations are to be performed, they can be placed properly. Although you can place phases in the script in any order, Citilabs suggests that you use a basic template for all applications. If you use a basic template, then only the actual operations of each segment need be completed.
Example of suggested basic application template
RUN PGM=HIGHWAY FILEI FILEO FUNCTION ; include V, TC, and COST functions here PHASE=SETUP ; normally this phase is not used ... PHASE=LINKREAD ; insert any statements required to: ; extract custom information from the input network. ... PHASE=ILOOP ; build paths, skim paths, load trips to paths ... PHASE=ADJUST ; revise special LW.values for next iteration ... PHASE=CONVERGE ; optional for user specified convergence tests ... ENDRUN

248 Cube Voyager Reference Guide

Highway Program Theory

The internal logic of the program is as follows: PHASE = SETUP Establish user SET arrays, etc. This phase is not specified by most users. If there is a PHASE=SETUP block, perform the statements of the block. ENDPHASE PHASE = LINKREAD Loop LINKNO=1,NUMLINKS Read each link record. If there is a user supplied LINKREAD block, process it, then set the required values that LINKREAD did not set properly Set the Time and Cost values

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

EndLoop ENDPHASE PHASE = ADJUST Loop LINKNO=1,NUMLINKS Read each link record. Obtain link values using most of the LINKREAD process Apply the appropriate Functions (V, TC, COST) for the link.

Cube Voyager Reference Guide 249

Highway Program Theory

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

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

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

User stacks
These are stacks of control statements that you provide to perform certain operations at various times in the process. The term stack, as used here, means all the user supplied statements for the phase. Stack and phase are sometimes used interchangeably. Phase refers to a phase the program automatically processes, and stack refers to the user supplied statement for that phase. The ILOOP stack is required, but all the others are optional. Most times, the other stacks will not be necessary, but it does provide a mechanism for altering program variable values at crucial times. Each stack begins with a PROCESS PHASE = StackName statement. (PHASE is a trigger key, so most users will just code PHASE= without the leading control word.) The operational statements that are to be preformed in this stack follow the PHASE statement. The stack is terminated by the presence of another PHASE = stackname statement, an ENDPHASE statement, or the end of input. Non-operational statements (FILEI, FILEO, PARAMETERS, FUNCTION and others) can be within a stack, but they are ignored during stack processing. It is suggested that all non-operational statements be placed at the beginning of the input for reader clarification. Each of the phases, may be specified one time only. IF and LOOP blocks must be

250 Cube Voyager Reference Guide

Highway Program Theory

complete within a stack, and GOTO and associated label statements must be within the same stack. EXIT and ABORT will cause termination of a stack, but will have impact on the actual program process only from ILOOP.
LINKREAD stack

This stack is in the LINKREAD phase, and is used as explained above in that section. Primarily, it is used to obtain required link values (if they are not directly available from the input network), and to set link LW.values and GROUP codes.
ILOOP stack

This stack is the entire ILOOP phase, and is described previously. It MUST be present.
ADJUST stack

This stack is processed as the last operation in the ADJUST phase link loop. It provides a place for computing and accumulating special values such as objective functions (currently undocumented). It also provides the capability to print certain link values during the process. If LW.values are dependent upon Time and/or Cost, and it is necessary to reflect the changes in those values to the LW.values for the next iteration, the adjustment can be made here. Alternatively, the LW.values can be adjusted with ILOOP statements.
CONVERGE stack

This stack is processed during convergence testing in the ADJUST phase. Its primary purpose is to set BALANCE to 1 if certain conditions are met. Most users will not have any need for this stack.

Cube Voyager Reference Guide 251

Highway Program Examples

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

Highway example 1
/* EXAMPLE 1 This example shows a simple equilibrium assignment procedure assuming a typical input highway network providing CAPACITY, DISTANCE AND SPEED on the link attributes. */ RUN PGM=HIGHWAY FILEI NETI = Network.net FILEI MATI[1] = TRIPS.mat FILEO NETO = LOADED.NET PARAMETERS COMBINE=EQUI MAXITERS = 99 GAP=.0001 PROCESS PHASE = LINKREAD C = LI.CAPACITY ; set capacity equal to a link field ; assumes DISTANCE and SPEED are available on the input network ; no LINKCLASS defined, therefore defaults to 1 for all links ENDPROCESS PROCESS PHASE=ILOOP ; main loop for program PATHLOAD PATH=TIME, ; build path based on time VOL[1]=MI.1.CAR, ; load trips from input matrix to volume set 1 ENDPROCESS ; No TC functions defined therefore congested travel times computed using ; the standard BPR formula for all links. ; No COST function defined therefore COST defaults to TIME ENDRUN

252 Cube Voyager Reference Guide

Highway Program Examples

Highway example 2
/* EXAMPLE 2 Simple example of using HIGHWAY to SKIM level of service information from the loaded highway network from Example 1. This example builds paths on the congested travel time variable in the loaded network and Skims or extracts the zone-to-zone times and distances for those paths to an external matrix file. */ RUN PGM=HIGHWAY FILEI NETI = LOADED.NET FILEO MATO[1] = HWY_SKIMS.MAT, MO=1-2,NAME= 'HWY Time', HWY Distance PROCESS PHASE=LINKREAD T0=li.TIME_1 ; Final congested travel times on the input network ENDPROCESS PROCESS PHASE=ILOOP ; Loop across all origin zones and build path using congested time. ; skim TIME and DISTANCE for the min TIME paths into work matrices 1 and 2 PATHLOAD PATH=TIME, MW[1]=PATHTRACE(TIME), MW[2]=PATHTRACE(LI.DISTANCE) ; For intrazonals, make the intrazonal time equal to half the time to the nearest zone COMP MW[1][I] = rowmin(1) * 0.5 ; Intrazonal time ; Set the intrazonal distance equal to 0 COMP MW[2][I] = 0 ENDPROCESS ENDRUN

Highway example 3
/* EXAMPLE 3 This example shows a multi user class equilibrium assignment, building paths on a generalized cost function with the cost functions differentiated by the facility type (LINKCLASS). Turn penalties are included in the path building process and the PATH file is saved for graphical analysis */ RUN PGM=HIGHWAY FILEI NETI = NETWORK.NET FILEI MATI[1] = TRIPS.MAT FILEI TURNPENI = TURNPEN.PEN FILEO NETO = LOADED.NET

Cube Voyager Reference Guide 253

Highway Program Examples

FILEO PATHO[1] = HWY_PATHS.PTH ; set parameters and values for time and distance costs PARAMETERS COMBINE = EQUI GAP = 0.005 time_cost1 = 0.5 time_cost2 = 0.7 distance_cost1 = 0.2 distance_cost2 = 0.4 ; ----- SET CAPACITY and LINKCLASS PROCESS PHASE=LINKREAD CAPACITY = LI.CAPACITY * 1.0 ; set link classes for major roads IF (li.CLASS = 1-4) LINKCLASS = 1 ; set link classes for minor roads IF (li.CLASS = 5-10) LINKCLASS = 2 ; group railway links for exclusion from assignment IF (li.CLASS = 11 | li.CLASS = 12) ADDTOGROUP=1 ENDPROCESS PROCESS PHASE=ILOOP PATHLOAD PATH=COST, PENI=1-2, ; include turn penalties, VOL[1]=MI.1.CAR, ; load car trips, VOL[2]=MI.1.TRUCKS, ; load truck trips, EXCLUDEGROUP=1, ; exclude rail links PATHO=1 NAME=COST_PATH INCLUDECOSTS=T ALLJ=T ; save path file ENDPROCESS PROCESS PHASE=ADJUST ; Define cost and delay functions function { tc[1]=t0*(1.0+0.15*((v/c)^8)) ; congested time function for major roads tc[2]=t0*(1.0+0.15*((v/c)^4)) ; congested time function for minor roads cost[1]=time*time_cost1+li.distance*distance_cost1 ; cost function for major roads cost[2]=time*time_cost2+li.distance*distance_cost2} ; cost function for minor roads ENDPROCESS ENDRUN

Highway example 4
/* EXAMPLE 4 This example script runs a junction constrained equilibrium assignment dumping the path file, final turn delays and the binary junction data file */ RUN PGM=HIGHWAY

254 Cube Voyager Reference Guide

Highway Program Examples

FILEI NETI = NETWORK.NET FILEI MATI[1] = VEHICLETRIPS.MAT FILEI JUNCTIONI = JUNC_BASE.IND, period=60,set=1 FILEO NETO = LOADED.NET FILEO PATHO[1] = ROADPATHS.PTH FILEO TURNPENO = TURNDELAYS.DAT FILEO JUNCTIONO = TURNS.INT ; set convergence method and criteria PARAMETERS COMBINE = EQUI, GAP = 0.005, maxiters=99 PARAMETERS EQUITURNCOSTFAC=1 ; ----- SET CAPACITY and group links PROCESS PHASE=LINKREAD C = LI.CAP IF (LI.FUNC_CLASS = 1-2) LINKCLASS=1 IF (LI.FUNC_CLASS = 3-10) LINKCLASS=2 ENDPROCESS PROCESS PHASE=ILOOP PATHLOAD PATH = TIME, VOL[1]=MI.1.1, PATHO=1, NAME='assignment',ALLJ=T, INCLUDECOSTS=T,PENI=1 ENDPROCESS PROCESS PHASE=ADJUST function { tc[1]=t0*(1.0+0.15*((v/c)^8)) ; congested time function for major roads tc[2]=t0*(1.0+0.15*((v/c)^4)) ; congested time function for minor roads ENDPROCESS ENDRUN

Highway example 5
/* EXAMPLE 5 This script shows an example of both subarea assignment and subarea matrix extraction for multiple trip purposes. The subarea network is created with CUBE/VIPER POLYGON tools with the default renumbering of the network. */ RUN PGM=HIGHWAY NETI=DEMO.NET ; subarea network created with POLYGON tools in CUBE/VIPER FILEI SUBAREANETI=subarea1.net MATI=TRIPSBYPURPOSE.MAT FILEO NETO=Loaded_DEMO.NET FILEO SUBAREAMATO=submat1.mat NAME=HTW,WTH,HTO,OTH,NHB,TOTAL

Cube Voyager Reference Guide 255

Highway Program Examples

PARAMETERS COMBINE=EQUI GAP=.0001 PHASE=LINKREAD LINKCLASS=LI.CLASS C=LI.CAPACITY ENDPHASE PHASE=ILOOP ; this PATHLOAD statement builds paths on TIME, assigns each trip purpose ; and the total trips to separate volume sets, ; extracts a subarea matrix for each trip purpose and the total trips PATHLOAD PATH=TIME,VOL[1]=mi.1.1,,VOL[2]=mi.1.2,VOL[3]=mi.1.3,VOL[4]=mi.1.4, VOL[5]=mi.1.5,VOL[6]=mi.1.6, SUBAREAMAT[1]=mi.1.1,SUBAREAMAT[2]=mi.1.2, SUBAREAMAT[3]=mi.1.3,SUBAREAMAT[4]=mi.1.4, SUBAREAMAT[5]=mi.1.5,SUBAREAMAT[6]=mi.1.6 ENDPHASE PHASE=ADJUST ; volume function V sets the volume to use for V/C in the delay function ; No delay functions (TC[#]=) are specified here so the default BPR ; formula is used for all link classes FUNCTION V=VOL[6] ; set volume to use in congested travel time functions ENDPHASE ENDRUN

Highway example 6
/* EXAMPLE 6 This script has two steps. In step 1 several examples of select link assignment are shown. In step two a MATRIX job is run to build trip end reports for the select link trip matrices created in step 1 */ ; Step 1 Select Link Assignment RUN PGM=HIGHWAY MATI=TRIPS.MAT NETI=DEMO.NET NETO=DEMOSelectLink.NET MATO = MATVOUT.MAT,mo=1-2,4 dec=2, combine=Y ; this is an example of an incremental assignment procedure ; the number of fractions defines the number of iterations ; at each iteration the listed fraction of the trip table is assigned COMBINE=SUM,FRACTIONS=0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.05,0.05,0.05,0.05,0.0 5,0.05 ; Equilibrium assignment could be performed specifying COMBINE=EQUI ; or volume averaging by specifying COMBINE=AVE if desired PHASE=LINKREAD

256 Cube Voyager Reference Guide

Highway Program Examples

LINKCLASS=LI.CLASS C=LI.CAPACITY ENDPHASE PHASE=ILOOP PATH=TIME,VOL[1]=mi.1.6, mw[1] = mi.1.6, selectlink = (L=1449-1495), vol[2] = mw[1] mw[2]=mi.1.6 /* this step says build paths based on time, assign trips from mi.1.6 to these paths and put them in Volume set 1 (V1_1 on the output network), put trips from mi.1.6 into working matrix 1 if they are on paths that use the selected links (L=), assign the trips in working matrix 1 (the select link trips) back to the time based paths and put them into Volume set 2 (V2_1 on the output network), and lastly put the total trips assigned from mi.1.6 into working matrix 2. Note that on the MATO line mo=1-2 will output the selected trip matrix (1) and the total trip matrix assigned (2) */ PATH=TIME,VOL[3]=mi.1.6, mw[4] = mi.1.6, selectlink = (L=1494-1423), vol[4]=mw[4] /* this step says build paths based on time, assign trips from mi.1.6 to these paths and put them in Volume set 3 (V3_1 on the output network), put trips from mi.1.6 into working matrix 4 if they are on paths that use the selected links (L=), assign the trips in working matrix 4 (the select link trips) back to the time based paths and put them into Volume set 4 (V4_1 on the output network). Note that on the MATO line mo=4 will output the selected trip matrix (4) for the links L=. Now you have 4 volume sets, but only want to calculate congested travel times based on the true total volumes on each link. This is why you need the function V=vol[1]. Note that V=vol[3] would give the same result as these two sets are the same. The V function is automatically executed during the adjust phase. */ ENDPHASE PHASE=ADJUST function { V=vol[1] } /* this function sets the volume for the capacity restraint to be the total volume. Without this statement, V is set to the sum of all volume sets which double counts volume when you have a select link volume set */ ENDPHASE ENDRUN ; Step 2 Extract and report select link trip ends RUN PGM=MATRIX ; note this example was for a 25 zone network

Cube Voyager Reference Guide 257

Highway Program Examples

FILEI MATI=matvout.mat mw[1]=mi.1.1 array sum_mat = 25 array row_tot = 25 row_TOT[I] = rowsum(1) Jloop sum_mat[J] = sum_mat[J] + mw[1][J] endjloop IF (I=25) LOOP INDEX=1,25 PRINT FORM=10.0, LIST=INDEX,ROW_TOT[INDEX],SUM_MAT[INDEX], file =SelectTripEnds.txt ENDLOOP ENDIF ENDRUN

Highway example 7
/* EXAMPLE 7 This script is an example of using LINKIDARRAY to accumulate information about toll gate use from the paths into working matrices. In this example, the LINKIDARRAY uses li.TOLL. This network data field contains a value of 1-8 corresponding to one of the 8 toll bridges in the San Francisco Bay Area network. The output work matrices include: #1 is the travel time on the I-J path, #2 is the number of toll gates traversed on the path, #3 is the number of the last toll gate traversed on the path and #4-#8, include the 1st, 2nd, 3rd and 4th gate number traversed on the path if used. */ RUN PGM=HIGHWAY FILEI NETI = SF_BAY_AREA.NET FILEO MATO[1] = test.mat, mo=1-8 PHASE=LINKREAD LW.TIM=LI.DISTANCE/LI.FFS * 60 If (li.USE=2,3) ADDTOGROUP=1 ; don't use HOV facilities, ; they by pass tolls ENDPHASE PHASE=ILOOP PATHLOAD PATH = LW.TIM, EXCLUDEGROUP=1, MW[1] = PATHTRACE(LW.TIM), LINKIDARRAY=li.TOLL, LINKIDCNTMW=2 LINKIDLASTUSE=3 LINKIDMW=4-8 ENDPHASE ENDRUN

258 Cube Voyager Reference Guide

Highway Program Examples

Highway example 8
/* Example 8 Example of using TOLLMATI to incorporate closed system tolls into the pathbuilding process. In this example, the paths are built on COST and the COST function will include any gate to gate tolls traversed on a path. */ RUN PGM=HIGHWAY FILEI TOLLMATI[1] = "TOLL.DBF", ENTRYGATE=ON_RAMP, EXITGATE=OFF_RAMP, TOLLS=COST_CAR,COST_TRUCK, NETIENTRY=ONRAMP, NETIEXIT=OFFRAMP, NETITOLLROAD=TOLLROAD FILEI NETI = "BASE.NET" FILEI TURNPENI = "PROHIBIT1.PEN" FILEI MATI[1] = "PKHOURTRIPS.MAT" FILEO TURNVOLO[1] = "TURNS.DBF", FORMAT=DBF FILEO NETO = "TOLLLOAD.NET" FILEO PATHO[1] = "TOLLPATH.PTH" FILEO JUNCTIONO = "JUNCTION1.DAT" FILEO MATO[1] = "TOLLSKIM.MAT", MO=1-5,99 NAME=PATHCOST,COST,PATHTOLL,TIME,VEHTOLLS,LOADS PAR MAXITERS=20 TURNS N=1-9999 PROCESS PHASE=LINKREAD C = LI.CAP IF (LI.FUNC_CLASS = 1-2) LW.COEF=0.15 LW.EXPO=8.00 ELSE LW.COEF=0.15 LW.EXPO=4.00 ENDIF ENDPROCESS PROCESS PHASE=ILOOP ; ----------------------------------------------------------; trips to load MW[99]=MI.1.1+MI.1.2 ; ----------------------------------------------------------; Assign WITH TOLL COST CONSIDERED PATHLOAD PATH=COST, VOL[1]=MW[99],

Cube Voyager Reference Guide 259

Highway Program Examples

PENI=1 TOLLMATI=1,1, TOLLFACTOR=2.0, ; toll factor is in min/toll units, ; here 2min/$ (implies VOT=$30/hr) MW[1]=PATHCOST, NOACCESS=0, MW[2]=PATHTRACE(COST,1), NOACCESS=0, MW[3]=PATHTOLL, MW[4]=PATHTRACE(TIME,1),NOACCESS=0, MW[5]=mw[3]*mw[99] ; cross trips with tolls ENDPROCESS PROCESS PHASE=ADJUST function { tc=t0*(1.0+LW.COEF*((v/c)^LW.EXPO)) ; congested time function for major roads } ENDPHASE ENDRUN

260 Cube Voyager Reference Guide

Cube Voyager Reference Guide

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

Intersection Modeling Introduction to intersection modeling

Introduction to intersection modeling


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

Why use intersection modeling?


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

262 Cube Voyager Reference Guide

Intersection Modeling Introduction to intersection modeling

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

How the intersection models work


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

Limitations of intersection modeling


As noted above, intersection modelling tends to make the overall network model less stable. Consequently the assignment may take many more iterations to converge. Indeed, using the default method of combination, the model may never reach adequate levels of convergence. If necessary, you can change to using COMBINE=AVE to guarantee eventual convergence.
NOTE: A global minimum capacity of 1 vehicle (or PCU) per hour is

now enforced. A PCU is similar to a vehicle but it is adjusted for vehicle length, so a car counts 1, a bus counts 2. Trucks vary between 1.5 (light van) and 2.5 (tractor-trailer).

Cube Voyager intersection modelling and other programs


This chapter describes only those junction description keywords that are directly relevant to Cube Voyager intersection modelling. However there are several other keywords permitted in an intersection description. Some of these extra keywords are used by

Cube Voyager Reference Guide 263

Intersection Modeling Introduction to intersection modeling

Cube graphics to assist in editing and display of intersections. Some of these extra keywords are used to preserve data that is required or used by Cube Dynasim.

264 Cube Voyager Reference Guide

Intersection Modeling Control statements

Control statements
A junction file contains a sequence of statements, of which at most one is a UNITS statement, and the remainder are JUNCTION statements. This section describes: JUNCTION UNITS

JUNCTION
Each JUNCTION statement describes the control of some particular intersection in the network. It follows the usual syntax for Cube Voyager script statements. Comments, also following the usual Cube Voyager script syntax, are also allowed in the file.
JUNCTION statement keyword overview
Priority Saturation v v v v Roundabout Gap acceptance v v Roundabout Empirical v v v Signals Geometric v v v v v v v Signals Saturation v v v v v

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

Allway Stop v v

Priority Geometric v v

Twoway Stop v v

Cube Voyager Reference Guide 265

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|

|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

Intersection Modeling Control statements

JUNCTION statement keyword overview (continued)


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

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

Allway Stop v v v v v v

Priority Geometric v v v v v minor only v v v

Twoway Stop v v v v minor only v v v

See the individual topics for descriptions of each keyword.

UNITS
Defines units of measurement for junction geometry. UNITS LENGTH

Cube Voyager Reference Guide 267

Intersection Modeling Control statements

This statement defines whether the lengths used to define junction geometry are measured in feet or meters. The value of the Length may be either feet or meters (case insensitive). At most one UNITS statement may appear in a junction file. If no UNITS statement is found, measurements will be taken to be in meters. The keywords, in the Junction statement, that have units of length are: AverageLaneWidth, ApproachWidth, EntryWidth, EntryRadius, FlareLength, InscribedDiameter, Width, Visibility, MajorRoadWidth and CentralReservationWidth.
Example
UNITS LENGTH=FEET UNITS LENGTH=METERS

268 Cube Voyager Reference Guide

Intersection Modeling Common keywords

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

APPROACH
The APPROACH keyword takes a list of integers as its value. It has two functions within the junction description:
1. It begins a sequence of keywords which describe the specified

approach. This sequence continues until the next occurrence of Node, Type, LaneAdjust, CentralBusinessDistrict, CycleTime, Phase, MajorRoadWidth, CentralReservationWidth, StorageSpace, FourLaneMajor, Approach1, Approach, or the end of the JUNCTION statement.
2. It describes how neighbors of the modeled node are grouped

into approaches. The value of the keyword is a list of node numbers of nodes adjacent to the node being modeled. The grouping of neighboring nodes into a single approach may be necessary, for example, because Cube Voyager can only model

Cube Voyager Reference Guide 269

Intersection Modeling Common keywords

three- or four-legged intersections (although, at roundabouts, this restriction may be overcome by modeling the circulating section explicitly); because some of the neighbors are fictional (for example, zone centroid connectors); or because the two lanes of a road are represented by individual links. Every node, which is a neighbor of the modeled node, must appear in exactly one Approach clause. Cube Voyager requires that the legs of a junction can be assigned a clockwise ordering by using the coordinates of the nodes involved. Any grouping of links into legs must not invalidate the ordering. For example, in the diagram below, a is a modeled node. Any valid approach which includes both nodes b and d must also include node c.

270 Cube Voyager Reference Guide

Intersection Modeling Common keywords

APPROACH1
Every junction description must contain exactly one occurrence of the integer-valued keyword APPROACH1. Its value is the node number of a node adjacent to the modeled node, Node. The approach containing the specified node, is taken to be the first approach and the other approaches are numbered in relation to it. By default, the approaches are numbered in anti-clockwise order, but if LEFTDRIVE = y is in force, the approaches are numbered in clockwise order. At two-way stop-controlled and priority (two-way yield-controlled) intersections, the first and third approaches are major and the second and fourth (if any) approach are minor. At three-legged intersections, the value of APPROACH1 determines which movements are available from each approach:
LeftDrive = n First Approach Second Approach Third Approach Through Right Right Left Left Through LeftDrive = y Through Left Left Right Right Through

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

ENABLE
Every junction description may contain at most one occurrence of the logical-valued keyword ENABLE. If it has the value false, Cube Voyager will ignore the entire junction description (that is, no intersection modeling will occur at the node).

Cube Voyager Reference Guide 271

Intersection Modeling Common keywords

ENABLE is a quick way of turning modeling on and off at a

particular node from within the junction file during model development. Modeling can also be turned on and off in the Cube Voyager Highway script file using the N clause of the FILEI JUNCTIONI command.

ESTIMATEDDELAY
NOTE: Keywords are case insensitive. Capitalizing as EstimatedDelay might improve readability.

This real valued keyword specifies the delays, in minutes per vehicle, to be used during the first PATHLOAD command to be executed. This occurs prior to the first Adjust phase, so no calculated values will be available yet. Once an Adjust phase has been executed, calculated values will replace these initial estimates. By default, a value of 0.0 minutes is used. However, in urban areas, this is a very poor estimate and it is very desirable that better values be supplied. An approachs ESTIMATEDDELAY value is analogous to a links initial travel time. On the assignments first iteration, no volumes exist yet to use for junction-delay calculations. During the first iteration, this user-specified value provides an initial estimate of the movement delay during path building.

EXITONLY
NOTE: Keywords are case-insensitive. Capitalizing as ExitOnly might

improve readability. For any approach, EXITONLY=y indicates that the leg is not an approach; it is an exit only. No other keywords, except EXITLANES, may be coded for the approach.

272 Cube Voyager Reference Guide

Intersection Modeling Common keywords

The coding of EXITONLY must agree with the network (that is, the exit only approach must correspond to a set of one-way links leading away from the modeled intersection).

INITIALQUEUE
NOTE: Keywords are case insensitive. Capitalizing as InitialQueue might improve readability.

This is the number of vehicles (pcu) that are waiting to make the specified movement from the specified approach at the beginning of the model period. It defaults to zero.
INITIALQUEUE is the queue at the start of the modeled period. INITIALQUEUE generates additional delay after Cube Voyager

assigns flows and calculates delay because the vehicles arriving during the assignment must wait for the queue in front of them to discharge before they reach the stop line (or give-way line). Consequently, if there is no assignment (that is, just path building for skimming), INITIALQUEUE has no effect. Note that the initial queues discharge rate is not a constant; the discharge rate depends on the junctions conflicting flows. Rather than being additional time added to the delay at the end of the process, INITIALQUEUE is more like additional demand added to the assigned demand prior to junction calculations. However, the delay to the vehicles in the initial queue is not part of the results. The results only include the delay that these initially queueing vehicles cause to the vehicles that arrive during the modeled period.

MINIMUMCAPACITY
The MINIMUMCAPACITY keyword takes a positive value in vehicles per hour as its argument. It is coded by approach. If no value is coded, a default value of one vehicle per hour is applied. If the calculated capacity for any stream from an approach is less than the minimum capacity value for that approach, the minimum capacity will be used instead of the calculated value. This substitution occurs before any delay calculations are started.

Cube Voyager Reference Guide 273

Intersection Modeling Common keywords

The minimum capacity is most likely to apply when a movement is very lightly trafficked but is very heavily opposed. In this circumstance, the delay for the lightly trafficked movement will be close to 60/MinimumCapacity (that is, the default value leads to delays being estimated as an hour). The default minimum capacity of one vehicle per hour is sufficient to prevent division by zero errors from crashing program execution but there are two arguments in favor of applying a higher value:
1. Modeling expediency: If a minimum capacity of one vehicle per

hour results in a predicted delay of the order of an hour, trips will be diverted away from that turn during subsequent iterations. So long as the turn has low traffic there is little reason for the turn model to allocate capacity to that movement (especially at adaptive signal models where the signal optimizer will be trying to allocate the available green time where the flow is heaviest). Thus a positive feedback may occur between having low traffic on the turn and having high delay on the turn.
2. Driver behavior: If conditions are very congested, drivers will no

longer wait for an appropriate gap in the opposing stream. Eventually, they will just force their way into a smaller gap. This is especially true when the opposing stream is a slow moving queue.

MOVEMENT
The MOVEMENT keyword takes one of three case-insensitive values: Left Right Through

Each occurrence begins a sequence of keywords which describe the specified movement from the current approach. The sequence continues until the next occurrence of APPROACHWIDTH, AVERAGELANEWIDTH, BUSBLOCKAGE, CAPACITYINTERCEPT,

274 Cube Voyager Reference Guide

Intersection Modeling Common keywords

CAPACITYSLOPE, ENTRYANGLE, ENTRYRADIUS, ENTRYWIDTH, EXITONLY, FLARELENGTH, GRADE, INSCRIBEDDIAMETER, MINIMUMCAPACITY, MOVEMENT, NUMBEROFLANES, PARKINGMANEUVERS, RANDOMNESS, SINGLELANE, TURNCHANNELIZED, FREEFLOWCAP, or the end of the approach.

Care should be taken when coding CRITICALGAP and FOLLOWUPTIME which can occur as keywords at both the approach and movement levels. When coding gap-acceptance roundabouts, these two keywords should appear within each approach, before any movements for that approach are described. When coding two-way stop-controlled intersections, it will not usually be necessary to code CRITICALGAP or FOLLOWUPTIME, but if they are coded they must be coded by movement.

NODE
Every junction description must contain exactly one occurrence of the integer-valued keyword NODE. Its value is the node number of the junction to be modeled.

RANDOMNESS
RANDOMNESS is a real-valued keyword which specifies how random the service times are with respect to the arrival times. Its value must satisfy the inequality 0.0 < RANDOMNESS <= 1.0. At geometrically modeled signals, the platoon ratio is estimated as 2(1.0 - RANDOMNESS)

By default, RANDOMNESS is 0.55 for signalized intersections and 1.0 for unsignalized intersections. These values are appropriate for isolated junctions (that is, arrivals are random). The lower value for signals reflects that even if arrivals at a signal are random, the service times depend on whether the arrival was at a green signal aspect or a red one. However, in urban areas where there are signal linkage effects, the appropriate RANDOMNESS values are reduced. RANDOMNESS values of 0.1 or 0.2 are appropriate for signals in advanced traffic

Cube Voyager Reference Guide 275

Intersection Modeling Common keywords

management systems (for example, SCOOT, SCATS, OPAC) or in offline signal plans at the time that they are installed. Unsignalized intersections in this region should have RANDOMNESS values of the order 0.3 or 0.4. Offline signal plans are generally not completely up to date so they are usually more random than ATMS. Consequently, in areas where offline signal plans operate RANDOMNESS values for signals should be 0.3 or 0.4; values of 0.6 to 0.8 are appropriate for unsignalized intersections in these areas. When using dummy links to model internal parts of a signal (such as modelling a five-armed signal as two nodes) synchronization across the dummy link is perfect. Therefore, code very low values of randomness, such as 0.01, for the relevant approaches.

TYPE
Every junction description must contain exactly one occurrence of the keyword TYPE. It determines the type of junction to be modeled. Its value should be taken from the following list: Roundabout Priority FixedTimeSignal Adaptive Signal TwoWayStop AllWayStop

The keywords are case insensitive; the capitalization in the list above is merely to improve readability. Note that the type field only distinguishes between different types of intersection on the ground. When Cube Voyager offers more than one methodology for modeling a particular kind of junction control, other keywords will be used to distinguish between them:

276 Cube Voyager Reference Guide

Intersection Modeling Common keywords

The presence or absence of CRITICALGAP and FOLLOWUPTIME (by approach) distinguishes between gap-acceptance and empirical roundabout modeling The presence or absence of MAJORROADWIDTH distinguishes whether a priority junction uses geometric modeling or measured saturation flows The value of LANEADJUST distinguishes whether a fixed time signal uses geometric modeling or measured saturation flows

The exception to the above rule is signals when there are several layers of choice of modeling methodology. When observed baseyear signal settings are available, use TYPE=FixedTimeSignal to perform delay calculations for those settings. However, given a feasible signal setting and a set of constraints, Cube Voyager can optimize the settings for the forecast flows. This facility is invoked using TYPE=AdaptiveSignal. (Note that when forecasting future years, adaptive modeling is always recommended; even if the signal controller is fixed time, some traffic engineer will reset the signals every few years.) The next level of modeling methodology chooses between calculating capacities using supplied saturation flows or calculating them using the methodology described in HCM 2000, Chapter 16. The HCM methodology is invoked using the keyword LANEADJUST. Both methodologies may be invoked either using supplied settings or adaptive green time calculations. Note that the HCM methodology can model semi-actuated signal controllers. Giving the keyword UnitExtension to a positive value for some approach invokes this model. The issues of adaptive settings (that is, future or base year) and actuated controllers (that is, hardware in the field) are independent of each other. When HCM capacity calculations are executed, by default Cube Voyager also applies the HCM delay calculations. However, for all other models, a delay equation formulated by Ian Catling is used. If you code DELAYEQUATION=Catling you can force the use of Catlings delay formulation at an HCM signals.

Cube Voyager Reference Guide 277

Intersection Modeling Common keywords

Note that the type of control called a priority junction in the U.K. (where they are very common) would be called a two-way yieldcontrolled intersection in the U.S. (where stop-controlled intersections are the norm).

278 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

Signal-controlled intersections
This section describes signal controls. Topics include: Overview of signals Generic keywords Geometric keywords Geometric signals example Saturation flow signals example

Overview of signals
Signalized intersections are controlled by sets of traffic lights. At any given time, vehicles making a particular movement through the intersection will see a particular signal aspect: In the U.K., red, green, amber, red amber, flashing amber. In the U.S., green, yellow, red, green.

Modelers reclassify the aspect into effective green (when the traffic can go) and effective red (when the traffic stops). Note that effective green begins and ends later than actual green (due to reaction times). A set of signal aspects for all movements through an intersection is called a phase. Note that the total duration of all the phases should be significantly less than the duration of the signal cycle. The difference is primarily due to two factors: lost time while the signals are changing phase and pedestrian phases. Cube Voyager offers two ways of modeling the capacity of signals. There is a detailed model of junction geometry, which has been calibrated to traffic conditions in the U.S., and there is a model which requires saturation flows to be estimated or measured externally, which has been calibrated to traffic conditions in the U.K. The detailed model also imposes more constraints on the allowed signal phasing than the saturation flow only model.

Cube Voyager Reference Guide 279

Intersection Modeling Signal-controlled intersections

A left turn (right turn when LEFTDRIVE=T) which sees a green phase will either be protected (that is, no opposing flow is running) or permitted (that is, the vehicles must give way to some oncoming traffic). Both methodologies can model both permitted and protected phases. Cube Voyager does not offer any model of right turn on red although this is allowed in many areas of the U.S. (The LEFTDRIVE=T equivalent, left turn on red, is not permitted in the U.K.) This is best handled by introducing a dummy link into the network, allowing the right-turners to bypass the signal control, and omitting some lane(s) from the definition of the approach.

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

CANSHARELEFT
NOTE: Keywords are case insensitive. Capitalizing as CanShareLeft

might improve readability. This keyword specifies that there is a shared lane to the left of the exclusive lanes for this movement (that is, the movement can share with the movement to its left). Note that this keyword does not

280 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

mean can share with left turners unless either the movement is THROUGH or the movement is on the minor leg of a three-arm junction. If a movement has CANSHARELEFT = T coded, then there must be a movement to this movements left and the movement to this movements left must have CANSHARERIGHT = T coded. If SINGLELANE = T then CANSHARELEFT should not be coded.

CANSHARERIGHT
NOTE: Keywords are case insensitive. Capitalizing as CanShareRight

might improve readability. This keyword specifies that there is a shared lane to the right of the exclusive lanes for this movement (that is, the movement can share with the movement to its right). Note that this keyword does not mean can share with right turners unless either the movement is THROUGH or the movement is on the minor leg of a three-arm junction. If a movement has CANSHARERIGHT = T coded, then there must be a movement to this movements right, and the movement to this movements right must have CANSHARELEFT = T coded. If SINGLELANE = T then CANSHARERIGHT should not be coded.

CYCLETIME
NOTE: Keywords are case insensitive. Capitalizing as CycleTime

might improve readability. This real-valued keyword is required for all signals. Its value is the length of the signal cycle in seconds. The cycle time must be strictly greater than the sum of all the coded green times.

Cube Voyager Reference Guide 281

Intersection Modeling Signal-controlled intersections

At actuated signals, the CYCLETIME value is taken to be part of the example feasible solution and the subkeywords MAXIMUM and MINIMUM may be used to supply constraints. For example: Actual Cycle = 120, Minimum = 60, Maximimum=180, If no constraints are placed on the cycle time at an adaptively modeled signal, the constraints will be deduced from the constraints on the individual green times.

EXCLUSIVELANES
NOTE: Keywords are case insensitive. Capitalizing as ExclusiveLanes

might improve readability. This integer-valued keyword gives the number of lanes, on the specified approach, which are reserved for the exclusive use of vehicles making the specified movement. If SINGLELANE = T, then EXCLUSIVELANES should not be coded.

LANEADJUST
NOTE: Keywords are case insensitive. Capitalizing as LaneAdjust might improve readability.

Set LANEADJUST to Y at a signal to invoke the HCM2000 capacity calculations. Set LANEADJUST to N at a signal if you are supplying saturation flows.

PHASE and ACTUALGREEN


These keywords occur in pairs; every occurrence of the integervalued keyword, PHASE must be followed by a single occurrence of the real-valued keyword ACTUALGREEN. There should be one such pair for each phase of the signals during which vehicles move (that is, all-red and/or pedestrian phases should not be coded).

282 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

The values of the PHASE keyword should form a continuous sequence, starting at one and increasing, without gaps, until the number of phases is reached. Every phase must be mentioned in a PHASE keyword for some movement at the intersection. The value of the ACTUALGREEN keyword is the duration, in seconds, of the effective green-time associated with the phase. The effective green time is the period during which vehicles move across the stop line. It starts shortly after the signals change to green (because the vehicle drivers must react to the change in signal aspect) and continues through the following red/yellow. If the signal is being modeled adaptively, then the keywords maximum (required) and minimum (optional) may be used to specify constraints, and the coded value of ACTUALGREEN is taken to be part of the example feasible solution. If no minimum is applied, Cube Voyager may remove the phase altogether (that is, set green-time to zero).

PHASES
The keyword PHASES is integer-valued but, conceptually, it consist of either one phase number (that is, digit) or of two phase numbers (that is, two digits). The vehicles making the movement see a green signal aspect when the specified phase(s) is/are running and red otherwise. Note that the (node-level) keyword PHASE is used to define phases and the (movement-level) keyword PHASES associates movements with the defined phases. At geometrically specified signals, then any two-digit phase specifications must specify contiguous phases. No such restriction is required when saturation flows are coded.

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

Cube Voyager Reference Guide 283

Intersection Modeling Signal-controlled intersections

This real-valued keyword allows the specification of saturation flows in pcu (vehicles) per hour per lane. Saturation flows at signals are the flows that would be observed if the movement had a continuous green all other movements had no flow and no green. Saturation flow at a priority junction (two-way yield-controlled intersection) is defined similarly, except that no signal aspects are involved.

SINGLELANE
NOTE: Keywords are case-insensitive. Capitalizing as SingleLane might improve readability.

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

Priority intersection (two-way yieldcontrolled intersection)

Saturation Flows Roundabout Empirical Gap Acceptance

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

284 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

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

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

AVERAGELANEWIDTH
NOTE: Keywords are case insensitive. Capitalizing as AverageLaneWidth might improve readability.

This real-valued keyword describes the mean lane width, in meters or feet, of an approach to a geometrically modeled signalized junction. If no value is provided, a default of 3.6m is used. The average lane width must be in the range from 2.4m to 4.8m. If the value falls outside this range, the approach should be recoded to have more or fewer lanes, as appropriate.

Cube Voyager Reference Guide 285

Intersection Modeling Signal-controlled intersections

CONFLICTINGBIKE
NOTE: Keywords are case insensitive. Capitalizing as ConflictingBike might improve readability.

The flow of bicycles in from the curb-side lane in units of bicycles per hour. Bicycle traffic which weaves with turning traffic in advance of the stop line should be excluded from this value, because these bicycles do not interact with the other vehicles while they are still within the intersection. The diagram below illustrates the relevant bicycle flow for right hand rule of the road. In the diagram, the crossed box is the bicycle conflict zone where right turning traffic may be impeded by any bicycles crossing the intersection. The CONFLICTINGBIKE is the flow of bicycles through this region.

BUSBLOCKAGE
NOTE: Keywords are case insensitive. Capitalizing as BusBlockage

might improve readability. The real values supplied to this keyword are number of buses stopping per hour. The first element refers to the normal curb side of the road; the second refers to the other side of the road (for example, if there is a tram line in the center of the road or there is a

286 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

bus stop on the offside of a one-way street). Only buses stopping within 75 meters (246 feet) of the stop line (either upstream or downstream) should be included. This keyword is only applicable at geometrically modeled signals.

CENTRALBUSINESSDISTRICT
NOTE: Keywords are case insensitive. Capitalizing as CentralBusinessDistrict might improve readability. You can also use

the abbreviation, CBD.


CENTRALBUSINESSDISTRICT is a logical-valued keyword which may

be applied at geometrically-modeled fixed-time signals. Coding


CENTRALBUSINESSDISTRICT=Y causes all calculated capacities to be

90% of the value that would be obtained otherwise.

DELAYEQUATION
Selects the delay modeling methodology applied to the capacities calculated by the HCM2000 signal capacity modeling methodology. The keyword accepts the values HCM or Catling (case-insensitive). By default, The HCM delay equations are invoked.

EXITLANES
The number of lanes traveling away from the modeled intersection. This key may occur on the same arm as the EXITONLY keyword but is invalid for a one-way link that travels towards the intersection. Cube Voyager only uses this value for pedestrian and bicycle modeling.
NOTE: If exit lanes are omitted from an arm that pedestrians cross,

the capacity of movements entering the arm may be reduced significantly.

Cube Voyager Reference Guide 287

Intersection Modeling Signal-controlled intersections

GRADE
The real-valued keyword GRADE describes the grade, expressed as a percentage, of an approach to a geometrically modeled signals or a two-way stop-controlled intersection. It is a signed value; negative values indicate that the approach is downhill and positive values indicate that the approach is uphill. By default the approach is assumed to be flat (GRADE = 0). The models have been calibrated for grades the range -6% to +11%, but more extreme grades do occur. For example the maximum grade in San Francisco is about 31%.

PARKINGMANEUVERS
NOTE: Keywords are case insensitive. Capitalizing as ParkingManeuvers might improve readability.

The real values supplied to this keyword are number of maneuvers per hour. The first element refers to the normal curb side of the road; the second refers to the other side of the road (that is, if there is parking in a central reservation or on the offside of a one way street). Only parking within 80 meters of the stop line should be included By default, parking is not allowed. Coding PARKINGMANUEVERS = 0 means that parking is allowed, but it is extremely rare. This keyword is only applicable at geometrically modeled signals.

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

PEDESTRIANPHASE
The keyword PEDESTRIANPHASE is integer-valued but, conceptually, it consist of either one phase number (that is, digit) or of two phase numbers (that is, two digits). In this respect, it is like

288 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

the keyword PHASES. The phases mentioned are the phases when pedestrians crossing the approach are given permission to use the crosswalk. The symbols displayed to the pedestrians vary by country, for example in the U.S. the word WALK or an icon of a man walking is displayed in white whereas in the U.K. an icon of a man walking is displayed in green. If using a two-digit number, the two phases must be adjacent.

PHASES
The keyword PHASES is integer-valued but, conceptually, it consist of either one phase number (that is, one digit) or of two phase numbers (that is, two digits). The vehicles making the movement see a green signal aspect when the specified phase(s) is/are running and red otherwise. Note that the (node-level) keyword PHASE is used to define phases and the (movement-level) keyword PHASES associates movements with the defined phases. At geometrically specified signals, any two-digit phase specifications must specify contiguous phases. No such restriction is required when coding saturation flows.

UNITEXTENSION
The minimum gap, in seconds, between successive vehicles moving on a traffic-actuated approach to a signalized intersection that will cause the signal controller to terminate the green display.

Geometric signals example


Cube Voyager does not contain a model for right turn on red. The right filter phase coded below might be used as a proxy for RTOR when the right turns are heavy.
Junction, Node = 276, laneadjust=t, Type = FixedTimeSignal,

Cube Voyager Reference Guide 289

Intersection Modeling Signal-controlled intersections

Approach1 = 291, CycleTime = 90, Phase = 1, ActualGreen = 59, Phase = 2, ActualGreen = 5, Phase = 3, ActualGreen = 11, Approach = 291, AverageLaneWidth = 3.6, minimumcapacity=50, Movement = Left, ExclusiveLanes = 1, EstimatedDelay = 0.1, Phases = 1, Movement = Through, EstimatedDelay = 0.1, ExclusiveLanes = 1, Phases = 1, Movement = Right, ExclusiveLanes = 1, EstimatedDelay = 0.1, Phases = 12, Approach = 264, AverageLaneWidth = 3.6, minimumcapacity=50, Movement = Left, EstimatedDelay = 0.3, ExclusiveLanes = 1, Phases = 3, Movement = Through, EstimatedDelay = 0.3, Phases = 3, ExclusiveLanes = 1, Movement = Right, EstimatedDelay = 0.3, ExclusiveLanes = 1, Phases = 32, Approach = 267, AverageLaneWidth = 3.6, minimumcapacity=50, Movement = Left, ExclusiveLanes = 1, EstimatedDelay = 0.1, Phases = 1, Movement = Through,

290 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

EstimatedDelay = 0.1, ExclusiveLanes = 1, Phases = 1, Movement = Right, ExclusiveLanes = 1, EstimatedDelay = 0.2, Phases = 12, Approach = 306, AverageLaneWidth = 3.6, Movement = Left, EstimatedDelay = 0.2, ExclusiveLanes = 1, Phases = 3, Movement = Through, EstimatedDelay = 0.2, Phases = 3, ExclusiveLanes = 1, Movement = Right, EstimatedDelay = 0.2, ExclusiveLanes = 1, Phases = 32

Saturation flow signals example


This example illustrates the coding of fixed-time signals:
Junction, Node = 276, Type = FixedTimeSignal, Approach1 = 291, CycleTime = 90, Phase = 1, ActualGreen = 59, Phase = 2, ActualGreen = 5, Phase = 3, ActualGreen = 11, Approach = 291, Movement = Left, CanShareRight=y, EstimatedDelay = 0.1, Phases = 1, Movement = Through, CanShareLeft=y, EstimatedDelay = 0.1,

Cube Voyager Reference Guide 291

Intersection Modeling Signal-controlled intersections

ExclusiveLanes = 1, Phases = 1, Movement = Right, ExclusiveLanes = 1, EstimatedDelay = 0.1, Phases = 2, Approach = 264, Movement = Left, EstimatedDelay = 0.3, CanShareRight=y, Phases = 3, Movement = Through, EstimatedDelay = 0.3, CanShareLeft=y, Phases = 3, ExclusiveLanes = 1, Movement = Right, EstimatedDelay = 0.3, ExclusiveLanes = 1, Phases = 23, Approach = 267, Movement = Left, CanShareRight=y, EstimatedDelay = 0.1, Phases = 1, Movement = Through, CanShareLeft=y, EstimatedDelay = 0.1, ExclusiveLanes = 1, Phases = 1, Movement = Right, ExclusiveLanes = 1, EstimatedDelay = 0.2, Phases = 2, Approach = 306, Movement = Left, EstimatedDelay = 0.2, CanShareRight=y, Phases = 3, Movement = Through, EstimatedDelay = 0.2, CanShareLeft=y, Phases = 3, ExclusiveLanes = 1, Movement = Right, EstimatedDelay = 0.2,

292 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

ExclusiveLanes = 1, Phases = 23

Cube Voyager Reference Guide 293

Intersection Modeling Two-way stop-controlled intersections

Two-way stop-controlled intersections


This section describes two-way stop-controlled intersections. Topics include: Overview Keywords Example

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

294 Cube Voyager Reference Guide

Intersection Modeling Two-way stop-controlled intersections

The capacity model, which has been implemented in Cube Voyager, is a gap-acceptance model that has been calibrated against traffic conditions in the USA. Users in other countries may need to adjust the base critical gap and base follow up time to reflect local conditions. If there is a central reservation, or there are islands, between the lanes of the major road, minor road traffic, which crosses the major road, may do so in two stages. First the vehicle crosses to the central reservation; then it completes its movement through the intersection. This situation is enabled when a non-zero value of storage space is coded. The value is the number of vehicles which can wait in the center of the major road without obstructing major road flows.

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

Cube Voyager Reference Guide 295

Intersection Modeling Two-way stop-controlled intersections

CRITICALGAP
NOTE: Keywords are case insensitive. Capitalizing as CriticalGap

might improve readability. The critical gap, in seconds, is one of the parameters of any gapacceptance capacity model. At two-way stop-controlled intersections, it is applicable by movement. It is defined as the minimum time interval in a higher priority stream that allows intersection entry for one vehicle. Note that the coded value is the base critical gap. It is modified to allow for junction geometry. The default value depends on the movement:
Base critical gap (seconds)
Vehicle Movement Left turn from major Right turn from minor Through traffic on minor Left turn from minor Two-Lane Major Street 4.1 6.2 6.5 7.1 Four-Lane Major Street 4.1 6.9 6.5 7.5

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

FLARESTORAGE
The number of vehicles that may queue in the flared region of a minor approach without disrupting the flowing or queueing of traffic in the main lane. By default this value is zero, that is, no or negligible flare.

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

296 Cube Voyager Reference Guide

Intersection Modeling Two-way stop-controlled intersections

The follow-up time, in seconds, is one of the parameters of any gapacceptance capacity model. At two-way stop-controlled intersections, it is applicable by movement. It is defined as the time between the departure of one vehicle the next using the same gap in a higher priority stream, under a condition of continuous queuing on the entry. The default value depends on the movement:
Vehicle Movement Left turn from major Right turn from minor Through traffic on minor Left turn from minor Base Follow-Up Time (seconds) 2.2 3.3 4.0 3.5

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

FOURLANEMAJOR
NOTE: Keywords are case insensitive. Capitalizing as FourLaneMajor might improve readability.

This logical-valued keyword determines the number of lanes on the major road of a two-way stop-controlled intersection. If FourLaneMajor = y is coded, then the major road has two lanes in each direction (total four); otherwise the major road has one lane in each direction (total 2).

FREEFLOWCAP
NOTE: Keywords are case insensitive. Capitalizing as FreeFlowCap

might improve readability. This value is only relevant for major approaches where FOURLANEMAJOR is false. It is the capacity for the unmodelled movements from the arm. By default, these movements have

Cube Voyager Reference Guide 297

Intersection Modeling Two-way stop-controlled intersections

infinite capacity, which, when combined with the capacity of the modelled turn, gives strange large capacities in the results. If you code a sensible value (such as 1800 vph), the resulting capacity will be reduced, but there will be a corresponding increase in delays.

GRADE
The real-valued keyword GRADE describes the grade, expressed as a percentage, of an approach to a geometrically modeled signals or a two-way stop-controlled intersection. It is a signed value; negative values indicate that the approach is downhill and positive values indicate that the approach is uphill. By default the approach is assumed to be flat (GRADE = 0). The models have been calibrated for grades the range -6% to +11%, but more extreme grades do occur. For example the maximum grade in San Francisco is about 31%.

PEDESTRIANFLOW
The number of pedestrian platoons crossing the approach per hour. Pedestrians may cross the road singly, or they may cross in groups, two or three abreast. Each such group counts as one pedestrian platoon. For more details of pedestrian platoons refer to Chapter 18 of HCM 2000, especially to Equation 18-18 and the surrounding text.

PEDESTRIANSPEED
The average speed at which pedestrians cross the approach in feet or meters per second. By default this value is 1.2 meters or, equivalently, 4 feet per second.

SINGLELANE
NOTE: Keywords are case insensitive. Capitalizing as SingleLane

might improve readability.

298 Cube Voyager Reference Guide

Intersection Modeling Two-way stop-controlled intersections

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

Priority intersection (two-way yield-controlled intersection)

Saturation Flows Roundabout Empirical Gap Acceptance

Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES, CANSHARERIGHT, or CANSHARELEFT on that approach. At two-way stop-controlled intersections and priority junctions, a minor arm, which does not have SINGLELANE = Y explicitly coded, has two lanes.

STORAGESPACE
NOTE: Keywords are case insensitive. Capitalizing as StorageSpace

might improve readability.

Cube Voyager Reference Guide 299

Intersection Modeling Two-way stop-controlled intersections

This integer-valued keyword applies to two-way stop-controlled intersections. It is the number of vehicles (PCU) that can wait in the central reservation without impeding major road traffic. It does not matter whether the central reservation is curbed or striped (ghost islands).

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

300 Cube Voyager Reference Guide

Intersection Modeling Two-way stop-controlled intersections

The turn referred to is the turn which follows the curb (by default, the right turn; when LEFTDRIVE = T, the left turn). The turn is said to be channelized if there is a triangular, curbed island separating the turners from the other movements on the approach. The effect of turn channelization is ensure that the turning flows do not act as conflicting flows during the calculation of capacities on other legs. Setting TURNCHANNELIZED to T for an approach indicates that the unopposed turn from that approach is channelized. By default, no turns are channelized.

Example
The example describes a two-way-stop-controlled intersection with two-lane majors, two-lane minors and a central reservation.
Junction Node = 9 Type = TwoWayStop Approach1 = 8, FourLaneMajor = y, StorageSpace = 3, Approach = 6, TurnChannelized = y, Approach = 7, Approach = 8, Approach = 5,

Cube Voyager Reference Guide 301

Intersection Modeling All-way-stop-controlled intersections

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

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

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

302 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

Roundabouts
This section describes roundabouts. Topics include: Overview of roundabouts Empirical roundabouts: Keywords Empirical roundabouts: Example Gap acceptance roundabouts: Keywords Gap-acceptance roundabouts: Example

Overview of roundabouts
Roundabouts are a form of unsignalized intersection in which traffic circulates around a one-way closed lane to travel from an approach to an exit. Traffic on an approach must give way to traffic which is already on the circulating section. There are no constraints on traffic leaving the roundabout. The circulating flow past an entry is the only flow which influences the capacity of that entry. The model builder, therefore, can always represent the circulating lane explicitly in the network, without compromising the modeling of the intersection. Individual roundabout models are placed at each entry. The approach characteristics of the actual roundabout entries remain unchanged. One of the circulating legs is exit only and the other circulating leg should be coded so that vehicles entering the roundabout from

Cube Voyager Reference Guide 303

Intersection Modeling Roundabouts

that approach are not significantly constrained. This technique is particularly useful for modeling roundabouts with five or more legs.

Cube Voyager offers two ways to model roundabouts: Gap-acceptance model Each entry is characterized by a critical gap and a follow-up time. Empirical model Each entry is characterized by a capacity slope and a capacity intercept. You can calculate the slope and intercept outside of Cube Voyager, or you can supply geometric data and let Cube Voyager calculate the slope and intercept using formulas calibrated in the UK. Worldwide experience with roundabouts and roundabout models leads to the following conclusions: When a well calibrated empirical model exists, it should be used in preference to a gap acceptance model However, the calibration of relationships between geometry, on one hand, and slope and intercept, on the other, requires very large amounts of data The number of roundabouts in the US is not yet sufficiently great to allow calibration of a US empirical model Even when general countrywide empirical relationships exist, it may be necessary to fine tune the slope and intercept for local conditions

304 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

When no general countrywide empirical relationships exist, it is better to use a gap acceptance model

The Highway Capacity Manual (HCM 2000) indicates appropriate parameter ranges for a single-lane roundabout entry in the US.

Empirical roundabouts: Keywords


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

APPROACHWIDTH
NOTE: Keywords are case-insensitive. Capitalizing as ApproachWidth might improve readability.

This real-valued keyword allows the specification of the approach half width (in meters or feet), one of the geometric parameters for the U.K.-calibrated empirical roundabout model.

Cube Voyager Reference Guide 305

Intersection Modeling Roundabouts

To measure the approach half width, measure from the road center line to the curb at a point sufficiently far from the roundabout that the curb and center line are parallel. In the diagram below, the double arrow marked v (below the arrow) and AWID (to the left of the arrow) illustrates the measurement.

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

306 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

At an empirically modeled roundabout, each approach is characterized by two real numbers, the capacity slope and the capacity intercept. The capacity intercept is the entry capacity when the circulating flow is zero. The CAPACITYINTERCEPT keyword may be used to supply the capacity intercept directly.

If CAPACITYINTERCEPT is coded for a roundabout entry, CAPACITYSLOPE must also be coded for that entry and none of the roundabout geometric parameters may be coded for that entry.

CAPACITYSLOPE
NOTE: Keywords are case insensitive. Capitalizing as CapacitySlope

might improve readability. At an empirically modeled roundabout, each approach is characterized by two real numbers, the capacity slope and the capacity intercept. The capacity slope is the marginal decrease in

Cube Voyager Reference Guide 307

Intersection Modeling Roundabouts

entry capacity when the circulating flow is increased by one PCU per hour. The CAPACITYSLOPE keyword may be used to supply the capacity slope directly.

If CAPACITYSLOPE is coded for a roundabout entry, CAPACITYINTERCEPT must also be coded for that entry and none of the roundabout geometric parameters may be coded for that entry.

CROSSING2ENTRY
This keyword specifies the position of a zebra crossing on an approach to a roundabout or a minor approach priority junction. Its value is the number of vehicles that may queue at the junction without impeding pedestrians who wish to cross. At roundabouts and single lane minor approaches to priority junctions, a single integer value should be supplied. However, on two-lane minor approaches to priority junctions, separate values should be supplied for each of the two lanes.

308 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

CROSSING2EXIT
This integer-valued keyword specifies the position of a zebra crossing on an exit from a roundabout or priority junction. Its value is the number of vehicles that may queue at the crossing without impeding vehicles using other exits from the junction.

CROSSINGLENGTH
This real-valued keyword allows the specification of the length of a zebra crossing that crosses an approach to a roundabout or priority junction. If it is absent then no crossing will be modeled.

ENTRYANGLE
NOTE: Keywords are case insensitive. Capitalizing as EntryAngle

might improve readability. This real-valued keyword allows the entry angle, theta, of a roundabout to be coded. There are three cases for the measurement of phi.
Case 1: A roundabout with straight weaving sections

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

Cube Voyager Reference Guide 309

Intersection Modeling Roundabouts

Let D be the point on the median island (or line) of the following entry which is nearest to A EF is curve which is in the middle of the area of road for vehicles entering the junction BC is a tangent to EF at the point where EF intersects the stop line phi is the angle between BC and AD

Case 2: A roundabout with long curved weaving sections

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

EF and BC are constructed as in case 1

310 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

JK is constructed in the same way as EF, but for the following exit GH is the tangent to JK where JK meets the edge of the circulating section L is the intersection of BC and GH phi is zero or (90 - (angle GLB)), whichever is greater

ENTRYRADIUS
NOTE: Keywords are case insensitive. Capitalizing as EntryRadius

might improve readability. This real-valued keyword allows the specification of the entry radius (in meters or feet), one of the geometric parameters for the U.K.-calibrated empirical roundabout model. The entry radius is defined as the minimum radius of curvature of the curb line at the entry.

Cube Voyager Reference Guide 311

Intersection Modeling Roundabouts

ENTRYWIDTH
NOTE: Keywords are case insensitive. Capitalizing as EntryWidth might improve readability.

This real-valued keyword allows the specification of the entry width (in meters or feet), one of the geometric parameters for the U.K.calibrated empirical roundabout mode. To measure the entry width: Let A be the point where the stop-line meets the inside edge of the lane Let B be a point on the curb-line such that the line A-B is normal to the curb at B The entry width is the length of the line A-B

In the diagram below, the double arrow marked C and EWID illustrates the measurement.

312 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

FLARELENGTH
NOTE: Keywords are case insensitive. Capitalizing as FlareLength might improve readability.

This real-valued keyword allows the specification of the modified flare length (in meters or feet) for the entry to an empirically modelled roundabout. This is measured using the following procedure:

Let A be the point where the stop line meets the inside edge of the lane. Let B be the point on the curb line such that the line A-B is normal to the curb line at B (A-B is the entry width, e). Let v be the approach width. Let D be a point on A-b such that the length of A-D is v. Let D-G be a curve through D and parallel to the inside edge of the lane. (G is the point where the curve meets the curb). Let C be the mid point of D-B.

Cube Voyager Reference Guide 313

Intersection Modeling Roundabouts

Let C-F be a curve parallel to the curb which intersects the curve D-G at F. The modified flare length is the length of the curve C-F.

INSCRIBEDDIAMETER
NOTE: Keywords are case insensitive. Capitalizing as InscribedDiameter might improve readability.

This real-valued keyword allows the specification of the inscribed circle diameter of the roundabout (in meters or feet). Usually this is the largest circle that can be inscribed wholly within the outline of the junction (see figure below). However, when the intersection is very asymmetrical, a local value in the region of the entry should be taken.

Empirical roundabouts: Example


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

314 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

Node = 213, Type = Roundabout, Approach1 = 223, Approach = 223, EntryWidth = 12.5, ApproachWidth = 7.3, FlareLength = 25.0, InscribedDiameter = 25.0, Approach = 224, EntryWidth = 10.0, ApproachWidth = 6.0, FlareLength = 15.0, InscribedDiameter = 25.0, Approach = 321, EntryWidth = 10.0, ApproachWidth = 6.0, FlareLength = 15.0, InscribedDiameter = 25.0,

After comparing the model results to the performance of the intersection on the ground, it was decided to recode approach 224 to give the slope and intercept directly:
Junction, Node = 213, Type = Roundabout, Approach1 = 223, Approach = 223, CapacitySlope = 0.2, CapacityIntercept = 3600, Approach = 224, EntryWidth = 10.0, ApproachWidth = 6.0, FlareLength = 15.0, InscribedDiameter = 25.0, Approach = 321, EntryWidth = 10.0, ApproachWidth = 6.0, FlareLength = 15.0, InscribedDiameter = 25.0,

Cube Voyager Reference Guide 315

Intersection Modeling Roundabouts

Gap acceptance roundabouts: Keywords


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

CRITICALGAP
Keywords are case-insensitive but the recommended capitalization CriticalGap may improve readability. The critical gap, in seconds, is one of the parameters of any gapacceptance capacity model. At roundabouts, it is applicable by arm. It is defined as the minimum time interval in the circulating stream that allows intersection entry for one vehicle. The U.S. Highway Capacity Manual 2000 suggests that, for a singlelane roundabout entry in the US, the critical gap should be in the range 4.1 to 4.6 seconds.

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

The follow-up time, in seconds, is one of the parameters of any gapacceptance capacity model. At roundabouts, it is applicable by arm. It is defined as the time between the departure of one vehicle from the entry and the departure of the next vehicle using the same circulating flow gap, under a condition of continuous queuing on the entry. The U.S. Highway Capacity Manual 2000 suggests that, for a singlelane roundabout entry in the America, the follow-up time should be in the range 2.6 to 3.1 seconds.

316 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

Gap-acceptance roundabouts: Example


The following illustrates a gap-acceptance roundabout model:
Junction, Node = 253, Type = Roundabout, Approach1 = 32, Approach = 32, 208, CriticalGap = 4.6, FollowUpTime = 3.1, Approach = 256, CriticalGap = 4.35, FollowUpTime = 2.85, Approach = 486, CriticalGap = 4.1, FollowUpTime = 2.6

Cube Voyager Reference Guide 317

Intersection Modeling Priority junctions

Priority junctions
This section describes priority junctions (two-way yield-controlled intersections). Topics include: Overview of priority junctions Keywords Geometric priority junctions: Keywords Geometric priority junctions: Example Saturation-flow priority junctions: Keywords Saturation-flow priority junctions: Example

Overview of priority junctions


A priority-junction control is an unsignalized intersection between a major road and a minor road. It has different names in the U.K. (where priority junctions are common) and the U.S. (where twoway yield-controlled intersections are rare). In the U.S., the minor road approach (at a T), or approaches (at a crossroads) have yield signs. In the U.K., the yield signs are optional. Traffic on the minor need not stop before entering the intersection, but must give way to any major road traffic. Cube Voyager offers two model variants, both of which are calibrated to U.K. traffic conditions: a full empirical model based on junction geometry and a simplified models in which the user provides saturation flows which have been estimated or measured externally to Cube Voyager. When a single-lane major road is being modeled, very large capacities may be reported. This occurs when a movement, which is unconstrained, shares a lane. The capacity is chosen to give the correct ratio of volume to capacity (as calculated for the constrained movement).

318 Cube Voyager Reference Guide

Intersection Modeling Priority junctions

Keywords
This section describes keywords for priority junctions: GEOMETRIC SINGLELANE

GEOMETRIC
The keyword Geometric=y, invokes modeling of layout geometry at a priority junction. The default, GapAcceptance=n, at a priority junction is for the user to supply saturation flows directly.

SINGLELANE
NOTE: Keywords are case insensitive. Capitalizing as SingleLane

might improve readability. The logical-valued keyword is used to indicate that an approach consists of a single lane. It is applicable to many junction types:
Junction type Signals All-way stop-controlled intersection Two-way stop-controlled intersection Priority intersection (two-way yield-controlled intersection) Roundabout Geometric Data Geometric Data Saturation Flows Use SINGLELANE may be coded SINGLELANE may be coded SINGLELANE may not be coded; code NUMBEROFLANES = 1 SINGLELANE may be coded for minor road Use FOURLANEMAJOR to describe major road SINGLELANE may be coded

Saturation Flows Empirical Gap Acceptance

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

Cube Voyager Reference Guide 319

Intersection Modeling Priority junctions

Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES, CANSHARERIGHT, or CANSHARELEFT on that approach. At two-way stop-controlled intersections and priority junctions, a minor arm, which does not have SINGLELANE = Y explicitly coded, has two lanes.

Geometric priority junctions: Keywords


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

CENTRALRESERVATIONWIDTH
NOTE: Keywords are case insensitive. Capitalizing as CentralReservationWidth might improve readability. CENTRALRESERVATIONWIDTH is a real-valued keyword (only)

applicable to geometrically modeled priority junctions. Its value is the width, in meters or feet, of the curbed central reservation in the major road. If there is no central reservation, or the central reservation is composed of ghost islands (that is, road markings), then CENTRALRESERVATIONWIDTH should be zero (the default). Otherwise its value should be in the range from 2.2 to 5.

320 Cube Voyager Reference Guide

Intersection Modeling Priority junctions

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

CROSSING2ENTRY
This keyword specifies the position of a zebra crossing on an approach to a roundabout or a minor approach priority junction. Its value is the number of vehicles that may queue at the junction without impeding pedestrians who wish to cross. At roundabouts and single lane minor approaches to priority junctions, a single integer value should be supplied. However, on two-lane minor approaches to priority junctions, separate values should be supplied for each of the two lanes.

CROSSING2EXIT
This integer-valued keyword specifies the position of a zebra crossing on an exit from a roundabout or priority junction. Its value is the number of vehicles that may queue at the crossing without impeding vehicles using other exits from the junction.

CROSSINGLENGTH
This real-valued keyword allows the specification of the length of a zebra crossing that crosses an approach to a roundabout or priority junction. If it is absent then no crossing will be modeled.

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

Cube Voyager Reference Guide 321

Intersection Modeling Priority junctions

By default, the unmodelled movements from the major approaches of a priority junction have infinite capacity. However, this may result in too large a capacity for the approach as a whole when it must share a lane with a modelled turn. You can supply a capacity for these movements by coding FreeFlowCap=value and SingleLane=t.

MAJORROADWIDTH
NOTE: Keywords are case insensitive. Capitalizing as MajorRoadWidth might improve readability. MAJORROADWIDTH is only applicable to geometrically modeled

priority junctions, where it is required. The presence or absence of this keyword allows the two methodologies for priority junction modeling to be distinguished.
MAJORROADWIDTH is a real valued keyword whose value is the

width, in meters or feet, of the major road lane (excluding any central reservation or ghost islands) near the intersection. It is illustrated in the four diagrams below. In each case the major road width is given by the expression (W1 + W2 + W3 + W4).

322 Cube Voyager Reference Guide

Intersection Modeling Priority junctions

VISIBILITY
This real-valued keyword allows the visibilities, in meters or feet, at a geometrically coded priority junction (two-way yield-controlled intersection) to be entered. Visibilities may be coded for the minor road left and right movements and for the opposed movement from the major road. Minor road visibilities should be measured from a point ten meters before the give-way line and 1.05 meters above the road surface. The major road visibility is measured from the mid-point of the turning lane (again at height 1.05m), along the major road, towards the road center line.

Cube Voyager Reference Guide 323

Intersection Modeling Priority junctions

WIDTH
This real-valued keyword is used to specify the lane widths (in meters or feet) for a minor road at a priority junction (two-way yield-controlled intersection). Code widths for left and right movements on minor roads and for the opposed movement from the major road. The width for the major roads opposed movement is the width of the lane from which vehicles on the major road turn. Coding techniques for minor roads vary with the number of lanes. To describe a two-lane minor road: Do not code SINGLELANE = T. Code the width of the left-hand lane in the left movement. Code the width of the right-hand lane in the right movement.

To describe a one-lane minor road: Code SINGLELANE


= T.

Code the width of the single lane in the left movement, or the right movement, but not both.

The coded widths should be the lanes average width during the final 25 meters of the approach before the give-way line.

Geometric priority junctions: Example


This example illustrates the coding of a three-arm priority junction, with input geometric data.
Junction, Node = 250, Type = Priority, Approach1 = 455, MajorRoadWidth = 10.9, CentralReservation = 1.2, Approach = 455, Movement = Right, Width = 2.5,

324 Cube Voyager Reference Guide

Intersection Modeling Priority junctions

Visibility = 170.0, Approach = 249, Movement = Left, Width = 2.05, Visibility = 130.0, Movement = Right, Width = 2.05, Visibility = 125.0, Approach = 251, Movement = Right, Width = 2.9, Visibility = 150.0, Approach = 255, SingleLane = y, Movement = Left, Visibility = 100.0, Movement = Right, Width = 3.1, Visibility = 127.0

Saturation-flow priority junctions: Keywords


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

CANSHARELEFT
NOTE: Keywords are case insensitive. Capitalizing as CanShareLeft

might improve readability. This keyword specifies that there is a shared lane to the left of the exclusive lanes for this movement (that is, the movement can share with the movement to its left). Note that this keyword does not

Cube Voyager Reference Guide 325

Intersection Modeling Priority junctions

mean can share with left turners unless either the movement is THROUGH or the movement is on the minor leg of a three-arm junction. If a movement has CANSHARELEFT = T coded then there must be a movement to this movements left and the movement to this movements left must have CANSHARERIGHT = T coded. If SINGLELANE = T then CANSHARELEFT should not be coded.

CANSHARERIGHT
NOTE: Keywords are case insensitive. Capitalizing as CanShareRight

might improve readability. This keyword specifies that there is a shared lane to the right of the exclusive lanes for this movement (that is, the movement can share with the movement to its right). Note that this keyword does not mean can share with right turners unless either the movement is THROUGH or the movement is on the minor leg of a three arm junction. If a movement has CANSHARERIGHT = T coded, then there must be a movement to this movements right, and the movement to this movements right must have CANSHARELEFT = T coded. If SINGLELANE = T then CANSHARERIGHT should not be coded.

EXCLUSIVELANES
NOTE: Keywords are case insensitive. Capitalizing as ExclusiveLanes might improve readability.

This integer-valued keyword gives the number of lanes, on the specified approach, which are reserved for the exclusive use of vehicles making the specified movement. If SingleLane = t then ExclusiveLanes should not be coded.

326 Cube Voyager Reference Guide

Intersection Modeling Priority junctions

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

This real-valued keyword allows the specification of saturation flows in pcu (vehicles) per hour per lane. Saturation flows at signals are the flows that would be observed if the movement had a continuous green all other movements had no flow and no green. Saturation flow at a priority junction (two-way yield-controlled intersection) is defined similarly, except that no signal aspects are involved.

Saturation-flow priority junctions: Example


The example describes a priority junction using with a three-lane major and two-lane minor using default saturation flows per lane.
Junction, Node = 229, Approach1 = 396, Type = Priority, Approach = 228, Movement = Left, ExclusiveLanes = 1, CanShareRight = y, Movement = Through, ExclusiveLanes = 1, CanShareLeft = y, CanShareRight = y, Movement = Right, ExclusiveLanes = 1, CanShareLeft = y, Approach = 396, Movement = Left, ExclusiveLanes = 1, CanShareRight = y, Movement = Through, ExclusiveLanes = 1, CanShareLeft = y,

Cube Voyager Reference Guide 327

Intersection Modeling Priority junctions

CanShareRight = y, Movement = Right, ExclusiveLanes = 1, CanShareLeft = y, Approach = 315, Movement = Left, ExclusiveLanes = 1, CanShareRight = y, Movement = Through, CanShareLeft = y, CanShareRight = y, Movement = Right, ExclusiveLanes = 1, CanShareLeft = y, Approach = 409, Movement = Left, ExclusiveLanes = 1, CanShareRight = y, Movement = Through, CanShareLeft = y, CanShareRight = y, Movement = Right, ExclusiveLanes = 1, CanShareLeft = y

328 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Network Program

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

Cube Voyager Reference Guide 329

Network Program Introduction to the Network program

Introduction to the Network program


Network is a utility program for processing highway networks. Up to ten input networks can be processed simultaneously, and one output network can be generated. The input network files can be of various formats: ASCII records, standard database in dBASE style (DBF), or any Cube Voyager, TP+, MINUTP, Tranplan, or TRIPS binary network format. Beginning with version 5.0, input highway networks may be a Cube geodatabase network. A data record is generated for each unique node and each link that is found in all the input files. The minimum requirement for a valid node record is a node variable and the Network program expects this variable to have the variable name N. The minimum requirement for a valid link record is an A node and a B node variable (each of which must exist on a node record) and the Network program expects these variables to be named A and B respectively. If the network is to be opened in Cube Graphics for viewing and/or editing then the node records must also have two additional variables to represent the X and Y coordinates of each node. Cube expects these coordinate variables to be named X and Y. Each of these records can be processed through user controlled logic, and its data can be summarized and reported in various manners. In v3.2.x and earlier, node and link records in a given data file had to be unique. This limitation has been lifted starting with v4.0. In v4.0, the COMBINE keyword has been added to both the LINKI and NODEI keywords under the FILEI statement so that users can specify how they would like to treat the values on the fields of redundant data records. If a Tranplan network is detected as input, the program will immediately write it in a Cube Voyager format onto a temporary file, and then use that file in place of the original file for subsequent processing. (Note: Cube Voyager treats a FSUTMS network as a standard Tranplan network. No auxiliary files will be open. Only Cube deals with FSUTMS networks differently.)

330 Cube Voyager Reference Guide

Network Program Introduction to the Network program

If an output network is specified, a file is written in a proprietary (Cube Voyager or MINUTP) binary format. It is a network database that contains speed/capacity information, node records, and link records. In MINUTP networks, the node information consists solely of coordinates for each node. In a Cube Voyager or TP+ network, there may be any number of items for nodes. Optionally, a file of link records and/or a file of node records may be written in either ASCII or DBF format. Beginning with version 5.0, output networks may be a Cube Voyager custom network feature class, stored in an ESRI custom geodatabase. See the description for the FORMAT subkeywords under NETO keyword for the FILEO statement on page 354 for information on specifying output networks to a Cube Voyager custom feature class network in a geodatabase file. Subsequent topics discuss: Built-in variables Built-in functions

Cube Voyager Reference Guide 331

Network Program Introduction to the Network program

Built-in variables
Variable A B GEOMETRYSOURCE Description Node number of a links A node Node number of a links B node Defines the input file index number that controls the source of the geometry to be applied to the output NETO file when multiple input networks are specified. The Network program may take up to ten input networks. These ten networks can be any of the supported binary formats, Cube geodatabase networks, or combinations of link and node files in ASCII, DBF, or MDB formats. When specifying an output network to a Cube geodatabase network, GEOMETRYSOURCE specifies which # from the FILEI LINKI[#]= specifications provides the geometry to be applied to the output geodatabase network. Each input network coming from a geodatabase network will have a field called GEOMETRYSOURCE. This fields value is the index of the input file (3 for LINKI[3], for example). Other input formats could also have a field called GEOMETRYSOURCE defined by the user. The value of the GEOMETRYSOURCE field in the output network dictates the source of the link geometry. By default, the value is taken from the first available value from all the input networks. So if LINKI[1] is a binary network without a GEOMETRYSOURCE field and LINKI[2] is a geodatabase network, the output GEOMETRYSOURCE field will have a value of 2 (unless there is no record in LINKI[2] for a certain link). If Merge Record=T, records that are merged from other LINKIs retain their GEOMETRYSOURCE value. Therefore, the output network could have a mix of GEOMETRYSOURCE values. In addition, you can specifically set the value in a script based on other attributes in the various input networks (for example, downtown use LINKI[3], and other areas use LINKI[2]). N X Y _COMPARE _ZONES Node number of the node X-coordinate value of a node Y-coordinate value of a node Stores a return code value resulting from the COMPARE statement Holds the number of zones read from the input network as set by the ZONES parameter

332 Cube Voyager Reference Guide

Network Program Introduction to the Network program

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

Cube Voyager Reference Guide 333

Network Program Control statements

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

334 Cube Voyager Reference Guide

Network Program Control statements

ABORT
Aborts the Network program and Cube Voyager. MSG Use ABORT to quit the Network program at with a fatal return code. Use this statement if you can determine from the data that you desire no further processing.
ABORT keyword
Keyword MSG |S| Description Optional message to be printed along with the ABORT message.

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

ARRAY
Declares user single dimension arrays. VAR=size, VAR=size Use ARRAY to allocate user arrays that are to be used in the process. An array is different than a variable in that it represents vectored data. Values stored in arrays must be numeric. Arrays cannot store string values. When an array is referenced, it should include an index [], and if the index exceeds the size, the program may fatally terminate. Arrays can be useful for different processes; the most

Cube Voyager Reference Guide 335

Network Program Control statements

common use may be to store information for specific zones. ARRAY statements are not dynamic (stack oriented); they are allocated prior to any stack operations.
ARRAY variable
Variable VAR |I| Description VAR is the name of the variable that is to be allocated according to the specified size. VAR must be a unique name. The size following the keyword is the highest index possible for VAR. Size may be either a numeric constant, or a special name. Special names are: ZONES, NODES, and LINKS if there is a binary input network. NODES and LINKS should not be used if links are to be added to the network. Arrays are cleared when they are allocated.

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

BREAK
Breaks out of stack processing for current data record. When a data record is being subjected to the operations in a phase block, and the operation is BREAK, the remainder of the block operations are bypassed and the next data record is processed. Most likely, BREAK would be used in conjunction with an IF statement. However, if BREAK is encountered within a LOOP, stack processing jumps to the statement after the associated ENDLOOP statement.
Example 1
if (a=1-500 || b=1-500) BREAK ; do not process centroid links. if (a.x > b.x) ; bypass the links that go from right to left BREAK endif

336 Cube Voyager Reference Guide

Network Program Control statements

Example 2
/* this example finds the index where subtotal of ARRAY1 exceeds 1000 */ loop index=1,_zones _total = _total + array1[index] if (_total>1000) BREAK endloop list=INDEX =,index ; BREAK jumps to here

COMP
Computes a value for a variable.
Variable = Expression

COMP statements specify that new variables are to be created or that existing variables are to have new values computed for them. During any phase other than the SUMMARY, any name that appears on the left side of the equals sign will be placed into the output network record, unless it is a working variable (begins with an underscore). There may be more than one variable computed on a statement, but there must be comma between an expression and the next variable=expression. The statement need not begin with COMP.

The expression will be solved and the results stored in the named variable. The phase for which this COMP statement is coded will establish which variables may be included within the expression, and where the results can be stored. The maximum length of the name is 15 characters. This limit includes the _ prefix of temporary variables. A normal numerical expression is required. If the expression results in a string, the mode of the target (named) variable will be set to string instead of numeric. A variables mode should be consistent throughout the application. The program tries to detect any possible changes, or misuse of variable modes, but it might not detect all inconsistencies. If a variable is misused as to mode,

Cube Voyager Reference Guide 337

Network Program Control statements

unpredictable results could occur. It might be prudent to have a standard naming convention for string variables, such as always beginning with the same letter. The expression may contain function names with their arguments. To obtain speed and/or capacity values from the SPDCAP tables, the SPEEDFOR and CAPACITYFOR functions are utilized. They are coded as:
Function SPEEDFOR(lanes,spdclass) CAPACITYFOR(lanes,capclass) Description Returns the speed from the SPEED table for the designated number of lanes and spdclass. Returns the capacity times the lanes for the designated number of lanes and capclass.

In the SPEEDFOR and CAPACITYFOR functions, the first argument is the number of lanes and the second argument is the class. If the lanes value is less than 1, or greater than 9, the function value of lanes will be reset accordingly. Thus, if CAPACITYFOR (88...) were specified, lanes would be reset to 9, and the capacity extracted for that value would be multiplied by 9. Similarly, if the second argument is less than 1, or greater than 99, the internal value will be reset to the appropriate limit.
Example
i = 0 j = a / i, k=j*2+3*i newb = nodecode(b) sumab = newb+newa cdist = sqrt((a.x-b.x)^2 + (a.y-b.y)^2) _LinkSpeed = SPEEDFOR(Lanes,Facility*10+Area)

COMPARE
Compares network records. RECORD (LIST TITLE)

338 Cube Voyager Reference Guide

Network Program Control statements

COMPARE statements are dynamic and are used to compare the

records of either the link or node portion of two networks. At the end of the phase (NODEMERGE or LINKMERGE), a summary of the comparison is reported. The LIST parameter controls the listing of individual differences. To make this statement function properly, the MERGE RECORD=T statement should be coded. In addition to a summary report, COMPARE also returns a value indicating the result after the comparison of each record. The value is stored in a temporary variable: _COMPARE. The meaning of the returned value is as follows:
Value of _COMPARE n 0 -1 -2 Meaning n attributes are different between two records. No differences between two records. Record not in file one. Record not in file two.

There may be multiple COMPARE statements in a single application.


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

LIST

|I|

Cube Voyager Reference Guide 339

Network Program Control statements

Example 1
LINKI[1] = current.net LINKI[2] = future.net COMPARE RECORD=1-2

The following is a sample output in the print file:


COMPARE 1 vs. 2: 1=2 ------- 1 < 2 ------Variable Cnt Cnt Min Max Ave -------- --- --------A 321 ----B 321 ----LANES -- 321 1 1 -1 DISTANCE -- 321 1 1 -1 SPDCLASS -- 321 2 2 -2 CAPCLASS -- 321 1.23 1.23 -1.23 NAME -- 321 ------- 1 > 2 ---Cnt Min Max Ave --- --- --- --7 -- -- -7 -- -- --- -- -- --- -- -- --- -- -- --- -- -- --- -- -- --

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

The 1=2 column lists the number of records where the records are the same. The 1<2 set of columns lists the number of records where the values for the listed variables are lower in file 1 than in file 2, and the 1 > 2 set lists the summary where file 1 values are greater than file 2, The final AVE column lists the average difference for the variable, using only records where there is a difference. The Min and Max differences show the range of differences for the variable.
Example 2
RUN PGM=NETWORK NETI=NET1.NET, NET2.NET NETO=NET3.NET MERGE RECORD=T PHASE=LINKMERGE COMPARE RECORD=1-2, LIST=20 ; compare link record 1 with 2 IF (_COMPARE=-2) CMPFLAG=1 ; link in NET1, not in NET2 IF (_COMPARE=-1) CMPFLAG=2 ; link in NET2, not in NET1 IF (_COMPARE>0) CMPFLAG=3 ; link in both but different ENDRUN

Example 2 illustrates how to use _COMPARE to flag the links in the merged network. The CMPFLAG attribute can be used in selection expressions in Viper to post the comparison results.

340 Cube Voyager Reference Guide

Network Program Control statements

CONTINUE
Immediately jumps to the end of a loop, bypassing all stack statements until the associated end of loop. If it is within a loop, control passes to the appropriate ENDLOOP statement. Otherwise (not in a loop), stack processing for the record is terminated.
Example
LOOP _L1=1,3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE ; no more processing for this data record LOOP _L2=_K1,_K2,_KINC LOOP _L3=_L2,_L2+5 IF (condition) CONTINUE ; jump to ENDLOOP for _L3 ENDLOOP ENDLOOP

CROSSTAB
Cross tabulates variables. VAR (FORM) ROW (RANGE) COL (RANGE) COMP (FORM) Use the CROSSTAB control statement to accumulate a tabular summary from the network. Use the VAR keyword to specify the variables you want tabulated. Use the ROW keyword along with the RANGE subkeyword and the COL keyword along with the RANGE subkeyword to specify the tables dimensions. If you omit either ROW or COL, the report collapses into only one column or one row. Although the CROSSTAB statement can include several instances of the VAR keyword, the statement tabulates all the variables to the same specifications. Use the COMP keyword to generate additional reports after network generation using the values from the

Cube Voyager Reference Guide 341

Network Program Control statements

tabulated variables. For example; if the statement includes VAR = VehDist, VehTime, then including COMP = VehDist / VehTime would produce a table of average speeds.
NOTE: The program does not automatically produce totals because

your ranges may overlap. You can produce totals and subtotals with appropriate use of RANGE values. See below for a description of the process used in placing values in the appropriate range slots.
CROSSTAB keywords
Keyword COL COL RANGE Subkeyword |S| |RV50| Description Name of the variable that will be used for the column definition of the report. Same as for ROW (RANGE), but applies to the COL variable. Care should be taken to not cause the reported line to be too long (limit the number of column ranges). Expression that can be used to generate a report that is some combination of the reports generated by the VAR variables on this statement. The only variable names that may appear in the COMP expressions are the VAR variables that are on this statement. There may be up to ten COMP expressions on a statement. Specifies the format for the COMP reports. The standard Cube Voyager FORM syntax is used. If FORM is not coded for any COMP, the program will supply 7cs. The format applies to the COMP that it is coded with, and to all subsequent COMP variables until a new value is encountered. The first format will be backfilled to apply to any prior COMP variables Name of the variable that will be used for the row definition of the report.

COMP

|NV|

COMP

FORM

|S|

ROW

|S|

342 Cube Voyager Reference Guide

Network Program Control statements

CROSSTAB keywords (continued)


Keyword ROW Subkeyword RANGE |RV50| Description Series of ranges (and increments) for stratifying the row variable for use in the report. A range as either one, two, or three numbers. If more than one number, the values are separated by dashes. The three values are low, high, and increment. The program establishes ranges for stratifying the ROW variable values. Each range has a lower limit, an upper limit, and an increment. If there is no upper limit, the program makes the upper limit equal to the lower limit. If there is no increment, the program assumes one row. If there is an increment, the program generates a row for each increment, starting at the lower limit, and progressing until the upper limit is reached. There are certain problems associated with stratifying non-integer data; they are discussed below. Name(s) of the variable(s) that are to be tabulated. The value of each variable will be accumulated into the cells of the generated table(s). A separate report will be generated for each variable named. There may be up to ten VAR keywords on a statement. Format to use when printing the accumulated values in the table. The standard Cube Voyager FORM syntax is used. If FORM is not coded for any VAR, the program will supply 7cs. The format applies to the VAR that it is coded with, and to all subsequent VAR variables until a new value is encountered. The first format will be backfilled to apply to any prior VAR variables.

VAR

|SV10|

VAR

FORM

|S|

Range classification strategy

The ROW RANGE and COL RANGE values are stored as singleprecision numbers, and the actual variable values are computed and stored as double-precision floating-point numbers. Single precision provides accuracy to about six, or seven, significant digits, whereas double precision provides accuracy to up to fifteen, or sixteen, digits. Because computers do arithmetic on a binary basis, numbers which seem to be easily described in base 10 cannot always be represented exactly in the computer. For example: the number 0.01 is a definite number in base 10, but it can only be approximated in base 2. If the program compares a variable to a

Cube Voyager Reference Guide 343

Network Program Control statements

range limit, it might fail due to this limitation of the computer. The comparison result may differ, depending upon the floating point capabilities of the computer. Another concern is the definition of limits. If RANGE is 1-10, should a value of 0.9999999999 be included in it? If RANGE is 1-10-1, should a value of 10.001 be included, and which range should the value of 2.0001 fall into? To address all these concerns, the program is designed to check for RANGE satisfaction based upon an integer representation of both the RANGE limits and the data. You can control the level of precision when specifying the RANGE values. The level of precision is set by the maximum number of decimal places in any of the RANGE values (low-high-increment). The RANGE values and the ROW and COL variable values are factored and integerized (rounded) according to the decimal digits. If a single RANGE (no increment) is used, the program checks the value against the limits as: if the value is greater than, or equal to, the lower RANGE, and less than, or equal to, the higher value, the value satisfies the range. If a RANGE with an increment is used, a similar initial check is made to determine if the value fits within the outer RANGE limits. If the value fits with the range, the increment index is computed (in integer) as: ((value-lo) / inc) + 1. Examples may best illustrate this process.
RANGE 1-10 1-10-1 1-10-1 1-10-1.0 1-10-0.5 1-3-0.5 1-3-0.3 1-3-0.3 1-3-0.3 Internal Range 1-10 1-10-1 1-10-1 10-100-10 10-100-5 10-30-5 10-30-3 10-30-3 10-30-3 Integer Value 0.99 1.50 1.45 1.45 1.45 3.00 1.29 3.01 3.001 Value 1 2 1 15 15 30 13 30 30 Index -2 1 1 2 5 2 7 7

344 Cube Voyager Reference Guide

Network Program Control statements

There is a caveat with this process. The maximum integer revised value for either RANGE or ROW is 2,147,483,647. For this reason, the program may adjust the number of decimal digits if either RANGE limit would exceed the maximum after revising.
Example
CrossTab VAR=DIST, _CNT, ROW=VC, RANGE=0.5-1.2-0.1, 0.5-1.2, 1.2-2.5-0.5, 2.5-9999, COL=LANES, RANGE=1-7-1, 1-3, 4-7, 1-7, 1-100-5, VAR=VMT FORM=6.1c, VAR=VHT, FORM = 6.2c, ROW=CLASS, RANGE=1-50-1, COL=LANE, RANGE=1-10, COMP=sqrt(VMT)+10*(min(1000,VHT)), COMP=VMT / VHT, FORM=8.3 ; weird example & ave trip length

CrossTab

DELETE
Deletes data record. When a data record is being subjected to the operations in a phase block, and the operation is DELETE, the remainder of the block operations are bypassed, and the record is removed from the network. Most likely, DELETE would be used in conjunction with an IF statement.
Example
If (a=2150-2199 || b=2150-2199) DELETE ;remove all links connected to nodes 2150-2199

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

Cube Voyager Reference Guide 345

Network Program Control statements

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

and for important limitations when using Application Manager. Inputs data files. LINKI (EXCLUDE VAR (BEG LEN TYP MIN MAX) RENAME START STOP SELECT REV TRIPSXY DETAILS COMBINE (FIRST LAST AVE SUM MAX MIN CNT AVEX0)) NODEI (EXCLUDE VAR (BEG LEN TYP MIN MAX) RENAME START STOP SELECT COMBINE (FIRST LAST AVE SUM MAX MIN CNT AVEX0)) LOOKUPI The FILEI statement specifies the files that contain the network data. There may be up to ten NODEI and ten LINKI files designated. The index appended to the NODEI/LINKI control is used primarily for identification purposes and to try to assist in editing for possible user mistakes. If a LINKI file is a recognized binary file, an automatic corresponding NODEI file is assumed. However, the user can preclude the use of the node data from the automatic NODEI by providing a NODEI with the same index as the LINKI. This is not normally recommended, but it is at the users discretion. If a NODEI has the same index as a LINKI, and the LINKI file is a binary network, the NODEI must precede the LINKI. If the LINKI and NODEI files are not binary, the records need not be in any sorted order. Cube geodatabase networks have associated link and node stand-alone feature classes. If a LINKI file is a Cube geodatabase network, the automatic corresponding NODEI file is the networks node standalone feature class. If the user codes value limits for a variable (MIN=, MAX=), those limits are checked during the INPUT phase only. If the limits are exceeded, the record is rejected as an error and is not available for processing. Input record keys are not edited before being subjected to stack processing. This allows the user to decide what to do with records that have invalid record keys. Upon return from

346 Cube Voyager Reference Guide

Network Program Control statements

stack processing, the key is checked to see that is in the range of 1nodes. If it is not, the record is then listed as an error. If the input file contains many bogus records (not valid data recordspossible if coming from a GIS DBF with extraneous records), you can check the key (N, A, or B) and DELETE the record, or recode the key.
FILEI keywords
Keyword LINKI Subkeyword |KFV10| Description Name of a file that contains link based records. The file format can be: ASCII DBF MDB data table Cube geodatabase network Link stand-alone feature class in a geodatabase network Recognized binary network.

The program will try to detect what type of file it is. If it cannot identify the file as a DBF, MDB, Cube geodatabase network, or a binary network, it will assume ASCII. If it detects that the file is a MINUTP binary network, the variables DIST, SPDC, CAPC, and LANE will automatically be renamed to DISTANCE, SPDCLASS,CAPCLASS, and LANES, respectively. Since most applications will input binary networks or Cube geodatabase networks, you can use the keyword NETI as an alias for LINKI. If the LINKI file and the NODEI file are DBF or MDB format then at a minimum, the LINKI file must have a field named A and a field named B and the NODEI file must have a field named N. If these fields in the DBF or MDB do not use this naming convention, then the RENAME keyword below can be used to rename the variables on input. NOTE: A valid network in Cube Voyager/TP+ need not have coordinate variables on the node records. If the network is to be viewed/edited in Cube then it must have variables named X and Y on the node records to hold the coordinate data.

Cube Voyager Reference Guide 347

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. The following subkeywords can be used to specify how to combine attributes values across multiple link or node records. FIRST, LAST, AVE, SUM, MAX, MIN, CNT, AVEX0 The descriptions of these keywords are identical to those described for the MERGE statement. The default for any variables not combined will be consistent with the value of PARAMETERS REPL_DUPL. If REPL_DUPL is true, the unlisted vars will be set to LAST, otherwise to FIRST. Example of usage:
FILEI LINKI=linki.dat, vars= v1,v2,v3,v4,v5,v6,v7,v8 combine=t, ave=v1,v3,v4 ave=v6,v8 FILEI NODEI=node.dat, vars=n,x,y, combine=t, first=x, last=y

LINKI

DETAILS

|?|

Switch to indicate if you would like to keep the full iteration results from an input loaded Tranplan network on the output file and have the iteration specific attributes available as li. variables during the run. Specifies name(s) of variable(s) to be excluded from the file. It is relevant only if the file is a DBF or binary network file and certain variables from it are not wanted, or if the input is defined as a series of variables (in delimited format -- not with BEG/LEN), and certain variables are not to be extracted from the input records. May be used to rename a variable from the input file. The format is RENAME=oldname-newname; both names must be specified. Names can be swapped on one statement; to swap names for V1 and V2: RENAME=V1-temp1,V2-V1,temp1-V2

LINKI

EXCLUDE

|SV|

LINKI

RENAME

|SP|

348 Cube Voyager Reference Guide

Network Program Control statements

FILEI keywords (continued)


Keyword LINKI Subkeyword REV [I| Description Parameter that can be used in conjunction with files that are ASCII or DBF to specify if an input record is to represent a single directional link or if it is to be considered as two links (A-B and BA, with the B-A values being the same as the A-B values). Under normal conditions, an input record represents a single directional link from A to B. The REV parameter is used only if: There is no REV variable on the record. There is a REV variable on the record, but its value is neither 1 nor 2.

If there is a VAR=REV defined for the link data records, the value of the REV should be a 1 or a 2. If the value is not a 1 or a 2, the reversibility of the link is determined by the value assigned to this keyword. The only valid values for this keyword are 1 and 2; the default is 1. The record variable defined as REV will be treated as any other link variable, but it will not be written to the output network (the NETO will not contain a variable named REV). LINKI SELECT [s] Used only with ASCII input when it is desired to select only certain records from the file. The syntax is the same as for START. SELECT is processed after any STOP statement, and before any editing. Used only with ASCII input where the first valid data record follows some identifying header record. The expression value must be enclosed within parenthesis (), and the only valid variable is RECORD, which is the actual data record. The primary purpose is to allow the user to specify that there is a header, and how to identify it. The expression should contain a SUBSTR function to extract the header. START is used to position the file before actual data records are read. Used in a manner similar to the START keyword, but is associated with a trailer record. STOP is processed immediately after a record is read, and before any field editing. Name of a file that contains TRIPS X-Y data. This keyword is only required for TRIPS networks.

LINKI

START

[s]

LINKI

STOP

[s]

LINKI

TRIPSXY

[F]

Cube Voyager Reference Guide 349

Network Program Control statements

FILEI keywords (continued)


Keyword LINKI Subkeyword VAR |SV| Description Name of a variable to be extracted from the file. Name lengths may not exceed 15 characters; case is ignored. To read variables from fixed-format text files, use the BEG and LEN subkeywords. To read character-string variables from free-format text files, use the subkeywords TYP and LEN, or append (C) or (Cn) to the variable name, where n specifies the number of characters. To read character-string variables from fixed-format text files, use the TYP, BEG, and LEN subkeywords. If the file is ASCII, and the variable is to be extracted from specific positions on each file record, BEG and LEN will have to be specified. The program assumes that ASCII files are free format and all fields are separated by white space, a comma, or some combination of both. Examples of free-form records:
1 2 3 1,2,3 1 , 2 3 1 ,2,3

All four of the above illustrated records contain three fields: 1, 2, and 3. Subkeywords of VAR include: BEG |I| Designates the beginning of the field in the input records. The first column of the record is designated as 1. Designates the length of the field that begins at position BEG. May be used to specify that the format of the variable is not numeric. An A means that the variable is alphanumeric. If TYP=A is specified for free format input, the LEN must also be specified, or it will default to 1. TYP A variable values on free format input must be enclosed within quote or literal marks ('...' or "..."), if they contain special characters (other than alphanumeric characters: a-z, 0-9). May be used to specify a minimum allowable value for the field. If the input value of the variable is less than this value, the variable will be rejected as an error.

LEN |I| TYP |S|

MIN |R|

350 Cube Voyager Reference Guide

Network Program Control statements

FILEI keywords (continued)


Keyword LINKI Subkeyword VAR (continued) Description VAR may also be specified with parameters directly (without the above subkeywords). If the field following the variable name is a number, this format is automatically triggered. The total format is name,beg,len,min,max,typ. All these fields must be numeric, or null. A null field is specified by coding two commas with nothing between them. The parameter list is considered as exhausted when a non-numeric field is encountered. Typ must be coded as 1 to indicate that the variable is to be an alphanumeric field. Example: VAR=A,1,5,B,6,5 (A is in columns 1-5 and B is in 610). If the first two numbers that follow the name are separated by a dash, the numbers indicate the actual columns of the data record where the field is located. For example: VAR=A,1-5,B,6-10 (A is in columns 1-5, and B is in columns 6-10). If both forms may be used to specify variable (numeric format, followed by any of the sub-keywords); the keyword values will override the positional numbers LOOKUPI |FKV999| Name of file containing records for a lookup function implemented with the LOOKUP control statement. Equivalent to the FILE keyword of the LOOKUP control statement. You must index LOOKUPI. NODEI |KFV10| Name of a file or an MDB and element that contains node-based records. See LINKI on page 347 for comments regarding file detection. NODEI uses the same keywords as LINKI except REV and TRIPSXY.

Example

This section contains some examples of FILEI LINKI and FILEI NODEI usage.
LINKI[1]=\demo\demo20.dat exclude=dist,tsin ; file is binary network NODEI[1]=C:\DEMO\DEMOXY.DAT VAR=N,X,Y ; file is ASCII NODEI[2]=\demo\demo21.dat, LINKI[2]=\demo\?07.dat, var=a,beg=1,len=5, var=b,beg=6,len=5, var=dist,beg=14,len=4, var=rev,beg=35,len=1 LINKI[3]=freeform.fil, VAR=a,b,name,21,5,,,1,section,0,5 ;section follows name in free form nodei[4]=c:\citya\nets\linka.dbf, linki[4] = c:\citya\nets\nodea.dbf

Cube Voyager Reference Guide 351

Network Program Control statements

LINKI[8]=Mixed_Node_and_Link.lxy, var=a,b,distance, start=(substr(record,1,2)=='LD'), stop=(substr(record,1,2)=='XY') NODEI[8]=Mixed_Node_and_Link.lxy, var=n,x,y, start=(substr(record,1,2)=='XY'), stop=(substr(record,1,2)=='LD')

FILEO
Outputs network file. LINKO (FORM FORMAT DELIMITER INCLUDE EXCLUDE VARFORM) NETO (FORMAT (TRIPSXY) EXCLUDE INCLUDE LEFTDRIVE) NODEO (FORMAT DELIMITER INCLUDE EXCLUDE FORM VARFORM) PRINTO (APPEND)
FILEO keywords
Keyword LINKO Subkeyword |KF| Description Name of a non-Cube Voyager output file onto which link records are to be written. May be any of the formats described by the FORMAT subkeyword or may be an MDB/element name. LINKO DELIMITER |S| Specifies a character that is to be used as the delimiter in SDF and TXT files. If the value is a special character (, - / + * = ;), it must be enclosed within quote marks, or it can be specified by using its decimal equivalent (for example, tab is code 9). The default value is a comma; but there is no default value for TXT files. Similar to EXCLUDE under NETO. Used to set the format of all variables to be written to the file. FORM is usually specified as w.d to indicate the maximum field width and number of decimal places to preserve. The optional FORM characters (CTDLR) are usually not appropriate for use on this statement. See the PRINT FORM definition in PRINT on page 62 for details of this parameter.

LINKO LINKO

EXCLUDE FORM

|SV| |S|

352 Cube Voyager Reference Guide

Network Program Control statements

FILEO keywords (continued)


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

LINKO

VARFORM

|SV|

Cube Voyager Reference Guide 353

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

NETO

FORMAT

|S|

354 Cube Voyager Reference Guide

Network Program Control statements

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. This is primarily for use in JUNCTION modeling in the Network program; it does not have any affect on any PLOT statements in Network. This keyword is not necessary if the lowest numbered LINKI file had the LEFTDRIVE parameter set, or if PARAMETERS LEFTDRIVE was specified. The setting of the NETO value follows the rules: NODEO |KF| If PARAMETERS LEFTDRIVE is specified, use that value Else if NETO LEFTDRIVE is specified, use that value Else if lowest LINKI contains a LEFTDRIVE value, use that value Else do not set this value

Name of a non-Cube Voyager output file onto which node records are to be written. Its subkeywords are the same as those for LINKO. May be any of the formats described by the FORMAT subkeyword under the LINKO keyword, or may be an MDB/element name.

PRINTO

|KF|

Specifies the name of the file where the output from a PRINT statement is to be directed using PRINT PRINTO=#. See APPEND under PRINT on page 62.

PRINTO

APPEND

|?|

When writing output files, an output network will be generated first even if NETO is not specified. Both LINKO and NODEO are derived from this output network, hence, subsets of it. Consequently, if NETO is specified and a link variable is excluded from it then that link variable will not be available for LINKO.
Example
FILEO NETO=MY.NET NETO=DEMOMINU.DAT, FORMAT=MINUTP, EXCLUDE=TEMP1, TEMP2 NODEO=TEXTNODE FORMAT=TXT, FORM=8.0 INCLUDE=A,B,DIST,SPEED,SPDCAP(2) LINKO=LINK FORMAT=DBF VARFORM=VC(6.3)

Cube Voyager Reference Guide 355

Network Program Control statements

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


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

LOOP ... ENDLOOP


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

where: LVAR is the name of the loop control variable. LVAR is not protected during the loop; computational, program, and other LOOP statements can alter its value. LVAR must be followed by Lbeg, and optionally, by Lend and Linc. Lbeg is a numeric expression that initializes LVAR.

356 Cube Voyager Reference Guide

Network Program Control statements

Lend is a numeric expression that is computed and stored when the LOOP statement is first processed. LVAR is incremented by Linc, and compared with Lend when the ENDLOOP statement is processed. If Lend is not specified, it is assumed no comparison is to be made (rather meaningless loop). Linc is a numeric expression that is computed and stored when the LOOP statement is first processed. The value is added to LVAR before the ENDLOOP comparison is made. If Linc is not specified, it will be set to 1 (-1 if Lbeg and Lend are both constants and Lbeg < Lend; a backwards loop).

NOTE: All variables in a LOOP statement expression (Lbeg, Lend, Linc) must begin with the underscore character _ to prevent confusion with record variables.

Use LOOPENDLOOP blocks to repeat of a series of statements. LOOP initializes a variable(LVAR); ENDLOOP compares the contents of the variable to another value (Lend), and branches back to the statement following the LOOP statement if the comparison fails. LOOP blocks may be nested; they may not overlap IF blocks. The logic is as follows: At LOOP: Initialize LVAR to Lbeg. Compute the value for Lend. Compute the value for Linc (default to 1 if missing). Proceed to next statement. At ENDLOOP: If Lend not specified, jump to next statement. Add Linc to LVAR. Compare LVAR to Lend. Either jump back to statement following associated LOOP, or drop through.

Cube Voyager Reference Guide 357

Network Program Control statements

The Lend and Linc variables are processed somewhat differently than in the other programs; they are computed at the LOOP statement and can not be modified by other statements. This helps to protect against possible endless loops. The loop will be processed at least one time regardless of Lend and Linc values. Most uses will involve constants. Because LVAR values can be expressions, Lbeg, Lend, and Linc must be separated by commas (standard white-space delimiting cannot be interpreted properly). If an expression is used, it is suggested that it be enclosed in either parentheses or quote marks.
Example
LOOP _pass=1,10 ; perform 10 passes ... ENDLOOP LOOP _xyz=_abc*_def,_ghi+_jkl,_mno/_pqr LOOP _abc=_xyz,_xyz+2,2 ; nested LOOP ... ENDLOOP ENDLOOP LOOP _jj=10,3,-2.5 ; perform 3 passes -- 10, 7.5, 5.0 ... ENDLOOP

MERGE
Specifies record and variable merging. RECORD AVE AVEX0 CNT FIRST LAST MAX MIN SUM Use MERGE to specify how records from different files are to be merged, and how variables of the merged record are to be combined. It is important to note that merging records and combining variables are independent processes. Use the RECORD keyword to specify which records are to have their data merged when records with identical keys are encountered during the NODEMERGE or LINKMERGE phases.

358 Cube Voyager Reference Guide

Network Program Control statements

Use the other keywords to specify how individual variable values are to be obtained for the resulting merged record when there are duplicate records from different input files. (Duplicate records from the same file may not occur in the MERGE phase.) Each resulting record will have a cell for every variable that is specified in any input file or any COMP statement.
MERGE keyword selecting records
Keyword RECORD |?| Description Specifies if duplicate records are to be merged. If the value is false, only the records that exist in the FILEI with the lowest index [] will be included. If the value is true, any unique record is included. The default is true. If two networks (NETI[1] and NETI[2]) are input, and RECORD=FALSE, only the links that are in NETI[1] will be processed.

The following keywords indicate a process to use in obtaining the value for the variables that are listed following the keyword. The values for the variables will be obtained only from file records that contain the variable. A variable may appear in only one keyword list; any variables that are not in any list will be set to FIRST.
MERGE keywords technique
Keyword AVE AVEX0 CNT FIRST LAST MAX MIN SUM |SV| |SV| |SV| |SV| |SV| |SV| |SV| |SV| Description Average of all records. Average of all records, where the value from the file records is not 0. Count of the records that contain the variable. Directly from the record from the FILEI with the lowest index[]. Directly from the record from the FILEI with the highest index []. Maximum value of all the records. Minimum value from all the records. Sum of all the records.

Cube Voyager Reference Guide 359

Network Program Control statements

Example
MERGE RECORD=TRUE FIRST=CAPCLASS,SPDCLASS, LAST=LANES, AVE=DISTANCE, SUM=COUNT

Illustration for sample input files (-- indicates variable not defined for file):
FILEI LINKI[1]=FILE1,VAR=A,B,DISTANCE,SPDCLASS,CAPCLASS,LANES FILEI LINKI[2]=FILE2,VAR=A,B,COUNT FILEI LINKI[3]=FILE3,VAR=A,B,DISTANCE,LANES
LINKI[] A 1 1 2 2 3 3 3 101 105 101 102 101 102 104 B DISTANCE SPDCLASS CAPCLASS 11 12 -----11 12 -----LANES 1 3 --2 2 3 COUNT --1000 1000 ----

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

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


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

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

MERGE RECORD=FALSE ; Resulting file:


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

360 Cube Voyager Reference Guide

Network Program Control statements

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


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

PARAMETERS
Specifies basic parameter values. LEFTDRIVE LIST_ERRS MAX_IP_ERRS NODES REPL_DUP ZONES
PARAMETERS keywords
Keyword LEFTDRIVE |?| Description Used to force a LeftDrive switch into the NETO. By default, this value is not set. See FILEO NETO LEFTDRIVE in FILEO on page 352 for more details. Specifies how many records with data errors will be listed before turning off the error listing. Default value is 20. Specifies how many records with data errors are allowed. If this value is exceeded, the program will terminate with a fatal condition. Default value is 20. Records with errors are not skipped, unless the error is in the key (for example, node number). The bad fields will be set to 0, unless the error is a limits error.

LIST_ERRS

|KI|

MAX_IP_ERRS

|KI|

Cube Voyager Reference Guide 361

Network Program Control statements

PARAMETERS keywords (continued)


Keyword NODES |KI| Description Specifies the highest node number to be allowed in the network. This need not be specified (by default, the program detects the highest number); but if it is specified, any node numbers that exceed this value are considered errors. The value must be a greater than 0 and less than 999,999. Switch that indicates how to process records from an input file with matching node numbers. If this switch is true, the later record will replace any previously read records. Default value is false. This keyword applies to each NODEI or LINKI file as it is read within any PHASE=INPUT. (Any nonbinary file will automatically be processed within an input phase; binary files should not have duplicate records.) The MERGE control statement is used to determine how duplicate links from different inputs are to be processed during the MERGE phases. To obtain a listing of duplicate links, specify REPORT DUPLICATES=T. ZONES |KI| Specifies the number of zones in the network. This is required only if the number of zones cannot be determined from the LINKI and NODEI files, or it is desired to alter the number of zones. By default, the program detects the value. The value must be greater than 0 and less than 20000. A temporary variable _ZONES is initially set equal to this value, and can be used in COMP and IF expressions. If ZONES is used in a COMP statement, it will become a variable in the output network. If this parameter value is not supplied (or is not available from an input binary network), the program will set it to the highest node number in a monotonic string beginning at 1.

REPL_DUP

|K?|

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

362 Cube Voyager Reference Guide

Network Program Control statements

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

PLOT
Selects links/nodes for plotting. DRAWA DRAWLINK LINKPOST NODEPOST
PLOT statements in the LINKMERGE phase control plotting. After

the program completes the LINKMERGE stack for a link, it processes the final values for the PLOT keywords that may have been applied to the link. If there are no DRAWLINK values present, the link is not processed for plotting. If there are DRAWA and/or NODEPOST values, they are saved until all the links from the current A-node are completed. When the A-node is completed, the node values are saved for post processing, so that node symbols will be prominent on the display. If there is a LINKPOST value, but there is no DRAWLINK value, the LINKPOST value is ignored. The situation for nodes is different; a node can be posted without a symbol.

Cube Voyager Reference Guide 363

Network Program Control statements

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

Specifies the characteristics for drawing this link: color, size, and style. Color is a value as shown in the PLOTTER description, below. Size is the width of the line; current Windows drivers do not allow both size and style at the same time (style is changed to solid if a width is specified). Possible styles are: Solid, Dash, Dot, DashDot, DashDotDot. If PLOTTER BANDWIDTH is specified and the bandwidth variable has a value, Size and Style are ignored. It is recommended that Size usually be left null. Specifies the color that this link is to be posted with. Specifies the color and size of the variables that are to be posted for this Anode. (See NODEPOSTVARS under PLOTTER on page 364 for information about which variables are to be posted.)

LINKPOST NODEPOST

|S| |S2|

Example

See Examples on page 387.

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

364 Cube Voyager Reference Guide

Network Program Control statements

The PLOTTER statement specifies the configuration for plotting link and/or node information. See Plotting on page 384 for some information about getting your printer device installed and its basic configuration established. The printer driver properties are established by left-clicking the desired printer and then modifying the properties as desired. The orientation (portrait or landscape) determines how the plot will be generated, and the size determines the plate size of the drawing.
PLOTTER keywords
Keyword BANDWIDTH Subkeyword |S| Description Specifies the variable that is to be used to control the drawing of bandwidths along drawn links. Usually, a temporary variable should be designated. The variable must be scaled appropriately, or the plot will be unreadable. Specifies if the band is to be filled in or left empty. On raster plotters, this value should be specified as solid, but on pen plotters, solid could require excessive time for generating and actually drawing the plot. The possible values are: Solid and None. The default is None. Specifies that the ends of the bands are to be tapered towards the nodes rather than being perpendicular to the link. In grid plots where Fill is not used, a taper of 45 might be more presentable. Any integer value from 0 to 45 (degrees) may be specified. Name of the printer driver that is to be selected and written to. The name must match the name of the printer as it appears in the Printers dialog box. Case is not essential. If the name has spaces in it, the value must be enclosed within quotes so that the spaces can be considered as part of the name. There must be a DEVICE specified; otherwise the program will not know anything about the printer

BANDWIDTH

FILL

|S|

BANDWIDTH

TAPER

|I|

DEVICE

|S|

Cube Voyager Reference Guide 365

Network Program Control statements

PLOTTER keywords (continued)


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

FOOTER

|S16|

Specifies how the footers should be aligned on the plot. The value can be: Left, Right, or Center. ALIGN must be placed after a FOOTER or FONT value; if more headers are to be specified after ALIGN, the FOOTER[]= must be specified. Specifies the font characteristics of the footers. There may be up to nine values following FONT, but currently, only the first three are used. The values are (position), name, size, color.

FOOTER

FONT

366 Cube Voyager Reference Guide

Network Program Control statements

PLOTTER keywords (continued)


Keyword HEADER Subkeyword |S16| Description Specifies lines of text that are to be printed at the top of the plot page. There may be up to 16 headers. Since headers most likely have special characters in them, it is recommended that each header be enclosed within quote marks ("..."). The highest index for a header sets the number of header lines that will be printed. Example: if only one header is specified, say HEADER[6]="...", 6 lines will be printed, with the first 5 being blank. Specifies how the headers should be aligned on the plot. The value can be: Left, Right, or Center. ALIGN must be placed after a HEADER or FONT value; if more headers are to be specified after ALIGN, the HEADER[]= must be specified. Specifies the font characteristics of the headers. There may be up to nine values following FONT, but currently, only the first three are used. The values are (position), name, size, color. Specifies the position for additional user text is to be printed on the plot page. There are four possible legend positions: TopLeft TopRight BottomLeft BottomRight

HEADER

ALIGN

|S|

HEADER

FONT

|S4|

LEGEND

|S|

NOTE: The four positions can also be designated as TL, TR, BL, and BR, or 1, 2, 3, and 4. See Examples on page 387. The legends are placed within the plot window area, and their areas are not written into by network drawing. The coding rules are similar to those for HEADER and FOOTER, but you can also enter symbols on each line. Legends are primarily for identifying the characteristics of the network drawing. Each LEGEND may have its own font characteristics; they will be used for the text for all lines in the legend. Each LINE can have its own symbol.

Cube Voyager Reference Guide 367

Network Program Control statements

PLOTTER keywords (continued)


Keyword LEGEND Subkeyword FONT |S9| Description Specifies the font characteristics for the text in this legend. See HEADER FONT on page 367 for details. Text to be printed at the specified line of the legend. Specifies the symbol that is to precede the LINE text. There should be four values specified for the symbol: name, size, color, and fill color. Name See DRAWA under PLOT on page 363 for valid symbol names. If a sample line style is to be drawn, see DRAWLINK under PLOT on page 363 for valid names. The size of the symbol, or the length of the line. Standard color designation. Standard color designation if the symbol is to be filled with a color.

LEGEND LEGEND

LINE SYMBOL

|S16| |S4|

Size Color Fill LINKOFFSET |R|

Specifies the distance (in inches) that the links are to be drawn from the normal centerline. This allows two-way links to be more visually presented. If this keyword is not used, or the value is 0, the high-to-low node link will overwrite the low-tohigh link. Specifies a scale factor to be used to convert coordinate units to inches. The value is expressed as coordinate units/inch. If the value is not specified, a scale factor will be computed from known information. Note that when a factor is specified, the MAPWINDOW will be used mainly to orient the center of the plot.

MAPSCALE

|R|

368 Cube Voyager Reference Guide

Network Program Control statements

PLOTTER keywords (continued)


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

MARGINS

|R4|

Cube Voyager Reference Guide 369

Network Program Control statements

PLOTTER keywords (continued)


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

POSTLINKVAR

|S4|

POSTLINKVAR

FONT

|S4|

370 Cube Voyager Reference Guide

Network Program Control statements

PLOTTER keywords (continued)


Keyword POSTLINKVAR Subkeyword POST |S| Description Specifies how link post text is to be printed when it is too long for the link. The possible selections are: Fit All AutoSize AutoSize(ss) Omit the text; it doesnt fit. Print it, regardless if it overruns the link. Decrease the font size until it fits, or is too small. Same as AutoSize, but the optional (ss) indicates the minimum size to allow.

POSTNODEVAR

|S4|

Specifies the variables that are to printed to the upper left of a node that is designated for posting by a PLOT NODEPOST value. Specifies the font characteristics for node posting. The standard font designations are specified, but the color is ignored; the PLOT NODEPOST statements set color. The font size can be overwritten on a node-by-node basis.

POSTNODEVAR

FONT

|S4|

Font specifications

You can control all text that is to be printed on the plot. In general, you can specify the name of the font, the size, and the color. The font name must be recognized (and available), or the printer driver will substitute a font of its choosing. If no font is specified, the program will supply the name ARIAL. The size is always specified as absolute, in inches; changing to a different size printer will not alter the size the text. If no size is specified, the program will supply a value of 0.01. The color can be specified in various ways: by a standard name, or a numeric value to index color mix. Colors are processed in Windows by using a number that is a combination of the three colors (red green and blue). You can create the internal number by specifying an integer number (not too likely), a hexadecimal value (very common process), or by a string of digits preceded by a color indicator. Three bytes are used to store the intensity of each of the colors; the values can range from 0 to 255. To use the mixing string, the string must begin with one of the letters (RGB) followed by a number in the range of 0-255, and more

Cube Voyager Reference Guide 371

Network Program Control statements

color strings, if desired. The order of the strings is irrelevant. To enter the hexadecimal value, the string must begin with 0x and be followed by a string of hexadecimal values (0-f ). The table below indicates the standard colors and their various representations. If there is no color for the font, a color will be chosen by the printer driver. For pen plotters, the driver will translate the color number to a pen number. The pen color correlation is determined by the properties of the driver. You may have to experiment to obtain which pen is selected for each color used.
Color black red green blue yellow purple aqua gray silver lime white none Decimal 0 255 49152 16711680 65535 8388736 16776960 8421504 12632256 65280 16777215 -1 HexValue 0x000000 0x0000ff 0x008000 0xff0000 0x00ffff 0x800080 0xffff00 0x808080 0xc0c0c0 0x00ff00 0xffffff -R#G#B# -r255 g128 b255 r255g255 r128b128 g255b255 r128g128b128 r192g192b192 g255 r255g255b255 --

372 Cube Voyager Reference Guide

Network Program Control statements

Example

See Examples on page 387.

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

Cube Voyager Reference Guide 373

Network Program Control statements

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

PROCESS ... ENDPROCESS


Specifies a PROCESS and ENDPROCESS block. PHASE (FILEI (comp))
PROCESS keywords
Keyword PHASE Subkeyword |KS| Description Indicates the phase to which the statements which follow it are to be applied. The end of the phase block is established when an ENDPROCESS or another PROCESS statement is encountered. The value for PHASE must be either INPUT, NODEMERGE, LINKMERGE, or SUMMARY. Used only with PHASE=INPUT, and indicates that the block statements are to be applied only when the specified FILEI file is being processed. Normally, only DBF and ASCII files are processed in the INPUT phase, but if a FILEI with a different mode is specified, the file will be processed in the INPUT phase. The value must be NI.# or LI.#, to indicate a file from NODEI[#], or LINKI[#] that was previously specified on a FILEI statement.

PHASE

FILEI

|F|

Normally, a PROCESS statement contains only the above keywords and values, and the operations to be performed on the designated file during the phase follow on additional control statements. The ENDPROCESS statement can alternatively be specified as ENDPHASE; that is more consistent if the PROCESS control is triggered by PHASE=. Citilabs recommends using PROCESS/ENDPROCESS blocks be used to contain all operational (stack) statements. That way there is no confusion about what is intended. If there is no specific PHASE=LINKMERGE statement, any stack statements that are not explicitly within a PROCESS block, will be executed in the LINKMERGE phase. Even if there are PROCESS blocks surrounded by stack statements, all the stack statements will be executed during the LINKMERGE phase. The program will skip over the PROCESS block.

374 Cube Voyager Reference Guide

Network Program Control statements

There are some rules about PROCESS blocks: There may be only one PHASE=NODEMERGE There may be only one PHASE=LINKMERGE If there is a PHASE=LINKMERGE statement, there may not be stack statements that are not explicitly within a PROCESS block. In other words, once a LINKMERGE phase has been designated, all stack statements must be with an explicitly stated PHASE.

Example 1
; ; ; ; Re-code node numbers for LINKI[1] and NODEI[1] using a lookup function. The 2nd PROCESS statement also acts as an ENDPROCESS statement, but an ENDPROCESS is required after the 2nd PROCESS.

PHASE=INPUT FILEI=NI.1 N = NODECODE(N); PHASE=INPUT FILEI=LI.1; A = NODECODE(A), B = NODECODE(B) ENDPROCESS

Example 2
PHASE=LINKMERGE IF (LI.1.DIST != LI.2.DIST) LIST='Distances Differ for link:', LIST=A(5) B(6), FORM=6.2, LI.1.DIST, LI.2.DIST ENDPHASE

Cube Voyager Reference Guide 375

Network Program Control statements

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

REPORT keywords
Keyword ALL CAPACITY DEADLINKS |?| |?| |?| Description Set all the following reports to this value (not usually recommended). Default value is F. Capacity tables. Default value is F. Links that are missing either an entry or exit link. Such links cannot be used by any path processing. Additional file processing may be required. Default value is F. Duplicate links that are detected during PHASE=INPUT. Default value is F. Internal specifications for the input files (use for debugging only). Default value is F. Internal specifications for the allocation of output variables use for debugging only). Default value is F. Summary statistics following input phases. Default value is F. Summary statistics following every phase. Default value is T. Speed tables. Default value is F. List of zones that do not have links into and out of them. Default value is T.

DUPLICATES FILEI FILEO INPUT MERGE SPEED UNCONNECTED

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

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

376 Cube Voyager Reference Guide

Network Program Control statements

SORT
Sorts user-defined arrays. ARRAY NUMRECS See SORT on page 72 for more information about this standard Cube Voyager statement.
Example
ARRAY AN=LINKS, BN=LINKS, VMT=LINKS ; NETI must be a binary network PHASE=LINKMERGE _L = _L + 1 AN[_L] = A BN[_L] = B VMT[_L] = V_1 * DISTANCE ENDPHASE /* note: The User has to keep count of the records entered into the arrays If links are deleted, the number of entries will be less than the original number number of links. */ PHASE=SUMMARY SORT ARRAY=-VMT, AN,BN, NUMRECS=_L LOOP _K=1,30 ; only want to see the highest 30 LIST=AN[_K](6),BN[_K](6),VMT[_K](10.2c) ENDLOOP ENDPHASE

Cube Voyager Reference Guide 377

Network Program Control statements

SPDCAP
Revises speed and capacity tables. CAPACITY LANES SPEED
SPDCAP keywords
Keyword CAPACITY |RV*99| Description Capacity in vehicles per lane per hour. Actual link capacity is obtained by multiplying the link capacity based upon its capacity classification (CAPCLASS) value by the number of LANES. All values must be 0-9999, inclusive. The capacity array is initialized to 20 times the index number, for all lane stratification (CAPACITY[1]=20, CAPACITY[2]=40...). Lane stratification that any following CAPACITY and/or SPEED values are to apply to. LANES may be interspersed with other keywords and values on the statement. All values must be 1-9, inclusive. Speed to be applied to the link. All values must be 0-3276.7, inclusive. The speed array is initialized to the index number, for all lane stratification (SPEED[1...99]=1,2,...99). Speed is maintained with one decimal place.

LANES

|IV|

SPEED

|RV*99|

A network contains an array of capacity and speed data. Each array is dimensioned with ninety-nine values for each of nine lane stratification, and contains 891 values. When an array is accessed, the program uses the number of lanes (LANES) as the row index, and the capacity and/or speed classification (CAPCLASS, SPDCLASS) as the column index to obtain a value for a link. If CAPACITY or SPEED is encountered prior to a LANES keyword on the statement, LANES will be preset to 1-9. CAPACITY and SPEED are entered as vector data, and may be indexed to set a specific loading place, and may have null fields to skip the revision of certain columns. The SPEEDFOR and CAPACITYFOR functions can be used to obtain values for these tables.
Example
;Set entire table to 50, ; then revise the values for 20,21, and 24 for lanes 1,3,8 SPDCAP CAPACITY=99*50, LANES=1,3,8, CAPACITY[20]=300,400,,,700 SPDCAP LANES=2,4-9, SPEED=20.5,30.3,50.6,,,88.2, LANES=5,SPEED[15]=15 SPDCAP SPEED=30, LANES=2-8; Inappropriate; the LANES will not be used.

378 Cube Voyager Reference Guide

Network Program Theory

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

Phase descriptions
The program processes the input files in separate phases, which are listed below. For most applications, the user need not be concerned with process phases; they are used only when special processing is to be undertaken. In general, the user must code operational statements within a PROCESS PHASE block defined for each phase. There may be only one block for each phase, and the order of the blocks in the input is not crucial. It is suggested that for readability and ease of editing, the phase blocks be defined in the normal process order. Only statements that specifically apply to the phase should be coded within the block. However, statements that are not dynamic operations, but that appear within a phase block will be recognized as such and will be processed properly. A block should be terminated with an ENDPROCESS statement. If another PROCESS PHASE statement is encountered before an ENDPROCESS statement, the previous block is terminated, and the new block is begun. The basic phases are: INPUT phase Read ASCII and DBF files, re-code values from any input files specifically designated. NODEMERGE phase Read all node data and organize it LINKMERGE phase Read all link data and process it (main phase)

Cube Voyager Reference Guide 379

Network Program Theory

SUMMARY phase Report results of LINKMERGE phase

There need not be a specific PROCESS PHASE for LINKMERGE, because it is anticipated that most applications will be functioning in only this phase. If an operational statement is encountered, and it is not within a PROCESS block, it is tagged as being in the LINKMERGE phase. A PROCESS PHASE=LINKMERGE statement may be coded, but it is not mandatory. Internally, the program processes the phases in the order in which they are described below. As it processes each phase, it determines the files that must be processed in that phase, and processes them. If there are no relevant files for an INPUT phase, the phase is bypassed. As the program processes each file record, it applies any phase operations that the user has designated for the phase.

INPUT phase
All ASCII and DBF files must pass through this phase. The records are processed and edited for errors and duplication. The user may specify selections and computations to be applied to each record as it is processed. It is possible to re-code node numbers in this phase. Binary input files are processed in this phase only if the user has specifically designated the file through the use of a PROCESS PHASE=INPUT block. Any file (or file segment) that passes through this phase, is no longer used in its original format after this phase is completed; but its data are used in subsequent phases in a revised internal format. The file segment records are sorted in appropriate order (node or link) before being stored in the revised format.

NODEMERGE phase
The node based records from all the NODEI files must pass this phase. As in the INPUT phase, the user may specify computations and/or selections to be applied to each node record as it is processed. It is not permissible to re-code node numbers in this phase. The resulting record for each unique node is written to the output network, and saved for subsequent referencing in the LINKMERGE phase.

380 Cube Voyager Reference Guide

Network Program Theory

LINKMERGE phase
The link based records from all the LINKI files must pass through this phase. As in the above phases. the user may specify selections and computations to each link record as it is processed. This is the phase that most users are mostly interested in. Records can be deleted, summarized, tabulated, and extracted to an external device or file. Node based data can be accessed during the link processing. Tabulated and summarized data is reported at the end of the phase, and, in most cases, passed onto the final phase.

SUMMARY phase
In this phase, certain post-processing operations can be performed. This is generally restricted to computations on working variables, usually to obtain averages, etc. Every record is processed according to the purpose of the current phase. If there are operations to be performed in the phase, the record is processed against the operation statements designated by the user. Operation statements are generally expressed in the standard IF/ELSEIF/ELSE block and COMP statements. These and other operations available to the user are described in Control statements on page 334. In the NODEMERGE phase, a node record is processed for each unique node from the NODEI files. If a node is re-coded in the INPUT phase, the re-coded node number is included. In the LINKMERGE phase, a link record is processed for each unique link found from the LINKI files. If a link is recoded in the INPUT phase, the recoded link is included.

Variable referencing
The main logic of the program involves processing variables. A variable name may be up to 15 characters in length, and may consist of only letters, digits, and the underscore character. The first character of the name may not be a digit. If the first character of a name is an underscore (_), the variable is only a local working variable, and will not be included in the network. Variables are usually classified as either node or link based. Classification

Cube Voyager Reference Guide 381

Network Program Theory

depends upon the process phase in which the variable is referenced. If a new variable is computed (NEWVAR=...), it will be attached as either a node or link variable. During any INPUT phases, the variables will be associated with the type of file being processed. During the NODEMERGE phase, the variables are node based. During the LINKMERGE phase, variables are link based, but node variables can be referenced. A node variable is referenced during LINKMERGE as either A.name or B.name. If a variable from an input file is to be referenced during NODEMERGE or LINKMERGE, the associated NODEI or LINKI file number must precede the variable name. For NODEMERGE the prefix is NI.#., and for LINKMERGE the prefix is LI.#. For example: LI.3.ABC references the variable ABC from the LINKI[3] file. The program establishes a buffer for a record from each input file for every record in the phase, and the prefix allows access to each of those buffers. If there is no input record for the current working record, the values are all zero. The formal designation for the prefix is LI.#., but the program allows the following variations: For node records: NI.#.name* NI#.name N.#.name N#.name For link records: LI.#.name* LI#.name L.#.name L#.name

*The preferred method of designation. Another type of variable is the working variable. Working variables are variables that are to be used for intermediate storage, and will not be part of an output network. They are distinguished by their first letter, which must be an underscore. Working variables are set to zero at the beginning of the application, and are changed only by user statements. If there is a user SUMMARY phase, every variable referenced within the SUMMARY block is a working variable, unless it is the same as a link variable. If it matches a link variable, the variable from the last link will be processed. Working

382 Cube Voyager Reference Guide

Network Program Theory

variables allow the user to accumulate statistics during link processing, and to then compute and print summaries at the end of processing.
NOTE: In some situations, a PRINT LIST variable may not be

recognized if it is cross-referenced. For example: LIST=A,B,A.X,B.X may not be accepted. To be sure, node based variables to be listed should be set into temporary variables and then listed with that name. (See Examples on page 387 for an illustration.)
Example
_vdiff = L1.vol - L2.vol; get assignment differences _vcnt = _vcnt + 1 if (_vdiff != 0) _sumsqdiff = _sumsqdiff + _vdiff*_vdiff . . Phase=SUMMARY if (_vcnt > 1) RMSV = sqrt(_sumsqdiff / _vcnt); possibly (_vcnt-1) list = 'RMSV =', RMSV endif Phase=LINKMERGE _ax = a.x ; get the Node variable named X for Node A _ay = a.y LIST=a,b,_ax,_ay EndPhase

Output variables
During the merge phases, a work record is generated for each unique record that appears in all the input files (depending upon the value of the MERGE RECORD keyword). Each work record will contain all the unique variables that are defined in/for all the input files and any COMP statements for the phase. The value that is stored for each variable is controlled by the MERGE control statement. If all the variables are not to be included in the output network, the variable list can be modified on the FILEO statement.

Cube Voyager Reference Guide 383

Network Program Theory

Plotting
The network that is formed during the LINKMERGE phase can be plotted by sending information to a standard Windows printer device. There must be an appropriate printer device driver for the media where the network is to be plotted. Typical types of drivers are available for printers, faxes, raster plotters, and pen plotters. The Network program uses the Windows driver to perform the actual formatting of the network information. Many default drivers come with Windows and provide considerable capabilities. This process provides for current and future flexibility. It is possible to directly fax a network plot to a facsimile machine. Windows operating systems are geared towards more recent technology, so pen plotters are being left somewhat behind. They do cause some problems. Pen plotter problems: The standard Windows drivers for pen plotters do not seem to function properly; in particular, they do not always write text at the proper location and angle. There are thirdparty software drivers available that correct this problem, but deficiencies have been reported in these systems, as well. With one driver (WinPlus), if legends are used, the link posting will be oriented properly, but mis-positioned. This release of the program does not address these driver deficiencies; perhaps later versions will internally rectify them. Plotting pens are selected by RGB (RedGreenBlue) standards, so it becomes the responsibility of the user to ensure that the colors that are selected correspond with the pens on the plotter. If standard colors are used (red, green, blue, yellow, etc.), there should be no problems. If esoteric colors are requested, color correspondence is not guaranteed. If roll size is selected in the device driver, the program may not be able to properly scale the plot. In those cases, the user must specify the desired plate size. It is recommended that if pen plotters are to be used that the WinPlus driver be obtained and installed as a printer driver and that the PLOTTER statement contains no LEGEND keywords.

384 Cube Voyager Reference Guide

Network Program Theory

A PLOTTER control statement is used to define the plotting system and the parameters for performing the plot. PLOT statements processed during LINKMERGE determine what will be plotted from the network. If there are PLOT statements, but no PLOTTER statement, the program will fatally terminate; the opposite is not an error. The PLOTTER statement contains information about: The plotting device name, and whether the output is to be sent directly to the plotting device, or to a file. The logical layout of the plot plate on a sheet of the plotter device: the desired size, if different than the driver provided size, and the margins to place the plate within the driver provided dimensions. The optional network window for selection, and optional scaling. The headers and footers to be printed on the plot. Legends that can be displayed in the corners of the plotting window. The link variables that are to be posted when a link is selected for posting. The node variables that are to be posted, when a node is selected for posting. Bandwidths and type of fill and end tapers.

In general, all text that is to be plotted can have its font, color and size specified by the user. The default values for each of these are: ARIAL, black, 0.10. All sizes are specified in inches, so that if a different driver is used, the text would still be readable. Link posting (writing text along a link) can not be varied by link; if a link is posted, its posting will contain the same type of information at the same size and font as any other link that is posted. The user controls the color of link posts; individual variables can not be colored differently. Node posting (writing text near a node) will always post the same variables, but the size and color is controlled by PLOT statements.

Cube Voyager Reference Guide 385

Network Program Theory

Before performing a plot, the device driver must be properly installed. This is done by left clicking the Windows Start button and choosing Printers and Faxes. In the Printers and Faxes window, click Add a printer and follow standard installation processes. The orientation of the plot, (portrait, landscape) is set in the device. If a device is not attached directly to the computer, the driver should have the file option specified, and the PLOTTER DEVICE FILE value (filename) should be specified. Files are generally processed by copying them directly to the plotter port.
PLOT statements control actual plotting. If a PLOT statement is processed in LINKMERGE, the current link is flagged for processing by the plotting process. The following processes are considered:
Process DrawLink LinkPost DrawA NodePost Description Draw the link as specified. Post variables for the link. Draw a specified symbol for the Anode of the link Post variables at the A node.

These values can be specified multiple times for each link; the values that are current at the end of the link are used for plotting. For node processing, the values that are current following the last link outbound from a node are used. If the PLOT statement is invoked by the use of one of these trigger keywords, it may be placed on a short IF statement. Example: IF (...) DrawLink=red, LinkPost=red. If a keyword specifies plotting, but then later conditions determine that it should not really be plotted, the keyword can be nullified by setting its value to -1. Example: NodePost=-1. Many times a link posting may be too long for the link. You can deal with these situations by specifying the fourth value for PLOTTER POSTLINKVAR FONT.

386 Cube Voyager Reference Guide

Network Program Examples

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

Listing links to the print file


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

Merging link records from multiple ASCII files


run pgm=NETWORK ; merge two ASCII files with different links linki[1]=demo07.dat,var=a,2,4, b,7,4, dist,14,4, v1,2,4, v2,2,4 linki[3]=demo07m.dat,rev=2, var=a,2,4, b,7,4, dist2,14,4, rev,35,1, v1,2,4, v2,2,4 nodei[1]=c:\demo\demoxy.dat,var=n,x,y merge record=true, AVE=dist report all=no zones=19 phase=LINKMERGE if (li.1.a == 0) list=' LI[1] missing link:', a,b if (li.3.a == 0) list=' LI[3] missing link:' a,b endphase endrun

Dumping link and node records to DBF files excluding select fields
run pgm=NETWORK ; write DBFs for nodes and links, ; but exclude many variables from input

Cube Voyager Reference Guide 387

Network Program Examples

neti=test.Hnt neto=test.tpn, EXCLUDE= SCENARIO STATUS NAME TPCAP1 TPCAP2 TIPRTP CNT, EXCLUDE= FIELDOPT TCNUMBER COUNTY USER DATE OCOUNTA OCOUNTP, EXCLUDE= OCOUNTD OSPEEDA OSPEEDP OSPEEDD, EXCLUDE= OSPEEDX OSPEEDY ECOUNTA ECOUNTP ECOUNTD ECOUNTY, EXCLUDE= ESPEEDA ESPEEDP ESPEEDD ESPEEDY COMMENT6 COMMENT1, EXCLUDE= ATYPE nodeo=testxy linko=testld if (STATUS=='D' || ft==15) delete endrun run pgm=NETWORK ;now look at the results from the link DBF linki=testld.dbf nodei=testxy.dbf,exclude=xcoor,ycoor If (a>b && lanes > 4) list=a,b,lanes endrun

Building network from inline data records


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

388 Cube Voyager Reference Guide

Network Program Examples

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

Simple link plot


; Sample Quickie plot with no parameters: draw links only RUN PGM=NETWORK ; sample quick link plot NETI = C:\DEMO\DEMO20.DAT PLOTTER DEVICE = "HP 7475A", FILE=f:\sample.plt DRAWLINK=0xffff ENDRUN

Complex plot
;This sample illustrates various capabilities of plotting. RUN PGM=NETWORK NETI = C:\DEMO\DEMO20.DAT PLOTTER { ; SETUP Plotter DEVICE="HP LASERJET 4" POSTLINKVAR=A,B,_AB,_STR FONT='COURIER',0.10,YELLOW,BOLD POST=AUTOSIZE(.05) POSTNODEVAR=A, FONT='COURIER',.10 LINKOFFSET=0.01 BANDWIDTH=_BANDWIDTH FILL=SOLID TAPER=45 HEADER= "This is header 1", "This is header 2", align=center, font='courier' ,0.1,green FOOTER="Footer 1" FOOTER[3]="Footer 3" FOOTER[5]='Shows various date tokens: [date] [idate]' FOOTER[7]='Shows various time tokens: [time] [times]', FOOTER[7]='Shows window and scale tokens: [window] [scale]' align=right font='Courier',0.15,green LEGEND=TopLeft, font='courier',.10,blue,italics, LINE[1]=TL.LINE1,symbol=triangle,.15,red LINE[5]=tl.line5,symbol=Dash,.15,red LEGEND=TR, font='courier',.20,blue,italics, LINE[1]=TR.LINE1,symbol=triangle,.5,red LINE[3]=tr.TRne3,symbol=rectangle,.08,red LEGEND=3, font='courier',.10,red,italics, LINE[1]=BL.LINE1,symbol=circle,.10,red LINE[5]=BL.line5,symbol=dashdot,.15,red LEGEND=BottomRight font='courier',.15,purple,italics,

Cube Voyager Reference Guide 389

Network Program Examples

LINE[2]=BR.LINE2,symbol=triangle,.15,red } ; Plotting Controls if (a<=19 || b<=19) _BANDWIDTH = lane/10 _AB = A*100 + B _STR = str(_ab/100,5,2) DRAWLINK=RED,,SOLID, LINKPOST=GREEN IF (A.X == B.X || A.Y == B.Y) LINKPOST=BLUE; FLAT|VERTICAL LINES DRAWA=BLUE,0.20,CIRCLE,YELLOW NODEPOST=r123b220g100,.1 IF (A>=30 && A <40) LINK=GREEN,,DASH ; reset the color of these links ; set node postings and symbols IF (A<=5) DRAWA=RED,0.10,CIRCLE,WHITE NODEPOST=0XFF00FF IF (A>5 && A<=10) DRAWA=RED ,0.40 CIRCLE NODEPOST=G255 IF (A>10 && A<20) DRAWA=R255,0.15,RECTANGLE,BLACK NODEPOST=R255 ENDRUN

390 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Matrix Program

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

Cube Voyager Reference Guide 391

Matrix Program Using the Matrix program

Using the Matrix program


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

Introduction to the Matrix program


The Matrix program processes zonal data and matrices according to specified expressions. Zonal data and matrices can be input, and matrices and reports can be output. Various file formats for both input and output are supported. There are no default processes; it is the users responsibility to specify what is to be accomplished. This program is also used when invoked as a special function via RUN PGM= FRATAR, GENERATION, or DISTRIBUTION. It is used for the following purposes: Computation of new matrix values Trip distribution (called by Distribution program) Trip generation (called by Generation program) Converting and merging matrices between various formats Reporting values from matrices and zonal data: Selected rows Marginal summaries (trip ends, etc.) Frequency distributions User formatted files

392 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Transposing matrices Generating matrices Renumbering, aggregating, and disaggregrating matrices

Almost any and all of the above processes can be performed in a single application. There are some restrictions when used as a special function (Fratar, Distribution, and Generation programs). The program processes within an overall origin zone loop controlled by the variable named I. The remainder of this document refers to this loop as the I loop. The loop begins with I set to one and continues monotonically until the highest zone number is processed. When Matrix is called by Distribution, I-loops are nested within iteration loops. (See Chapter 6, Highway Program, for details.) The standard input is comprised of definition, computational, reporting, and flow control statements (illustrated below). Definition statements are those that define the input and out files, and are, in most cases, processed outside of the I loop. Computational statements are those that cause data to be revised. Flow control statements provide the capability to iterate through portions and conditionally or unconditionally branch to a different place, within the I loop. When all control statements have been checked for basic syntax, and have been stored in the control stack, the program builds a list of required variables. The input files are opened; zonal data files are read and stored, and other housekeeping is performed. If any input matrices need to be transposed, they are transformed to a single file and made ready for subsequent retrieval. It then starts the I loop, reads the matrices for I, and processes the control stack from the beginning. When the end of the stack is reached, the program performs some end-of-zone summaries, and writes any matrices requested. When the I loop completes (or is terminated), any requested reports are printed, and the program exits.

Cube Voyager Reference Guide 393

Matrix Program Using the Matrix program

All variables are initialized to zero (or blank) before the I loop, and are thereafter altered only by computational statements or internal processing. In addition to any variables explicitly specified by the users, there are certain built-in variables that can be referenced. The built-in variable are usually protected; the user is not allowed to alter their values. Subsequent topics discuss: Built-in variables Built-in functions Transposed matrices

Built-in variables
Matrix program built-in variables
Variable FIRSTZONE Description Stores the zone number of the first zone being processed. In a normal run this is 1. Under intrastep distributed processing with Cube Cluster, this is the first zone number of the zones to be processed on the current Cube Cluster node. The current row zone. The iteration number; usually 1. A column index, usually 1, and varies (1-Zones) for MW[] and LOOPs. Stores the last zone number to be processed. In a normal run this would be the same as ZONES. Under intrastep distributed processing with Cube Cluster, this is the highest zone number to be processed on the current Cube Cluster node. Result of LOWEST(); A work matrix; see COMP on page 460 for more details. Holds the number of fields on the input record file. Holds the number of records in the input record file. Holds the record number of the current record being processed from the input record file.

I ITERATION J LASTZONE

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

394 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Matrix program built-in variables (continued)


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

Z ZONES

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

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

Cube Voyager Reference Guide 395

Matrix Program Using the Matrix program

Control statement types in Matrix program


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

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

updated. BSEARCH CALL CHOICE COMP FREQUENCY SET XCHOICE


Reporting statements Cause values to be accumulated

and/or displayed dynamically. FREQUENCY PRINT PRINTROW REPORT


Flow control statements Set which statement is to be

performed next. GOTO :label

396 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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

Working with intrazonal cells of a matrix


During the processing of demand data it is often necessary to access the intrazonal element of a matrix or to set its value. Special keywords INTRAZONAL or INTRA are provided to assist in this. To set the intrazonal element of a matrix row, the normal COMP command is amended to take one of the following forms:
INTRAZONAL MW[] = expression COMP MW[][INTRAZONAL] = expression COMP MW[][INTRA] = expression

where the appropriate working matrix number is inserted into the []. When such commands are executed, all elements of the matrix which lie off the diagonal are left unchanged. Note that it is invalid to use the above forms of calculation with a JLOOP (as JLOOP implies varying the j, or column, whereas INTRAZONAL or INTRA fixes it to i, or the row index). Neither can it be used with the INCLUDE or EXCLUDE subkeywords of the M[] statement, which are used to select destination zones. Such commands may be used in conjunction with the LOWEST function set an intrazonal cost based on the cost to the nearest zone(s). As an example:
INTRAZONAL mw[10] = 0 INTRAZONAL mw[10] = LOWEST(10, 1, 0.01, 99999)

Cube Voyager Reference Guide 397

Matrix Program Using the Matrix program

sets the intrazonal cost to the cost from the origin to the nearest destination, but ignoring destinations with costs less than 0.01 or more than 99999. The preceding setting of MW[10]s intrazonal cell to zero ensures that any starting value in that cell does not become the result of the LOWEST function. The INTRAZONAL or INTRA keywords may be used to access the diagonal element of a matrix during calculations. This keyword is coded in a similar manner to the j (or column) position when a matrix is referenced in an arithmetic expression. Examples are:
MW[1] = MW[1][INTRA]

which copies the intrazonal (or diagonal) element of the first working matrix into all column positions, and:
var1 = MW[10][INTRAZONAL]

which sets a scalar variable var1 to the intrazonal element of working matrix ten, taken from the current row of the matrix.

Working with lists of zones


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

398 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Working with list of zones using the substitution method Defines lists in the Pilot program, then uses the substitution facility to work with them; it is less easy to define the required lists, but they may be used in a wider range of contexts.

Working with lists of zones using the INLIST function


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

Cube Voyager Reference Guide 399

Matrix Program Using the Matrix program

Working with list of zones using the substitution method


As an example, zones 1 to 12 and 15 to 20 form the CBD of a study area. A list called CBD may be defined, using the COMP or computation control statement. The list of zones is specified as text data which is enclosed in quotes ('). This is done in the script before any RUN PGM statements for programs, and forms part of the script of the Pilot program. Wherever this list of zones is required by a program, its script contains the name of the list, which is enclosed by @ symbols (denoting substitution of the list of zone numbers, in place of the lists name). The example:
CBD='1-12,15-20' ... RUN PGM = MATRIX ... MX[10]=mi.1.LOSmatrix ... JLOOP INCLUDE = @CBD@ MX[10] = MX[10] + 10 ENDJLOOP ... ... ENDRUN

defines the list of zones in the CBD, then adds a parking cost of 10 units into the skim (or level of service) matrix for destination zones in that area. The defined list may contain individual zone numbers and / or ranges of zone numbers; the latter are specified in the form 1-10 with neither space or ',' (comma) between the start and end values. To ensure that the list is generally acceptable, it should be written with commas between items. (Although Cube Voyager scripting allows spaces to be used as delimiters between items of a list, this form is not accepted by the conditional or IF statement which requires commas, and so use of commas is recommended.) A further example changes that part of a matrix which corresponds to origins in the suburbs and destinations in the CBD, dividing these matrix cells by 1.05:
...

400 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

suburbs = '100-145,148-191,194-224,227-341' CBD = '1-12,15-20' ... RUN PGM = MATRIX ... if(i = @suburbs@) jloop if(j = @CBD@) mw[1]=mw[1]/1.05 endif endjloop endif ... ... ENDRUN

The calculation may be expressed more concisely as:


if(i = @suburbs@) jloop include = @CBD@ mw[1]=mw[1]/1.05 endjloop endif

or even:
if(i = @suburbs@) mw[1]=mw[1]/1.05 include=@CBD@

The following illustrates the case where the calculation applies to all destination zones for selected origins:
... CordonZones = '540-578' ... RUN PGM = MATRIX ... if(i = @CordonZones@)mw[5]=mw[5] * 1.27 ... ENDRUN

Cube Voyager Reference Guide 401

Matrix Program Using the Matrix program

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


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

402 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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

Cube Voyager Reference Guide 403

Matrix Program Using the Matrix program

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

Working with logit choice models


This section discusses logit choice models. Topics include: Introduction to choice modeling Absolute logit model Incremental logit model Hierarchical logit model Destination choice

404 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Mode and destination choice General notes

Introduction to choice modeling


Beginning with version 4.1 of Cube Voyager, the XCHOICE control statement replaces the CHOICE control statement for implementing logit choice models. XCHOICE implements the same logit model structures as the original CHOICE statement but improves choicemodel run times. A choice model implemented with XCHOICE should run significantly faster than the same model implemented with CHOICE. The CHOICE command statement continues to function as in prior versions. Existing choice models that use the CHOICE statement will continue to run as scripted. However, Citilabs recommends modifying existing models to use the XCHOICE command statement and take advantage of the improvements in run time. Use the XCHOICE command statement whenever developing new choice models in the Matrix program. Note that some of the keywords are different with the XCHOICE command statement. When converting a logit model that uses CHOICE to use XCHOICE, you must make additional changes at the keyword level. For detailed changes please refer to XCHOICE on page 451. The XCHOICE (CHOICE prior to v4.1) command in Cube Voyager scripting provides powerful extensions to the core language designed to allow complex logit choice models to be specified easily. Logit choice models have a number of distinct possible outcomes (for example mode of travel), and the model estimates the probability of choosing each particular outcome. The alternatives are evaluated using either their costs or their utility values. Costs and utilities are related. As the utility of an alternative increases the alternative becomes more attractive, but an increase in cost makes the alternative less attractive. Apart from sign, the other difference is that a utility directly measures the users benefit, whereas the cost has to be multiplied by an appropriate coefficient (or scale parameter) before use in choice models.

Cube Voyager Reference Guide 405

Matrix Program Using the Matrix program

The simplest choice model splits total travel demand between two alternatives (or modes); it is known as the binary choice model. This may be extended by adding further alternatives, so forming a multinomial model. In practice when several alternatives exist, the alternatives are not always independent of each other. To overcome this hierarchic choice models are used which sub-divide the choice process into a sequence of decisions. Alternatives which are similar are grouped together to form sub-nests. Typical examples of sub-nests are public transport (which brings together various transit modes), or car use (which includes through-trip by car and park-and-ride). These sub-nests are then brought together in the main (or toplevel) choice process. The choice process may be viewed as initially choosing between sub-nests (representing types of travel), and then choice at the sub-nest level which decides the mode used. The simple choice and hierarchic models described above are forms of the absolute logit choice model. An alternative form is the Incremental model (also known as the Pivot Point model) which has a different methodology. It uses data for demand (by alternative) in the base situation together with changes in costs (or utilities) between the base and forecast scenario, in order to re-allocate the demand between the alternatives in response to those cost changes. The destination choice model is an extension to the logit choice concept where the alternatives are not modes of travel, but destination zones which the traveler chooses between. It may be combined with mode choice to form complex models, and may be used in absolute or incremental form. The section uses a number of examples to illustrate use of the CHOICE command and to explain the underlying theory. The examples start at the simplest level and increase in complexity. They are: Absolute logit model Incremental logit model

406 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Hierarchical logit model Destination choice Mode and destination choice

Each model is described in the context of a typical problem, supported with the relevant theory. Then the method for implementing a solution in the Matrix program is shown, with example scripts. For some models, alternative strategies or more complex variations are also illustrated. Finally, any practical issues related to setting up such a model are discussed. At the end of the section there are some general notes concerning coding of demand models. For a detailed description of the demand modeling function syntax see XCHOICE on page 451.

Absolute logit model


This section discusses the absolute logit model. Topics include: Introduction Logit Choice model Scale parameter (cost-based models) Matrix script for cost-based model Matrix script for utility-based model

Introduction

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

Cube Voyager Reference Guide 407

Matrix Program Using the Matrix program

between a given set of origins and destinations. A user of such a system is said to have a binary choice, because there are just two alternatives (car and PT).

Structure of absolute logit model

The following paragraphs explain how the absolute logit model can be applied to the problem of estimating the probability of choosing each mode, and in particular how this is implemented in Cube Voyager.
Logit Choice model

The process begins by calculating the generalized cost of travel between each origin and destination by either mode. Usually, this cost is a linear combination of the monetary cost (fare, fuel, etc.) and time (walk, wait, interchange, in-vehicle-time, etc.). There may also be an additive constant to approximate those elements of the cost that cannot be readily quantified, for example the convenience of bus services, or the quality of railway rolling stock. Lets call the cost of travel by car, Ccar, and by PT, Cpt. Suppose that there is a total demand, D, that make such a journey in a given period. For the sake of clarity, subscripts relating to the origin and destination zone have been omitted.

408 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

The Absolute Logit Model states that the probabilities of choosing car, Pcar, and PT, Ppt, are given by the equations below.

Where is the scale parameter, of which more later. The forecast demand for car is given by Dcar and for PT, Dpt.

The model also calculates a composite cost (C) that represents the cost of the combined choice (in this case, car and public transport), where:

Where utilities are used instead of costs, this simple choice model does not require a distinct scale parameter, as its effects have already been incorporated into the utility values. Using utilities, the probabilities of choosing car, Pcar, and Ppt, are:

Cube Voyager Reference Guide 409

Matrix Program Using the Matrix program

the composite utility (or logsum) is:

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

The behavior of the model is determined by a positive constant known as the scale parameter, called in the equations above. The graph below illustrates the model sensitivity with different values of . If =0 the model is completely insensitive to cost, and demand is shared equally between each of the available choices. Notice that Pcar= and Ppt= when =0. As increases, the sensitivity of the logit model increases, progressively allocating more demand to the choice with the lower cost. The figure Logit model sensitivity on page 411 shows how the model becomes more responsive to the difference in cost for =0.01, 0.02 and 0.04. Finally, as approaches infinity, the model will allocate all the demand to the alternative with the lowest cost.

410 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

The value of the scale parameter will depend on the nature of the choice, characteristics of the demand and the units of cost. The examples used here are for illustrative purposes and should not be adopted as default values.

Logit model sensitivity

Where choice models are based on utilities, there is no cost coefficient as it has already been combined with the actual cost to form the utility values. Thus for simple choice models, the scale parameter is not required. Scale parameters are used in more complex (or hierarchic) models, but their specification and values are different from the style of use in cost-base models.
Matrix script for cost-based model

This section describes how this example can be implemented using the XCHOICE command. The fragment of script below will run this model. Variable names have been chosen to match those used in the preceding equations.
; Absolute logit model

Cube Voyager Reference Guide 411

Matrix Program Using the Matrix program

XCHOICE, ; List choices ALTERNATIVES = car, pt, ; Input total demand DEMANDMW = 10, ; Input costs COSTSMW = 3, 4, ; Forecast demand ODEMANDMW = 15,16, ; Model structure SPLIT = TOTAL 0.02 car pt, ; Forecast composite cost SPLITCOMP = 19, ; Working matrices STARTMW = 30

The XCHOICE command comprises a number of clauses of the form keyword = value(s) each of which defines some aspect of the logit choice model. These specify what alternatives may be chosen, the inputs to the calculations, the resulting outputs, and the structure of the logit choice model. The block begins with the ALTERNATIVES clause listing of the names of the alternatives. In this case the choices are car and PT. These names will be used later to define the model structure. The model inputs are specified, starting with the total demand which is coded in the DEMANDMW clause. The specified input may represent a matrix of true demand (in trips), as shown here using MW[10], or it may be set to 1, in which case the output demand will be the probabilities associated with each alternative. Next, the generalized costs are specified for car, as matrix MW[3], and PT, as matrix MW[4]. These should be listed in the same order as the modes in the ALTERNATIVES clause. Now the output variables are specified. These are forecast demand for each alternative, again specified in the same order as the ALTERNATIVES clause, so MW[15] will contain car trips and MW[16] PT trips.

412 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Finally the structure of the choice model is defined. In this example the choice is between two modes, car and PT, but this may be extended to three or more alternatives. The SPLIT clause defines the models structure in terms of the scale parameter (or coefficient of generalized costs) and the choices given in the ALTERNATIVES clause. The word TOTAL indicates that the entire input demand is to be split between the alternatives listed in this specification. The scale parameter has a value of 0.02 (or =0.02 in the above equations) and the choice is between the car and PT alternatives. In this script, the scale parameter is given as a numerical value but it is equally valid to use a variable instead. The forecast composite cost is output as MW[19] with the SPLITCOMP keyword. Both the forecast demand and composite cost are optional outputs, and either clause may be omitted from the script. The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the XCHOICE command. The STARTMW clause specifies a working matrix number which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the XCHOICE command, and should not be used elsewhere in the script. Where a Matrix program script contains several XCHOICE commands, the same STARTMW value may be used in all instances.
Matrix script for utility-based model

This section describes how this example can be implemented using the XCHOICE command. The fragment of script below will run this model. Variable names match those used in the preceding equations.
; Absolute logit model XCHOICE, ; List choices ALTERNATIVES = car, pt, ; Input total demand DEMANDMW = 10, ; Input utilities

Cube Voyager Reference Guide 413

Matrix Program Using the Matrix program

UTILITIESMW = 5, 6, Forecast demand ODEMANDMW = 15,16, ; Model structure SPLIT = TOTAL car pt, ; Forecast composite utility SPLITCOMP = 18, ; Working matrices STARTMW = 40 ;

The XCHOICE command comprises a number of clauses of the form keyword = value(s), each of which defines some aspect of the logit choice model. These specify what alternatives may be chosen, the inputs to the calculations, the resulting outputs, and the structure of the logit choice model. The block begins with the ALTERNATIVES clause listing of the names of the alternatives. In this case the choices are car and PT. These names will be used later to define the model structure. The model inputs are specified, starting with the total demand which is coded in the DEMANDMW clause. The specified input may represent a matrix of true demand (in trips), as shown here using MW[10], or it may be set to 1, in which case the output demand will be the probabilities associated with each alternative. Next, the utilities for car, as matrix MW[5], and PT, as matrix MW[6]. These should be listed in the same order as the modes in the ALTERNATIVES clause. Now the output variables are specified, as working matrix (MW) numbers. These are forecast demand for each alternative (MW[15] for car trips and MW[16] for PT, again specified in the same order as the ALTERNATIVES clause). Finally the structure of the choice model is defined. In this example the choice is between two modes, car and PT, but this may be extended to three or more alternatives. The SPLIT clause defines the models structure in terms of the choices given in the ALTERNATIVES clause; here the choice is between the car and PT alternatives. The word TOTAL indicates that this split divides the entire input demand between the specified

414 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

alternatives. The forecast composite utility is output as MW[18] with the SPLITCOMP keyword. Both the forecast demand and composite utility are optional outputs, and either clause may be omitted from the script. The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the XCHOICE command. The STARTMW clause specifies a working matrix number which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the XCHOICE command, and should not be used elsewhere in the script. Where a Matrix script contains several XCHOICE commands, the same STARTMW value may be used in all instances.

Incremental logit model


This section discusses the incremental logit model. Topics include: Introduction Incremental logit choice model Matrix script for cost-based model Alternative script using cost differences Matrix script for utility-based models Alternative script using differences in utilities

Cube Voyager Reference Guide 415

Matrix Program Using the Matrix program

Introduction

This example returns to the structure of the absolute choice example, but now forecasts the change in demand based on the change in cost from a known base situation. This is known as the incremental form of the logit model. The structure of the model shown below in Figure 1.

Structure of incremental logit model

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


Incremental logit choice model

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

Base probabilities are denoted by Pcar and Ppt where:

416 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

The choice model now takes the form of the equation below where P denotes the forecast choice probability and is the scale parameter.

So that the forecast demand by mode (Dcar, Dpt) is:

The incremental composite cost (DC) is given by:

When working with utilities, the above equations are adapted to reflect the absence of any scale parameter (as this is combined into the utility values). The utility differences are calculated as:

Cube Voyager Reference Guide 417

Matrix Program Using the Matrix program

and the probabilities of using each alternative are:

The equations for base and forecast demand by mode are the same as for cost-based models. The utility-based form of the composite costs is given by:

Matrix script for cost-based model

Comparing the example code below with the first example (same structure, but an absolute logit model), one can see that only the model inputs change to construct an incremental model. The model requires base demand, base costs and forecast costs for both modes as input. The output composite cost is the incremental change in composite cost.
; Incremental logit model XCHOICE, ; List choices ALTERNATIVES = car, pt, ; Input base demand by mode BASEDEMANDMW = 10, 11, ; Input base costs by mode BASECOSTSMW = 20, 21, ; Input forecast costs by mode COSTSMW = 30, 31, ; Forecast demand ODEMANDMW = 2,3, ; Model Structure SPLIT = TOTAL 0.02 car pt, ; Forecast incremental composite cost SPLITCOMP = 7, ; Working matrices

418 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

STARTMW = 40

Alternative script using cost differences

The XCHOICE command allows cost changes to be given instead of base and forecast costs. This variant is particularly useful when the costs do not change for all modes. For example, suppose that the car cost is constant and that a series of tests are to be conducted for different PT scenarios. In this case, there is no need to calculate the car cost for each test. Instead, the change in car cost, DCcar, can be set to zero. Where the cost difference is zero, the numeric value may be specified as the cost difference for the alternative (rather than needing to construct a matrix of zero values). The example excludes the calculation of incremental composite costs.
; Incremental logit model (specifying cost differences) ; Specify scale parameter (or cost coefficient) lambda = 0.02 XCHOICE ; List choices ALTERNATIVES = car, pt, ; Input base demand by mode BASEDEMANDMW = 10, 11, ; Input CHANGE in cost (= ForecastCost - BaseCost) DCOSTSMW = 24, 25, ; Forecast demand ODEMANDMW = 2,3, ; Model Structure SPLIT = TOTAL lambda car pt, ; Working matrices STARTMW = 30

Matrix script for utility-based models

Comparing the example code below with the first example (same structure, but an absolute logit model), one can see that only the model inputs change to construct an incremental model. The model requires base demand, base costs and forecast costs for both modes as input. The output composite cost is the incremental change in composite cost.
; Incremental logit model

Cube Voyager Reference Guide 419

Matrix Program Using the Matrix program

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

mode mode by mode

composite utilities

Alternative script using differences in utilities

The XCHOICE command allows changes in utility to be given instead of base and forecast utilities. This variant is particularly useful when the costs do not change for all modes. For example, suppose that the car cost is constant and that a series of tests are to be conducted for different PT scenarios. In this case, there is no need to calculate the car utility for each test. Instead, the change in car utility, DCcar, can be set to zero. The example excludes the calculation of incremental composite costs.
; Incremental logit model (specifying cost differences) XCHOICE ; List choices ALTERNATIVES = car, pt, ; Input base demand by mode BASEDEMANDMW = 10, 11, ; Input CHANGE in cost (= ForecastCost - BaseCost) ; Car Utilities are unchanged, so are specified as '0' DUTILSMW = 24, 25, ; Forecast demand ODEMANDMW = 2,3, ; Model Structure SPLIT = TOTAL car pt,

420 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Working matrices STARTMW = 100

Hierarchical logit model


This section describes the hierarchical logit model. Topics include: Introduction Cost-based examples of hierarchic logit models Utility-based examples of hierarchic logit models

Introduction

The second example splits the PT mode of the first example into two distinct sub-modes; bus and train. This is an example of a Hierarchical Logit Model, which can be implemented in Absolute or Incremental form.

Structure of hierarchical logit model

Hierarchic models group related choices together in nests (or hierarchies). In this example, bus and train are members of the public transport nest that is considered to be distinct from the (private) car mode. In an absolute model, the choice probabilities are calculated by starting at the bottom of the tree and moving up the hierarchy, calculating the choice probabilities and the composite costs in each nest. In this model the process begins in the PT nest.

Cube Voyager Reference Guide 421

Matrix Program Using the Matrix program

Firstly, conditional probabilities for each of the two PT modes (Pbus|pt and Ptrain|pt) and the composite PT cost are calculated within the lower nest with equations similar to those in the previous section. The composite PT cost will be used next to represent the cost associated with the combined PT choice. The choice probabilities for car (Pcar) and all PT (Ppt) can now be calculated using the technique described in the first example. It is now possible to move back down the hierarchy forecasting demand for each mode with the information derived above, so that:

For incremental models, the calculations are again performed in two stages, using the equations of the Incremental Logit Choice Model. The first pass calculates conditional probabilities and composite costs working up the tree structure; then in the second pass working down the tree, the resulting probabilities are calculated.
Cost-based examples of hierarchic logit models

As before the total demand is specified together with generalized costs for each choice (car, bus and train). A scale parameter must be associated each nest. In this example, the scale parameters are =0.02 in the upper nest (consistent with the previous example) and =0.03 in the lower nest. It is a result of the model theory that the value of the parameters must increase (or at least not decrease) as one moves down the hierarchy. That is to say, the models sensitivity to cost increases down the hierarchy.
Matrix script

422 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

The example below shows how the earlier absolute-choice example can be extended to include the lower nest in the hierarchy:
; Absolute hierarchical logit model ; Specify scale parameters lambda = 0.02 mu = 0.03 XCHOICE, ; List choices ALTERNATIVES = car bus train, ; Input demand DEMANDMW = 1, ; Input costs COSTSMW = 4, 5, 6, ; Forecast demand ODEMANDMW = 14,15,16, ; Model Structure ; Top level nest SPLIT = TOTAL lambda car pt, ; Forecast composite cost top level SPLITCOMP = 19, ; PT nest SPLIT = PT mu bus train ; Forecast composite cost PT level SPLITCOMP = 20, ; Working matrices STARTMW =70

First the modes (car, bus and train) are declared with the ALTERNATIVES clause. Notice that PT is not declared as an alternative; this is the name given to the combined choice of bus and train. Then the model inputs and outputs are specified. The input total demand and costs for the three distinct modes are given first, followed by the output forecast demand by mode. The hierarchical structure is specified by moving down the tree describing each nest. Beginning at the top of the tree, the first split command divides TOTAL (the total demand) into car and (all) PT with scale parameter =0.02. Notice that a scalar variable called lambda has been used to

Cube Voyager Reference Guide 423

Matrix Program Using the Matrix program

represent the scale parameter in this case. PT is not considered as an individual mode now, but as a link with the lower nest. The SPLITCOMP keyword computes the composite costs for the nest associated with this SPLIT, in this case the top level. The second split command sub-divides PT trips between the bus and train alternatives using a scale parameter =0.03. The name pt is used as the first value in the SPLIT clause, and this acts as a link to the next level up the tree (where total demand was divided between car and PT). Another SPLITCOMP keyword for this SPLIT keyword computes the composite costs specific to the PT nest.
More complex absolute hierarchical models

The hierarchy can be extended with additional nests on either side of the tree. For example, a large absolute hierarchical logit model structure might have six choices: car, park and ride, bus, heavy rail, light rapid transit (LRT), and metro.

Structure of a large absolute hierarchical logit model Matrix script illustrating the complex example

This example may be codes as an absolute model as below, with park and ride abbreviated as pandr, and heavy rail as hrail:
; Extract from a large absolute logit model XCHOICE, ; List choices ALTERNATIVES = car pandr bus hrail lrt metro, ; Input demand DEMANDMW = 1,

424 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Input costs COSTSMW = 11, 12, 13, 14, 15, 16, ; Forecast demand ODEMANDMW = 21,22,23,24,25,26, ; Model Structure ; Top level nest SPLIT = TOTAL 0.02 allcar allpt, ; All car nest SPLIT = allcar 0.05 car pandr, ; All PT nest SPLIT = allpt 0.03 bus train, ; Train nest SPLIT = train 0.04 hrail lrt metro, ; Working matrices STARTMW = 45

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

The hierarchic choice model comprises a main choice nests, and a number of sub-nests. As with cost-based models, there is a requirement that higher level nests are less sensitive to cost differences than any sub-nests which lie below them. In the estimation of the utility equations used in the choice model coefficients are estimated for individual cost-terms (such as travel time, and fare) and for scale parameters. The scale parameter is a factor which is applied to the composite utility of a sub-nest before it is used in the choice process of the parent choice nest. To meet the sensitivity requirements noted above, the scale parameter must be greater than 0, and must not exceed 1.0. Thus, the scale parameters of utility-based models are viewed as part of the specification of the output of a split process, and different values may apply to each sub-nest in a choice nest. Where the scale parameter for a sub-nest is 1.0 there is no need to specify its value as this the assumed default. Where a scale parameter applies to two or more sub-nests, it may be specified once and brackets used to group the relevant sub-nests, so avoiding repetition of the parameter.
Matrix script illustrating two-level hierarchy

Cube Voyager Reference Guide 425

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, the total demand is specified together with the utility of each choice (car, bus and train). A scale parameter of 0.6 is applied to the PT sub-nest when its composite (or logsum) utility is used in the calculations of the higher-level nest.
; Absolute hierarchical logit model XCHOICE, ; List choices ALTERNATIVES = car bus train, ; Input demand DEMANDMW = 1, ; Input costs UTILITIESMW = 4, 5, 6, ; Forecast demand ODEMANDMW = 14,15,16, ; Model Structure ; Top level nest. PT sub-nest has scale parameter 0.6 SPLIT = TOTAL 1.0 car 0.6 pt, ; Forecast composite cost for the top level SPLITCOMP = 19, ; PT nest SPLIT = PT bus train ; Forecast composite cost for the PT nest SPLITCOMP = 20, ; Working matrices STARTMW =70

First the modes (car, bus and train) are declared with the ALTERNATIVES clause. Notice that PT is not declared as an alternative; this is the name given to the combined choice of bus and train. Then the model inputs and outputs are specified. The input total demand and utilities for the three distinct modes are given first, followed by the output forecast demand by mode. The hierarchical structure is specified by moving down the tree describing each nest.

426 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Beginning at the top of the tree, the first split command divides TOTAL (the total demand) into car and (all) PT, and specifies a scale parameter of 0.6 which applies to the PT sub-nest. PT is not considered as an individual mode now, but as a link with the lower nest. The composite costs for this SPLIT are output with SLITCOMP. The second split command sub-divides PT trips between the bus and train alternatives, but no scaling parameters are used. The name pt is used as the first value in the SPLIT clause, and this acts as a link to the next level up the tree (where total demand was divided between car and PT). The composite cost for this SLIT are output with another SPLITCOMP keyword.
Matrix script illustrating the complex example

A more complex utility-based example uses the model structure illustrated in Structure of a large absolute hierarchical logit model on page 424. The example below is coded below in incremental form using utility differences:
; Extract from a large absolute logit model XCHOICE, ; List choices ALTERNATIVES = car pandr bus hrail lrt metro, ; Base demand BASEDEMANDMW = 1, 2, 3, 4, 5, 6, ; Utility differences DUTILSMW = 11, 12, 13, 14, 15, 16, ; Forecast demand ODEMANDMW = 21,22,23,24,25,26, ; Model Structure ; Top level nest SPLIT = TOTAL 0.4 allcar 0.667 allpt, ; All car nest SPLIT = allcar car pandr, ; All PT nest SPLIT = allpt 1.0 bus 0.75 train, ; Train nest SPLIT = train hrail lrt metro, ; Working matrices STARTMW = 45

Cube Voyager Reference Guide 427

Matrix Program Using the Matrix program

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

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

Introduction

This section shows how a logit model can be used to forecast destination choice. Suppose that an aggregate demand model has 100 zones. Associated with each origin zone (denoted i) there is a total demand of Di that is to be distributed between the 100 possible destinations (denoted j) according to the cost of the trip Cij. The figure Structure of destination choice model illustrates the structure, where d1, d2,... denote the choice of destination 1, destination 2 and so on.

Structure of destination choice model

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

428 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Where is the scale parameter. This equation is no more than a generalized case of the equation in the absolute logit model that forecasts the demand for car and PT. In this case, the choices are destination zones. The incremental logit model is also supported. Its underlying theory is similar to the equations in the incremental logit model, but with alternative modes replaced by destination zones. In this model, the base situation matrices of demand and cost (or cost differences) are also input rather than total travel demand. The incremental model is more widely used in studies than the absolute formulation. For absolute utility-based models, the destination choice model takes the form:

The incremental forms of logit choice model is also supported, and uses the incremental choice equations with alternative modes replaced by different destination zones. The clauses defining data input reflect the data required by the model, for examples UTILITIESMW (utilities) and DUTILSMW (differences in utilities).
Matrix script

The destination choice model described above is coded in the script below.
;Simple destination choice model ;Specify choice parameter lambda = 0.01 XCHOICE, ; Alternatives (only one, as doing destination choice) ALTERNATIVES = all ; Input demand from each origin DEMAND = TripsFromI[i], ; Input cost matrix COSTSMW = 3,

Cube Voyager Reference Guide 429

Matrix Program Using the Matrix program

Forecast demand from each origin to each destination ODEMANDMW = 7 ; Model Structure DESTSPLIT = TOTAL lambda all, ; Working matrices STARTMW = 20

The extract begins with the specification of alternatives, which comprises just one alternative as we have no choice between modes. This is followed by the model inputs, in this case the demand is an array of trips from each zone and the generalized cost is matrix MW[3]. The outputs are a forecast demand matrix, MW[7]. The structure of this model is defined by the DESTSPLIT clause which defines a destination choice process. A scale parameter of =0.01 has been chosen for this example. The output from the split clause is the alternative all, as listed on the ALTERNATIVES keyword. The main differences for utility-based scripts are use of utility keywords (UTILITIESMW being used in place of COSTSMW ), and no use of lambda, the scale parameter, so that the DESTSPLIT clause now becomes DESTSPLIT = TOTAL all.

Mode and destination choice


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

Introduction

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

430 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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

Consider first an example of mode followed by destination choice. The figure illustrates a system with two modes, car and PT, and 100 destination zones (labelled d1, d2,..., d100).

Mode followed by destination choice

Here the total demand is split first by mode (into two vectors representing car and PT demand for each origin) then by destination (giving car and PT matrices).
Matrix script

The script extract below is similar to previous examples shown in Incremental logit model on page 415 and Destination choice on page 428. The model structure specification splits the total demand by mode first with scale parameter =0.01, then across destinations for each mode individually. The parameters for destination choice are =0.02 and =0.03 for car and PT respectively.
; Mode choice above destination choice model ; Specify choice parameters lambda = 0.01 mu = 0.02 theta = 0.03 XCHOICE,

Cube Voyager Reference Guide 431

Matrix Program Using the Matrix program

; ; ; ; ; ; ; ; ; ;

List choices ALTERNATIVES = car pt, Base Demand BASEDEMANDMW = 1,2, Base Costs BASECOSTSMW = 11,12, Forecast costs COSTSMW = 21,22, Forecast demand matrices by mode ODEMANDMW = 31,32, Model Structure Mode choice SPLIT = TOTAL lambda destcar destpt Car destination choice DESTSPLIT = destcar mu car, PT destination choice DESTSPLIT = destpt theta pt, Working matrices STARTMW=110

Destination followed by mode choice

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

Destination followed by mode choice

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

432 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Matrix script

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

General notes
This section provides general notes about logit choice models: Availability of choices Applying choice models to selected parts of matrices Practical considerations: Incremental models Practical considerations: Scale parameters

Availability of choices

Within a demand model, it is often useful to make certain choices unavailable. For example, a rail mode might not be a practical alternative for travel between all zones in the study area. To make a choice unavailable you should give that choice a large positive generalized cost (or large negative utility). Large in this context is

Cube Voyager Reference Guide 433

Matrix Program Using the Matrix program

100 times greater than typical costs. For example, if costs are up to 400 generalized minutes, try using a cost of 40000 minutes to make a particular choice unavailable.
Applying choice models to selected parts of matrices

There are instances when it is desirable to apply choice models to selected parts of a matrix, rather than the entire matrix. These typically arise when matrices can be broken down into distinct segments (such as trips entirely within study area, through trips etc.), and different choice models apply to these different segments. In some instances the model structure is common to all segments, but the sensitivity (and so cost-coefficient) varies between segments. Under these conditions, the cost coefficient may be specified as a matrix (such as MW[5], or mi.1.coefficient) rather than a scalar value. Where the model structure varies between segments, or the user wishes to apply the choice model separately for each segment, the following provides guidance on techniques used. When a XCHOICE control statement occurs in the Matrix program it will typically be applied to all cells (or origin-destination pairs). The XCHOICE control statement may be coded inside a conditional test which selects the origin zones it is applied to:
; test to see if model applies to this origin zone if (i < 45) ; if so, then apply the model XCHOICE, ; subsequent clauses of XCHOICE statement, as needed ; ... endif

For simple choices between alternative modes, this may be extended, by use of the JLOOP command, to select particular rows and columns of the matrix where the choice model is applied:
;apply the model to trips from zones 1-45 to zones 46-53 if (i < 45) JLOOP INCLUDE = 46-53 XCHOICE, ; subsequent clauses of XCHOICE statement, as needed ; ...

434 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

ENDJLOOP endif

Where the choice model applies to a segment which is not a regular set of rows and columns, but is determined by some other matrix attribute (such as distance from origin to destination), a script may be coded as follows:
;start a JLOOP to process each origin-destination pair in turn JLOOP ; test to see if O-D meets selection criteria for the segment if (mi.1.distance > 50) ; if so, then apply the model XCHOICE, ; subsequent clauses of XCHOICE statement, as needed ; ... endif ENDJLOOP

Where a model seeks to use destination choice, this cannot be coded inside a JLOOP construct. If only selected destinations are valid for the destination choice, then the INCLUDE or EXCLUDE subkeyword should be specified immediately after the DESTSPLIT keyword in order to include or exclude the required zones.
Practical considerations: Incremental models

In an incremental model, if the base demand for a choice is zero, the forecast demand for that choice will always be zero. This is made clear if one examines the equation in the Incremental logit model on page 415, where, if Pcar=0 then Pcar=0 whatever costs are given. If this effect is a problem, then the modelling approach should be reviewed.
Practical considerations: Scale parameters

For models calibrated in terms of generalized costs to give sensible results, it is important to ensure for cost-based models that the size of the parameters increase (or at least not decrease) as one moves down the hierarchy. That is to say, the models sensitivity to cost increases down the hierarchy. Where these conditions are not met, an error message will be output.

Cube Voyager Reference Guide 435

Matrix Program Control statements

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

436 Cube Voyager Reference Guide

Matrix Program Control statements

Control word SORT WRITE XCHOICE

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

ABORT
Programs: Distribution, Fratar, Generation, Matrix

Aborts the entire run. MSG Use ABORT to terminate the program and return a fatal code to Cube Voyager. Though not normally used, you can use this statement to terminate processing due to some detectable conditions. For example, suppose that during a mode-split process, the program detects walk access and drive access between the same zone pair, but you know that this should not occur. You can create a test to find this and abort if it occurs.
Keyword MSG |S| Description Optional message that can be printed when the program terminates.

Example
IF (MW[1][I] != 0) ABORT ; Intrazonal present in MW[1] INTRA = MW[1][I] IF (! INTRA) LIST='No intrazonal value for MW[1] at Zone ', I ABORT ENDIF

ARRAY
Programs: Distribution, Fratar, Generation, Matrix

Declares user single-dimension arrays. VAR=n, VAR=n-str

Cube Voyager Reference Guide 437

Matrix Program Control statements

Use ARRAY to allocate user arrays. An array is different than a variable in that it represents vectored data. Values stored to arrays in this program can be numeric or string. When an array is referenced, it must include an index [ ], and if the index exceeds the size, the program will fatally terminate. Arrays can be useful for different processes; the most common use may be to store information for specific zones. ARRAY statements are not dynamic (stack oriented); they are allocated prior to any stack operations. When an array variable appears in a SET statement, all the cells in the array are set to the same value.
ARRAY keyword
Keyword VAR |I| Description Name of the variable that is to be allocated according to the specified size, n. VAR must be a unique name. The size following the keyword is the highest index possible for VAR. Size may be either a numeric constant, or a special nameZONES. Arrays are cleared when they are allocated. Designate an array as a string array by appending a dash followed by the string size, str, to the array size, n. The size n defines the dimension of the array, either numeric or string, and an appended -str defines the array as a string array and sets the string length.

Example
ARRAY sum_mat=10, cbd2ext=500 IF (M <= 10) sum_mat[M] = sum_mat[M] + rowsum(M) IF (I=1-10,51-58,63,96) cbd2ext[I] = cbd2ext[i] + MW[1] include=501-535 ARRAY row_total=zones ; example of defining a string array ARRAY StrArray=1000-5 ; defines a string array with size of 1000 and a character width of 5.

438 Cube Voyager Reference Guide

Matrix Program Control statements

BREAK
Programs: Distribution, Fratar, Generation, Matrix

Use BREAK to break out of a loop. When encountered, control immediately passes to the stack statement after the associated end of loop. If BREAK is within a LOOP or JLOOP block, control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J will be reset to 1). Otherwise, stack processing for the I zone is terminated but output and zonal reporting statistics will not be bypassed.
Example
LOOP L1=1,3 IF (condition) statements ELSE BREAK ; jump to IF statement ENDIF ENDLOOP IF (condition) BREAK ; no more processing for this origin zone LOOP L2=K1,K2,KINC JLOOP EXCLUDE=25-50,88 IF (condition) BREAK ; jump to LOOP L3= ENDJLOOP LOOP L3=L2,L2+5 IF (condition) BREAK; ; jump to ABC= ENDLOOP ABC=... ENDLOOP

BSEARCH
Program: Matrix

Performs a binary search to find a key or set of keys in a sorted array or series of sorted arrays. The format is:
BSEARCH ARRAY=value, ARRAY=value, ...

ARRAY |N| is the name of a user array that is in ascending sort. The

routine will do a binary search to expedite the search for the key. If there are multiple arrays specified, the search will begin at the first

Cube Voyager Reference Guide 439

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Matrix Program Control statements

split=total,0.5,auto,1.0,pt,

Scalar 1.0 can be omitted in CHOICE, but it cannot be omitted in XCHOICE.


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

COMP
Programs: Distribution, Fratar, Generation, Matrix

Computes a variable, matrix, or matrix element.


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

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

460 Cube Voyager Reference Guide

Matrix Program Control statements

COMP keywords (continued)


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

Cube Voyager Reference Guide 461

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. The name may be as long as desired (within reason). The expression is solved one time for each encounter, with J being either one (not in JLOOP), or the value of the JLOOP J. If expression results in a character string, the variable must be a character string variable. All variables are assumed to be numeric variables, unless their first appearance as a result in a COMP statement is with an expression that results in a character string. Examples:
abc = '123' def = 123 abc = def ; invalid: abc has been declared a string abc = abc+'456' ; valid abc = abc+def ; messy -- dont mix types jkl = 1 ; jkl is declared numeric jkl = xyz ; invalid: xyz is declared a string (later) xyz = 'xyz' ; xyz is declared a string

The program does not always bother computing expressions for variables that are not used as input to some process. In the above examples, the statements with jkl= might never be executed, because jkl is never used.

If a COMP statement includes any INCLUDE or EXCLUDE filters, the filters apply to all MW[]= values, and special matrix functions on the statement, no matter where they appear on the statement. EXCLUDE is processed after INCLUDE. INCLUDE and EXCLUDE may not be specified within a JLOOP block.
Supported expressions

Special Matrix variables:


MW[] MI.n.name MI.n.matnum MI.n.name.T MI.n.matnum.T

462 Cube Voyager Reference Guide

Matrix Program Control statements

The expression is a standard Cube Voyager numeric expression, but there are also certain special variables names that may be used within it.
Variable MW[Rexpression] Description Value from any work matrix; the column index (not explicitly expressed) will be supplied as J. Rexpression may contain nested MW[]; be careful! MW[Rexpression][Cexpression] is the value from any work matrix for zone Cexpression. Value from the MATI[n].name matrix; the column index (not explicitly expressed) will be supplied as J. The row index [n], must be a constant. MI.n.name[Cexpression] is a variation; the column index is computed. Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). If matrix names have spaces, then you must include the entire MI matrix reference in double quotes to recognize the name. For example:
MW[1]="MI.1HBW TRIPS"

MI.n.name

MI.n.matnum

Value from the MI[n].matnum matrix; the column index (not explicitly expressed) will be supplied as J. The row index [n] and the matnum must be constants. MI.n.matnum[Cexpression] is a variation; the column index is computed. Special cases for the above two MI formats. The appended .T indicates to use the transposed values for the matrix. This triggers a preprocessor program that will transpose the matrix. Thus, the retrieved cell represents the J-I value, instead of the I-J value. If a column index is used, the retrieved cell will represent the value of the cell for the index to I. Transpose operation can only be applied to binary data. Value from the ZDATI[n].name matrix; the zone index (not explicitly expressed) will be supplied as I. ZI.n.name[Cexpression] is a variation; the zone index is computed.

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

ZI.n.name

Cube Voyager Reference Guide 463

Matrix Program Control statements

The expression may contain the following special matrix row processing functions: ROWSUM() ROWCNT() ROWMIN() ROWMAX() ROWAVE() ROWFIX() ROWFAC() LOWEST() ROWADD() ROWMPY() ROWDIV() ROWREAD() In addition to the standard numeric expression functions (abs, exp, int, ln, log, max, min, round, sqrtsee Expressions on page 30 for more details), some special purpose functions are available. The matrix oriented functions process all cells in a matrix (subject to the restrictions of any INCLUDE and EXCLUDE lists), and should not be used within JLOOP blocks and MW[]= expressions. Most of these functions could be duplicated with a combination of MW[]= statements. The function format has two advantages: coding is much easier, and processing is more efficient. Combining functions on a single statement is permissible; they will be processed in appropriate order. Example: DUMMY = ROWFAC(3,1.5) + ROWFIX(3) will factor matrix 3 and then integerize it. In the following matrix function descriptions, the first argument (mw) indicates the work matrix to process, and must be specified. If lo,hi is allowed, and lo is supplied, and hi is not, hi will be set to lo. Lo and hi are inclusive values. If an invalid argument is detected by a function, the function will return a zero, without any diagnostics.
Matrix function descriptions
Function1 ARRAYSUM(array_name) LOWCNT Description Returns sum of an array (see Examples on page 534). Stores actual number of cells used in LOWEST. Warning: Dividing by LOWCNT, if it is 0, will cause a program error message. In some cases, you can use the max function to prevent this. For example:
W[mw][I] = LOWEST(mw,4,.01,5,I) /max(1,LOWCNT)/ 2

464 Cube Voyager Reference Guide

Matrix Program Control statements

Matrix function descriptions (continued)


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

Cube Voyager Reference Guide 465

Matrix Program Control statements

Matrix function descriptions (continued)


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

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

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

ROWDIV(d,s)

ROWFAC (mw,fac)

Factors the row by fac. Same as:


MW[mw] = MW[mw] * fac

ROWFIX(mw) ROWFIX(mw,n)

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

466 Cube Voyager Reference Guide

Matrix Program Control statements

Matrix function descriptions (continued)


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

Cube Voyager Reference Guide 467

Matrix Program Control statements

Matrix function descriptions (continued)


Function1 ROWREAD(MW#, MATI#, I, M) Description Reads a random row from the input matrix and places it in the current row of the referenced working matrix. Allows for processing input matrix data not in I zone ascending sort order. Where: MW# Desired MW to which the record will be saved MATI# Number of the input matrix file being accessed (Mati[#]) I Desired origin zone M Desired matrix number on the input file to process Example:
run pgm=matrix FILEI MATI[1]=trips00.mat ; input matrix ; with random I zone order from ; external user program FILEO MATO[1]=Fixed_trips00.mat,mo=1-20, dec=20*8 ; Matrix automatically runs an ILOOP ; from I=1 to I=ZONES loop m=1,20 ; loop over the 20 matrices ; in the input file x=ROWREAD(m,1,I,m) ; read row for the ; current value of I and places it ; in the work matrix endloop endrun

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

Row total Row total, but include only cells where: lo>=value<=hi

1. mw is a working matrix number (that is, MW[1]) lo is the lo end of a range hi is the hi end of a range; defaults to lo if not specified

468 Cube Voyager Reference Guide

Matrix Program Control statements

Example
MW[2]=J MW[K]=MW[2] * MW[5] / SQRT(A*MW[3][MW[22]]) A=1, B=2, MW[A]=A+B INCLUDE=1-5,8,47-93 MW[3]=5*A, MW[4]=MW[3]*2, MW[K][I%10+1]=ODD, INCLUDE=1-100,401-500, EXCLUDE=90,93,452; will apply to all MW[]s= ABC=LOOKUP(DEF)*3 ; move input matrices to work areas MW[11]=MI.1.1, MW[12]=MI.1.2, MW[13]=MI.1.3 MW[21]=MI.2.1, MW[22]=MI.2.2, MW[23]=MI.1.3 JLOOP J=I MW[6]=J ; store only at intrazonal column ENDJLOOP set var=sumaf1,rowsum1 ; clear variables lookup name=f1, file=f1.txt JLOOP rowsum1 = rowsum1 + mw[1] ; get total for mw[1] mw[2] = zi.1.attr[j] * f1(mi.12.1) ; A * F's sumaf1 = sumaf1 + mw[2] ; sum A*F endjloop ; Next line is same process done with functions: rowsum1=ROWSUM(1) mw[2]=zi.1.attr[j]*f1(MI.12.1) sumaf1=ROWSUM(2)

CONTINUE
Programs: Distribution, Fratar, Generation, Matrix

Jumps to end of loop. Use CONTINUE to immediately jump to the end of a loop, bypassing all stack statements between it and its associated end of loop. If it is within a LOOP or JLOOP block, control passes to the appropriate ENDLOOP or ENDJLOOP statement. Otherwise, stack processing for the I zone is terminated but output and zonal reporting statistics will not be bypassed.
Example
LOOP L1=1,3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE ; no more processing for this origin zone LOOP L2=K1,K2,KINC

Cube Voyager Reference Guide 469

Matrix Program Control statements

JLOOP EXCLUDE=25-50,88 IF (condition) CONTINUE ; jump to ENDJLOOP . ENDJLOOP LOOP L3=L2,L2+5 IF (condition) CONTINUE ; jump to ENDLOOP for L3 . ENDLOOP ENDLOOP

EXIT
Programs: Distribution, Fratar, Generation, Matrix

Exit the program before the end of zone processing Upon encountering EXIT, the program immediately terminates stack processing, and goes to the end of I loop processing.
Example
IF (expression) EXIT

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

and for important limitations when using Application Manager.


Programs: Distribution, Fratar, Generation, Matrix

Selects input data files. DBI (FIELDS name SORT DELIMITER AUTOARRAY MAXRECS JOINTODBI(JOINTOFIELDS)) LOOKUPI MATI (PATTERN FIELDS) RECI (FIELDS name SORT DELIMITER MAXERRS LISTERRS MAXRECS MAXSCAN)

470 Cube Voyager Reference Guide

Matrix Program Control statements

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

vector format. Matrix data is read dynamically (at the start of each I loop), and must be in origin zone (I) order, whereas zonal data is read prior to the initiation of the I loop, and need not be in any specified order. Data from these files is accessed via COMP statements, and are identified as MI.n.name and ZI.n.name. The n designates subscript of the file, name designates the matrix name or number. Cube Voyager matrices can have names and/or numbers, other matrices have only numbers, and zonal data files have names only. Example: MI.1.3 indicates matrix number 3 on the MATI[1] file. ZI.6.POP indicates the POP variable from ZDATI[6] file. Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). If matrix names have spaces, then you must include the entire MI matrix reference in double quotes to recognize the name. For example:
MW[1]="MI.1HBW TRIPS"

On the FILEI statement the subscript is either explicitly, or implicitly, specified. MATI=... defaults to MATI[1], and MATI[3]=name3,name4,name5 sets up MATI[3], MATI[4], and MATI[5]. Since it is required that ZDATI files have variables explicitly defined for them, the vector form of ZDATI (ZDATI=file1, file2...) will be treated as an error. When an input file is used in an expression, it may have an additional subscript appended to it to specify a zone number. For matrices, the subscript references the column within a row, and for zonal data, it references the nth item in the vector. Zonal data can be viewed as having zones rows with one column per zone, or as

Cube Voyager Reference Guide 471

Matrix Program Control statements

one row having zones columns (users choice, it doesnt matter). If there is no subscript specified, the current value of J is used. J will always be in the range 1-zones. Example: MI.6.3[I] accesses the intrazonal cell. ZI.1.TRMTIME[I] and ZI.1.TRMTIME[J] reference the origin and destination terminal times, respectively. Matrices can be input as either binary matrices, EMME/2 matrices stored in an EMME/2 data bank file, or as data on ASCII or DBF type records. In the latter case, PATTERN and FIELDS must be specified. ASCII type records are more subject to variation (empty fields, invalid values, etc.), and the program is a bit more tolerant with them. If a J or M is out of range, the values for the field are ignored. On the other hand, if the field contains non-numeric data, it is treated as an error, and further processing of the record is terminated. If MATI specifies an EMME/2 data bank file, then the file name must be emme2ban with no file extension. The Matrix program will not recognize any other file name as an EMME/2 data bank file. In this case, input matrices referenced in the script can be referenced by their matrix number in the bank just as they are in a binary Cube Voyager matrix file. The FILEI file keywords ZDATI, RECI, and DBI can point to elements in a multidatabase (MDB) file by designating the filename followed by a backslash and the element name. The program will generate a temporary file of records, each record containing all the variables in the element. If the FILEI file keyword value is followed by variable definitions, those definitions are ignored, or in some cases, cause a fatal termination. On a ZDATI file name, you can specify a definition for Z to indicate which MDB element represents the zone number. Z= is not necessary if one of the element variables has an appropriate name for the zone number (see description of ZDATI for details). If ZDATI specifies an EMME/2 data bank file, the Matrix program can read the scalar and vector matrices stored in the EMME/2 data bank file as zonal data records. To specify an EMME/2 data bank file, the file name must be emme2ban with no file extension. The Matrix program will not recognize any other file name as an EMME/2 data bank file.

472 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords
Keyword DBI Subkeyword |KF9| Description Name of a DBF file, MDB data element, or an ASCII record file with either delimited (separated by a space or a comma or combination of both space and comma) or fixed format records. If you specify a DBF file, the program recognizes the file and the fields. Reference the field names in the DBF header directly in the script as DI.#.fieldname. Do not explicitly define the variables in the DBI statement. If you specify an MDB\element file and name, the program recognizes the file and the fields. Reference the field names in the MDB data element directly in the script as DI.#.fieldname. Do not explicitly define the variables in the DBI statement. If you specify an ASCII record file, define all variables that you want the program to recognize (DBI.#.name) in the DBI statement, using the appropriate keywords. ASCII record files are either a fixed format text file (fixed field locations and lengths), or free format. You must indicate which format is used in the definition of each field. Indicate free format with field definitions containing a single number. Indicate fixed format fields by using name=lo[-hi] or field=lo[-hi] syntax, where lo is the first column number of the field and hi is the last column. (Indicate a single-column character with the hi column number the same as the lo column number.) Define a field as a character variable by appending (C) to the name. For example, TITLE(C)=1 would define the variable named DI.#.TITLE as a character variable, and would read the data from the first data field in the input file You can specify the delimiters for free-format records using the DELIMITER keyword.

Cube Voyager Reference Guide 473

Matrix Program Control statements

FILEI keywords (continued)


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

474 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)


Keyword DBI Subkeyword DELIMITER |S2| Description Use to specify two different controls for free-format records. DELIMITER[1] specifies the field-separator characters. The default values are ,t; where t is used to designate a tab:
DELIMITER[1]=" ,t"

DELIMITER[2] specifies escape-character sequences that permit field-separator characters in free-format records. Specify characters in pairs, the character that marks the start of an escape sequence along with the character that marks the end of an escape sequence. Upon encountering the starting escape-sequence character, Cube Voyager treats all subsequent data as part of the same record until it encounters the ending escape-sequence character, even if it encounters a field-separator character. The default value specifies single quotes, double quotes, parenthesis, brackets, and braces as escape character sequences:
DELIMITER[2]="""''()[]{}"

NOTE: You must enclose the entire value in double quotes or single quotes. If you include a single space as the last character in DELIMITER[2], Cube Voyager will remove the leading and trailing character from any string it reads. The starting escape-sequence character in DELIMITER[2] cannot be a field-separator character in DELIMITER[1]. You can specify both DELIMITER[1] and DELIMITER[2] in one expression: Specify DELIMITER= followed by two values enclosed within quotes and separated by a space or a comma. Cube Voyager automatically removes leading spaces from all fields, unless the field is enclosed in an escape-character sequence and DELIMITER[2] does not contain a space as its last character. Example Suppose you set a comma as field-separator and double quotes as an escape sequence:
DELIMITER=',' '""'

When reading the following input data:


John Smith, "Oakland, CA", USA

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

Cube Voyager Reference Guide 475

Matrix Program Control statements

FILEI keywords (continued)


Keyword DBI Subkeyword FIELDS |IPV| Description An optional method for defining data fields in the input file. Used only when the DBI records are fixed or free format. If this keyword is present, only the fields specified will be extracted. The values specify the columns or fields of the DBI file records where a desired field is located. If a data field (FIELDS= or name=) is defined by a pair of numbers (lo-hi), that sets the format as fixed. If a data field is defined by a single number (field number on the records), that sets the format as freeform. All data fields must be defined in the same format. For example:
FIELDS=1-5,6-10,21-25

Specifies that the data is fixed format and DBI.#.NFIELD[1] is in columns 1-5, DBI.#.NFIELD[2] is in columns 6-10, and DBI.#.NFIELD[3] is in 21-25.
FIELDS=6,9,13

Specifies that the data is in free format and defines DBI.#.NFIELD[1] comes from field number 6, DBI.#.NFIELD[2] comes from field number 9, and DBI.#.NFIELD[3] comes from field number 13. Optionally, FIELDS can specify multiple successive fields with a single specification (providing all fields are the same type, N or C). For example:
FIELDS=6(7)

Specifies that DBI.#.NFIELD[1]DBI.#.NFIELD[7] will be obtained from fields 6 through 13 of the data records.
FIELDS=6(C7)

Specifies the same, but those fields would all be character values. You can reference these field values as DBI.#.NFIELD[#], DBI.#.CFIELD[#] or as DI.FIELD# in script statements. DBI JOINTODBI |I| Specifies the number of the input DBI file to join this DBI file to. If JOINTODBI is specified for a DBI file, then the SORT keyword must also be specified. The field names referenced by the SORT keyword define the join key. You must also specify the JOINTOFIELDS subkeyword.

476 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)


Keyword DBI Subkeyword JOINTOFIELDS |SV8| Description Specifies the fields on the file referenced by JOINTODBI that corresponds to the join key fields identified by the SORT keyword. This keyword can have fewer referenced field names than the SORT keyword but cannot have more than the number of sort keys. For example:
FILEI DBI[1] = "TRIPRECORDS.DBF", SORT=HHNO,PERSNO TRIPNO FILEI DBI[2] = "PERSON.DBF", SORT=HHID,PERSID JOINTODBI=1 JOINTOFIELDS=HHNO,PERSNO

In this example, DBI file 2 is a person-level survey record file. This file contains the fields HHID and PERSID, which uniquely identify the person record, along with other household and person-level demographic data fields. DBI file 1 contains the person-level trip records from a travel survey. This file contains the fields HHNO, PERNO, and TRIPNO, which uniquely identify each person-trip record, along with other trip-related data fields. Note that the key field name on which the join is performed does not need to match in the two files. With the files joined, script statements that process a trip record are linked to the corresponding person-level data file, enabling trip-based computations to directly reference the household and person-level characteristics in the joined file. DBI MAXRECS |I| Limits the number of records read from the DBI file. If the DBI is not a DBF file, the program treats both zero length and blank records as legitimate records. If the file is a DBF file, deleted records (flagged with a *) are not counted as records.

Cube Voyager Reference Guide 477

Matrix Program Control statements

FILEI keywords (continued)


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

LOOKUPI

|FKV999|

478 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)


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

Cube Voyager Reference Guide 479

Matrix Program Control statements

FILEI keywords (continued)


Keyword MATI Subkeyword PATTERN |S| Description Sequence of letters that specifies how the program processes the associated text or DBF MATI file. The pattern has two portions separated by a colon: a base portion and a repeating portion. In the pattern definition: There must be a single I, J, and V. I must be the first letter in the base portion, and V must be in the repeating portion. There may be one M to specify the starting matrix number. If there is no M, matrix 1 is assumed. The highest M that the program recognizes is 255. If there are multiple characters in the base portion, the last character in the base portion indicates which variable is incremented for each repeating set.

Valid combinations are: IJ:V I J values for J,J+1,J+2... IMJ:V I M J values for J,J+1,J+2... IJM:V I J M values for M,M+1,M+2... I:JV I sets of J and V I:VJ I sets of V and J IJ:VM I J sets of V and M IJ:MV I J sets of M and V IM:JV I M sets of V and J IM:VJ I M sets of J and V I:JVM I sets of J, V, and M I:JMV I sets of J, M, and V I:MJV I sets of M, J, and V I:MVJ I sets of M, V, and J I:VJM I sets of V, J, and M I:VMJ I sets of V, M, and J

480 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)


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

Cube Voyager Reference Guide 481

Matrix Program Control statements

FILEI keywords (continued)


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

482 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)


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

Cube Voyager Reference Guide 483

Matrix Program Control statements

FILEI keywords (continued)


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

RECI

LISTERRS

|?|

RECI

MAXERRS

|I|

RECI

MAXRECS

|I|

484 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)


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

RECI

NAME

|IP|

RECI

SORT

|S5|

ZDATI

|KFV10|

Cube Voyager Reference Guide 485

Matrix Program Control statements

FILEI keywords (continued)


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

486 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)


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

ZDATI ZDATI ZDATI ZDATI

Cube Voyager Reference Guide 487

Matrix Program Control statements

FILEI keywords (continued)


Keyword ZDATI Subkeyword name |S| Description Identifies a data variables that is to be extracted from each record. Only the variables named will be extracted. If the file is a dbf, the value for each name is the name from the DBF dictionary. In most DBF cases, name=name would be the standard, but it is not necessary to keep the same names. For text files, the value assigned to name is either a field number (delimited format), or the columns (fixed format) where the variable is located on the record. All names must be specified with the same format; the first name value (including Z) establishes the format. If the first value is a number, fixed format is assumed; otherwise, delimited format is assumed. If delimited format is specified, each name value MUST end in a number. It doesnt matter what string precedes the number (the value need not be prefixed with a string). Example: Z=#1,POP=#2, AREA=3, SALES=xxx4. These are all be valid, because Z specified triggered delimited format. Z=15,POP=#2 would be invalid because Z specifies fixed format. Used to cause selective reading of zonal data records from ASCII files. The program will compare a field from each record with the string specified in SELECT[1], and if the comparison fails, the record is bypassed. This selection is not used if SELECT is not specified. SELECT[2] specifies the input record field whose value is to be compared with the value of SELECT[1]. If SELECT[2] is a number, it designates the beginning column of the comparison field on the input record, and SELECT[3] can be optionally specified to designate the ending column. SELECT[2] and [3] must both be numeric and should be separated by a dash. Alternatively, if`SELECT[2] is not numeric, but ends with a number (first example), it is assumed that the value indicates a relative field number on the data record. That field is the comparison string. SELECT[3] is ignored if SELECT[2] is a free field definition. SELECT=abc,6-8 select only if columns 6-8=abc SELECT=1,#2 select only if a 1 in field no. 2 ZDATI ZDATI SUM Z |SV| |S| Sum of all the records. Identifies where the zone number identifier is found on each data record; Z is required only for ASCII files. 'Z=' is a special case for 'name='.

ZDATI

SELECT

|S3|

488 Cube Voyager Reference Guide

Matrix Program Control statements

Caveat: The program establishes a buffer to read file records into. It has to know how long a buffer is required. With DBFs and fixed format records, the required length is known, but with delimited format, the required length can not be estimated exactly. For delimited files, the record length is estimated by multiplying the highest field number by 10. If the estimated length is inadequate, a dummy variable with a high field number can be specified to generate a larger record length.
More on DBI

DBI files are not automatically processed. You must write scripts to read the records. Several functions are available to read the records. Use these functions in a COMP statement with the form: N=DBIfunc(DBI#,...). DBI# must always be the first argument. All the functions return a value to indicate the success of the operation. A return value of 0 indicates a successful operation; any other value indicates the read was not 100% successful. You must check the return code. The functions are: DBIReadNext(#,R) where R indicates the record to read, specified relative to the current record. A negative R means prior to the current record, and a positive R means after the current record. Write sequential reads as DBIReadNext(#,1), though DBIReadNext(#) is also allowed. A return code of 1 indicates any of the following errors: bad #, R<1, or R>DBI.#.NUMRECORDS. DBIReadRecord(#,R) where R indicates the record to read. R must be 1 DBI.#.NUMRECORDS, or the return code will be 1. DBISeek(#, R,...) where R is a value to search for in the field specified as SORT[1]. In order to use this function, there must be at least as many SORT values as there are R arguments. There may be fewer R values than there are SORT fields, but not more. This function searches for the record that matches all the specified R values. The return values are: 0 A match was found. 1 An error in setup occurred.

Cube Voyager Reference Guide 489

Matrix Program Control statements

2 A match was not found, and DBI.#.RECNO is set to the record that is above the R selections. 3 The R values are greater than the last record and DBI.RECNO is set to the last record. In all cases, the DI.#.field values are extracted from the record indicated by DBI.#.RECNO, and the record pointer points to that record. See Example 5 on page 538 and Example 6 on page 539 for examples of DBI processing.
NOTE: You can create and populate arrays with just a FILEI DBI

statement; you do not need DBIRead functions.


More on MATI PATTERN Example for MATI[1]
PATTERN Data record fields I M [J] Values IJ:V 1 15 21 22 23 24 I=1 MI.1.1[15-18] 21,22,23,24 IMJ:V 1 6 18 100 101 105 I=1 MI.1.6[18-20] 100,101,105 I:JMV 5 12 1 8 14 2 90 I=5 MI.1.1[12] 8 I=5 MI.1.2[14] 90 IJM:V 5 12 3 8 14 2 90 I=5 MI.1.3[12] 8 I=5 MI.1.4[12] 14 I=5 MI.1.5[12] 2 I=5 MI.1.6[12] 90

The above PATTERNS do not provide for the situation where the record contains I, J, then multiple values to represent matrix 1, 2, 3 In this case, the PATTERN IJM:V, with the FIELD value of M set to zero, can be used to describe the input data. The matrix number is implied and always starts with 1 on each record. The following example illustrates the specification of PATTERNS and FIELDS for input data with implied matrix number:
Example (implied matrix number)

(input data record)


1 15 21 22 23 24 (Cube Voyager script)

490 Cube Voyager Reference Guide

Matrix Program Control statements

MATI[1]=input.txt, PATTERN=IJM:V, FIELDS=1-2,3-4,0,5-7-4 ; fixed format or MATI[1]=input.txt, PATTERN=IJM:V, FIELDS=#1,2,0,3-6 ; variable format or MATI[1]=input.dbf, pattern=IJM:V, FIELDS=I,J,0,V1,V2,V3,V4; DBF format ; The input dbf in this example would have the named ; fields I,J,V1,V2,V3,V4 (results) I=1, J=15, MI.1.1=21, MI.1.2=22, MI.1.3=23, MI.1.4=24

The above PATTERNs also do not provide for the situation where the record contains I, then multiple values to represent J values 1, 2, 3... for a single matrix (implied matrix number M=1). In this case, the PATTERN IJ:V, with the FIELDS value of J set to zero, can be used to describe the input data. The J value is implied and always starts with 1 on each record. The following example illustrates the specification of PATTERN and FIELDS for input data with implied J number:
Example (implied j index number)

(input data record)


1 2 3 4 37.3912 167.1612 13.0612 31.6512 54.5413 269.2513 22.1213 54.2813 6.8414 35.5314 4.8514 12.2914 14.5015 75.1215 10.6815 31.3815

This example data represents a 4 zone matrix with the I values in column and the cell values for the implied J zones in columns 2 through 5. The script example below will build a binary matrix using the implied J values.
RUN PGM=MATRIX FILEI MATI=temp1.DAT FILEO MATO=temp1.mat PAR ZONES=4 MW[1]=mi.1.1 ENDRUN PATTERN=IJ:V MO=1 FIELDS=#1,0,2-5

Cube Voyager Reference Guide 491

Matrix Program Control statements

More on RECI

Example RECI statements:


FILEI RECI=myfile.dbf, SORT=key2, -key1, +key6 FILEI RECI=myfile.mdb\mytable, SORT=key2, -key1, +key6 FILEI RECI=myfile.txt, nvar1=1-3, nvar2=5-8, cvar3(c)=1010, SORT=nvar2, cvar3 FILEI RECI=myfree.txt, nvar1=1, cvar2(C)=2, cvar3(C)=3, DELIMITER[2]='//' FILEI RECI=myfree.txt, nvar1=1, cvar2(C)=2, cvar3(C)=3, DELIMITER[2]='""'' ' FILEI RECI=myfree.txt, nvar1=1, cvar2(C)=2, cvar3(c)=3, DELIMITER=' ,;t' , '//() ' SORT=-nvar1,+cvar3

Example of usage: to sum all the housing units in a record (even if the exact names are not known, but we do know that all units fields are named xxUNITS):
TotUnits=0 Loop k=1,RECI.NUMFIELDS If (RECI.TYPE[K] = 'N' && substr(RECI.NAME[k],3,5) = 'UNITS') TotUnits = TotUnits + RECI.NFIELD[K] EndLoop

Example: In a record processing run of matrix


VAR1TOTAL=VAR1TOTAL+VAR1 IF (I=0) VAR1AVG=VAR1TOTAL/RECI.NUMRECORDS PRINT LIST=RECI.NUMRECORDS,VAR1TOTAL,VAR1AVG ENDIF

would sum the values of the variable VAR1 and once all records have been read (I=1) compute the average value of VAR1 and print to the report file the number of records, the total of VAR1 and the average of VAR1 Example:
RUN PGM=MATRIX FILEI RECI=network_link.dbf PARAMETERS MAXSTRING=100 if (RI.A>25 & RI.B>25)

492 Cube Voyager Reference Guide

Matrix Program Control statements

print, list=ri.A,',',ri.B,',',ri.ROAD_TYPE,',', ri.IMPORTANCE,',',ri.ROAD_NAME,',', ri.CLASS,',',ri.SPEED,',', ri.PICTUREFIL file=tmp1.csv endif if (I=0) print list='Number of link records=', RECI.NUMRECORDS file=tmp2.dat endif ENDRUN

Example:
copy file = junk.txt 11 22 33 44 55 66 77 88 99 aa bb cc dd 56 78 90 12 aa bb cc dd 56 78 90 12 endcopy RUN PGM=MATRIX ;get 1st 5 data fields as numeric fields and also as character fields FILEI RECI = junk.txt,Fields=1(c5),1(n5) FILEO RECO[1]=junkout.dbf FIELDS=reci.allfields FILEO PRINTO[1]=junkprn.prn write reco=1 print printo=1 form=5lr,list='\nRecno=',reci.recno,' NumFields=',reci.numfields, ' highest field=',reci.fields,' lng=',reci.lng print printo=1 form=5lr,list=reci,'\ncfield[1-5] =', reci.cfield[1],'..',reci.cfield[2],'..',reci.cfield[3],'..', reci.cfield[4],'..',reci.cfield[5],'..\nnfield[6-9] =', reci.nfield[6],'..',reci.nfield[7],'..',reci.nfield[8],'..', reci.nfield[9],'..',reci.nfield[10],'..\nri.field1..5 =', ri.field1,'..',ri.field2,'..',ri.field3,'..', ri.field4,'..',ri.field5,'..\nri.field6..10=', ri.field6,'..',ri.field7,'..',ri.field8,'..', ri.field9,'..',ri.field10,'..' endrun Results of the PRINTO file from the above example:

Cube Voyager Reference Guide 493

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..22..33..44..55.. nfield[6-9] =11..22..33..44..55.. ri.field1..5 =11..22..33..44..55.. ri.field6..10=11..22..33..44..55.. Recno=2 NumFields=10 highest field=5 lng=23 aa bb cc dd 56 78 90 12 cfield[1-5] =aa..bb..cc..dd..56.. nfield[6-9] =0..0..0..0..56.. ri.field1..5 =aa..bb..cc..dd..56.. ri.field6..10=0..0..0..0..56..

Example of FILEI statements

These statements show various examples of FILEI usage:


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

These statements show an example of simple record processing:


copy file=reci_in.txt ; generate input file A 1 2 3 4 5 6 7 8 9 10 B 1 2 3 4 5 6 7 8 9 10 endcopy run pgm=matrix reci=reci_in.txt, FIELDS=1-3 ; switch to record processing mode ; each data record is stored in a string variable reci s2=substr(reci,11,12) s3='Z' if (substr(reci,1,1)=='A') s3='B' ; I is the end-of-file indicator print list=i(3.1), ' ', reci(10), s2, '.', s3, file=out_reci.txt, print=y ; will result in ; 1.0 A 1 2 3 4 5 6 7 8 9 10.B ; 0.0 B 1 2 3 4 5 6 7 8 9 10.Z

494 Cube Voyager Reference Guide

Matrix Program Control statements

endrun

These statements show an example of getting I-J values from a delimited file:
RUN PGM=MATRIX RECI = myfile, org=1, dest=2 MATI[1] = mymat; contains time and distance matrices in 1 and 2 If (RI.ORG > 0 && RI.DEST>0) Time = matval(1,1,RI.ORG,RI.DEST,0) Dist = matval(1,2,RI.ORG,RI.DEST,0) Else Time=0, dist=0 Endif print file=outfile, list=reci, time(6.2LR), dist(8.2LR) ; duplicate RECI and append time and dist in delimited format ENDRUN

These statements show an example of getting matrices from an EMME/2 data bank file:
RUN PGM=MATRIX FILEI MATI[1]="emme2ban" FILEO MATO[1]="M2_to_Voy.mat" mo=1-8 DEC=8*9 ; get matrices mf104 to mf111 from emme2ban ; and put into work matrices 1 to 8 MW[1]=MI.1.104 MW[2]=MI.1.105 MW[3]=MI.1.106 MW[4]=MI.1.107 MW[5]=MI.1.108 MW[6]=MI.1.109 MW[7]=MI.1.110 MW[8]=MI.1.111 ENDRUN

These statements show an example of getting zonal vector and scalar matrices from an EMME/2 data bank file:
RUN PGM=MATRIX FILEI ZDATI[1]="emme2ban" FILEO RECO[1]="emmeVector2Voy.dbf" FIELDS=ms10(5.2),mo20(6.3),mo21(6.3),mo23(6.3), mo22(6.3),mo25(6.3),md22(6.3),md23(6),md25(6.3),md80(6), md81(6),md82(6) report zdat=t

Cube Voyager Reference Guide 495

Matrix Program Control statements

zones=900 ro.ms10=zi.1.ms10 ro.mo20=zi.1.mo20 ro.mo21=zi.1.mo21 ro.mo23=zi.1.mo23 ro.mo22=zi.1.mo22 ro.mo25=zi.1.mo25 ro.md22=zi.1.md22 ro.md23=zi.1.md23 ro.md25=zi.1.md25 ro.md80=zi.1.md80 ro.md81=zi.1.md81 ro.md81=zi.1.md82 write reco=1 ENDRUN

FILEO
Programs: Distribution, Fratar, Matrix

Outputs data files. MATO (FORMAT MO NAME DEC PATTERN DELIMITER FIELDS MAXFIELDS) PRINTO (APPEND) RECO (FIELDS EXCLUDERECI CFORM FORM REPORT) Use FILEO to specify the type and number of output files for the program to produce. Cube Voyager writes matrix type output files at the end of each I zone.

496 Cube Voyager Reference Guide

Matrix Program Control statements

PRINT statements write formatted print files to the PRINTO file. WRITE statements write RECO files to the referenced DBF file or can point to elements in a multidatabase (MDB) file by designating the file name followed by a backslash and the element name.
FILEO keywords
Keyword MATO Subkeyword |KFV20| Description Name of an output matrix file. May have an index [x] appended. If you do not specify an index, the program assumes the index is 1. Indices need not be monotonic or sequential. The program can write output matrices in various formats, which you can use with other software. MATO may reference an existing EMME/2 data bank file in order to store matrix data into the existing data bank. EMME/2 data bank files must be named emme2ban. The program will overwrite an EMME/2 data bank file in the format specified by FORMAT if the name is not emme2ban. The data bank file must exist already. If it does not exist, the program will not create the data bank file.

Cube Voyager Reference Guide 497

Matrix Program Control statements

FILEO keywords (continued)


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

498 Cube Voyager Reference Guide

Matrix Program Control statements

FILEO keywords (continued)


Keyword MATO Subkeyword DEC (continued) Description MINUTP or Tranplan files Do not set DEC. The program ignores the DEC setting and automatically writes 4-byte values, usually integer numbers. You must set the included work matrices to the desired external format before the program writes the matrices. Storing numbers larger than the maximum integer value (2,147,483,647) will result in erroneous values. NOTE: Normally, you round matrices that represent levelof-service (time, distance, cost, and so on), and bucket round matrices that represent trips to ensure row totals.
COMP MW[1]=INT(MW[1]*100+.5) ; LOS rounding COMP MW[2]=MW[2]*100, Total=ROWFIX(2) ; bucket rounding

Optionally, set DEC=S to write a single-precision matrix. However, you cannot use such a matrix as input to Cube Voyager. TRIPS files Set DEC to the number of digits after the decimal point (0 to 9). The program stores numbers as integers with implied decimal. If you set DEC to S or D, the program treats as DEC=0. If a numbers integer value with implied decimal exceeds the maximum integer value (2,147,483,647), the program substitutes the maximum integer value for that number. Text files Set DEC to the number of decimal places to format in text records. If you do not code DEC, the program uses the default value of 2. If you specify DELIMITER, the program writes variable-length values and truncates trailing zeros, otherwise the program writes fixed field lengths, based on the values of FIELDS. DBF files Set DEC as for Cub Voyager files. However, the program uses the DEC[1] value for all the matrix data fields unless M immediately precedes the colon in PATTERN (for example, PATTERN=IJM:V ). If you set PATTERN such that M varies in a records matrix data values, the program uses DEC[#] appropriately.

Cube Voyager Reference Guide 499

Matrix Program Control statements

FILEO keywords (continued)


Keyword MATO Subkeyword DEC (continued) Description EMME/2 data bank files Do not set DEC. The program stores values in singleprecision floating-point format in the data bank file. MATO DELIMITER |S| For text files only (FORMAT=TXT ). Character that separates data values. When you code this subkeyword, the program writes data values in variable length and separates values with this character. If you do not specify DELIMITER, the program writes fixed field lengths, based on the values of FIELDS. Usually, you delimit data with a comma or space. To use a comma or space, enclose with quotes, ' '. Field width for data values when DELIMITER is not specified. The number of values specified with FIELDS must match the number of letters in PATTERN (the base portion precedes the colon, and the repeating portion follows the colon). The first FIELDS value always sets the length for I. After exhausting the list of FIELDS values, the program reverts to the FIELDS value that corresponds to the repeating portion of PATTERN. If the FIELDS value that corresponds to a base portion of PATTERN is set to 0, the program omits the corresponding data. Examples:
PATTERN=IJ:V FIELDS=4,4,6

MATO

FIELDS

|IV4|

I will always be in 1-4 J will always be in 5-8 V will be in 9-14,15-20,21-26 ... I will always be in columns 1-4 J will be in 5-8, 17-20, 29-32 ... V will be in 9-14, 21-26, 33-38 ... M will be in 15-16, 27-29, 39-40 ... I will always be in columns 1-4 J will always be in 5-8 M will not be written to the data records V will be in 9-16,17-24,25-32 ...

PATTERN=I:JVM FIELDS=4,4,6,2

PATTERN=IJM:V FIELDS=4,4,0,8

500 Cube Voyager Reference Guide

Matrix Program Control statements

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, unless you set PATTERN. With PATTERN set, the default value is TXT. Ignored if MATO is set to emme2ban. In that case, the program updates an EMME/2 data bank file.

Cube Voyager Reference Guide 501

Matrix Program Control statements

FILEO keywords (continued)


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

502 Cube Voyager Reference Guide

Matrix Program Control statements

FILEO keywords (continued)


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

Cube Voyager Reference Guide 503

Matrix Program Control statements

FILEO keywords (continued)


Keyword MATO Subkeyword PATTERN |S| Description Sequence of characters that indicates the order the program writes values to the output records. Valid values of PATTERN are listed and described under FILEI MATI PATTERN on page 480. The program begins a new record each time either of the first two characters of PATTERN change values (exception: IJ:V begins new record for each I change). Specifies the name of the file where the output from a PRINT statement is to be directed using PRINT PRINTO=#. See APPEND under PRINT on page 62. File name for the RECO specified. Each RECO must have an index [x] appended to it. If there is no index, the index is assumed to be 1. The indices need not be monotonic or sequential. Data written to this file is defined with the FIELDS keyword below and directed to the appropriate file using the RECO keyword on the write statement. See WRITE on page 532. Currently, DBF, MDB and EMME/2 data bank files are the only file formats supported for this record file. If specifying an EMME/2 data bank file, the file name must be
emme2ban. The program will write any other file name to binary

PRINTO PRINTO RECO APPEND

|KF| |?| |KF20|

format and not in bank-file format. The bank file must exist already. If it does not exist, the program will not create the bank file. You can use RECO to write scalar or vector matrices into an EMME/2 data bank file. RECO CFORM |I| Length of field for all character variables that follow it on the statement, and do not have a specific format associated with it. A later occurrence of CFORM will reset the value for character variables following it. The allowed range is 1-255; the default is 15. Used to exclude selected fields when using the RECI.ALLFIELDS include macro described under FIELDS above.

RECO

EXCLUDERECI

|S|

504 Cube Voyager Reference Guide

Matrix Program Control statements

FILEO keywords (continued)


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

Cube Voyager Reference Guide 505

Matrix Program Control statements

FILEO keywords (continued)


Keyword RECO Subkeyword FORM |R| Description Format specification (w.d) for all numeric variables that follow it on the statement, and do not have a specific format associated with it. A later occurrence of FORM will reset the value for numeric variables following it. The allowed range is 1-31.5; the default is 10.2. Optional. Used in conjunction with the FIELDS subkeyword. For output to EMME/2 data bank files, specifies name in the data bank for scalar and vector matrices. Example:
reco[1] =..\emme2\emme2ban Z=I, fields=MS1 MO1 MD1 name=ms1 mo1 'md1 term time'

RECO

NAME

|S|

For this example, the script must set the variables .MS1, RO.MD1, and RO.MD2. Upon encountering each WRITE RECO=1 statement in the script, the program would update the data bank, changing the names as defined. RECO REPORT |?| Can be specified to have the program print a listing of the fields (name, mode, length, decimals) as they will appear in the DBF. Default value is F. Optional. Used in conjunction with the FIELDS subkeyword. Required when writing MO or MD matrices. For output to EMME/2 data bank files, specifies zone for which the program stores the data.

RECO

|S|

Example: FILEO

These statements demonstrate FILEO.


RUN PGM=MATRIX FILEI RECI = " LINK_DATA.DBF",SORT = -VULNERABIL FILEO RECO[1] = "PRESCEENED_LINKS.DBF", FIELDS=A,B,rank_bas NUMLINKS=RECI.NUMRECORDS ; number of records (links) in the input file LOG PREFIX=CNT VAR=NUMLINKS ; writes the number of links to CNT.NUMLINKS ; in the *.var file ; PrescreenType and PRESCREEN value set in SM with KEYS IF ({PrescreenType}=1) ; screen based on a fixed number of links ; (i.e., top N based on Vulnerability) PRESCREEN={PRESCREEN} ELSE ; screen based on a percentage of number of links ; in the input network (i.e., top N% of links based ; on Vulnerability) PRESCREEN=ROUND(NUMLINKS*{PRESCREEN}/100)

506 Cube Voyager Reference Guide

Matrix Program Control statements

ENDIF LOG PREFIX=CNT VAR=PRESCREEN RO.RANK_BAS=RO.rank_bas+1 Anode=RI.A Bnode=RI.B If (RO.rank_bas<=PRESCREEN) If (Anode <={Zones} | Bnode <= {Zones}) ; prevents any centroid links ; from being included in set ; of links to be analyzed RO.rank_bas=RO.rank_bas-1 Else WRITE RECO=1 EndIf EndIf ENDRUN

Example: FILEO MATO for EMME/2 file

These statements demonstrate FILEO MATO to an EMME/2 data bank file.


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

Cube Voyager Reference Guide 507

Matrix Program Control statements

Example: FILEO RECO for EMME/2 file

These statements demonstrate FILEO RECO to an EMME/2 data bank file.


RUN PGM=MATRIX FILEO RECO[1] = " EMME2BAN", Z=I FIELDS=ms02,ms10,mo20,mo21,mo22,mo23,mo25,md22,md23, md25,md80,md81,md82 FILEI ZDATI[1] = "VECTORDATA.DBF" FILEI MATI[1] = "HWY_SKIMS.MAT" ;get mo20, mo21, mo23 FILLMW MW[1]=mi.1.1(3) JLOOP IF (I=J) ro.z=I ro.mo20=MW[1][I] ro.mo21=MW[2][I] ro.mo23=MW[3][I] ro.mo22=zi.1.MO22 ro.md22=zi.1.MD22 ro.mo25=zi.1.MO25 ro.md25=zi.1.MD25 ro.md23=zi.1.MD23 ro.md80=zi.1.MD80 ro.md81=zi.1.MD81 ro.md82=zi.1.MD82 ro.ms02=8 ;scalar ro.ms10=34.7 ;scalar WRITE RECO=1 ENDIF ENDJLOOP ENDRUN

508 Cube Voyager Reference Guide

Matrix Program Control statements

FILET
Programs: Distribution, Fratar, Matrix

Sets temporary file paths. PATH FILET is used to specify where various temporary files are to be written.
FILET keyword
Keyword PATH |KS| Description Specifies the path(s) to the disk area where any temporary files are to be written. When transposing is required, the transposed matrices are written to a temporary file and then recalled during stack processing. Up to two files are required for this process. The first file is the actual transposed data, and the second file is an index to the data file. The index file may not be necessary, and if it is, it will be relatively small. It may speed retrieval somewhat if the two files are on different physical drives. If there is a ram disk installed, then the index file might fit on it. The index file size will be zones * chunks * transposes * 4 bytes. Chunks depends upon the amount of RAM that is available for the transposing processing; it could be none. Assume a 1000 zone system, 20 matrices to be transposed, and 2 Mb of RAM available. The actual RAM requirement would be 1000 * 1000 * 20 * 4, or 80 Mb. The number of chunks would be 40 (80 Mb / 2 Mb). The index file would require 800,000 bytes of RAM. The amount required for the data would be something less than 80 Mb, depending upon how well it compresses. In most cases, the compressed data would require about 30 Mb. The values for PATH are entered as standard operating system paths. If PATH[1] is specified, and PATH[2] is not, or vice-versa, the non-specified path is set equal to the specified one. If neither is specified, they both will default to the path in the environment variable named TMP, or TEMP. The logic for determining the appropriate path, and opening the files is: If the PATH=' ', use current directory. If the PATH is specified, use the PATH. If not specified, and TMP is specified in the Operating System environment, use the TMP.setting. (Same logic for TEMP.) If the open fails, Fatal.

Cube Voyager Reference Guide 509

Matrix Program Control statements

Example
PATH=' ' ; use current directory for both PATH=..\,R: ; up a directory for data, drive R: for index PATH=c:\ d ; root of c: for data, current directory on d: for index

FILLMW
Programs: Distribution, Fratar, Matrix

Fill work matrices MW This statement is used to speed up the process of filling matrices with values from other matrices. Because of its structure, matrices can be very easily moved from input matrices to work matrices or from work matrices to other work matrices. Multiple matrices can be easily filled on one specification. The beginning MW target is the keyword and the values are the matrices that are to be moved into the target matrices. After the first value, the following values may be unqualified (they do not have to have MI.#. prefixed to their names/numbers). This is also true for MW sources. Everything that can be done on a FILLMW statement can be accomplished by COMP statements, but FILLMW sets up very fast moves in contrast to internal computational solutions performed by COMP statements.
FILLMW keyword
Keyword MW |s| Description Specifies the matrices to be moved directly from their source to the destination work matrices named on the keyword.

Example
; The following five statements all do the same thing FILLMW MW[1]=mi.1.1(3) FILLMW MW[1]=mi.1.1,mi.1.2,mi.1.3 FILLMW MW[1]=mi.1.time,mi.1.distance,mi.1.cost FILLMW MW[1]=mi.1.1,2,3 FILLMW MW[1]=mi.1.time,distance,cost

510 Cube Voyager Reference Guide

Matrix Program Control statements

; The next two statements illustrate the simplicity of FILLMW vs. COMP FILLMW MW[11]=mw[1],2,3,9,6 COMP MW[11]=mw[1], mw[12]=mw[2], mw[13]=mw[3], mw[14]=mw[9], mw[15]=mw[6] ; An example of multiple keywords FILLMW MW[1]=mi.1.1,2,3, MW[4]=mi.2.2,3,4 FILLMW MW[101]=mi.1.1(5), MW[1](3) ;will fill MW[101-108] with MI.1.1-5,MW[1,2,3]

FREQUENCY
Program: Distribution, Fratar, Matrix

Stratifies one matrixs values based upon the values of another. BASEMW RANGE REPORT SAVE TITLE VALUEMW

Use FREQUENCY to obtain a frequency of occurrence of the values of a work matrix. A typical use is for a trip length distribution, where the number of trips in a matrix is stratified according to the times from a time or distance matrix. The final results are reported at the end of all zone processing.
FREQUENCY keywords
Keyword BASEMW |I| Description Work matrix number ( MW[ ] ) whose values will be used for the stratification (the time matrix for a trip length distribution).

Cube Voyager Reference Guide 511

Matrix Program Control statements

FREQUENCY keywords (continued)


Keyword RANGE |RP| Description Set of two, or three, numbers that establishes the valid values for stratification. The numbers are separated by a dash. The first number (RANGE[1]) is the lowest value for which there is to be a stratification. The second number (RANGE[2]) is the highest value for stratification. The third, optional, number (RANGE[3]) is an increment for stratification. If there is no increment, the default will be 1. During accumulation, if the value from BASEMW is less than RANGE[1], or higher than RANGE[2], the value from VALUEMW is accumulated into an out-of-range bucket. Iterations for which the report will be printed. If this keyword is not specified, or if any of the values exceed the last iteration, the report will be printed for the last iteration. REPORT is used primarily only when the Matrix program is invoked as a process that runs in a multiple iteration mode (Distribution program). Not yet in use. Title for identifying the final report at the end of the application. Work matrix number ( MW[ ] ) whose values will be accumulated according to the values of BASEMW (the trip matrix for a trip length distribution).

REPORT

IP|

SAVE TITLE VALUEMW

|?| |S| |I|

Example
FREQUENCY BASEMW=1,VALUEMW=2,RANGE=1-100, TITLE='Work Trips vs. Minutes' FREQUENCY BASEMW=1,VALUEMW=2,RANGE=0-100-0.5, REPORT=99

GOTO
Program: Distribution, Fratar, Generation, Matrix

Use GOTO to jump to statement named :label. When GOTO is processed, flow immediately branches to the statement named label. Label can be within IF and LOOP blocks; but care should be taken if this is to be done.

512 Cube Voyager Reference Guide

Matrix Program Control statements

label is a character string that must have a matching LABEL statement. The leading colon : is removed from label when determining the qualified name of the statement to branch to.
NOTE: The placement of a :label inside a JLOOP is not allowed. This prevents using GOTO from jumping into a JLOOP. A GOTO may be

used inside a JLOOP to jump to a :label that is outside the JLOOP but not to one that is inside the JLOOP.
Example
GOTO buildhwy GOTO :buildhwy

A statement that begins with : is a label statement, that has meaning with only GOTO statements. A label statement can be within IF and LOOP blocks; care should be taken if this is done. The leading : is ignored.
Example
GOTO buildhwy . . :buildhwy IF (expression) GOTO :buildhwy

; It is permissible to go backwards.

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


Program: Distribution, Fratar, Generation, Matrix

IF (expression) ELSEIF (expression) ELSE (expression) ENDIF IF/ENDIF blocks are used to determine if certain operations are to be performed. IF blocks may be nested, but they may not overlap LOOP, JLOOP, or other IF blocks. If a variable in the expression is MI.n.name, ZI.n.name, or MW[], the same rules for indexing in a COMP statement are applied. MI.n.name or MW[] should realistically only be used within a JLOOP. Lengthy IF expression solutions could be time consuming; it is suggested that they be used judiciously. Although IF expressions can be quite powerful for

Cube Voyager Reference Guide 513

Matrix Program Control statements

zonal selection, sometimes INCLUDE and EXCLUDE filters may provide a much more efficient selection process (see the examples in this section). The following control statements may be appended to a single IF statement:
BREAK CONTINUE COMP EXIT GOTO PRINT Example
IF (time_to_bcd < 20) simple statement ;single IF with process IF (expression) EXIT IF ( ( j=3-5,6-30,57 & k=(2*j-4) ) || ((J*k) = 14-20,56) ) . ELSEIF (loop_cntr > 10) . ELSEIF (loop_cntr > 5 && diff.time < 32) . ELSE . ENDIF ; The above IF example is rather esoteric, ; and probably can not be aided by a filter. ; The J selection could have been filtered, but that might have caused ; conflicts with the use of J in other parts of the expression. ; The following illustrates a more efficient process for using IF for ; lengthy zonal selections within JLOOPs ; ***** Inefficient ***** JLOOP IF (I=i_ranges... && J=j_ranges...) statement ENDJLOOP ; ***** More efficient ***** IF (I=i_ranges...) JLOOP INCLUDE=j_ranges... statement ENDJLOOP ENDIF

JLOOP ... ENDJLOOP


Programs: Distribution, Fratar, Generation, Matrix

Control a J loop for processing matrices.

514 Cube Voyager Reference Guide

Matrix Program Control statements

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

Cube Voyager Reference Guide 515

Matrix Program Control statements

PRINT REPORT SET


NOTE: The placement of a :label inside a JLOOP is not allowed. This prevents using GOTO from jumping into a JLOOP. A GOTO may be used inside a JLOOP to jump to a :label that is outside the JLOOP but not to one that is inside the JLOOP. JLOOP and ENDJLOOP keywords
Keyword J Jbeg Jend |I| Description Sets Jbeg, Jend and Jinc. Expression to initialize J; the value may not be less than 1, nor greater than Zones. Expression that establishes the Jend for the loop; the value may not be less than 1 nor greater than Zones. If there is no Jend, Jend is set to Jbeg, and Jinc is set to 1. Expression that establishes the Jinc for the loop. If Jinc is not specified, Jinc is set to 1 or -1, depending upon the direction from Jbeg to Jend.

Jinc

If Jbeg is not specified, Jend and Jinc can not be, and the values 1,Zones,1 are used. If Jend is not specified, Jinc can not be, and the values Jbeg and 1 are used. If Jinc is not specified, it is set to 1 ( -1, if Jbeg > Jend). Because all these values can be expressions, they must be separated by commas; if an expression contains any commas, it must be enclosed within ().
Example
JLOOP J=I EXCLUDE=500-535 ;process only intra zonal values . ; but exclude externals ENDJLOOP ROWSUM1 = 0 ROWSUM3=0 JLOOP ; get rowsums for matrices ROWSUM1 = ROWSUM1 + MW[1] ROWSUM3 = ROWSUM3 + MW[3] ENDJLOOP

516 Cube Voyager Reference Guide

Matrix Program Control statements

LOOP ... ENDLOOP


Programs: Distribution, Fratar, Generation, Matrix

Control a general variable loop. LVAR = Lbeg, Lend, Linc LOOP ENDLOOP blocks are used to repeat of a series of statements. LOOP initializes a variable; ENDLOOP compares the contents of the variable to another value, and branches back to the statement following the LOOP statement if the comparison fails. LOOP blocks may be nested; they may not overlap IF blocks. The process differs considerably from JLOOP. The logic is as follows: at LOOP: Initialize LVAR to Lbeg. Proceed to next statement. at ENDLOOP: If Lend not specified, jump to next statement. Compute Lend. If Linc not specified: Set Linc to 1 or -1 (if Lbeg and Lend are constants, and Lbeg > Lend) Else compute Linc. Add Linc to LVAR. Compare LVAR to Lend. If (Linc > 0 and LVAR > Lend) jump to statement after ENDLOOP If (Linc > 0 and LVAR <= Lend) jump to statement after LOOP If (Linc < 0 and LVAR < Lend) jump to statement after ENDLOOP If (Linc < 0 and LVAR >= Lend) jump to statement after LOOP

Cube Voyager Reference Guide 517

Matrix Program Control statements

Because of the flexibility of this logic, unpredictable results and/or endless loops can occur if care is not taken. This would only happen if the Lend and/or Linc values are expressions that contain variables which could be altered during the loop. On the other hand, the flexibility provides for powerful control. The loop will be processed at least one time regardless of Lend and Linc values. Most uses will involve constants. Because LVAR values can be expressions, Lbeg, Lend, and Linc must be separated by commas (standard white space delimiting can not be interpreted properly).
LOOP and ENDLOOP keywords
Keyword LVAR Description Name of the loop control variable. LVAR is not protected during the loop; computational, program, and other LOOP statements can alter its value. LVAR must be followed by Lbeg, and optionally, Lend and Linc. Numeric expression to initialize LVAR. Numeric expression that LVAR is to be compared with when the ENDLOOP statement is processed. If it is not specified, it is assumed no comparison is to be made (rather meaningless loop). Numeric expression that is to be added to LVAR before the ENDLOOP comparison is made. If Linc is not specified, it will be set to 1 (-1 if Lbeg and Lend are both constants and Lbeg < Lend; a backwards loop).

Lbeg Lend

Linc

Example
LOOP iter=1,10 ; perform 10 iterations . ENDLOOP LOOP xyz=abc*def,ghi+jkl,mno/pqr LOOP abc=xyz,xyz+2,2 ; nested LOOP ENDLOOP ENDLOOP LOOP jj=10,3,-2.5 ; 10, 7.5, 5.0 ENDLOOP

PARAMETERS
Program: Matrix

518 Cube Voyager Reference Guide

Matrix Program Control statements

Sets general parameters. MATVALCACHE MAXMW MAXSTRING TRAM ZONEMSG ZONES


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

MAXMW

|KI|

MAXSTRING

|KI|

Cube Voyager Reference Guide 519

Matrix Program Control statements

PARAMETERS keywords (continued)


Keyword TRAM |KI| Description Establishes the maximum amount of memory that is to be used for temporary storage when transposing matrices. The program will request the amount that it thinks will provide the most efficient processing. The most efficient amount would be (Zones * Zones * 8 * NumberTransposes), but that would probably be more than the computer has available in real memory. However, if Windows is controlling the computer, it will provide that much memory, but a portion of it might be virtual memory (temporary work space on disk). The use of virtual memory is disastrous in terms of efficiency for the transposing process. The program can not detect if the ram is real or virtual; therefore, care should be taken to not specify a value that is too large. In general, 4MB (4000000) should be adequate for most applications; 4000000 is the default, and should not normally be reset. Optional. Frequency with which the program writes zonal timing messages to the run monitor or console. Value corresponds to number of zones. For example, with a value of 1, the program writes a message for every zone. With a value of 10, the program writes a message for every 10 zones. With a value of 0, the program writes no zonal messages. Specify a larger value to reduce run times. Program writes to the run monitor when initiated through Application Manager or voyager.exe. The program writes to the console when initiated through runtpp.exe. Valid values are greater than or equal to zero. Default value is 1. ZONES |KI| Establishes the number of zones to process. If ZONES is not specified, and the program has no other way to identify the appropriate number of zones, it will be set to 100. If there are any input MATIs being processed, the default value for ZONES will be determined by the highest value from any of the MATIs.

ZONEMSG

|IK|

520 Cube Voyager Reference Guide

Matrix Program Control statements

Example
ZONES=3000

PRINT
Programs: Distribution, Fratar, Generation, Matrix

Format and print a line of information. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) See PRINT on page 62 for details about the standard Cube Voyager statement.
Example
PRINT FORM=0 LIST=I,J,TOTAL(6.2CS) 'ABCDE'(6.3), FORM=LRCD, LIST=N,JLOOP_J ;Note this line is a continuation LIST= I(6) J(6) TOTAL1, TOTAL2, TOTAL3 FILE=PRINTFIL.001 PRINT FORM=6.0CDLR LIST=I,J,TOTAL1,TOTAL2 FILE=PRINTFIL.002

PRINTROW
Program: Distribution, Fratar, Matrix

Prints row of matrices. MW J TITLE FORM MAXPERLINE BASE1 See PRINTROW on page 69 for details about the standard Cube Voyager statement.
Example

Examples of output with various parameters follow:


pagewidth=80 mw[1]=j mw[2]=j include=1-5,31-60,90-100 exclude=35,83 printrow mw=1-2,1 form=LRD title='form=LRD' printrow mw=1-21 form=6D base1=y maxperline=10, title='form=6D base1=y, maxperline=10'

Cube Voyager Reference Guide 521

Matrix Program Control statements

Resulting Output:
J: I=1 1: 1 2 27: 27 50: 50 73: 73 96: 96 J: I=1 1: 1 2 33: 33 57: 57 90: 90 J: I=1 1: 1 2 11: 11 21: 21 31: 31 41: 41 51: 51 61: 61 71: 71 81: 81 91: 91 J: I=1 1: 1 2 31: 31 41: 41 51: 51 81: -91: 91 PRINTROW MW[1] form=LRD Tot=5,050 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 97 98 99 100 PRINTROW MW[2] form=LRD Tot=2,390 3 4 5 - - - - - -- - - - - - - - - - -- - - - - - - - - - 31 32 34 - 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 58 59 60 -- - - - - - - - - - -- - - - - - - - - - -- - - - - - 91 92 93 94 95 96 97 98 99 100 PRINTROW MW[1] form=6D base1= Tot=5,050 3 4 5 6 7 8 9 10 12 13 14 15 16 17 18 19 20 22 23 24 25 26 27 28 29 30 32 33 34 35 36 37 38 39 40 42 43 44 45 46 47 48 49 50 52 53 54 55 56 57 58 59 60 62 63 64 65 66 67 68 69 70 72 73 74 75 76 77 78 79 80 82 83 84 85 86 87 88 89 90 92 93 94 95 96 97 98 99 100 PRINTROW MW[2] form=6D base1= Tot=2,390 3 4 5 -- -- -- -- -32 33 34 -- 36 37 38 39 40 42 43 44 45 46 47 48 49 50 52 53 54 55 56 57 58 59 60 -- -- -- -- -- -- -- -- 90 92 93 94 95 96 97 98 99 100

RENUMBER
Programs: Fratar, Matrix

Renumbers (aggregate, split) zones for output matrices FILE ZONEO ZONES MISSINGZI MISSINGZO FILES INRAM
RENUMBER causes the program to assign new zone numbers to all values in the output matrices. This causes an extra layer of processing, because the matrices must be saved, and then retrieved and combined after all normal processing is completed.

522 Cube Voyager Reference Guide

Matrix Program Control statements

Each input zone must be assigned a new output zone number, and a pair of percentages (ROWPCT and COLPCT ) to indicate how the outgoing matrix zonal values are to be allocated to the renumbered zones. These equivalencies are obtained from records in the designated FILE. The records may have from one to four fields to specify the renumbering. A semi-colon (;) terminates data on a record; anything following the ; is a comment. The standard fields are:
Field IPZONE OPZONE ROWPCT COLPCT Description Input zone number Output zone number Percentage of IPZONEs values to be assigned to OPZONE when renumbering the IPZONE row Percentage of IPZONEs values to be assigned to OPZONE when renumbering the IPZONE columns

If there is only one field, OPZONE is set to 0. If there are less than three fields, ROWPCT and COLPCT are set to 100. If there are three fields, COLPCT is set to ROWPCT. ROWPCT and COLPCT may not exceed 327 An alternate record format for aggregating several zones into a single district:
Description District OPZONE IPZONEs Word that begins with the letter D (for traditional DISTRICT). The word may be any length, but the first character must be D. Output zone number; it MUST be followed by =. Remaining fields are the input zones that are allocated 100% (ROWPCT and COLPCT) into OPZONE. Two fields may be separated by a dash (-) if the two are to form a range.

Cube Voyager Reference Guide 523

Matrix Program Control statements

If the list of IPZONEs is large, and the length of the record would exceed 250 characters, the record must be broken into several records. Each record must begin with the District string, and may not terminate with a dash.
Example

D 1=1-10,20-30 45,48, 58-60 D 1=100-110 200-210 300-305 410 415 500-515 Those two formats can be mixed in the same file to allow efficient specification of zonal equivalencies. An IPZONE may appear more than one time; usually the case when a zone is to be split into several new zones. An OPZONE may appear more than one time, usually the case when aggregating zones. The sum of all ROWPCTs and COLPCTs for each IPZONE should each be 100; if not, a message is issued. Every IPZONE (1-IPzones) should be fully allocated. An IPZONE of 0 means there is intentionally no IPZONE for the OPZONE. An OPZONE of 0 means there is intentionally no OPZONE for the IPZONE. There should be an OPZONE for every zone (1-OPZONES); if not, a message is issued. To accommodate this process, the normal output matrices are trapped, renumbered, and saved, at the normal output phase. When all zones have been processed, the saved matrices are retrieved in appropriate order, combined when necessary, and written to the MATO files. The intermediate matrices are saved either in RAM (normal format), or on disk files (compressed format). If saved on disk, there must be sufficient disk space for both the intermediate rows, and the final output files. The process is optimized to the extent possible; the use of the FILES and INRAM keywords could help considerably in reducing running times.
RENUMBER keywords
Keyword FILE |F| Description File that contains the zonal equivalencies. FILE and ZONEO are mutually exclusive. Only one of those two keywords can be used at one time.

524 Cube Voyager Reference Guide

Matrix Program Control statements

RENUMBER keywords (continued)


Keyword FILES |I| Description Number of temporary files to use to store intermediate factored matrix rows, until they can be sorted and combined in the final stages of the application. The value must be in the range 1-10, inclusive. If the keyword is not specified, the program will set the value to ZONES/100, but never less than 1, nor greater than 10. The number of files affects the running time when the final matrices are being formed; more files generally speeds up the final stage. Ten files will normally reduce the application time by a factor of about 20-35 per cent as compared to one file. Single character (if a longer string is specified, only the first character is processed) to indicate how to treat input zones that are not fully allocated (ROWPCT and COLPCT totals of 100). The character may be F, W, or M, and if it is none of these, or MISSINGZI is not specified, it defaults to F. The meanings are: F Fatal W Warning M Message only (no penalty associated) MISSINGZO ZONEO |S| |S| Indicator similar to MISSINGZI. It indicates the level of error associated with gaps in the OPZONE structure. Alternate method of specifying zonal equivalencies using an input zonal data file. A typical value of ZONEO is an input zonal attribute: ZI.**.***. In this convention, the IPZONE is the current zone number and the OPZONE is the specified input zonal attribute, for example, district or TAZ number. ZONEO and FILE are mutually exclusive. Only one of those two keywords can be used at one time. Designates the highest new zone number and serves as an editor as the file records are read, to ensure that each OPZONE doesnt exceed this value. If ZONES is not designated, no edit is performed, and ZONES is set to the highest OPZONE. A check is made to ensure that there is an OPZONE for all values: 1-ZONES; if there are any gaps, a message is issued.

MISSINGZI

|S|

ZONES

|I|

Example[1]
FILEI MATI=IN.MAT FILEO MATO=OUT.MAT, MO=1

Cube Voyager Reference Guide 525

Matrix Program Control statements

MW[1]=MI.1.1 ; must load values into MW[1], else OUT.MAT will be all zeros ; renumber OUT.MAT according to 2005ZON.EQ RENUMBER FILE=2005ZON.EQ, MISSINGZI=M, MISSINGZO=W

Example[2]
FILEI MATI=IN.MAT, ZDATI=ZDATIN.DAT, Z=#1, DIST=2 FILEO MATO=OUT.MAT, MO=1 MW[1]=MI.1.1 ; must load values into MW[1], else OUT.MAT will be all zeros ; renumber OUT.MAT according to ZDATIN.DAT RENUMBER ZONEO=ZI.1.DIST

Example[3]
/* This is a two step process to show an example of using RENUMBER to split an existing pair of trip tables for a new disaggregate zone system. A typical process might be to split zones into fully nested sub zones in ArcView. This example assumes such a spatial procedure has been preformed and the resulting dbf file has the zonal area of both the parent zones and the new split zones. This first step uses MATRIX to compute split factors based on the ratio of the new zone-to-old zone area and writes out the zonal equivalency file for use in the subsequent renumbering step. */ ;STEP 1 RUN PGM=MATRIX FILEI ZDATI[1] = TAZDATA1.DBF ; Data structure of TAZDATA1.DBF is: ;Z NEW_Z1 NEW_Z2 Z_AREA Z1_AREA Z2_AREA ;1 1 2 6.40 2.22 4.18 ;2 3 4 6.42 3.18 3.24 ;3 5 6 6.44 3.78 2.66 ;4 7 8 6.46 2.58 3.88 ;5 9 10 6.48 3.75 2.73 ; . . . PARAMETERS ZONES=2999 ; establishes a split factor based on the new zone geography ; the split factor is the ratio of the area of the new zone to the area ; of its parent. This set up assumes all input zones are split into two output zones ; and that the total area of the new zones is equal to the area of the parent zone. SPLIT1=100*(ZI.1.Z1_AREA/ZI.1.Z_AREA) SPLIT2=100-SPLIT1 ; writes the split factors to the PRN file PRINT LIST=SPLIT1,SPLIT2

526 Cube Voyager Reference Guide

Matrix Program Control statements

; write the zonal equivalency file PRINT LIST=I,ZI.1.NEW_Z1,SPLIT1, FILE = EQUIV_1.DAT" PRINT LIST=I,ZI.1.NEW_Z2,SPLIT2, FILE = EQUIV_1.DAT" ; data structure of EQUIV_1.DAT is : ; 1.00 1.00 34.69 ; 1.00 2.00 65.31 ; 2.00 3.00 49.53 ; 2.00 4.00 50.47 ; 3.00 5.00 58.70 ; 3.00 6.00 41.30 ; 4.00 7.00 39.94 ; 4.00 8.00 60.06 ; 5.00 9.00 57.87 ; 5.00 10.00 42.13 ; . . . ENDRUN ;STEP 2 split input trip table to new zonal system RUN PGM=MATRIX FILEO MATO[1] = TRIPS2.MAT, MO=1-2, NAME=AUTO, TRANSIT FILEI MATI[1] = TRIPS1.MAT mw[1]=mi.1.1 ; fill work matrix 1 with AUTO trips from input matrix 1 mw[2]=mi.1.2 ; fill work matrix 2 with TRANSIT trips from input matrix 2 RENUMBER, FILE = EQUIV_1.DAT ; the zonal equivalency file has the fields IPZONE, OPZONE and ROWPCT ; the default when no COLPCT is specified is to set the COLPCT=ROWPCT. ; if different COLPCT factors are desired they would need to be specified in the ; fourth column of the file. ENDRUN

REPORT
Program: Matrix

Request reports and establish tracing MARGINS TRACE MARGINREC (CFORM FORM LIST FILE (PRINT))

Cube Voyager Reference Guide 527

Matrix Program Control statements

ZDAT (DEC) MATSTAT


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

MARGINREC MARGINREC

CFORM FILE

|S| |F|

MARGINREC

FORM

|S|

528 Cube Voyager Reference Guide

Matrix Program Control statements

REPORT keywords (continued)


Keyword MARGINREC Subkeyword LIST |KSV| Description Specifies the items (variables and/or strings) that are to be formatted to the print line. If it is desired to have an explicit format for any item in the list, there may be a format appended to the it. Such a format is surrounded by (); the format applies to only that item. Example:
J ITEM1(6) ITEM2(8C) 'abcde' 'i='(8R) K(L)

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

Cube Voyager Reference Guide 529

Matrix Program Control statements

REPORT keywords (continued)


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

ZDAT

|?|

ZDAT

DEC

|I|

Example

These statements illustrate REPORT.


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

Example MATSTAT REPORT:


Table 1 - Matrix Summary (625 cells) ----------- Sum ----------- ---- Cnt --- ----------- Ave ---------ALL >0 <0 >0 <0 ALL >0 <0 MW[1] 16,455.14 16,455.14 -- 256 -- 26.32822 64.27789 -MW[2] 9,923.04 9,923.04 -- 256 -- 15.87686 38.76187 -MW[3] 978.99 978.99 -- 256 -- 1.56638 3.82418 -MW[4] 27,357.17 27,357.17 -- 256 -- 43.77147 106.86395 -Table 2 - Matrix Min/Max (625 cells) ---------- Minimum -------------- ------------ Maximum ------------->0 @I-J <0 @I-J >0 @I-J <0 @I-J MW[1] 2.5450 3-16 -- --- 1,007.71 13-13 -- --MW[2] 3.1050 3-16 -- --- 370.64 13-13 -- --MW[3] 0.1015 13-12 -- --- 39.65 1-1 -- --MW[4] 6.0145 3-16 -- --- 1,378.97 13-13 -- --Table 3 - Matrix Intrazonal Summary (625 cells) ---------- Sum ---------- ---- Cnt --- ----------- Ave ----------

530 Cube Voyager Reference Guide

Matrix Program Control statements

ALL >0 <0 >0 <0 ALL >0 <0 MW[1] 3,059.99 3,059.99 -- 16 -- 4.895984 191.24937 -MW[2] 1,629.70 1,629.70 -- 16 -- 2.607520 101.85625 -MW[3] 178.27 178.27 -- 16 -- 0.285232 11.14187 -MW[4] 4,867.96 4,867.96 -- 16 -- 7.788736 304.24750 -Table 4 - Matrix Intrazonal Min/Max (625 cells) ---------- Minimum ------------- ------------ Maximum ------------->0 @I-J <0 @I-J >0 @I-J <0 @I-J MW[1] 4.82 3-3 -- --- 1,007.71 13-13 -- --MW[2] 6.09 12-12 -- --- 370.64 13-13 -- --MW[3] 0.12 5-5 -- --- 39.65 1-1 -- --MW[4] 18.74 7-7 -- --- 1,378.97 13-13 -- ---

SET
Programs: Distribution, Fratar, Generation, Matrix

Stores numeric values into one, or more, variables. VAL VARS Use SET to set any number of variables to some value. All variables are set to zero at the beginning of the I loop, and are then changed only by the user. Most changes are the result of COMP statements. A COMP statement can accomplish all that SET does, but it is not as efficient, and is somewhat wordier.
SET keywords
Keyword VAL |R| Description Numeric value that the VARS that follow will be set to. VAL is initialized to zero when the statement is started, and then reset as this keyword is encountered. If there is no VAL, the coded VARS are all set to zero. List of variables that are to be set to the more recent value of VAL obtained from this statement. If a named VARS is an array allocated by an ARRAY statement, the entire array is set to the value of VAL.

VARS

|S|

Example
SET VAL=0, VARS=TOT1,TOT2,COUNTER COMP TOT1=0 TOT2=0 COUNTER=0 ; is the same as previous statement SET VARS=TOT1 TOT2 COUNTER ; is also the same (VAL defaults to 0)

Cube Voyager Reference Guide 531

Matrix Program Control statements

SET VAL=123 VARS=C123, VARS=TOT1, TOT2, TOT3 ; sets all to 123 ARRAY SUMS=50 SET VAL=100, VARS=SUMS ; sets all 50 cells of SUMS to 100 SET VARS=SUMS ; sets all 50 cells of SUMS to 0

SORT
Programs: Distribution, Fratar, Generation, Matrix

Sort user-defined arrays. ARRAY NUMRECS See SORT on page 72 for details about the standard Cube Voyager statement.
Example
ARRAY ZONENO=ZONES, HH=ZONES, INCOME=ZONES . . ZONENO[I] = I HH[I] = ZI.1.HH[I] INCOME[I] = ZI.1.INCOME[I] . . SORT ARRAY=-INCOME,-HH,ZONENO, NUMRECS=ZONES LIST= Zone Income HHs JLOOP PRINT FORM=8, LIST=ZONENO[J], INCOME[J], HH[J] ENDJLOOP

WRITE
Programs: Distribution, Fratar, Generation, Matrix

Output record data files to DBF format RECO

532 Cube Voyager Reference Guide

Matrix Program Control statements

Use WRITE to specify the record files that are to be written at the end of each I zone.
WRITE keyword
Keyword RECO |I| Description Number of the FILEO RECO[#] DBF file where you want to direct this print output.

Cube Voyager Reference Guide 533

Matrix Program Examples

Examples
This section contains examples that demonstrate the Matrix program: Example 1 Example 2 Example 3 Example 4

Example 1
RUN PGM=MATRIX /* Sample problem to generate a zonal data file from input files The resulting zonal file will contain combined data from the input zonal data and a summary of trips to the zones that are in the cbd */ mati[1]=tripfile.mat zdati[1]=socoecon.dat,z=#1, pop=#2, area=#3, income=#4, hh1=#5, hh2=#6, hh3=#7 zdati[2]=employ.dat, z=#1, gov=#2, retail=#3, other=#4 ARRAY pop=10, area=10 totemp=10, tothh=10 ; this is a 10 zone problem area[i]=zi.1.area totemp[i]=zi.2.gov + zi.2.retail + zi.2.other tothh[i]=zi.1.hh1 + zi.1.hh2 + zi.1.hh3 jloop include=1-5,38,56-100,145-150 ;cbd zones cbdtrips[j] = cbdtrips[j] + mi.1.tottrips[j] endjloop if (i==zones) ; at last zone jloop ; write a file of zonal records print file=newzdat.zda form=6 list=j(3) pop[j] area[j] totemp[j] tothh[j] cbdtrips[j] endjloop endif ENDRUN

Example 2
; Get I-J values for records with trip tours on them. /*Sample setup to use the MATRIX program to process the tours.dat file

534 Cube Voyager Reference Guide

Matrix Program Examples

For each leg of the tour, look up highway or transit time based on the major mode for that journey, assuming 1 is highway otherwise transit The program will read each input record from the RECI file and do calculations as specified. The MatVal function is used to random access any i-j value from any input matrix. The format is: MatVal( filenumber, tablenumber, i, j, failvalue) The failvalue is returned if lookup fails (invalid filenumber, tablenumber, i, or j) This script has been tested for validity, but has not been thoroughly tested for logical content. */ RUN PGM=MATRIX mati=hwytime.mat,trntime.mat reci=tours.dat, org=23, dst=26 ; there are 80 fields on the record, can be referenced by reci.nfield[#]. ; Field 23 can also be referenced as ri.org, and field 26 as ri.dst ; setup array to store time values with max of 8 legs on each tour array hwyt=8 trnt=8 set val=0, vars=hwyt trnt ; initialize output variables ; trips from org to dst from=ri.org leg=1 loop stops=32,42,5 ; flds 32,37,42 if (reci.nfield[stops] > 0) ; if main mode org-dst is hwy if (reci.nfield[76] = 1) ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,reci.nfield[stops],0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,reci.nfield[stops],0) endif leg=leg+1 from=reci.nfield[stops] endif endloop ; from last stop to dst if (reci.nfield[76] = 1) ; if main mode org-dst is hwy ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,ri.dst,0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,ri.dst,0) endif ; trips from dst to org

Cube Voyager Reference Guide 535

Matrix Program Examples

from=ri.dst leg=5 loop stops=47,57,5 if (reci.nfield[stops] > 0) if (reci.nfield[77] = 1) ; if main mode dst-org is hwy ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,reci.nfield[stops],0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,reci.nfield[stops],0) endif leg=leg+1 from=reci.nfield[stops] endif endloop ; from last stop to org if (reci.nfield[77] = 1) ; if main mode dst-org is hwy ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,ri.org,0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,ri.org,0) endif ; write out I/P record(RECI) and append highway and transit time values print file=tourtime.dat, form=5 list=reci, hwyt[1],hwyt[2],hwyt[3],hwyt[4],hwyt[5],hwyt[6],hwyt[7],hwyt[8], trnt[1],trnt[2],trnt[3],trnt[4],trnt[5],trnt[6],trnt[7],trnt[8] ; compute totals of highway and transit time arrays hwyt_tot=arraysum(hwyt) trnt_tot=arraysum(trnt) ENDRUN

Example 3
/* This is an example of using RECI/RECO processing of DBF data files */ RUN PGM=MATRIX FILEI RECI = ZONES_2002.DBF FILEO RECO[1] = ZONES_2002_NEW.DBF, FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), EXCLUDERECI=HOUSEHOLDS FILEO RECO[2] = ZONES_2010.DBF, FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), POP_2010(8.0), HH_2010(8.0), HHsiz_2010(4.2), Pden_2010(4.2),

536 Cube Voyager Reference Guide

Matrix Program Examples

EXCLUDERECI=HOUSEHOLDS FILEO RECO[3] = ZONES_2020.DBF, FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), POP_2010(8.0), HH_2010(8.0), HHsiz_2010(4.2), Pden_2010(6.2), POP_2020(8.0), HH_2020(8.0), HHsiz_2020(4.2), Pden_2020(6.2), EXCLUDERECI=HOUSEHOLDS ; compute regional base year statistics TotalHH=TotalHH+RECI.NFIELD[5] TotalPop=TotalPop+RECI.NFIELD[6] avgHHsize=TotalPop/TotalHH ; print regional base year statistics if (I=0) ; check for end of file PRINT LIST='Total Households = ',TotalHH PRINT LIST='Total Population = ',TotalPop PRINT LIST='Average Household size = ',avgHHsize endif ; rename RECI field RO.HH_2002=ri.HOUSEHOLDS ; calculate zonal average household size for base year RO.HHsiz_2002=ri.POP_2002/HH_2002 ; calculate zonal population density per/acre for base year RO.Pden_2002=ri.POP_2002/(ri.AREA/43560) ; factor base year data for 2010 RO.HH_2010=HH_2002*1.2 RO.POP_2010=RECI.NFIELD[6]*1.4 RO.HHsiz_2010=POP_2010/HH_2010 RO.Pden_2010=POP_2010/(ri.AREA/43560) ; factor base year data for 2020 RO.HH_2020=HH_2002*1.5 RO.POP_2020=RECI.NFIELD[6]*1.8 RO.HHsiz_2020=POP_2020/HH_2020 RO.Pden_2020=POP_2020/(ri.AREA/43560) ; write data to defined output files WRITE RECO=1,2,3 ENDRUN

Example 4
/* Example of using the CHOICE command in MATRIX to estimate a singly constrained gravity model constrained on Production trip ends */ RUN PGM=MATRIX FILEO MATO[1] = "C:\CUBETOWN\MODEL\MODELS\SINGLEPRODDIST.MAT" MO=1 NAME=HBW

Cube Voyager Reference Guide 537

Matrix Program Examples

FILEI ZDATI[1] = "{SCENARIO_DIR}\TRIPENDS.DBF" FILEI MATI[1] = "{SCENARIO_DIR}\CURRENTCOSTS.MAT" ;The general approach for a singly constrained in Voyager is to use the MATRIX ;program and the CHOICE command to implement a destination choice model. ;If you require a gamma curve deterrence function rather than the negative exponential, ;you need to specify the appropriate calculations yourself. ;This example gives a destination choice model constrained on production trip ends. CHOICE ALTERNATIVES=all1, DEMAND=ZI.1.P1, COSTS=mi.1.1, ODEMAND=1, STARTMW=99, DESTSPLIT = TOTAL 0.2 all1 ;To apply singly constrained on attractions; ;- transpose the cost matrix, saving it to output file ;- run MATRIX, reading the transposed costs, reversing your use of the ; production and attraction data (i.e., TOTAL=ZI.1.A[1] etc) ; to implement a destination choice, with attraction totals as the single constraint. ;- transpose the resulting matrix to correct orientation. ENDRUN

Example 5
/* Example of DBI processing to combined two fields from different tables stored in a MDB file to a new table in the MDB file using the JOINTTODBI functionality. */ RUN PGM=MATRIX FILEO RECO[1] = "DBI_Examples.mdb\AlfaBeta2", FIELDS=ZONE_ ALFA BETA FILEI DBI[2] = "DBI_Examples.mdb\BETA", SORT=ZONE_ JOINTODBI=1 JOINTOFIELDS=ZONE_ FILEI DBI[1] = "DBI_Examples.mdb\ALFA" ZONES=1 LOOP k=1,DBI.1.NUMRECORDS x=DBIReadRecord(1,k) RO.ZONE_=DI.1.ZONE_ RO.ALFA=DI.1.ALFA RO.BETA=DI.2.BETA WRITE RECO=1

538 Cube Voyager Reference Guide

Matrix Program Examples

ENDLOOP ENDRUN

Example 6
/* The same process as Example 5 but using AUTOARRAY functionality to accomplish the same task. */ RUN PGM=MATRIX FILEO RECO[1] = "DBI_Examples.mdb\AlfaBeta3", FIELDS = ZONE_ ALFA(10.4) BETA(10.4) FILEI DBI[2] = "DBI_Examples.mdb\BETA", AUTOARRAY=BETA FILEI DBI[1] = "DBI_Examples.mdb\ALFA", AUTOARRAY=ALFA ZONES = 1 LOOP L3=1,DBI.1.NUMRECORDS,1 RO.ZONE_ = L3 RO.ALFA = DBA.1.ALFA[L3] RO.BETA = DBA.2.BETA[L3] WRITE RECO = 1 ENDLOOP ENDRUN

Cube Voyager Reference Guide 539

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

10

Distribution Program Introduction to the Distribution program

Introduction to the Distribution program


This section introduces you to the Distribution program. Topics include: Overview Convergence: Iteration control Multiple purposes Referencing productions and attractions Travel function values: Friction factors

Overview
Trip distribution is the process of estimating the number trips that will travel between all the zones in the system. Usually the process uses the number of trip ends in each zone as the starting point. These margin totals are distributed to the rows and column of a generated matrix. Usually, additional information about some measure of travel between each zone pair should be included in the process. The most commonly used distribution process is the gravity model, but other processes are also employed. Cube Voyager does not have any automatic, or default, trip distribution process. The Matrix program provides a framework that allows the user to perform distribution in a variety of ways. In some cases, the Matrix program does have some built-in functions that aid in the implementation of the more popular distribution processes. A gravity model distribution can be easily implemented within Matrix, but it does need some help, and the user has to follow certain guidelines for proper implementation. A brief illustration of a typical gravity distribution follows. The gravity model equation is: TRIPi-j = Pi * Aj * func(Ti-j) / Sz=1..n (A * func(T)). where: P = the number of trip productions for a zone.

542 Cube Voyager Reference Guide

Distribution Program Introduction to the Distribution program

10

A = the number of trip attractions for a zone. T = the travel impedance factor between zones. i = the production zone. j = the attraction zone. z = any zone. n = the number of zones. In simple terms this states that the trip productions in zone I will be distributed to each zone J according to the relative attractiveness of zone J. Each Js attractiveness is determined by the product of its attractions and some function of the spatial separation between I and J. The sum of the these products for all Js (relative to I) is obtained and often referred to as the accessibility index for I. Each J will then be given a prorata share of the productions for I based upon its attractiveness relative to the accessibility index for I. The function of spatial separation (func(T)) is the indefinite portion of the equation. It is believed to be best described by an expression of the form of e^bT, where b is the curve factor, and T is the travel time. Experience has shown that often a single curve does not suffice, and it difficult to estimate what b should be used. To facilitate application, most gravity model processes use a lookup function to obtain empirical values for the function based upon the impedance. These curves are usually called friction factor curves. Numerous applications have shown that friction factor curves tend to follow the same patterns for similar conditions. Many agencies share the same curves when their regions are similar in nature. To implement the gravity model in Matrix, several guidelines must be followed: There must be a set of Ps and As for each purpose to be estimated. They are established by the presence of a SETPA control statement.

Cube Voyager Reference Guide 543

10

Distribution Program Introduction to the Distribution program

A mechanism must be established to obtain the travel function. Usually, a level-of-service matrix is used to obtain the zone-tozone impedance for I-J, and the travel function value (friction factor) is obtained by finding the impedance in a LOOKUP table. The gravity model equations must be executed in a specific order. At least three expressions are required. One to compute attractiveness for each J, one to sum them to form the accessibility index for I, and one to distribute the productions based upon the values and the accessibility index. Obviously, these expressions must be executed in the proper order.

As an alternative to complete user definition of the gravity formulation, the GRAVITY control statements can be used to perform a built in process for a doubly constrained GRAVITY model. This process is more efficient than complete formulation. A singly constrained gravity model can be formulated as a destinationchoice model with the CHOICE control statement in Matrix. See Examples on page 534 under the Matrix program for an example of a singly constrained gravity model.
Example 1
/* given: The impedances are in the first matrix of file: IMP.MAT The productions and attractions are in file: PA.ZDA The friction factors are in file: FF.DAT */ FILEI MATI[1] = IMP.MAT, ZDATI[1] = PA.ZDA,Z=#1,P1=#2,A1=#3 FILEO MATO[1] = OUT.MAT, MO=1 LOOKUP NAME=FF,LOOKUP[1]=#2,RESULT=#1, FILE=FF.DAT, INTERPOLATE=Y SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1 MW[1] = A[1] * FF(1,MI.1.1), PAF=P[1]/ROWSUM(1), MW[1]=PAF * MW[1] GRAVITY PURPOSE=1, LOS=MI.1.1, FFACTORS=FF ; faster process

544 Cube Voyager Reference Guide

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 row (production zone) totals for each will always match the number Ps for the zone. There is no method to guarantee that the correct column totals (number of attractions) will be obtained for each J zone. In all likelihood, the estimated column values will not match the desired number of As input for each zone. This problem is alleviated by iterating the model. An iteration is a complete pass for all I zones. At the end of each iteration, the estimated column totals are compared to the input As, and, based upon the comparison, the process is repeated with an adjustment in the data. The adjustment is based upon the closeness for each zone. The iteration process is repeated until it is decided that the results are close enough, or that a maximum number of iterations have been performed. Following is small example of this process: Prior to the first iteration the desired totals are:
Zone 1 2 3 Total 1 -- -- -- 100 2 -- -- -- 200 3 -- -- -- 300 Total 240 200 160 600

There really is no matrix yet. The totals are the values as obtained from the SETPA control statements. The model goal is to fill in the matrix with values so that the totals will match the totals shown. The row totals shown are the Desired Ps for each zone, and the column totals are the Desired As. A set of A values internally named Used are set equal to the Desired values. An iteration is performed and the Estimated results appear as: After Iteration 1:
Zone 1 2 3 1 57 24 19 2 64 106 30 3 102 61 137 Total 223 191 186 Use2 258 210 138 Total 100 200 300 600

Cube Voyager Reference Guide 545

10

Distribution Program Introduction to the Distribution program

As dictated by the formulation, the row totals are correct. But, the Estimated column totals do not quite match the Desired. The As for each zone are adjusted by a factor that is computed as: Desired * Used / Estimated. Another iteration is performed, and the results appear as: After Iteration 2:
Zone 1 2 3 1 60 24 16 2 67 108 25 3 113 66 121 Total 240 198 162 Use3 258 212 136 Total 100 200 300 600

The Estimated column totals are still not exactly what is desired, so adjustments are made to the used As, and another iteration is performed. After Iteration 3:
Zone 1 2 3 Total 1 60 24 16 100 2 66 109 25 200 3 114 67 119 300 Total 240 200 160 600

Now the Estimated totals and the Desired totals match for all zones. The model is completed. Further iterations would be useless; nothing would change. In the real world, with many zones, it is not likely that all the Estimated totals would match exactly with the Desired totals. As a matter of fact, in this simple three zone problem, the totals did not match exactly (there were some slight differences in the decimal places). But, the floating point values were close enough to be accepted as having matched. How does the program decide when it should stop? There are two parameters that can be used for controlling cutoff: MAXITERS and MAXRMSE. MAXITERS specifies that no more than a specified number of iterations are to be performed. The default is MAXITERS=3; this is usually sufficient for most gravity model applications. Additionally,

546 Cube Voyager Reference Guide

Distribution Program Introduction to the Distribution program

10

the program computes the root mean square error of the differences in Estimated vs. Desired attractions (sqrt (Sum(diff^2) / (n-1)). If the computed RMSE is less than MAXRMSE, a completion flag is set. The default is MAXRMSE=10, but that may not always be a good choice for certain applications. In the sample three zone problem the RMSEs for each iteration were computed as: 22.78, 2.08, and 0.26. The final value of 0.26 indicates that there were still some slight differences in the Estimated and Desired, but as noted above, they were insignificant. If the default MAXRMSE value had been used, the process would have cutoff after two iterations.

Multiple purposes
Usually a given application will consist of more than one purpose. Traditionally, at least three internal purposes are estimated, with the most commonly used purposes being: Home Based Work (HBW), Home Based Other (HBO), and Non Home Based (NHB). There are other popular purpose stratification, but these are the most commonly used. Often Internal-External and External-Internal and truck and taxi purposes are also estimated; some analysts prefer to estimate them in a separate application, and some prefer to do them all at once. With the Cube Voyager process, all the purposes can be estimated in one application because the user has the ability to specify different gravity equations for each of the purposes. Each purpose can have its own impedance matrix and different formulation (functions, expressions, friction factors, etc.). The Ps and As and lookup functions can be obtained from different sources. There is one caveat: If convergence has not been reached for any purpose, and MAXITERS has not been reached, another iteration will be processed with adjusted As for all purposes. That is no concern; the results will not get worse. The MAXRMSE parameter applies to the highest RMSE of all purposes. MATO files are written only on the last iteration. If the iteration number is equal to the PARAMETERS MAXITERS value, the program knows when the last iteration is being processed. But, convergence could be obtained at some lower iteration. In that case the program will perform another iteration, similar to the one just completed, but this time writing

Cube Voyager Reference Guide 547

10

Distribution Program Introduction to the Distribution program

the MATO files. In other words, if convergence is reached before MAXITERS, an additional iteration will be performed in order to obtain the matrices. The use of PARAMETERS MATOEVERY will preclude an additional iteration, but at the cost of additional time to write matrices during each iteration. The number of purposes is determined by the highest P[] or A[] index established via the SETPA control statement. The program assumes that there will be purposes from one, monotonically, through that highest index. Other COMP MW[]= statements may be specified, but they will not be involved in any internal purpose editing. If the estimates follow the same formulation, the set up is only slightly different from what is depicted, above. Example 2 illustrates a typical setup for a three purpose application.
Example 2: Three purpose - same P/A and FF file for all purposes
LOOKUP FILE=FF.DAT, INTERPOLATE=Y, NAME=FF, LOOKUP[1]=1,RESULT=2, LOOKUP[2]=1,RESULT=3, LOOKUP[3]=1,RESULT=4 SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1, P[2]=ZI.1.P2, A[2]=ZI.1.A2, P[3]=ZI.1.P3, A[3]=ZI.1.A3 LOOP PURP=1,3 MW[PURP] = A[PURP] * FF(PURP,MI.1.1) PAF=P[PURP]/ROWSUM(PURP) MW[PURP]=PAF*MW[PURP] ENDLOOP

In Example 3, purposes 1-3 are the same as in Example 2, and two internal-external purposes (with entirely different formulation) are to also be included. Purpose 4 uses an equation for distribution, and purpose 5 uses a simple lookup curve, with only three points in it.
Example 3
LOOKUP FILE=FF.DAT, INTERPOLATE=Y, FAIL=12000,1,0, NAME=FF, LOOKUP[1]=1,RESULT=2, LOOKUP[2]=1,RESULT=3, LOOKUP[3]=1,RESULT=4

548 Cube Voyager Reference Guide

Distribution Program Introduction to the Distribution program

10

LOOKUP NAME=XIFF, FAIL=500,100, R= '500 1-20', ; read the data directly '400 20-30', '300 30-40', '200 40-50' SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1, P[2]=ZI.1.P2, A[2]=ZI.1.A2, P[3]=ZI.1.P3, A[3]=ZI.1.A3 SETPA P[4]=ZI.2.PI, A[4]=ZI.3.STACNT_OB, P[5]=ZI.2.AI, A[5]=ZI.3.STACNT_IB LOOP PURP=1,3 IF (PURP <= 3) MW[PURP] = A[PURP] * FF(PURP,MI.1.1) ELSEIF (PURP==4) JLOOP INCLUDE=1-500 IMP = MI.2.IMPEDNACE IF (MI.2.DISTANCE < 3) IMP = MI.2.SHORTIMP MW[4] = A[4]*EXP(-B * IMP) ENDJLOOP ELSE MW[5] = A[5] * XIFF(MI.2.IMPEDANCE) INCLUDE=501-535 ENDIF PAF=P[PURP] / ROWSUM(PURP), MW[PURP]=PAF*MW[PURP] ENDLOOP

Of course, there are different ways that this distribution could have been written. Most likely, the purpose 4 and 5 Ps and As would not sum to the same total because they were derived from separate sources. If there is a difference in the totals for a purpose, the program issues a message and adjusts the As to match the P total. Differences in the totals would preclude convergence via RMSE calculations because there would always be differences.

Referencing productions and attractions


Productions and attractions are referenced by using array notation for P and A. P and A are doubly dimensioned arrays, where the first index references the purpose number, and the second index references the zone number. Since most users may not wish to always code a zone index (it is more intuitive to reference the arrays with just purpose number), the zone index need not be supplied; it will be automatically provided. However, the zone index has

Cube Voyager Reference Guide 549

10

Distribution Program Introduction to the Distribution program

different meanings for P and A. For P, the default zone index is I and for A, it is J. If a different index is required, it may be explicitly provided. Most times an invalid index will cause a fatal termination. Purpose 0 and Zone 0 are valid, but may not always be predictable. Zone 0 should always contain the total for the purpose. The lower bounds for both indices are zero, and the upper bounds are number of purposes and zones, respectively. P and A are protected variables; they may not be the result of COMP expressions, except on SETPA statements.

Travel function values: Friction factors


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

This file would be described with a LOOKUP statement such as:


LOOKUP FILE=FF_FILE, NAME=FF, LOOKUP[1]=1, RESULT=2, LOOKUP[2]=1. RESULT=3, LOOKUP[3]=1, RESULT=4

This statement indicates that the first four values from each record will be used. Field 1 will be the travel time value, and fields 2, 3, and 4 are the values for purpose 1, 2, and 3, respectively. The friction factor for purpose 1 for 1 minute would be 9000, and the friction factor for purpose 2 would be 8000. The friction factor for purpose 1 for a time value of 1.5 could be either 9000 or 8500, depending upon the options specified on the LOOKUP statement. If

550 Cube Voyager Reference Guide

Distribution Program Introduction to the Distribution program

10

SETUPPER=T is specified, the friction factor will be 9000, and if SETUPPER=F and INTERPOLATE=T, the friction will be 8500. This capability allows for compatibility with other model systems. In this example, a time value of 0.5 will result in the value 9000, because there is no explicit FAIL[1] specified. The friction for any value greater than 51 will be 0; no distribution. If the record for 51 were not in the file, the friction factor for any time greater than 50 would be 1. However, if FAIL[2]=0 were used, any time greater than 50 would be 0. It is recommended that a final value of 0 be used to preclude distribution to zones where the I-J time exceeds a certain value. This can also be controlled by use of the LOSRANGE keyword on the GRAVITY statement.

Cube Voyager Reference Guide 551

10

Distribution Program Control statements

Control statements
Most of the standard Matrix program statements are valid in the Distribution program, and a few additional ones are available. Since the Distribution program is a subset of the Matrix program, it is assumed that the user is familiar with the Matrix-program control statement set. Only the differences between the Matrix and Distribution control statements are included in this section. For descriptions of other control statements see Control statements on page 436 under the Matrix program. Matrix program statements not allowed in the Distribution program:
RENUMBER

Distribution program statements not in the Matrix program:


SETPA GRAVITY

Distribution program keywords not in the Matrix program:


PARAMETERS MAXITERS= MAXRMSE= REPORT ACOMP=

GRAVITY
Performs a standard gravity model. PURPOSE LOS FFACTORS KFACTORS LOSRANGE

552 Cube Voyager Reference Guide

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

KFACTORS

|S|

LOS

|S|

LOSRANGE

[R]

PURPOSE

|I|

PURPOSE, LOS, and FFACTORS must be specified. Example


lookup fail=12000,1,0, list=n, file=tstff1, name=ff, lookup[1]=1,result=2, lookup[2]=1,result=3, lookup[3]=1,result=4,

Cube Voyager Reference Guide 553

10

Distribution Program Control statements

lookup[4]=1,result=5, lookup[5]=1,result=6, interpolate=y,setupper=n gravity purpose=1, los=mw[11], gravity purpose=2, los=mw[11], gravity purpose=3, los=mw[11], gravity purpose=4, los=mw[11], gravity purpose=5, los=mw[11],

ffactors=ff ffactors=ff, losrange=11-48 ffactors=ff ffactors=ff ffactors=ff, Kfactors=MI.1.K5

PARAMETERS
Sets general parameters. MATOEVERY MAXITERS MAXRMSE ZONES In addition to the standard Matrix-program parameters, the parameters described here may also be specified.
PARAMETERS keyword
Keyword MATOEVERY |K?| Description Switch that can be used to force the program to write output matrices for every iteration, instead of waiting until the last iteration. This causes the program to run somewhat longer for each iteration, but may preclude the program from having to run another iteration to obtain the output matrices once convergence is reached. Since the program does not know that a particular iteration will be the final one until after it completes the iteration, it normally does not write matrices for the iteration. This saves a considerable amount of computer time for larger systems. But, it does force another processing iteration to write the matrices once it has determined that this is the last iteration. If it is anticipated that there will be many iterations to reach convergence, it is probably better to set this switch false. If it is anticipated that the process will involve only a few iterations, it is probably better to set this switch true.

554 Cube Voyager Reference Guide

Distribution Program Control statements

10

PARAMETERS keyword (continued)


Keyword MAXITERS |KI| Description Specifies the maximum number of iterations to perform. If the MAXRMSE criterion is met, the number of iterations actually performed could be less than this value. The default is 3, and the max is 99. If the model converges in fewer iterations, one more iteration will be run (with the same values as the converging iteration) so that the MATO matrices will be written. Specifies the cutoff criteria. If the highest RMSE (for any purpose) exceeds this value, automatic cutoff is not triggered. Conversely, if all the purpose RMSEs are less than this value, automatic cutoff is triggered. The default is 10, and the minimum is 0.0001. Specifies the highest zone number to process. If the number of zones can not be ascertained from the project file or from any binary input matrices, ZONES must be provided, or the value will default to 100. If present, this value controls the application. Normally, there will be an input matrix file, so this keyword should not be required.

MAXRMSE

|KR|

ZONES

|KI|

REPORT
Specifies Matrix program reports.

Cube Voyager Reference Guide 555

10

Distribution Program Control statements

ACOMP (ITERATIONS)
REPORT keywords
Keyword ACOMP |KIP| Description Requests that the comparison of Estimated vs. Desired attractions be reported for the specified purposes. The report is in a format that is similar the MARGINS report. The values are reported as nearest integers (without decimal places). Only the purposes specified by the keyword are reported. If the values for ACOMP are followed by ITERATIONS, then those ACOMP purposes will be printed only during the iterations specified. If there are no ITERATIONS specified, the report will be printed for every iteration (could be quite voluminous). In ACOMP reports, zero values are printed with and a printed value of 0 means there is a fractional value present for the cell (the fractions are not printed in the report). Specifies the iterations for which the prior ACOMP purposes reports are to be printed. If no ITERATIONS follow ACOMP values, the reports will be printed for all iterations. If at least one value is equal to, or exceeds, the PARAMETERS MAXITERS, the reports will be printed for the last iteration (no matter how it is determined: parameter or convergence).

ITERATIONS

|IP|

Example
REPORT ACOMP=1-3,5 ITERATIONS=5,10,99 ; specified purposes and iterations REPORT ACOMP=6 ; for all iterations

SETPA
Establishes base productions and attractions. P A INCLUDE EXCLUDE The SETPA statement is required; if it is not included, the program will fatally terminate. The statement defines to the program how the desired productions and attractions are to be obtained, and how many purposes are to be processed. There should be a P[]= and A[]= expression for every

556 Cube Voyager Reference Guide

Distribution Program Control statements

10

purpose beginning with 1 and continuing, monotonically, until all purposes are defined. The highest index encountered establishes the number of purposes. If there are any holes in the purpose scheme, the program will issue a warning statement. The total of the As should match the total of the Ps for each purpose. If the totals differ by more than five percent of the P total, a message is issued. If the totals differ by any amount, the As are scaled so that the A total will match the P total. The Ps and As are computed from the expressions that are supplied. In most cases, the expression will simply point to a ZDATI file variable. Complex expressions are allowed, but the use of any variables in the expression could cause unpredictable results. In a purpose where the Ps and As are the same for each zone, (NonHomeBased is a typical example), it is acceptable to set the Ps, and then set the As equal to the Ps. The SETPA expressions are computed in the order in which they appear in the control stream, and they are computed only one time -- prior to the first iteration. For each array, the expression is solved in a loop of J=1-Zones, and the results are stored in the A[n][J] or P[n][J] cells. A and P may not have a zone index in the SETPA statement. If the same purpose is referenced more than one time (this is acceptable), the subsequent values will replace the prior values. Duplication of purposes might be helpful if values for different zones for a purpose are to be obtained from different sources, or if different INCLUDE/EXCLUDE filters are to be used (separate SETPA statements must be used for different filters).
SETPA keywords
Keyword A EXCLUDE |NV| |IP| Description Expression that is solved to set the attractions for the indexed purpose. Processed the same as EXCLUDE on COMP statements. If it is used, the loop will not be processed for any zones in the list. EXCLUDE filtering follows any INCLUDE filtering. Processed the same as INCLUDE on COMP statements. If it is used, the loop will not be processed for any zones not in the list. INCLUDE filtering precedes any EXCLUDE zones.

INCLUDE

|IP|

Cube Voyager Reference Guide 557

10

Distribution Program Control statements

SETPA keywords (continued)


Keyword P |NV| Description Expression that is solved to set the productions for the indexed purpose.

Example
SETPA INCLUDE=1-500, ; internal zone data only P[1]=zi.1.p1, A[1]=zi.1.a1, P[2]=zi.1.p2, A[2]=zi.1.a2, P[3]=zi.1.nhb, A[3]=P[3], P[4]=zi.2.cnt, A[4]=10 ; equal attraction for all zones SETPA EXCLUDE=1-500, ; get only external data P[1]=zi.1.p1, A[1]=zi.2.cnt, ; merges with prior SETPA P[5]=sqrt(A[3]), A[5]=A[1]+A[2]+A[3] ; weird, but will work

558 Cube Voyager Reference Guide

Distribution Program Examples

10

Examples
This section contains examples of the Distribution program: Distribution example 1 Distribution example 2 Distribution example 3

Distribution example 1
RUN PGM=DISTRIBUTION REPORT ZDAT=Y ZDATI[1] = TSTPA1,Z=#1,P1=2,P2=3,P3=4,P4=5,P5=6,A1=7,A2=8,A3=9,A4=10,A5=11 MATI = IMPEDE.MAT MATO = GMTRIPS, MO=1-5, NAME=HBW, HBO, NHB, IX, XI LOOKUP FAIL=12000,1,0, LIST=N, FILE=TSTFF1, NAME=FF, LOOKUP[1]=1, RESULT=2, LOOKUP[2]=1, RESULT=3, LOOKUP[