By John Abraham, Geraldine Fuenmayor, Graham Hill and Shena Kaul Last updated November 25, 2019
- PECAS theoretical foundations
- System of modules
- AA module and its elements of choices
- PECAS's vision of the spatial economic system
- Data requirement for AA
- PECAS calibration
- Policy testing with PECAS, outputs and interpretation
- Running AA
- Troubleshooting AA
- Preprocessing Steps
- Inputs
- References
PECAS, which stands for Production, Exchange, Consumption Allocation System, is a generalized approach for simulating spatial economic systems. It is designed to provide land use simulation of the land use-transport interactive models [^John Douglas Hunt and Abraham 2005], which are suitable for policy tests in practical applications.
PECAS was developed in Calgary by HBA Specto in Calgary, primarily by John Douglas Hunt and John E. Abraham. They started working on formal applications using the whole system in 2005. The name of the framework comes from the Latin word pecas, which has the same root as 'pecadillo' meaning small sin or small error [^John Douglas Hunt 2012], making reference to the desirable small error in the land use forecasting.
PECAS like other land use models, uses discrete choice theory, specifically the nested logit formulation to simulate the choice behavior of groups of actors (e.g. firms, households, industries called "activities" in PECAS) selecting from a set of discrete alternatives (e.g. zones, commodities, lifestyles).
Discrete choice models have their theoretical roots in random utility theory developed by Domenich, Mc Fadden and others [^De la Barra 1989]. Actors are assumed to make choices in the pursuit of maximizing their utility, with a representative component that can be identified and a random component that cannot, and is associated with individual idiosyncrasies, preferences and perceptions.
PECAS uses a modified form of the logit equation called the "Additive Logit Model" and the random term of the utility measure assumes to follow Gumbel distribution [^J.E. Abraham and Hunt 2007]. As an example, a general form of the probability of an activity choosing location in the model is [^J. D. Hunt and Abraham 2009]:
With the logit model, when the probability of an activity to locate in a zone has the form shown above, then the change in consumer surplus between 2 scenarios as a measure of benefit has the form:
PECAS is a generalization of the spatial input-output modelling approach in frameworks developed previously such as MEPLAN and TRANUS. In addition, it also includes elements from DELTA. Under certain simplifying assumptions, PECAS reduces to these other modelling systems [^John Douglas Hunt and Abraham 2005]. It offers an integrated representation of spatially distinct markets for the full range of exchanges, with the transport system and space development represented in more detail with specific treatments. In PECAS choices by industries and households are represented using multinomial logit models.
PECAS is an open source software distributed under the Apache 2 license (The Apache Software Fundation. 2004). It works with 4 modules to represent the complete spatial economic system. Two of them are considered PECAS modules, called Activity Allocation (AA) and Space Development (SD). These modules interact with each other and are linked together with two external modules, called Transportation (TR) and Economics and Demographics (ED). A description of these modules is provided below [^J. D. Hunt and Abraham 2009]:
Activity Allocation Module (AA Module): This module represents how activities (households, industries or business and government) locate within the space provided by developers and how these activities interact with each other at a given point in time.
The AA module works through time in a series of discrete time steps from one point in time to the next (Figure 1).
Figure 1 Modules and flows in the Oregon StateWide Integrated Model (SWIM2)
Source: Parsons Brickerhoff, HBA Specto Incorporated, EcoNorthwest; Oregon Statewide Integrated Model. Model Description, 2013
Ideally, the TR module is used to calculate the congested travel times and associated transport disutilities is run for each year, after the AA module has been run for that year. Based on the study case, if the overall model run times are too long and travel conditions are relatively stable, the TR module can be run less often to save computation time.
The Activity Allocation (AA) module considers the behavior of the activities to locate in the spatial economic system. Activities are represented by industries (business or firms), households, and government. Government could be optional depending on the interest of the application.
The AA module is an aggregate allocation system using a modified form of the nested logit representation of three types of choices made by activities: location choice; technology choice, which imply ways (rates) of consumption and production of commodities (goods, services, labor, and floorspace); and, exchange location choice, which involve to choose an exchange zone for buying or selling the commodities given location and quantities produced and consumed (Figure 2).
The PECAS Space Development (SD) module is not used in the TLUMIP project. It applies a parcel based microsimulation (deterministically, if desired) to represent development of land into new floorspace. TLUMIP's ALD module takes the place of PECAS's SD.
Figure 2 Three level nesting structure used in the Activity Allocation module
Source: PECAS Theoretical Structure and System Module Implementation, 2012 by J.D. Hunt
AA uses an aggregate approach (data by zone and by category) and equilibrium structure with separate flows of exchanges divided in supply and demand. These flows go from production to consumption based on variable technical coefficients and market clearing with exchange prices.
The modelled area is divided into a set of zones called "Land Use Zones" (LUZs). Activities locate in these zones and interact among them. LUZs connect through a transport network. This network establishes the travel times and costs (interchange disutilities) used for these zone to zone interactions.
The movement of these flows of commodities from where they are produced to where they are consumed is the economic basis for travel and transport in the modelling system. It is the travel conditions (disutilities) for the movement of these commodities that results in the influence of the transportation system on the interactions among the activities, making the locations more or less attractive for households and business [^J. D. Hunt and Abraham 2009]. Prices of exchange determined for space inform the calculation of changes in space and in this manner simulate developer actions.
For the three choices in the AA module the utilities of the joint choice needs to be calculated. The general form of this utility is presented in equation 36 of the Theoretical Formulation document [^J. D. Hunt and Abraham 2009], as follows:
All of the equations associated with the choices in the PECAS framework are presented in the PECAS Theoretical Formulation document and also are presented and discussed in at least two papers: "Random Utility Location, Production, and Exchange Choice; Additive Logit Model and Spatial Choice Microsimulations"[^J.E. Abraham and Hunt 2007], and a book chapter called "Design and Implementation of PECAS: A generalized system for allocating economic production, exchange and consumption quantities"[^John Douglas Hunt and Abraham 2005].
The random components in the above formula are replaced by dispersion parameters (DP) in the operational equations in the PECAS software. Assumptions are made so that different combinations of the above random components (from the joint utility) have Gumbel distributions, which lead to closed form probability functions [^J.E. Abraham and Hunt 2007], which means that they can be calculated with a finite number of operations. Groups of alternatives are given a "size term" incorporated in the utility function to represent that larger groups are more likely to be chosen because are more likely a priori and they enclose more variety or variation. These size terms have the following general form:
Since the λ is in the denominator the size term becomes a more important part of the utility of the group of alternatives when λ is lower. This is because the standard deviation σ of the random component's Gumbel distribution is equal to σ = π/√(6λ), and random terms have more variety when λ become smaller, making it more likely that an individual option in a large zone has the highest utility for a decision maker.
Size terms are calculated by AA in each year, based on a special algorithm.
In addition to these three elements of choices shown in Figure 2 there are two other actions taking place in the AA module, imports and exports and the short term floorspace supply function. These five elements choices are summarized below:
Flows travel from the production location to the consumption location through exchange location. This choice is about where to travel (exchange zones) in order to interact with other activities, buying inputs or selling outputs (called either "puts" or "commodities") that have been produced or consumed in other zones. Utilities are influenced by price, size, and transport cost associated with each commodity. Examples of this choice are: workers choosing jobs (industry locations to sell their skills); or household choosing where to go shopping (buying allocation to where the retail is consumed and located) (Figure 3).
Figure 3 Buying and Selling Allocation of commodity flows
Source: PECAS — for Spatial Economic Modelling. Theoretical Formulation, 2009 by HBA Specto Incorporated
There is a production and consumption function defined for each activity in PECAS, where the variables are the rates (technical coefficients) at which commodities (goods, services, labor, capital and floorspace) are produced as outputs and/or consumed as inputs by the activities in different locations. The definition of technology options represent different ways of producing or consuming for each activity, and result in elasticities in production and consumption in the economic system. These technology options and associated rates are calculated based on data from different sources, but mainly from a social-accounting matrix, the floor space inventory and Census data.
Initially a technology option representing the average rates or the expected value of production and consumption is calculated, and then variations of this option are defined using smaller and larger rates. These options are called the "less" options when using a rate less than the expected value; or a "more" option when using a rate more than the expected value. However for households, cluster analysis on census data was used to identify lifestyle options involving different occupations, labor force participation, dwelling type (structure) and dwelling size.
This technology choice is about splitting activities among their available technology options by location. For industries, this choice it is about choosing which commodities make (produce) and use (consume) and at which rate. For households, it is about choosing a lifestyle depending on housing and labor market conditions. Utilities for the range of technology options associated with each activity are influenced by the utility of buying and selling commodities being produced and consumed, and the proportion of space available for a particular activity. Examples of this choice are: retail industry choosing how much retail space consumes; and, household with 1 to 2 people with a low income, working in sales, living in a larger-than-average multifamily dwelling.
The location of the activities is in the top level of the structure of the nested logit model. As a result, this choice is strongly influenced by the utility measures considered in the other two levels, exchange location and technology choice, plus the zonal constant. Examples of this choice are a 1 person high income household choosing to live in a particular neighbourhood; or business in an industry (e.g. manufacturing) choosing a particular LUZ.
Imports (supply) and exports (demand) of commodities are normally included in PECAS to tie and represent the choice of interaction of the spatial economic system with the rest of the country and with the world. These choices are represented defining external zones [^J.E. Abraham and Hunt 2007].
TODO: Write separate imports and exports appendix.
Floorspace supply functions are defined for each space type based on observed relationships between rent and floorspace supply. These curves simulate the landlord's behavior regarding the decision to accept or not a specific rent based on the space supply function. They enable the model to operate in case of extreme scenarios [^John Douglas Hunt and Abraham 2005]. An example is shown in Figure 4.
Figure 4 Landlord behavior function for a space type
PECAS has a particular vision about the spatial economic system. Households and industries are activities that interact through the puts (a.k.a. commodities) of the system categorized as: goods, services, capital, labor and floorspace. They are all connected by the transport system. A summary of their interactions is presented below:
In PECAS households are the social unit and are usually categorized by size and income, but other categorizations may be more appropriate depending on the case. They are the labor providers, and they consume goods, services and space. Businesses provide and consume goods, and services, and they are the consumers of labor and space.
All of the current and future aggregate/average values for demographic and socioeconomic data are exogenous inputs. The allocation of money by industry to zones is calculated based on the industry's inputs and outputs, taking in account employment by place of work, space use rates, and any other data.
The initial set of relationships in the AA module is based on a social-accounting matrix of the region, and so includes all of the ways activities interact through the production and consumption of goods and services [^HBA Specto Incorporated 2013a]. An example of how schools are treated in PECAS may be helpful to understand the treatment of other services. Schools are represented as the education industry consuming school buildings (floorspace). Money flowing in both directions are represented, the funding of schools (primarily by government, from input-output economic data) and the consumption of the education services by the households. Post-secondary education is treated separately from primary education. School location choice is modelled simultaneously with the service being consumed by the households (lifestyle choice and exchange location choice). These choices are modelled simultaneously because of the way choices are nested in the AA structure and due to the short-term equilibrium prices annually simulated. This same vision applies to other commodities included in any PECAS model.
Labor is classified by occupation, produced by the households and consumed by the industries. Some industries are split in categories to express the difference between "production" space and "management" or office space. Jobs are normally represented in terms of dollar amount (wages).
Commuting costs are calculated, and wages adjust spatially to match supply and demand in each location, for each occupation in each year.
The term floorspace in PECAS refers to the metrics related to the space. This includes measures of the space built or buildings in the city or region where the economic activities take place. For resource industries, space can represent quantities of land under cultivation, or quantities of fixed capital machinery used to extract the resource.
Floorspace quantities by space type are handled at the zonal level for AA and at the parcel level for SD. There is no specific limit of floorspace categories in PECAS, apart from practicality. Several categories of space are normally included during the design of the application. They correspond to the space consumed by the industries, – non-residential space –and by the households, residential space.
A consistent estimation of the floorspace by space type (built form) could be estimated using a floorspace synthesizer. This is an optional intermediate step to ensure that estimations are consistent with the household and employment data at a zonal level for AA and at a parcel level for SD. This type of approach has been applied in Baltimore [^John Edward Abraham and Fuenmayor 2010], San Diego [^HBA Specto Incorporated 2012], and Atlanta [^Fuenmayor and Abraham 2013] [^Fuenmayor et al. 2014].
PECAS assumes that the transportation system is modelled exogenously, so transport costs among zones (skims) come from the travel model. The connectivity among the LUZ is based on the representation provided by the congested network of the transport model (time, cost, etc.), which is used to establish transport disutilities used in its consideration of the interactions (buying or selling commodities) between zones. Transport is one of the disutilities that arises from the choice of exchange location (bottom level of Figure 2).
Trips are linked to economic flows through transport cost functions that calculate the money cost (or willingness-to-pay disutility) per unit of commodity (e.g. purchase of a dollar of retail goods, consumption of education services). These transport cost functions use the trip-based disutilities (mode choice logsums, distances, travel times etc.) and convert them into a commodity-based cost or willingness to pay. Origins and destinations (exchange locations) of all these interactions are solved simultaneously in the annual equilibrium that also establishes rents, technology (for business), lifestyle (for households) and location.
The sum of the space demand in a zone is compared with the space supply and the rent is adjusted to match demand and given the supply per year, and the activities and their rates of space use in their production functions are adjusted in response to these updated price signals until all the markets clear (supply matches demand for each space type) and the AA module is said to have 'converged'. The rents are determined in the same equilibrium with the prices and flows of goods, services and labor (wages), and result in a bid-rent allocation of space to the highest bidder [^HBA Specto Incorporated 2013a].
PECAS, as any other land use model, needs data of many different nature. Almost any data can be relevant to a PECAS model, because it is a general purpose framework representing the entire spatial economic system. However, the data that has commonly been used to develop an AA module using PECAS can be classified as follows (Figure 5):
Figure 5 Data componenets to run the AA module of PECAS
-
The Design Diagram is a drawing representation of the model design. It is a sketch of the model categories and the interactions defined for a particular application
-
Input-output model (region, or national level), social-accounting matrix, and any other data that shows household expenditure patterns. These pieces are critical to develop an aggregate economic flow table (AEFT), wherein total production, consumption, rates of production and consumption, imports and export, are calculated and reported
-
Floorspace by parcel (or building) also called the Built Form, by space by type and by zone
-
Rents by space type and vacancy rates are needed to develop landlord's behavior functions
-
Data of population and Employment by place of residence (POR) are required to develop a household (HH) categorization, usually based on size and income, but a socioeconomic categorization is sometimes more appropriate. The employment is typically categorized by industry and occupation to include elasticities in labor
-
Employment by place of work (POW) and space use rates could be useful to allocate activity amounts per industry by zone
-
Travel survey to know about the trip length (distance or time) by commodity and about the trips by purpose. These are required during the trip length calibration but also during the development and calculation of the Transport Cost Coefficients
-
Transport model to interact with the PECAS model, since Transport Skims are required. If it is plan to run the model through time integration will be required
The PECAS calibration process involves three stages regarding the nature of the parameter values, and includes three types of calibrations: trip length, option weight and floorspace. These procedures are performed in a particular sequence of steps. There are several separated documents describing this important step in the development of a PECAS model [^Geraldine Fuenmayor 2016] [^Abraham, J.E., T. Weider, and J. D. HUNT 2005] [^Abraham, J. E. 2014].
In general, PECAS simulates a landscape of prices by commodity, flow matrices by commodity and the locations of the activities (business and households) in the spatial economic system.
PECAS is suitable for policy analysis and typically these policies involve changes in: floorspace, rents, transit fares, property taxes, gas prices, tolls, parking prices, among others. A paper called "Policy Analysis using the PECAS framework" by [^J. Abraham, Hunt, and Fuenmayor 2013] illustrates the changes arising in 4 policy testing scenarios: new roads, public housing, carbon tax, and government stimulus. Measures of benefits are estimated in PECAS by activities, by commodity (or group of commodities) and by zone.
Another document illustrating policy sensitivity test using PECAS is the doctoral dissertation of G. Fuenmayor, showing the analysis of the impact of a public housing policy, and the impacts of increasing transit fare, both in Caracas [^Geraldine Fuenmayor 2016].
Maps are the most common way to show changes in rents by space type by zone; changes in space consumption by zone; and, changes in household allocation by type and by zone.
There are 3 components to the utility associated with buying or selling a given commodity in a given zone: transport, prices and size. When the commodity is labor, the term wages is used instead of prices. These three components drive decisions in the spatial economic system. They are the reasons why the households and industries behave in certain way in specific contexts. This is why the root of the policy investigation is centered on how the changes in these utility components are responsible for the changes in consumer surplus for a given amount of consumption of a particular commodity. These changes impact both the consumers and the producers of the commodity, whether they are households or industries.
Activity categories are sensitive to the changes in the commodity utilities, and each utility component (transportation, price, and size) could have influence on the other components. For example, changes in transportation costs could affect the accessibility in different locations, which would bring about changes in prices and sizes across locations. The total accessibilities are calculated for a commodity in PECAS in the following way:
The components of each zUtility for buying and selling in each zone are calculated as:
The transport and price components for each zone are represented as the weighted average impact of the transport and the weighted average impact of price. To calculate them individually, each component should be multiplied by the calculated weighted average associated with the specific case, which depends on the number of exchange zones involved in the estimation and the probability of choosing one of them. These are related to money value, so they are tangible and therefore are comparatively easy to interpret. However, the interpretation of the size component of this utility is more challenging. It represents the effects of both the greater likelihood of selecting from a larger aggregation and the increased probability of greater satisfaction arising from the greater variety inherent in a larger aggregation.
The size component is calculated and reported in PECAS in two parts: quantity and variation.
The quantity part is a proxy utility term that takes into account the higher probability of choosing a larger zone all other things being equal. The value of the quantity part for given commodity in the zone, k, where it is consumed (after being purchased and transported to the zone) or produced (before being transported from the zone and sold) is calculated as:
The Size~z indicator is intended to represent the relative magnitude of a zone and how this impacts the probability of selecting the zone, all other things being equal. For example, if a new school building is placed in a zone, the amount of education services potentially available is bigger, meaning bigger opportunities and greater probabilities for the education being consumed by households. This has nothing to do with the quality of the education – it is only accounting for the effect of the relative quantity. The precise attribute or variable used to represent the relative magnitude of zones will vary depending on context and its specification is part of the model design. In the Caracas model (and typically with PECAS) the variable used for each commodity is from an allocation of the commodity arising with uniform prices, where producing and consuming activities are allocated in proportion to relevant floorspace quantities. E.g., households are allocated evenly based on the amount of residential space, assuming they would consume services depending on the transport disutilities associated with what they consume and where they travel to consume it.
The variation part is a portion of utility representing the value arising from having more alternatives (zones) available, and therefore it being more likely that a more suitable selection can be made. The value of the variation part for given commodity in a zone, k, is calculated by subtracting the value of the quantity part from the value of the size component. Continuing the example regarding the school, if a new school facility is allocated in a zone where there were no schools before, the variation component for buying education would increase for those households who have a non-zero probability of purchasing education from the new facility.
More generally, if more zones become an option for a commodity exchange (more opportunities spread across more zones), then variation as a utility component goes up. The variation part is calculated as the size component of the utility by zone minus the quantity part in this way:
The separation of the size component or the "size effect" into two components (quantity and variation) is a function of how the zone boundaries are defined, and sometimes this separation is useful for analysis. Under the PECAS vision there are activities producing and consuming commodities exchanged in specific zones. For these commodities the quantities and the variation parts are added to calculate the size component, but the variation part becomes zero if only one zone is involved in the exchange. This is the case for the industries selling goods and services and buying labor. In both cases, the size effect is only associated to the quantity part, and not with the variation. For households, this variation part measures the loss or gains in heterogeneity (optimality, diversity) when they consume goods, services and when they face a variety of job options in different zones.
In general, it is expected that when the transport cost increases, for some zones the size component decreased for the consumer of the goods and services. All of the exchanges (zones and commodities) become less accessible for the consumers, meaning that the buyers obtain less variety in the product or service. For labor, it is expected that an increase in transport can decrease the average trip length going to work. Losses of benefits arise clearly due to the increase in transport disutility, but this also affects the size component, since households loss variety in job options making their size component decrease (due to the loss in variation).
In the activity allocation module, the space is being consumed by the activities, but is not produced by any agent in this particular module. That means that the model's outputs only show the consumer side of the story regarding the treatment of the space in the model.
When the model indicates losses of benefits from the consumption of floorspace, it is because the rents are increasing. This is because the activity allocation (AA) module does not consider the revenue that arises from owning a property. In a context where the proportion of ownership is high, this is not necessarily negative, since owners are paying rent to themselves. Based on this idea, benefits are considered to be positive for property owners when rents go up for the residential space, even if the plots show the bars going in the opposite direction.
The interpretation of rents going up for the non-residential space is different since for business rents are part of the operative cost, resulting in negative benefits.
To run the AA module, the user needs to perform two steps:
- Set up AA
- Run AA
The AA module is set up through the tSteps.csv (under "/[scenario_name]/model/config") file by turning on the "AA" property in the desired year.
To enable the property, edit the tsteps.csv file to contain a ‘1' in the AA column for each year where the user would like to run AA. Usually AA is run every year between the base year and the scenario end year. For example, the following setup runs AA in the years 19 to 25. The NED, ALD, and SPG1 modules for a given year need to be run before running AA in that year.
Table 1 Example tsteps.csv file
To run the AA module, first run the "/[scenario name]/build_run.bat" script. The script creates all of the necessary output folders and configuration files, as well as the batch files "/[scenario name]/run_model.bat" and "/[scenario name]/run_model_python.bat".
Next, run the "run_model.bat" to start a model run. Running either of the two batch files will start the model run. Both batch files have identical functionality, only one is purely in batch form and the other runs through a Python layer. The reason both exist is that the former is simpler, but the latter may be needed if certain use cases arise in the future.
AA does an iterative search for a set of commodity prices that will make the supply and demand of each commodity balance at each exchange location (referred to as clearing the market). At each iteration, it increases the price where the demand exceeds the supply (a shortage), and decreases the price where the supply exceeds the demand (a surplus). It then reruns the choice model to produce new supply and demand amounts. This continues until the difference between the supply and demand of each commodity in each zone is small enough.
AA fails when it reaches its maximum number of iterations with the difference between supply and demand still too big. This can happen for three main reasons:
-
Maybe it is impossible to clear the market while satisfying the constraints imposed on the model. AA notices that it cannot move the supply and demand for a commodity towards each other and gives up on that commodity, preventing it from ever reaching its target. This is an inconsistency problem.
-
Maybe clearing the market is theoretically possible, but the prices needed are so high (or so negative) that the exponential functions in the choice model overflow numerically. AA refuses to move the prices that high, so it never makes further progress on that commodity. This is an overflow problem.
-
Maybe clearing the market is possible with reasonable prices, but AA has trouble getting there because its logical next moves lead to worse surpluses or overflow. This is a bad guess problem - the initial guess at the prices for each commodity is too far from the solution for AA to make progress.
Inconsistency and overflow are related in that they both point to problems in the balance between producers and consumers. A bad guess may be a symptom of the same type of problem - the guess is bad because the solution is unreasonable - but it can also be a problem with the guess itself.
Diagnosing convergence problems starts with examining the run log (main_event.log). AA logs messages while reading and processing inputs and writing outputs, but the core of AA, in which the search for equilibrium happen, is logged between the messages "Beginning PECAS AA" and either "Equilibrium has been reached" or "MaxIterations have been reached", depending on whether the run converged. Within those bounds, each iteration logs the following pieces of information:
-
The iteration number ("Starting iteration XXX" and "End of iteration XXX")
-
The time taken to perform the iteration ("Time in seconds: XXX" after the "End of iteration" message), which can be used to estimate how long a run will take based on a few iterations.
-
The tClear and largestSClear values, which track how close AA is to clearing the market. The tClear value indicates the overall mismatch between supply and demand, while the largestSClear value indicates the worst mismatch in any zone. For both values, the smaller the better. AA reports convergence when both values are small enough (smaller than the aa.maxTotalClearance for tClear, aa.maxSpecificClearance for largestSClear).
-
The merit measure - a measure of the total remaining imbalance in the market across all commodities and zones, which decreases as AA makes progress.
These messages indicate whether AA is making progress or getting stuck; if the tClear and largestSClear values are decreasing consistently, AA is in good shape, while if they are bouncing around constantly, AA is having trouble finding a way to clear the market.
At regular intervals (usually every 25 iterations, configured by the aa.logFrequency setting), AA also logs a commodity-by-commodity breakdown of its status before summarizing the iteration in the usual way. These messages include:
-
The exchange with the largest surplus or shortage ("maxSurp"), and the price at that exchange. A positive maxSurp represents a surplus, while a negative maxSurp represents a shortage.
-
The exchange with the highest price ("PMax") and lowest price ("PMin").
-
The total surplus or shortage of the commodity ("Total surplus") and the average price of the commodity ("Average price") across the whole region.
-
The root mean square error ("Commodity RMS Error") and merit measure ("Weighted Commodity Merit Measure") for the commodity. The merit measure is the contribution this commodity makes to the overall merit measure.
-
The overall mismatch ("TClear") and worst mismatch in any zone ("maxSClear") between supply and demand for the commodity. The TClear values contribute to the overall tClear, while the overall largestSClear is the largest maxSClear out of all commodities.
The commodity-by-commodity breakdown is useful for determining which commodity is preventing AA from making progress.
If an AA run reaches the maximum iterations without converging, the first step is to look at how the tClear and largestSClear values change over time. Search for "largestSClear" in the run log and go through the matches. If tClear and largestSClear are both consistently decreasing, it may be that AA has a bad guess problem, and simply needs more time to find equilibrium. Delete ExchangeResultsI.csv, copy ExchangeResults.csv and rename the copy to ExchangeResultsI.csv, and run again. This causes AA to start with the best prices from the previous run, so it has a better chance of reaching equilibrium within the maximum iterations.
If, on the other hand, the value of tClear or largestSClear is decreasing very slowly or bouncing around without decreasing overall, or if there are frequent "Overflow" warnings, then there is probably an imbalance between producers and consumers - an inconsistency or overflow problem. The next step in this case is to find the commodity that is causing the imbalance. Find the last iteration where AA logs a commodity-by-commodity breakdown, or the last one before AA started oscillating or overflowing. Highlight the numerical value of largestSClear and search backwards; this will lead to the block of logging statements associated with the problem commodity. It can be helpful to check the PMin and PMax for this commodity - if the prices are extreme (negative or much higher than the default price in CommoditiesI.csv), then the commodity is more likely to be the problem.
Once the problem commodity is isolated, the inputs controlling that commodity can be investigated using the files in the "outputs/tXX" directory, where tXX is the model year where AA is failing.
First, check the overall balance between the commodity's producers and consumers. In TechnologyOptionsW.csv, look at the two columns that give technical coefficients for the problem commodity; the one whose name is the same as the commodity has the production amounts, while the one whose name is the commodity plus ":1" has the consumption amounts as negative numbers. To get the expected amount of production and consumption, multiply each activity's total amount in ActivityTotalsW.csv by the production or consumption coefficient in the row for that activity's EV (Expected Value) option (the one with "EV" in the OptionName column), and add up the production and consumption values. Maximum and minimum possible production and consumption amounts can be calculated in the same way, but using the largest or smallest coefficient amongst the activity's rows. This gives a range of possible production amounts that the technical coefficients and technology options allow.
If the range of possible production amounts barely overlaps with the range of possible consumption amounts, then the problem is most likely in ActivityTotalsW.csv or in the technical coefficients in TechnologyOptionsW.csv. Look back at the aggregate economic flow table or other sources for these values to check for errors or inconsistencies. It may be necessary to make one of the activities more elastic by increasing the difference in the technical coefficient between the options for that activity.
If the ranges of possible production and consumption amounts are close enough, check the total amounts of actual production and consumption reported in MakeUse.csv. If these are out of balance, the option weights in TechnologyOptionsW.csv may need to be recalibrated using the Option Weight Calibration procedure.
If the overall balance is good, check the zones reported in the log file as having the highest and lowest prices and the largest surplus or shortage. It may be that something is wrong with the inputs for this zone. First, confirm the ExchangeType of the problem commodity in CommoditiesI (p = exchange at producer, c = exchange at consumer, etc.). Then:
-
Check ActivityConstraintsI.csv (if the run is constrained) to confirm that the amounts of each activity in the zone are reasonable. It may be that the amount of producers (for "p" commodities) or consumers (for "c" commodities) is too high or too low to balance nearby customers.
-
Check the skims to confirm that the zone is accessible to the vehicles bringing the commodity from the producer (for "c" and "a" commodities) and taking the commodity to the consumer (for "p" and "a" commodities). It may be that the zone is disconnected from the network, or too far from possible customers.
-
Check FloorspaceW.csv to confirm that there is enough floor space in the zone to support the needed producers (for "p" commodities) or consumers (for "c" commodities). It may be that space is too expensive for the needed activity to locate in that zone.
A few small programs run before AA starts, though the SWIM system considers them to be part of AA. They prepare input files for AA in the format that AA expects, and adjusts some of the values so that AA is more stable in later years.
Retail Exchange is a Python program that adjusts the size terms for certain goods in proportion to the amount of retail and warehouse space in each zone.
The Java Preprocessor is a Java program, originally integrated into the main AA program, that does several small processing steps:
- It puts the total region-wide activity amounts into ActivityTotalsW.csv. These amounts are derived from ActivityTotalsI, and modified by household counts from SPG, activity and government forecasts from NED, and office support amounts required for production activities according to TechnologyOptionsI.
- It puts the amounts of floor space by zone into FloorspaceW.csv. These amounts are derived from FloorspaceI, modified with agricultural amounts from AgForestFloorspace.
- It puts the zone constants and size terms into ActivitiesZonalValuesW.csv. These amounts are derived from ActivitiesZonalValuesI and the previous year's ActivityLocations, and modified by the amounts of construction activity reported in the Increments file as well as an optional decay of the zone constants over time.
Technology Scaling is a Python program implemented using a SQLite database that it creates. Its purpose is to keep the economy balanced in future years, even if changing economic conditions produce a large shortage or surplus. For example, if the total quantity of industry in a region grows faster than the number of employable people, then at some point everyone will be employed and there will be a labor shortage. There are two possible responses to this situation:
- More people who live outside the region start commuting across the border to work in the region (or fewer people commute out of the region);
- Industry finds ways to produce other than hiring workers e.g. by investing in automation.
Technology scaling applies both of these responses to the AA inputs each year. It adjusts the total amounts of importer and exporter activities in ActivityTotalsW.csv, and scales the technical coefficients in TechnologyOptionsI.csv (to produce TechnologyOptionsW.csv), in response to changes in the net production of each commodity.
First, the total expected production of a commodity p in future year y is the sum of the amounts produced by each activity. Each production amount is the amount of activity (S) times the make coefficient (a) in the EV (expected value) option in TechnologyOptionsI.csv:
Some of this production is consumed within the model region, but the rest has to be exported by AA's exporter activities. We assume that the outside world is large enough that it can absorb increases in production by buying more from the model region. So the amount of each exporter activity is scaled in proportion to the increase in production:
The base year make is taken directly from the MakeUse.csv file in the base year, while the make in year y is estimated as above.
A similar calculation is done for the importers. First the expected consumption of commodity p in year y is calculated as:
Then the amount of each importer is scaled so that it can absorb increases in consumption by selling more to the model region:
We also have to account for "exogenous supply" - supply that the model artificially adds to a zone to make up for a shortage (or removes to make up for a surplus). The net exogenous supply ne is found by subtracting the base year total use from the base year total make, all from MakeUse.csv.
Now we balance each put, making the total expected supply equal the total expected demand. We do this by adjusting the import/export amounts a second time, and by adjusting the use coefficients so that industries use more or less of the put. Both of these adjustments are controlled by a single factor f that should be positive if there is too much consumption and negative if there is too much production. We scale the imports by a factor of (1 + f) and exports and use coefficients by a factor of (1 - f), so that the model will increase imports and limit exports and internal consumption if f is positive, and do the opposite if f is negative. For the example of a labor shortage, the import/export adjustment represents more people commuting across the border, and the use coefficient adjustment represents increasing automation so that fewer employees are needed.
After this adjustment, the total expected supply should equal the total expected demand:
Solving for f:
Now we scale the imports, exports, and use coefficients as described above:
Technology Scaling replaces earlier partial implementations of both import/export scaling and use coefficient scaling, which were part of the Java Preprocessor. The original import/export scaling simply set the total importers equal to the expected production and the total exporters equal to the expected consumption. The original coefficient scaling applied only to the consumption of labor and was independent of import/export scaling. Technology Scaling unifies these treatments into one step, with imports, exports, and use coefficients scaled together by a common factor chosen to balance the expected production and consumption.
When Technology Scaling is turned on (using the new aa.technologyScaling setting), the Java Preprocessor automatically turns off the replaced features.
The testing procedure for Technology Scaling is described at this page.
| Parameter | Value | Description |
|---|---|---|
| local.market.world.zone | 6006 | The "world" external zone |
| port.of.portland.zone | 5012 | The Port of Portland zone |
| world.to.external.distances | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.INPUTS@/t0/ WorldZoneExternalStationDistances.csv | the external zone distances file |
| aa.09.productivity.rate | 0.120753428 | Base year conversion factor from dollars of labor to number of jobs |
| aa.automaticTechnologySizeTerms | TRUE | Whether to calculate size terms from floorspace quantities; actually unnecessary because it defaults to TRUE and should never be FALSE |
| aa.base.data | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.INPUTS@/parameters/ | Path for AA inputs applicable to all years (commodity properties, technology options etc.) |
| aa.calculateAveragePrices | TRUE | Whether to use a newer method for adjusting prices in AA; actually unnecessary because it defaults to TRUE and should never be FALSE |
| aa.command.class | com.hbaspecto.oregon.pecas.aa.OregonAAControl | Specifies which class to use to start running AA (used to customize PECAS for Oregon) |
| aa.command.classpath | @ROOT.DIR@/@SCENARIO.NAME@/ model/code/aa/PecasV2.7_r3650.jar; @ROOT.DIR@/@SCENARIO.NAME@/ model/code/aa/censusdata_r2348.jar; @ROOT.DIR@/@SCENARIO.NAME@/ model/code/aa/common-base_r2753.jar; @ROOT.DIR@/@SCENARIO.NAME@/ model/code/aa/or124.jar; @ROOT.DIR@/@SCENAR | AA java classpath - contains the pathnames for all the necessary JAR files, must be updated when JAR file versions change |
| aa.command.java | @ROOT.DIR@/model/lib/java7/jre/bin/java.exe | AA java executable, parts of the system were not yet Java 7 compatible but AA requires Java 7 |
| aa.command.log4j.config.file | info_log4j_aa.xml | XML definitions for Log4j, here you can configure logging to your heart's content |
| aa.command.max.heap.size | 3000m | Amount of memory to allow Java to take up (e.g. 3000m = 3000 megabytes) |
| aa.ConFac | 0.01 | Changes the denominator in the calculation of percentage specific error; e.g. 0.01 means 1% of the global amount of a commodity is added to each denominator when calculating the zone percentage error, with aa.maxSpecificClearance; should be larger than zero otherwise very small zones receive too much importance in the convergence criteria |
| aa.createCompressedFlowVisuals | FALSE | Whether AA should cluster flow matrices into a GML file showing desire lines. |
| aa.current.data | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@CURRENT.INTERVAL@/ | Path for miscellaneous inputs to AA for the current year |
| aa.detailedCommodities | A1-Mgmt Bus, B1-Prof Specialty, B2-Education, B3-Health, B4-Technical Unskilled, C1-Sales Clerical Professionals, C2-Sales Service, C3-Clerical, C4-Sales Clerical Unskilled, D1-Production Specialists, D2-MaintConstRepair Specialists, D3-ProtectTrans Specialists, D4-Blue Collar Unskilled | List of commodities for which make and use values are needed at the alpha zone level; currently lists the occupation commodities |
| aa.directExcelInputs | FALSE | Not used, can remove (There used to be a way to have AA read excel files, but this has been deprecated due to bugs in the underlying library) |
| aa.externalZonesInHistogram | FALSE | Whether to include the external (gateway, rest-of-world) zones in the calculations of trip length distributions in Histograms.csv; usually leave as false so flow distances can be compared with intra-regional trip distances |
| aa.floorspace.data | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@CURRENT.INTERVAL@/ | Path for AA floor space inputs |
| aa.initialStepSize | 0.002 | Step size to start the price search process in AA; normally we start conservative, e.g. .0002, and let AA gradually increase the step-size; 1.0 is full Newton's Method but that is usually too agressive at the beginning of a new year |
| aa.localPriceStepSizeAdjustment | 1 | Whether to scale the "local" price search separately from the global price search; this is rarely used (i.e. it's usually set to 1.0 so local and global price search use the same step size) |
| aa.logFrequency | 25 | How often to write the minimum/maximum/average price and total surplus information by commodity to the log file. It's difficult to debug AA if this is less than 25, usually it's set to 10 during debug runs and 25 during production runs. Users often like to try a higher number (e.g. 100) to reduce log file sizes, but sooner or later John ends up turning it back down to 25 or 10 because he needs that level of information to debug convergence issues. |
| aa.makeTripMatrices | FALSE | Whether to divide economic flows in AA into truck/passenger trips as a trip list and trip matrices, not used in Oregon as PT and CT generate the trips |
| aa.maximumStepSize | 2.5 | Biggest allowable step size in price search; AA will not go above this even if many consecutive iterations are successful |
| aa.maxIterations | 1200 | Maximum number of iterations that AA will try to run; if not converged within this many iterations, AA will write whatever it has so far as outputs and stop (in the constrained base year, it will crash instead) |
| aa.maxSpecificClearance | 0.02 | AA convergence criterion; convergence reached when the largest surplus in any exchange (as a fraction of the exchange "size") is smaller than aa.maxSpecificClearance |
| aa.maxTotalClearance | 0.00005 | AA convergence criterion; convergence reached when the root-mean-square of surpluses in all exchanges (as a fraction of the exchange "size") is smaller than aa.maxTotalClearance; both aa.maxTotalClearance and aa.maxSpecificClearance must be met for convergence; aa.maxTotalClearance is always set smaller than aa.maxSpecificClearance, since one exchange that fails to clear is less of a problem than an overall lack of market clearing |
| aa.minimumStepSize | 0.025 | Smallest allowable step size in price search; AA will not go below this even if many consecutive iterations fail (overflow or regress to a worse total error) |
| aa.NEDandALDInputs | TRUE | Whether to integrate outputs from NED and ALD into AA's inputs |
| aa.oregonHHtypes | HH0to8k1to2, HH0to8k3plus, HH8to15k1to2, HH8to15k3plus, HH15to23k1to2, HH15to23k3plus, HH23to32k1to2, HH23to32k3plus, HH32to46k1to2, HH32to46k3plus, HH46to61k1to2, HH46to61k3plus, HH61to76k1to2, HH61to76k3plus, HH76to106k1to2, HH76to106k3plus, HH106kUp1to2, HH106kUp3plus | Activities that are household types, for alpha zone level detailed make and use |
| aa.oregonOccupations | A1-Mgmt Bus, B1-Prof Specialty, B2-Education, B3-Health, B4-Technical Unskilled, C1-Sales Clerical Professionals, C2-Sales Service, C3-Clerical, C4-Sales Clerical Unskilled, D1-Production Specialists, D2-MaintConstRepair Specialists, D3-ProtectTrans Specialists, D4-Blue Collar Unskilled | Occupation commodities for Oregon-specific make/use files (laborDollarProductionSum etc.) |
| aa.previous.data | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@AA.LAST.RUN@/ | Path for AA inputs that were written by AA itself in the previous year |
| aa.readActivityDollarDataForPI | TRUE | Whether to read forecast activity from NED |
| aa.readHouseholdsByHHCategory | FALSE (flips to TRUE after the bootstrap year) | Whether to read updated household counts from SPG |
| aa.reference.data | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.INPUTS@/parameters/ | Path for AA zone system inputs |
| aa.splitOutputToFloorspaceZones | TRUE | Whether AA should write the ActivityLocations2 file detailing activities by alpha zone |
| aa.stringsInZonalMakeUse | FALSE | Whether to include the commodity and activity names directly in the ZonalMakeUse file, rather than their ID numbers |
| aa.updateImportsAndExports | FALSE (flips to TRUE after the bootstrap year) | Whether to read forecast trade amounts from NED to update imports and exports; ignored if aa.technologyScaling is TRUE |
| aa.technologyScaling | TRUE | Whether to use Technology Scaling to adjust import/export amounts and use coefficients; disables the older import/export scaling feature controlled by aa.updateImportsAndExports |
| aa.useFloorspaceZones | TRUE | Whether floor space zones (alpha zones) are distinct from PECAS zones (beta zones) |
| aa.useLogitProduction | TRUE | Not used, can remove |
| aa.useLogitTechnologyChoice | TRUE | Not used, can remove |
| aa.useSQLInputs | FALSE | Whether to have AA read its inputs from an SQL database instead of CSV files; always false for Oregon |
| aa.visum | TRUE | Whether AA is integrated with VISUM (needed because some files are in different locations and VISUM mangles the AA activity names) |
| aa.writeAsciiZonalMakeUse | TRUE | Whether AA should create a plaintext ZonalMakeUse.csv file |
| aa.writeBinaryZonalMakeUse | FALSE | Whether AA should create a binary ZonalMakeUse.bin file |
| aa.writeExchangeDerivatives | TRUE | Whether AA should write the derivatives of surplus with respect to price to the ExchangeResults file |
| aa.writeFlowMatrices | TRUE | Whether AA should write out commodity flow matrices and histograms |
| aa.writeUtilityComponents | TRUE | Whether AA should write out to CommodityZUtilites a breakdown of how the commodity buy/sell utilities were calculated |
| ald.input.data | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@ALD.LAST.RUN@/ | Path for inputs to AA that are written by ALD. |
| calculateExchangeSizes | TRUE | Whether AA should use exchange size terms |
| constrained | @AA.CONSTRAINED@ | Whether to run AA constrained; this is set automatically by the run script according to constrained.years |
| constrained.years | 19 | Years in which to run AA constrained to a specific activity distribution; usually only the bootstrap year |
| constraint.iterations | 2 | Not used, can remove |
| constraint.maxConstantChange | 2.5 | Not used, can remove |
| constraint.smoothing | 1 | Controls how quickly AA adjusts zone constants for zones containing no activity of a given type during constrained runs |
| constraint.tolerance | 0.02 | How closely AA needs to meet its constraints in constrained runs; AA will report an error if it doesn't satisfy the tolerance |
| industry.occupation.to.split.industry.correspondence | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@CURRENT.INTERVAL@/ zzIndustryOccupationSplitIndustryCorrespondence.csv | |
| Model.skimFormat | zmx | AA skim input file format - a single CSV file, a bunch of CSV files, or a bunch of ZMX files? |
| ned.activity_forecast.path | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@CURRENT.INTERVAL@/ activity_forecast.csv | NED input |
| ned.construction_forecast.path | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@CURRENT.INTERVAL@/ construction_forecast.csv | NED input |
| ned.government_forecast.path | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@CURRENT.INTERVAL@/ government_forecast.csv | NED input |
| ned.population_forecast.path | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@CURRENT.INTERVAL@/ population_forecast.csv | NED input |
| ned.trade_forecast.path | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@CURRENT.INTERVAL@/ trade_forecast.csv | NED input |
| output.data | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@CURRENT.INTERVAL@/ | AA output directory |
| pi.oregonOutputs | TRUE | Whether to write Oregon-specific make/use files (laborDollarProductionSum etc.) |
| pprocessor.class | com.hbaspecto.oregon.pecas.aa.OregonAAPProcessor | Specifies which class to use to preprocess inputs for AA (used to customize PECAS for Oregon) |
| skim.data | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@TA.LAST.RUN@/ | Path for AA skim inputs |
| spg.income.size.conversion.factor | 1 | factor used to convert PUMS incomes to base year dollars |
| spg.income.size.hh.size.upper.bounds | 2 | Specify the break point for household size classification |
| spg.income.size.income.upper.bounds | 8000,15000,23000,32000,46000,61000,76000,106000 | the upper bounds for the SPG income categories |
| spg.input.data | @ROOT.DIR@/@SCENARIO.NAME@/ @SCENARIO.OUTPUTS@/t@SPG1.LAST.RUN@/ | Path for inputs to AA that are written by SPG |
| zip.extension | .zmx | File extension that AA should use when it writes ZipMatrix files |
In the inputs/parameters directory
| File | Description |
|---|---|
| ActivitySizeTermsI.csv | Specifies zonal "size" attractors for activities that do not use space |
| ActivityTotalsI.csv | Total amount of each activity in the entire model region |
| AgForestFloorspace.csv | Amounts of land dedicated to agriculture and forestry (since ALD does not update these each year) |
| CommoditiesI.csv | List of AA commodities and their attributes (dispersion parameters, transport characteristics, etc.) |
| ExchangeImportExportI.csv | Controls the import and export functions, and can also specify certain exchanges that should produce additional logging information to diagnose trade imbalances in the model (using the MonitorExchange column) |
| ExchangeSizeTermTypes.csv | Indicates which space types are used as exchange locations for commodities that can be exchanged anywhere; used to control the probability of exchanging those commodities in each zone. The current model considers retail and warehouse space to be suitable exchange locations. |
| FloorspaceSupplyI.csv | Specifies the "landlord functions" that control how vacancy varies with space rent |
| FloorspaceZonesI.csv | Lists the floorspace zones (alpha zones) |
| HistogramsI.csv | Defines the distance ranges into which commodity flows are grouped when producing the Histograms output file (see [Output Files][Output files]) |
| PECASZonesI.csv | Lists the LUZs (beta zones) |
| TechnologyOptionsI.csv | Defines the "technology vectors" - combinations of inputs and outputs that each activity consumes and produces |
| ActivitiesI.csv | List of AA activities and their attributes (dispersion parameters, and whether the activity is an importer, exporter, or neither) |
| ActivityConstraintsIWorldMarkets.csv | Constraints on the amount of importers and exporters in each external zone |
In the outputs/tXX directory, where tXX is the current year
| File | Description |
|---|---|
| aa.properties | Properties file that contains the [model settings][Model Settings] |
| activity_forecast.csv | Forecast of the total amounts of production by activity, used to update TechnologyOptionsW and ActivityTotalW (see [Working Files][Working Files]) |
| alpha2beta.csv | Correspondence between the TAZs (alpha zones) and LUZs (beta zones) |
| b4mcls_beta.zmx | Logsums for work-based trips, $15K-$30K income, autos < persons in household |
| b5mcls_beta.zmx | Logsums for work-based trips, $15K-$30K income, autos ≥ persons in household |
| b8mcls_beta.zmx | Logsums for work-based trips, ≥ $30K income, autos ≥ persons in household |
| betantautodist.zmx | Night auto distance skims |
| betantautofftime.zmx | Night auto free-flow time skims |
| betantautotime.zmx | Night auto congested time skims |
| betantautotoll.zmx | Night auto toll skims |
| betanttrk1dist.zmx | Night medium truck distance skims |
| betanttrk1fftime.zmx | Night medium truck free-flow time skims |
| betanttrk1time.zmx | Night medium truck congested time skims |
| betanttrk1toll.zmx | Night medium truck toll skims |
| betaopautodist.zmx | Off-peak auto distance skims |
| betaopautofftime.zmx | Off-peak auto free-flow time skims |
| betaopautotime.zmx | Off-peak auto congested time skims |
| betaopautotoll.zmx | Off-peak auto toll skims |
| betaoptrk1dist.zmx | Off-peak medium truck distance skims |
| betaoptrk1fftime.zmx | Off-peak medium truck free-flow time skims |
| betaoptrk1time.zmx | Off-peak medium truck congested time skims |
| betaoptrk1toll.zmx | Off-peak medium truck toll skims |
| betapkautodist.zmx | AM peak auto distance skims |
| betapkautofftime.zmx | AM peak auto free-flow time skims |
| betapkautotime.zmx | AM peak auto congested time skims |
| betapkautotoll.zmx | AM peak auto toll skims |
| betapktrk1dist.zmx | AM peak medium truck distance skims |
| betapktrk1fftime.zmx | AM peak medium truck free-flow time skims |
| betapktrk1time.zmx | AM peak medium truck congested time skims |
| betapktrk1toll.zmx | AM peak medium truck toll skims |
| betapmautodist.zmx | PM peak auto distance skims |
| betapmautofftime.zmx | PM peak auto free-flow time skims |
| betapmautotime.zmx | PM peak auto congested time skims |
| betapmautotoll.zmx | PM peak auto toll skims |
| betapmtrk1dist.zmx | PM peak medium truck distance skims |
| betapmtrk1fftime.zmx | PM peak medium truck free-flow time skims |
| betapmtrk1time.zmx | PM peak medium truck congested time skims |
| betapmtrk1toll.zmx | PM peak medium truck toll skims |
| c4mcls_beta.zmx | Logsums for school trips, $15K-$30K income, autos < persons in household |
| ExchangeResultsI.csv | Optional file containing starting prices for each commodity; see the section on initial prices |
| FloorspaceI.csv | Quantity of floorspace by floorspace zone (alpha zone) as produced by ALD |
| government_forecast.csv | Forecast of the total amounts of government activity (FGOV_acct_gov, SLGOV_acct_gov, CAP_acct_gov) |
| householdsByHHCategory.csv | Number of households in each category as produced by SPG |
| Increments.csv | Amounts of space constructed by ALD in each zone, used to modify zone constants for construction activities in AA |
| o4mcls_beta.zmx | Logsums for "other" purpose trips, $15K-$30K income, autos < persons in household |
| s4mcls_beta.zmx | Logsums for shopping trips, $15K-$30K income, autos < persons in household |
| w1mcls_beta.zmx | Logsums for work trips, < $15K income, no autos |
| w4mcls_beta.zmx | Logsums for work trips, $15K-$30K income, autos < persons in household |
| w7mcls_beta.zmx | Logsums for work trips, ≥ $30K income, autos < persons in household |
| w8mcls_beta.zmx | Logsums for work trips, ≥ $30K income, autos ≥ persons in household |
| zzIndustryOccupationSplitIndustryCorrespondence.csv | Which occupations are "white collar" and use office space, by industry |
An optional input file called ExchangeResultsI.csv can be provided in any or all outputs/tXX directories. This file gives AA a set of initial commodity prices to use for that year, which may help AA converge faster.
AA does an iterative search for a set of commodity prices that will make the supply and demand of each commodity balance at each exchange location (referred to as clearing the market). At each iteration, it increases the price where the demand exceeds the supply (a shortage), and decreases the price where the supply exceeds the demand (a surplus). It then reruns the choice model to produce new supply and demand amounts. This continues until the difference between the supply and demand of each commodity in each zone is small enough.
The number of iterations needed to clear the market depends on how close the initial guess is to the solution. By default, AA starts each commodity at the price in the ExpectedPrice field in CommoditiesI.csv, which is a very rough estimate. Better guesses can be provided using an ExchangeResultsI.csv file; AA will use the prices in the Price column as its starting guess, and if these are close to equilibrium, AA will converge faster. After the base year, AA will automatically use the equilibrium prices from the previous year as starting prices, so providing an ExchangeResultsI.csv file is most useful in the base year.
The general approach to creating an ExchangeResultsI.csv file is to copy the ExchangeResults.csv (without the I) from a suitable successful AA run and rename it to ExchangeResultsI.csv. The choice of where to get the ExchangeResults file from depends on the kind of run being done:
-
If the reference scenario is being rerun, possibly with small changes to the inputs, try copying ExchangeResults from the previous reference scenario's base year to let the new run take advantage of the searching that AA has already done.
-
If a policy scenario is being run, try copying ExchangeResults from the reference scenario's base year.
-
If the base year is not converging, try copying ExchangeResults from the most recent version of the scenario with similar inputs that did converge.
-
If the base year is not converging, but later years are converging, it is possible that AA simply needed more than the maximum iterations to search for the best prices; try copying ExchangeResults from the first year that converged back into the base year.
Conversely, when large changes to the inputs are made, the equilibrium prices might be so different from the previous version of the model that the prices in the ExchangeResultsI file are no better than the default starting prices. When AA stops converging after a change in inputs, the first step is usually to delete ExchangeResultsI and try again with the default prices. Only if AA still fails to converge should the cause be investigated further.
These are generated by the AA preprocessing steps based on the input files.
| File | Description |
|---|---|
| ActivityTotalsW.csv | Created by the Java Preprocessor to include SPG households, NED activity/government forecasts, and production activities; imports and exports modified by Technology Scaling |
| FloorspaceW.csv | Created by the Java Preprocessor to include agricultural land |
| TechnologyOptionsW.csv | Created by Technology Scaling |
| ActivitiesZonalValuesW.csv | Created by the Java Preprocessor to include construction activity and decaying zone constants |
| ExchangeImportExportI.csv | Created by Retail Exchange |
| File | Description |
|---|---|
| ActivityLocations.csv | Activity quantities by LUZ (beta zone) |
| ActivityLocations2.csv | Activity quantities by TAZ (alpha zone) |
| ActivityNumbers.csv | Lists the numbers that AA has assigned to each activity; some output files report activities by number rather than by name |
| ActivitySummary.csv | Top-level composite utility for each activity |
| buying_XXX.zmx | Matrices of flows of each commodity from the exchange location to the consumer |
| CommodityNumbers.csv | Lists the numbers that AA has assigned to each commodity; some output files report commodities by number rather than by name |
| CommodityZUtilities.csv | Shows the components of the utility function for buying and selling each commodity in each zone |
| ExchangeResults.csv | Shows the amounts of each commodity exchanged in each zone and their prices |
| ExchangeResultsTotals.csv | ExchangeResults aggregated to the entire region (total quantities, average prices, etc.) |
| FloorspaceZoneTotalMakeUse.csv | Total amount of each commodity produced and consumed in each floorspace zone (alpha zone) |
| Histograms.csv | For each distance range defined by HistogramsI (see [Input Files][Input Files]), shows how much of each commodity travels a distance within that range |
| laborDollarConsumptionSum.csv | Total amount of each type of labor consumed in each zone |
| laborDollarProduction.csv | Total amount of each type of labor produced by each household category in each zone |
| laborDollarProductionSum.csv | Total amount of each type of labor produced in each zone |
| MakeUse.csv | Total amount of each commodity produced and consumed by each activity in the model region |
| PctIntrazonalxCommodityxBzone.csv | For each zone, the amount of each commodity that is both bought and sold in that zone (i.e. is an intrazonal flow) |
| selling_XXX.zmx | Matrices of flows of each commodity from the producer to the exchange location |
| TAZDetailedMake.csv | Amount of labor production by household category in each TAZ (alpha zone) |
| TAZDetailedUse.csv | Amount of labor consumption by activity in each TAZ (alpha zone) |
| TechnologyChoice.csv | Amount of activity that chooses each technology option (from TechnologyOptionsI) |
| ZonalMakeUse.csv | Total amount of each commodity produced and consumed by each activity in each zone |
[^John Douglas Hunt and Abraham 2005]: Hunt, John Douglas, and John E. Abraham. 2005. "Design and Implementation of PECAS: A Generalized System for Allocating Economic Production, Exchange and Consumption Quantities." In Integrated Land-Use and Transportation Models: Behavioural Foundations. Amsterdam; Boston: Elsevier.
[^John Douglas Hunt 2012]: Hunt, John Douglas. 2012. "PECAS Theoretical Structure and System Module Implementation. Lecture 8." Land Use Modelling ENCI 595, University of Calgary, March 5.
[^De la Barra 1989]: De la Barra, Tomás. 1989. Integrated Land Use and Transport Modelling: Decision Chains and Hierarchies. Cambridge: Cambridge University Press.
[^J.E. Abraham and Hunt 2007]: Abraham, J.E., and J. D. Hunt. 2007. "Random Utility Location, Production and Exchange Choice: Additive Logit Model and Spatial Choice Microsimulations." Transportation Research Record: Journal of the Transportation Research Board 2003: 1–6.
[^J. D. Hunt and Abraham 2009]: Hunt, J. D., and John Edward Abraham. 2009. "PECAS — For Spatial Economic Modelling: Theoretical Formulation." HBA Specto Incorporated. http://www.hbaspecto.com/.
[^John Edward Abraham and Fuenmayor 2010]: Abraham, John Edward, and Geraldine Fuenmayor. 2010. "Generating PECAS Base Year Built Form in the Baltimore Metropolitan Area."
[^HBA Specto Incorporated 2012]: HBA Specto Incorporated. 2012. "Model Development - Trip Length Calibration Script." PECAS — for Spatial Economic Modelling. Calgary, AB.
[^Fuenmayor and Abraham 2013]: Fuenmayor, Geraldine, and John E. Abraham. 2013. "Generating PECAS Base Year Built Form for Clayton County in Atlanta." HBA Specto Incorporated.
[^Fuenmayor et al. 2014]: Fuenmayor, Geraldine, John Edward Abraham, Wei Wang, and John Douglas Hunt. 2014. "Generating PECAS Base Year Built Form for Clayton County in Atlanta." In . Baltimore, Maryland: Transportation Research Board.
[^HBA Specto Incorporated 2013a]: HBA Specto Incorporated. 2013a. "Best Practice Review of Integrated Land Use - Transport Models. Literature Review."
[^Geraldine Fuenmayor 2016]: Fuenmayor, G.J. 2016. “Building a Spatial Economic Model for Caracas using PECAS” Doctoral Dissertation. University of Calgary, Calgary.
[^Abraham, J.E., T. Weider, and J. D. HUNT 2005]: Abraham, J.E., T. Weider, and J. D. HUNT. 2005. “Calibrating the Oregon Spatial Allocation Models.” In . Las Vegas, NV.
[^Abraham, J. E. 2014]: Abraham, J. E. 2014. Calibration Sequence for the Sacramento PECAS Model. Calgary, AB. http://www.hbaspecto.com/pecas/pecas_videos/.
[^J. Abraham, Hunt, and Fuenmayor 2013]: Abraham, John, John Douglas Hunt, and Geraldine Fuenmayor. 2013. "Policy Analysis Using the PECAS Framework." In Compendium of Annual Papers. Washington, D.C.