Model System Configuration

If one would pass the above configuration to the run manager, it would perform steps as described in Section 20.1.1, but no model 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 processed. For example, the UrbanSim gridcell project consists by default of following models:

   '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 list above.

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 20.3.3 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 list 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 20.3.3.

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. ['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(). If it is 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 20.3.3 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.

From the preloaded datasets, ModelSystem creates a dataset pool (accessible to the models as dataset_pool). Creating this pool is controlled by the entry

    'dataset_pool_configuration': DatasetPoolConfiguration(
                package_order=['urbansim', 'opus_core'],
                )