GBNRTC Model

class emat.model.GBNRTCModel(configuration: Union[str, Mapping], scope: Union[emat.scope.scope.Scope, str], safe: bool = True, db: Optional[emat.database.database.Database] = None, name: str = 'GBNRTC')[source]

Bases: emat.model.core_files.core_files.FilesCoreModel

Setup connections and paths to GBNRTC core model

Parameters:
  • configuration – The configuration for this core model. This can be passed as a dict, or as a str which gives the filename of a YAML file that will be loaded.
  • scope – The exploration scope, as a Scope object or as a str which gives the filename of a YAML file that will be loaded.
  • safe – Load the configuration YAML file in ‘safe’ mode. This can be disabled if the configuration requires custom Python types or is otherwise not compatible with safe mode. Loading configuration files with safe mode off is not secure and should not be done with files from untrusted sources.
  • db – An optional Database to store experiments and results.
  • name – A name for this model, given as an alphanumeric string. The name is required by ema_workbench operations. If not given, “GBNRTC” is used.

Implementation-Specific Methods

These methods are defined specifically in this GBNRTC-specific class, in order to interface with the TransCAD model for the GBNRTC region.

GBNRTCModel.setup(params: dict)[source]

Configure the core model with the experiment variable values

Parameters:params (dict) – experiment variables including both exogenous uncertainty and policy levers
Raises:KeyError – if experiment variable defined is not supported by the core model
GBNRTCModel.start_transcad()[source]

Launch TransCAD and call methods to reset scenario

GBNRTCModel.run()[source]

Launches TransCAD and runs the model

Model should be prepared using setup first.

Raises:UserWarning – If model is not properly setup.
GBNRTCModel.run_model(scenario, policy)

Runs an experiment through core model.

This method overloads the run_model method given in the EMA Workbench, and provides the correct execution of a core model within the workbench framework. This function assembles and executes the steps laid out in other methods of this class, adding some useful logic to optimize the process (e.g. optionally short- circuiting runs that already have results stored in the database).

For each experiment, the core model is called to:

  1. setup experiment variables, copy files as needed, and otherwise prepare to run the core model for a particular experiment,
  2. run the experiment,
  3. post_process the result if needed to produce all relevant performance measures,
  4. archive model outputs from this experiment (optional), and
  5. load_measures from the experiment and store those measures in the associated database.

Note that this method does not return any outcomes. Outcomes are instead written into self.outcomes_output, and can be retrieved from there, or from the database at a later time.

In general, it should not be necessary to overload this method in derived classes built for particular core models. Instead, write overloaded methods for setup, run, post_process , archive, and load_measures. Moreover, in typical usage a modeler will generally not want to rely on this method directly, but instead use run_experiments to automatically run multiple experiments with one command.

Parameters:
  • scenario (Scenario) – A dict-like object that has key-value pairs for each uncertainty.
  • policy (Policy) – A dict-like object that has key-value pairs for each lever.
Raises:

UserWarning – If there are no experiments associated with this type.
GBNRTCModel.load_measures(measure_names: Optional[List[str]] = None, *, rel_output_path=None, abs_output_path=None)

Import selected measures from the core model.

This method is the place to put code that can actually reach into files in the core model’s run results and extract performance measures. It is expected that it should not do any post-processing of results (i.e. it should read from but not write to the model outputs directory).

Imports measures from active scenario

Parameters:
  • measure_names (Collection[str]) – Collection of measures to be loaded.
  • rel_output_path (str, optional) – Path to model output locations, either relative to the model_path directory (when a subclass is a type that has a model path) or as an absolute directory. If neither is given, the default value is equivalent to setting rel_output_path to ‘Outputs’.
  • abs_output_path (str, optional) – Path to model output locations, either relative to the model_path directory (when a subclass is a type that has a model path) or as an absolute directory. If neither is given, the default value is equivalent to setting rel_output_path to ‘Outputs’.
Returns:

dict of measure name and values from active scenario
Raises:

KeyError – If load_measures is not available for specified measure
GBNRTCModel.post_process(params: dict, measure_names: List[str], output_path=None)[source]

Runs post processors associated with measures.

For the GBNRTC model, this method calls TransCAD macros to generate output files.

The model should have previously been executed using the run method.

Parameters:
  • params (dict) – Dictionary of experiment variables - indices are variable names, values are the experiment settings
  • measure_names (List[str]) – List of measures to be processed
  • output_path (str) – Path to model outputs - if set to none will use local values
Raises:

KeyError – If post process is not available for specified measure
GBNRTCModel.get_experiment_archive_path(experiment_id=None, makedirs=False, parameters=None, run_id=None)

Returns a file system location to store model run outputs.

For core models with long model run times, it is recommended to store the complete model run results in an archive. This will facilitate adding additional performance measures to the scope at a later time.

Both the scope name and experiment id can be used to create the folder path.

Parameters:
  • experiment_id (int) – The experiment id, which is also the row id of the experiment in the database. If this is omitted, an experiment id is read or created using the parameters.
  • makedirs (bool, default False) – If this archive directory does not yet exist, create it.
  • parameters (dict, optional) – The parameters for this experiment, used to create or lookup an experiment id. The parameters are ignored if experiment_id is given.
  • run_id (UUID, optional) – The run_id of this model run. If not given but a run_id attribute is stored in this FilesCoreModel instance, that value is used.
Returns:

Experiment archive path (no trailing backslashes).
Return type:

str
GBNRTCModel.archive(params: dict, model_results_path: str, experiment_id: int = 0)[source]

Copies TransCAD settings, outputs and common input files

Parameters:
  • params (dict) – Dictionary of experiment variables
  • model_results_path (str) – archive path
  • experiment_id (int, optional) – The id number for this experiment.