Model Controller Configuration

The run configuration can contain an entry 'models_configuration' which can include any information specific to models or common to a set of models. The value of this entry is a dictionary. Model specific information would be included in an entry of the same name as the model name used in the entry 'models' (see Section 20.3.2). The ModelSystem class makes this information available to the controller by creating two local variables: 'models_configuration' (containing the value of 'models_configuration' and available to all models) and 'model_configuration' (available to each model at the time of its processing and containing information for this model). See the variable 'models_configuration' in the file urbansim/configs/general_configuration.py for an example how UrbanSim configures models.

Each model that is included in the configuration entry 'models' must have a controller entry in the 'models_configuration' entry. More specifically, the model specific section of 'models_configuration' is expected to contain an entry 'controller' for each model. For example, a controller specification for the model specified by the name 'land_price_model' would be contained in
config['models_configuration']['land_price_model']['controller'].

If a model is specified as a model group it is possible to define a member specific controller, called member_name + '_' + model_name, e.g. 'home_based_employment_location_choice_model'. When choosing the right controller, the ModelSystem checks for the member specific name. If it is not found, it uses the group name, in this example 'employment_location_choice_model'.

The value of this controller entry is a dictionary with a few well-defined entries:

"import"

A dictionary where keys are module names and values are names of classes to be imported.

"init"

A dictionary with a mandatory entry "name". Its value is the name of the class (or class.method) that creates the model. It can be the name of the model class itself. Or, if the model is created via a method e.g. get_model() of a class MyModelCreator, it would be given as "MyModelCreator().get_model".

Optional entry "arguments" specifies arguments to be passed into the constructor. It is given as a dictionary of argument names and values. All values are given as character strings and are later converted by ModelSystem to python objects. If an argument value is suppose to be a character string object, it must be given in double quotes, e.g. "'my_string'".

If the model in the 'models' entry of the configuration is specified as model group, the controller must contain an entry

"group_by_attribute"

Its value is a tuple of a grouping dataset name and grouping attribute (see Sec. 22.7.2). They define the specific kinds of subsets of agents on which this model can be run. This dataset must be contained in the datasets_to_preload entry of the configuration. For example, in the controller of the ``employment_location_choice_model'' this entry is ('job_building_type', 'name'), since the attribute 'name' of the dataset 'job_building_type' contains the various building types of jobs for which we want to run the model, i.e. 'commercial', 'governmental', 'industrial' and 'home_based'. If the 'group_members' entry (of the 'models' entry of the configuration) for this model is equal to '_all_', the model runs for all values found in this dataset. The 'group_members' can also be a list specifying explicitely for which types the model should be run.

The ModelSystem class evaluates the given imports and creates an instance of the model by processing the 'init' entry. The remaining entries below are related to specific methods of the created model instance. As mentioned in Section 20.3.2, models that are listed in the 'models' entry of the run configuration can be also specified using a list of methods to be processed. If the list is not given, a method run() is assumed to be the only method to be processed. The ModelSystem iterates over the set of methods. It first processes a ``preparation'' method (if required) and then the method itself. For this purpose, the controller should contain the following entries:

'prepare_for_...'

, where ... is the the method to be processed, e.g. 'prepare_for_run' is the method to call to prepare to run. This configuration entry is a dictionary with an optional entry 'name' giving the name of the preparation method. If 'name' is missing, the method name is assumed to be the same as this entry name. Optional entry 'arguments' specifies arguments of this method (see 'arguments' in 'init' above). Optional entry 'output' defines the name(s) of the output of this method. It can be then used as an input to other methods or models. The entry 'prepare_for...' is optional and if it's missing, no preparation procedure is invoked. There can be as many 'prepare_for...' entries as there are methods specified.

procedure

The procedure name must match to the method names given in 'models' (there must be one entry per method), or be called 'run' if no methods are specified in 'models'. It is a dictionary with optional arguments 'arguments' and 'output' (see above).

The entry 'arguments' in the above items can contain any character strings that are convertable (using python's eval()) to python objects, including python expressions. They must be objects that are known to the ModelSystem, for example datasets that are defined in 'datasets_to_preload' (described in Section 20.3.2), since those are created prior to the simulation. They can be called either by the dataset name, or using datasets['name']. Also, the model_configuration and models_configuration objects described in Section 20.3.3 can be used in 'arguments'. Other objects that ModelSystem provides are cache_storage (Storage object for the simulation cache storage in the simulated year), base_cache_storage (Storage object for the baseyear cache storage in the base year), model_resources (all preloaded datasets as an object of Resources), resources (Configuration passed into the simulation), datasets (all preloaded datasets as a dictionary), year (simulated year), base_year (the base year), dataset_pool (object of class DatasetPool pointing to the current dataset pool), debuglevel (integer controlling the amount of output messages). If you are using any class names as arguments, you need to make sure, that those classes are known to the ModelSystem, e.g. by putting the appropriate import statement into the 'import' section of the controller.

Here is an example of a controller settings for the land price model in UrbanSim:

run_configuration['models_configuration']['land_price_model']['controller'] = {
    "import": {"urbansim.models.corrected_land_price_model":
                                                "CorrectedLandPriceModel",
              },
    "init": {"name": "CorrectedLandPriceModel"},
    "prepare_for_run": {
        "arguments": {"specification_storage": "base_cache_storage",
                      "specification_table": "'land_price_model_specification'",
                      "coefficients_storage": "base_cache_storage",
                      "coefficients_table": "'land_price_model_coefficients'"},
        "output": "(specification, coefficients)"
        },
    "run": {
        "arguments": {"n_simulated_years": "year - base_year",
                      "specification": "specification",
                      "coefficients":"coefficients",
                      "dataset": "gridcell",
                      "data_objects": "datasets" ,
                      "chunk_specification":"{'nchunks':2}",
                      "debuglevel": "debuglevel"
                     }
           }
   }

Note on an implementation of model group: A constructor of a model group, must take as its first argument an object of class ModelGroupMember (Sec. 22.7.2). The controller should though ignore this argument, since the ModelSystem automatically takes care of creating this object and passing it to the model constructor.