Model System Configuration

If one would pass the above configuration to the run manager, it would perform steps as described in Section 4.1.3, but no models would be run. The configuration should in addition contain entries that control what models, in what order and with what input and output should be run. It determines the behaviour of the class ModelSystem. UrbanSim basic configuration of the model system can be found in the file urbansim/configs/general_configuration.py as an example.

The set of models to run is specified by the entry ``models''. It is a list of user-defined model names. The order in this list also specifies the order in which they are run. A production run of UrbanSim consists by default of following models:

run_configuration['models'] = [
        "prescheduled_events",
        "events_coordinator",
        "residential_land_share_model",
        "land_price_model",
        "development_project_transition_model",
        "residential_development_project_location_choice_model",
        "commercial_development_project_location_choice_model",
        "industrial_development_project_location_choice_model",
        "development_event_transition_model",
        "events_coordinator",
        "residential_land_share_model",
        "household_transition_model",
        "employment_transition_model",
        "household_relocation_model",
        "household_location_choice_model",
        "employment_relocation_model", 
       {"employment_location_choice_model": {"group_members": "_all_"}},
        "distribute_unplaced_jobs_model"
   ]

Note that the list can contain a particular model multiple times if that model should run multiple times within one year, such as the ``events_coordinator'' or ``residential_land_share_model'' in the above list.

We can also define a situation when the same model should be run on different subsets of a dataset, so called model group. Then we can give the names of the group members to be run, or just configure the model group to be run on all subsets. This is the case of ``employment_location_choice_model'' in the list above (see Section 4.2.4 for further details).

By default, the ModelSystem runs the method run() of the listed models. Each entry in this model list can be alternatively a dictionary containing one entry: The name of the entry is the model name, the value is a list of model methods to be processed. Thus, one can combine estimation and simulation of different models.

In addition (or alternatively), the configuration can contain an entry ``models_in_year''. It is a dictionary where keys are years. Each value is expected to be such list of models as above. In each year, it is checked if ``models_in_year'' (if it is present) contains that year. If it is the case, its list of models is run, instead of the global set of models. This allows users to set different set of models for different years, for example an additional model can be run only in the first year, or last year.

For each entry in the model lists above there must be a corresponding entry in the ``controller'' configuration which specifies how models are initialized, what methods to run and what arguments should be passed in. This will be described in Section 4.2.4.

Furthermore, the configuration can contain the following entries (the given values are defaults set by our system):

{
    'datasets_to_cache_after_each_model':[],
    'flush_variables': False,
    'seed':0,
    'debuglevel':0
}

The entry 'datasets_to_cache_after_each_model' specifies names of datasets that are flushed from memory to simulation cache at the end of each model run. This reduces the memory usage, but can increase the run time. We recommend to put datasets in this list that contain huge amount of data. E.g. UrbanSim sets this entry to ['gridcell', 'household', 'job'].

'flush_variables' can further decrease the memory usage. If it is True, after each variable computation all dependent variables are flushed to simulation cache , regardless to what dataset the variables belong to. Nevertheless, it increases the run-time considerably.

Entry 'seed' specifies the seed of the random number generator that is set at the beginning of each simulated year. It is passed to the numpy function seed() and therefore it should be a tuple with two integer values. If both values are 0, the function generates a pseudo-random seed from the current time.

'debuglevel' controls the amount of output information.

Models usually need various datasets to run with. They are specified in the configuration entry 'datasets_to_preload'. For example,

{
'datasets_to_preload': {
        'gridcell':{"id_name": "grid_id"},
        'household':{}
}

It is a dictionary that has dataset names as keys. Each value is again a dictionary with argument-value pairs that are passed to the corresponding dataset constructor. ModelSystem creates those datasets at the beginning of each simulated year and they are accessible to the models definition in the controller through their names (see Section 4.2.4 for details). One should put here all datasets that will be passed as arguments to the model constructors or to the model methods to be processed.

If you do not want to make any output to cache, for example in estimation mode, set

{
    'low_memory_mode': False
}

This should be only used when you're aware what you're doing. It suppresses any cache writing during the processing (after each model, as well as at the end of each year) and will not work for a simulation over multiple years. Also, the memory usage can increase considerably.