RTFM (Read The Fine Manual)

Read the help file for Matrix CALL statement.  The struct statement is pretty important, and the sprintf lines will be used throughout.

Memory Pointers

One of the most important things to understand is that because there are so many variables that can be passed between Cube and the C++ DLL, the memory pointers are passed instead.  Also, one of those “pull your hair out” things relates to this – if you attempt to access a memory pointer that hasn’t been initialized, you get a crash that gives no error.

Because of this, the variables in the struct statement have a *, which notes that it is a memory pointer.

To keep from getting the crash-with-no-error, the following statement works well to test and allows a default to be used if the variable ‘MarketSegments’ is not set in Cube.

int MarketSegments=4;

if(Stack->pfFindVar("MarketSegments")!=0)
MarketSegments=(int)*Stack->pfFindVar("MarketSegments");

Matrix In, Matrix Out

While the Help file says that you can get to defined working matrixes using

static double **MW;
MW=(*Stack->pfFindVar)("MW",1);

I can’t get it to work using C++ (I have gotten it to work in C).  Instead, use the following:

static double **MW=NULL;
MW=Stack->MW;

This will enable you to use MW[m][j] (where m is the MW number, and j is the j-zone).

You can also set the MW variables, but it does NOTHING if you don’t set the MW to something in Cube Voyager.  Ergo, if you set

MW[101][j]=10;

Your output will be 0 unless you do the following in Cube Voyager

MW[101]=0
CALL...

Array Variables

One of the tricks I use to get array variables out of Cube is this

float ArrayVariable[7]={0,0,0,0,0,0,0};  //Note: I'm using 1-6.  Setting this to 7 means 0-6.  Setting it to 6 would mean 0-5
if(Stack->pfFindVar("ArrayVariable")>0){
double* tmpAV=NULL;
tmpAV=Stack->pfFindVar("ArrayVariable",1,2,3,4,5,6);
for(int x=1;x<=6;x++)
ArrayVariable[x]=tmpAV[x];
}

This code above checks that the ArrayVariable, fills them into a temporary variable, and then sets the actual variable.

Compilation Linker Settings

When compiling, you need to set the EXPORT flag so the name is predictable and correct.  To do this, go to your project’s property pages – Configuration Properties – Linker – Command Line.  You need to add “/EXPORT:FunctionName” under Additional Options.  See the screenshot below

.

Other Weird Stuff

Any error in C++ that does not cause a compilation error results in one of those useless “this program has an error and will be closed” and crashes Task Monitor.  That being said, write messages to the output file frequently (if at least during debugging).  This can assist with finding typos (like, say, %10.65f in an sprintf statement, which means 65 decimal places in a 10-width line).

In Matrix when using DBI, PAR ZONES=1 will effectively shut off Cluster. Therefore, the following works really well.


DISTRIBUTEINTRASTEP ProcessID=Cluster ProcessList={CORES}

LOOP _r=start,end
x=DBIReadRecord(1,_r)
ENDLOOP


This script sets each core to process an equal portion of the database with any remainder (e.g if you cluster 4 records over 3 cores) to the last core.

In Cube Voyager, I’ve been finding more ways to cut runtimes down as much as possible, and below is the list with some of the rationale.

Keep JLoops at a Minimum

The Matrix program runs in an implied ILOOP.  This being the case, anything in the script runs many times (as many as the zones you have).  Using a JLOOP in a 2,000 zone model means that there are  4,000,000 calculations to be done for each COMP statement.  What happens if you have 3 COMP statements?  You go from 4,000,000 to 12,000,000 calculations.  This is even worse if the calculations include a lookup function, which are generally slow.

Keep Files Small – Only Write What You Have To

This is a no-brainer.  The more that Cube (or anything, for that matter) has to write to disk, the longer the runtime.

Replace RECI with DBI wherever possible

DBI can be clustered (look for a post on that in the coming weeks).  While I’m not sure if there is any difference on one core, being able to use Cluster is the trump card.

Use Cluster Dynamically and Wherever Possible

Standardize the Cluster ID in your code, but set the process list to a catalog key as with below:

DISTRIBUTEINTRASTEP CLUSTERID=Cluster PROCESSLIST=2-{CORES}

Using Cluster to your advantage is critical to having a fast model.

Binomial Logit Mode Choice: A process that compares the utility of two travel mode choices and determines the probability of using each mode.

BPR Equation: An equation used to determine the speed on a network link based on the ratio of the volume to the capacity.

Centroid: A point that is linked to a TAZ that loads traffic onto the network

Centroid Connector: The link that connects a centroid to the rest of the network.

Equilibrium Assignment: An assignment method that iteratively assigns and reassigns traffic based on revised travel times on each link.

Friction Factors: Factors that are used in distribution to refine the distance measure between zones.

The Four Step Process: A process of modeling that began in the 1950s that performs four major steps: trip generation, trip distribution, mode choice, and assignment.

Fratar Model: An iterative gravity model used to determine trip interchanges where total productions and attractions are known, but not necessarily balanced.

Gravity Model Distribution: A process to determine the likelihood of traveling from one zone to another based on the attractiveness of the destination compared to the distance from the origin to the destination.

Link: A piece of roadway in the network

Mode Choice: A process that determines the economic utility of all available forms of travel from one zone to another and splits trips (from the trip distribution step) into a variety of modes (depending on those that exist).

Multinomial Logit Mode Choice: A process that compares the utility of multiple travel mode choices where each is a separate and distinct choice.

Nested Logit Mode Choice: A process that compares the utility of multiple travel mode choices as a string of choices and sub-choices.  An example would be a structure illustrated below (click on the image for a larger view).

Network: A collection of links, nodes, centroids, etc. that simulate the major travel facilities in the model area.

Traffic Analysis Zone (AKA: zone, TAZ): A geographic division, much like a census block, that defines an area of homes and businesses used in the travel demand model.

Trip Generation: A process of counting the homes, employees (usually by type), schools, and other activities that generate traffic to and from them.  Trips are generated as attractions and productions.

Trip Distribution: A process of determine where generated trip productions are linked to generated trip attractions.  This determines the number of people that will go from one zone to another.

1. Trip Generation
2. Trip Distribution
3. Mode Choice
4. Trip Assignment

The first step in the process, Trip Generation, uses socioeconomic data to determine the number of trips produced by a traffic analysis zone (or census tract, census blockgroup, or other geographic division).  The socioeconomic data normally includes population, auto ownership, and employment information at the very least.

The second step is trip distribution.  Once the number of trips are known, trip distribution determines where the trips will go.  This normally uses a gravity model, which will be discussed in a future post.  This step takes in several factors, including the number of trip productions, the number of trip attractions, and an impedance value.  The impedance value is the resistance to travel, which could include distance, time, tolls, or a combination of those.  Each model is different in this regard.

The third step is mode choice.  This step determines what vehicle trips will utilize when going from one zone to another.  This step can be particularly complex or extremely simple, depending on the area included in the model.  Some models have very simple mode choice steps because transit isn’t available, or it doesn’t have a significant effect.  Other models can be extremely complex, such as a model for Chicago or New York, which would include autos, bus transit, subway transit, urban rail (such as Chicago’s Metra Rail), and intercity rail transit (such as the Amtrak service that connects New York to Boston, Baltimore, and Washington, DC).

The final step is trip assignment.  This step takes all of the trips from mode choice (which it now knows if they are trips that will drive alone, share a ride, use the bus, or use another mode of transportation) and assigns them to a transportation network.  Prior to the mid-1980s, these networks were largely text based, but with the advent of Geographic Information Systems and personal computers in the mid-1980s and moving forward, these networks became graphical.

These four steps represent the basic building blocks of most transportation models.  These steps are a basic way to ask:

• How many people are going to travel?
• Where are they going to go?
• What transportation mode are they going to use to get there?
• What route will they take to get there?