When calculating matrices, you often want to perform similar calculations for multiple matrices. Batch processing with the ForEach function allows you to do so in a single step. The ForEach syntax is very powerful and provides solutions for many use cases, e.g.:
- Generate a demand matrix for all demand layers per mode
- Initialize all matrices of the model
- Take the mean of all skim matrices from successive iterations within a demand calculation loop
- Add up the respective demand matrices of all demand strata for each mode
- Calculate the utility definition based on skims and under consideration of specific co-efficients for all demand strata
Using the ForEach function
Using the ForEach keyword, you can calculate multiple matrices. The ForEach loop within a procedure takes the following form:
ForEach (network object type Var <, condition >)
Matrix (matrix reference via properties) := expression
whereby
| Element | Description |
|---|---|
|
Network object type |
Any Visum network object type, such as matrices, demand strata, modes, demand segments |
|
Var |
User-defined loop variable, which must begin with a letter. This loop variable represents a different network object of the type in each loop via which you iterate. |
|
Condition |
(optional) limitation of the iteration to an amount of existing network objects |
|
Matrix/Matrices (matrix reference via properties) |
represents the target matrix/target matrices |
|
Formula expression |
corresponds to a matrix formula |
Loops with ForEach can also be used in nested form. In this case, you need to use a different loop variable for each network object type. When creating matrices interactively, you omit the assignment symbol := and the expression listed on the right of the assignment symbol.
Loop variables allow you to easily access attributes of the network object that are represented by a variable in the current loop. You may use variables on the left-hand side and the right-hand side of the allocation symbol.
The loop variable always represents a network object that already exists. For batch processing of matrices, you can also use the CONTEXT keyword available on the right-hand side of the allocation symbol. It may be used to e.g. access attributes of the target matrix.
Example 1
You want to reset all matrices of the model in a single step.
ForEach(MATRIX M)
M := 0
Iteration is performed on all matrices and their values are set to 0. If iteration is performed on the target matrix, you can use the M loop variable directly.
Example 2
You want to create a demand matrix per demand stratum and mode during the procedure sequence.
ForEach(DEMANDSTRATUM N)
ForEach(MODE K)
Matrix([DEMANDMODELCODE]="M01" & [NSTRATUMCODE]=N[CODE] & [MODECODE]=K[CODE]) := 0
This example shows a matrix reference defined for target matrices, based on attributes of the network objects on which iteration is performed. Here the loop variable N and K are used again.
Example 3
You want to average the skim matrices by performing two successive iterations. To do so, first duplicate the skim matrices. The matrix reference for the newly generated skim matrices must include at least one other attribute in order to avoid ambiguity with other skim matrices. To duplicate the matrices, use the following syntax:
ForEach(MATRIX M, M[MATRIXTYP]=4)
Matrix([NSEGCODE] = M[NSEGCODE] & [MATRIXTYP] = 4 & [CODE] = M[CODE] & [NAME] = M[NAME] & [SMOOTH] = "avg")
:= M
Iteration is performed for all matrices of the matrix type "Skim". In the target matrices, the values of the source matrices remain unchanged. Instead, the expression used on the right-hand side is the loop variable M. In addition, a user-defined attribute is assigned for the respective target matrix, which distinguishes from the respective source matrix.
To average matrices within the demand loop, use the following syntax:
ForEach(MATRIX M, M[MATRIXTYP]=4 & M[SMOOTH] = "avg" )
M:= 0.7 * Matrix([NSEGCODE] = M[NSEGCODE] & [MATRIXTYP] = 4 &
[CODE] = M[CODE] & [SMOOTH] = "")
+ 0.3 * M
The target matrices are the previously duplicated matrices. Iteration is limited to these matrices. The newly calculated skim matrices are assigned with the help of a matrix reference. The user-defined attribute SMOOTH is empty. The averaged skim matrix is addressed via loop variable M and multiplied by a factor of 0.3.
