Python model class

Model class

class pysd.py_backend.model.Model(py_model_file, data_files, initialize, missing_values)[source]

The Model class implements a stateful representation of the system. It inherits methods from the Macro class to integrate the model and access and modify model components. It also contains the main methods for running the model.

The Model object will be created with components drawn from a translated Python model file.

Parameters

  • py_model_file (str or pathlib.Path) – Filename of a model which has already been converted into a Python format.

  • data_files (dict or list or str or None) – The dictionary with keys the name of file and variables to load the data from there. Or the list of names or name of the file to search the data in. Only works for TabData type object and it is neccessary to provide it. Default is None.

  • initialize (bool) – If False, the model will not be initialize when it is loaded. Default is True.

  • missing_values (str ("warning", "error", "ignore", "keep") (optional)) – What to do with missing values. If “warning” (default) shows a warning message and interpolates the values. If “raise” raises an error. If “ignore” interpolates the values without showing anything. If “keep” it will keep the missing values, this option may cause the integration to fail, but it may be used to check the quality of the data.

initialize()[source]

Initializes the simulation model

run(params=None, return_columns=None, return_timestamps=None, initial_condition='original', final_time=None, time_step=None, saveper=None, reload=False, progress=False, flatten_output=True, cache_output=True, output_file=None)[source]

Simulate the model’s behavior over time. Return a pandas dataframe with timestamps as rows, model elements as columns.

Parameters

  • params (dict (optional)) – Keys are strings of model component names. Values are numeric or pandas Series. Numeric values represent constants over the model integration. Timeseries will be interpolated to give time-varying input.

  • return_timestamps (list, numeric, ndarray (1D) (optional)) – Timestamps in model execution at which to return state information. Defaults to model-file specified timesteps.

  • return_columns (list, 'step' or None (optional)) – List of string model component names, returned dataframe will have corresponding columns. If ‘step’ only variables with cache step will be returned. If None, variables with cache step and run will be returned. Default is None.

  • initial_condition (str or (float, dict) (optional)) – The starting time, and the state of the system (the values of all the stocks) at that starting time. ‘original’ or ‘o’uses model-file specified initial condition. ‘current’ or ‘c’ uses the state of the model after the previous execution. Other str objects, loads initial conditions from the pickle file with the given name.(float, dict) tuple lets the user specify a starting time (float) and (possibly partial) dictionary of initial values for stock (stateful) objects. Default is ‘original’.

  • final_time (float or None) – Final time of the simulation. If float, the given value will be used to compute the return_timestamps (if not given) and as a final time. If None the last value of return_timestamps will be used as a final time. Default is None.

  • time_step (float or None) – Time step of the simulation. If float, the given value will be used to compute the return_timestamps (if not given) and euler time series. If None the default value from components will be used. Default is None.

  • saveper (float or None) – Saving step of the simulation. If float, the given value will be used to compute the return_timestamps (if not given). If None the default value from components will be used. Default is None.

  • reload (bool (optional)) – If True, reloads the model from the translated model file before making changes. Default is False.

  • progress (bool (optional)) – If True, a progressbar will be shown during integration. Default is False.

  • flatten_output (bool (optional)) – If True, once the output dataframe has been formatted will split the xarrays in new columns following Vensim’s naming to make a totally flat output. Default is True. This argument will be ignored when passing a netCDF4 file path in the output_file argument.

  • cache_output (bool (optional)) – If True, the number of calls of outputs variables will be increased in 1. This helps caching output variables if they are called only once. For performance reasons, if time step = saveper it is recommended to activate this feature, if time step << saveper it is recommended to deactivate it. Default is True.

  • output_file (str, pathlib.Path or None (optional)) – Path of the file in which to save simulation results. Currently, csv, tab and nc (netCDF4) files are supported.

Examples

>>> model.run(params={'exogenous_constant': 42})
>>> model.run(params={'exogenous_variable': timeseries_input})
>>> model.run(return_timestamps=[1, 2, 3, 4, 10])
>>> model.run(return_timestamps=10)
>>> model.run(return_timestamps=np.linspace(1, 10, 20))
>>> model.run(output_file="results.nc")

See also

pysd.set_components

handles setting model parameters

pysd.set_initial_condition

handles setting initial conditions

select_submodel(vars=[], modules=[], exogenous_components={})[source]

Select a submodel from the original model. After selecting a submodel only the necessary stateful objects for integrating this submodel will be computed.

Parameters

  • vars (set or list of strings (optional)) – Variables to include in the new submodel. It can be an empty list if the submodel is only selected by module names. Default is an empty list.

  • modules (set or list of strings (optional)) – Modules to include in the new submodel. It can be an empty list if the submodel is only selected by variable names. Default is an empty list. Can select a full module or a submodule by passing the path without the .py, e.g.: “view_1/submodule1”.

  • exogenous_components (dictionary of parameters (optional)) – Exogenous value to fix to the model variables that are needed to run the selected submodel. The exogenous_components should be passed as a dictionary in the same way it is done for set_components method. By default it is an empty dict and the needed exogenous components will be set to a numpy.nan value.

Returns

Return type

None

Notes

modules can be only passed when the model has been split in different files during translation.

Examples

>>> model.select_submodel(
...     vars=["Room Temperature", "Teacup temperature"])
UserWarning: Selecting submodel, to run the full model again use model.reload()

>>> model.select_submodel(
...     modules=["view_1", "view_2/subview_1"])
UserWarning: Selecting submodel, to run the full model again use model.reload()
UserWarning: Exogenous components for the following variables are necessary but not given:
    initial_value_stock1, stock3

>>> model.select_submodel(
...     vars=["stock3"],
...     modules=["view_1", "view_2/subview_1"])
UserWarning: Selecting submodel, to run the full model again use model.reload()
UserWarning: Exogenous components for the following variables are necessary but not given:
    initial_value_stock1, initial_value_stock3
Please, set them before running the model using set_components method...

>>> model.select_submodel(
...     vars=["stock3"],
...     modules=["view_1", "view_2/subview_1"],
...     exogenous_components={
...         "initial_value_stock1": 3,
...         "initial_value_stock3": 5})
UserWarning: Selecting submodel, to run the full model again use model.reload()
get_dependencies(vars=[], modules=[])[source]

Get the dependencies of a set of variables or modules.

Parameters

  • vars (set or list of strings (optional)) – Variables to get the dependencies from. It can be an empty list if the dependencies are computed only using modules. Default is an empty list.

  • modules (set or list of strings (optional)) – Modules to get the dependencies from. It can be an empty list if the dependencies are computed only using variables. Default is an empty list. Can select a full module or a submodule by passing the path without the .py, e.g.: “view_1/submodule1”.

Returns

dependencies – Dependencies data object.

Return type

pysd.py_backend.utils.Dependencies

Notes

modules can be only passed when the model has been split in different files during translation.

Examples

>>> print(model.get_dependencies(
...     vars=["Room Temperature", "Teacup temperature"]))
Selected variables (total 1):
    room_temperature, teacup_temperature
Stateful objects integrated with the selected variables (total 1):
    _integ_teacup_temperature

>>> print(model.get_dependencies(
...     modules=["view_1", "view_2/subview_1"]))
Selected variables (total 4):
    var1, var2, stock1, delay1
Dependencies for initialization only (total 1):
    initial_value_stock1
Dependencies that may change over time (total 2):
    stock3
Stateful objects integrated with the selected variables (total 1):
    _integ_stock1, _delay_fixed_delay1

>>> print(model.get_dependencies(
...     vars=["stock3"],
...     modules=["view_1", "view_2/subview_1"]))
Selected variables (total 4):
    var1, var2, stock1, stock3, delay1
Dependencies for initialization only (total 1):
    initial_value_stock1, initial_value_stock3
Stateful objects integrated with the selected variables (total 1):
    _integ_stock1, _integ_stock3, _delay_fixed_delay1
get_vars_in_module(module)[source]

Return the name of Python vars in a module.

Parameters

module (str) – Name of the module to search in.

Returns

vars – Set of varible names in the given module.

Return type

set

reload()[source]

Reloads the model from the translated model file, so that all the parameters are back to their original value.

set_initial_condition(initial_condition)[source]

Set the initial conditions of the integration.

Parameters

initial_condition (str or (float, dict) or pathlib.Path) – The starting time, and the state of the system (the values of all the stocks) at that starting time. ‘original’ or ‘o’uses model-file specified initial condition. ‘current’ or ‘c’ uses the state of the model after the previous execution. Other str objects, loads initial conditions from the pickle file with the given name.(float, dict) tuple lets the user specify a starting time (float) and (possibly partial) dictionary of initial values for stock (stateful) objects.

Examples

>>> model.set_initial_condition('original')
>>> model.set_initial_condition('current')
>>> model.set_initial_condition('exported_pickle.pic')
>>> model.set_initial_condition((10, {'teacup_temperature': 50}))

See also

model.set_initial_value

Macro class

class pysd.py_backend.model.Macro(py_model_file, params=None, return_func=None, time=None, time_initialization=None, data_files=None, py_name=None)[source]

The Macro class implements a stateful representation of the system, and contains the majority of methods for accessing and modifying components.

When the instance in question also serves as the root model object (as opposed to a macro or submodel within another model) it will have added methods to facilitate execution.

The Macro object will be created with components drawn from a translated Python model file.

Parameters

  • py_model_file (str or pathlib.Path) – Filename of a model or macro which has already been converted into a Python format.

  • params (dict or None (optional)) – Dictionary of the macro parameters. Default is None.

  • return_func (str or None (optional)) – The name of the function to return from the macro. Default is None.

  • time (components.Time or None (optional)) – Time object for integration. If None a new time object will be generated (for models), if passed the time object will be used (for macros). Default is None.

  • time_initialization (callable or None) – Time to set at the begginning of the Macro. Default is None.

  • data_files (dict or list or str or None) – The dictionary with keys the name of file and variables to load the data from. Or the list of names or name of the file to search the data in. Only works for TabData type object and it is neccessary to provide it. Default is None.

  • py_name (str or None) – The name of the Macro object. Default is None.

property doc: <Mock name='mock.DataFrame' id='140394110350672'>

The documentation of the model.

property namespace: dict

The namespace dictionary of the model.

property dependencies: dict

The dependencies dictionary of the model.

property subscripts: dict

The subscripts dictionary of the model.

property modules: Optional[dict]

The dictionary of modules of the model. If the model is not split by modules it returns None.

clean_caches()[source]

Clean the cahce of the object and the macros objects that it contains

get_pysd_compiler_version()[source]

Returns the version of pysd complier that used for generating this model

initialize()[source]

This function initializes the external objects and stateful objects in the given order.

export(file_name)[source]

Export stateful values to pickle file.

Parameters

file_name (str or pathlib.Path) – Name of the file to export the values.

import_pickle(file_name)[source]

Import stateful values from pickle file.

Parameters

file_name (str or pathlib.Path) – Name of the file to import the values from.

initialize_external_data(externals=None)[source]

Initializes external data.

If a path to a netCDF file containing serialized values of some or all of the model external data is passed in the external argument, those will be loaded from the file.

To get the full performance gain of loading the externals from a netCDF file, the model should be loaded with initialize=False first.

Parameters

externals (str or pathlib.Path (optional)) – Path to the netCDF file that contains the model external objects.

Returns

Return type

None

serialize_externals(export_path='externals.nc', include_externals='all', exclude_externals=None)[source]

Stores a netCDF file with the data and metadata for all model external objects.

This method is useful for models with lots of external inputs, which are slow to load into memory. Once exported, the resulting netCDF file can be passed as argument to the initialize_external_data method.

Names of variables should be those in the model (python safe, without the _ext_type_ string in front).

Parameters

  • export_path (str or pathlib.Path (optional)) – Path of the resulting .nc file.

  • include_externals (list or str (optional)) – External objects to export to netCDF. If ‘all’, then all externals are exported to the .nc file. The argument also accepts a list containing spreadsheet file names, external variable names or a combination of both. If a spreadsheet file path is passed, all external objects defined in it will be included in the .nc file. Spreadsheet tab names are not currently supported, because the same may be used in different files. Better customisation can be achieved by combining the include_externals and exclude_externals (see description below) arguments.

  • exclude_externals (list or None (optional)) – Exclude external objects from being included in the exported nc file. It accepts either variable names, spreadsheet files or a combination of both.

Returns

Return type

None

get_args(param)[source]

Returns the arguments of a model element.

Parameters

param (str or func) – The model element name or function.

Returns

args – List of arguments of the function.

Return type

list

Examples

>>> model.get_args('birth_rate')
>>> model.get_args('Birth Rate')
get_coords(param)[source]

Returns the coordinates and dims of a model element.

Parameters

param (str or func) – The model element name or function.

Returns

(coords, dims) or None – The coords and the dimensions of the element if it has. Otherwise, returns None.

Return type

(dict, list) or None

Examples

>>> model.get_coords('birth_rate')
>>> model.get_coords('Birth Rate')
get_series_data(param)[source]

Returns the original values of a model lookup/data component.

Parameters

param (str) – The model lookup/data element name.

Returns

value – Array with the value of the interpolating series in the first dimension.

Return type

xarray.DataArray

Examples

>>> model['room_temperature']
>>> model['Room temperature']
set_components(params, new=False)[source]

Set the value of exogenous model elements. Element values can be passed as keyword=value pairs in the function call. Values can be numeric type or pandas Series. Series will be interpolated by integrator.

Examples

>>> model.set_components({'birth_rate': 10})
>>> model.set_components({'Birth Rate': 10})

>>> br = pandas.Series(index=range(30), values=np.sin(range(30))
>>> model.set_components({'birth_rate': br})
set_initial_value(t, initial_value)[source]

Set the system initial value.

Parameters

  • t (numeric) – The system time

  • initial_value (dict) – A (possibly partial) dictionary of the system initial values. The keys to this dictionary may be either pysafe names or original model file names

set_stateful(stateful_dict)[source]

Set stateful values.

Parameters

stateful_dict (dict) – Dictionary of the stateful elements and the attributes to change.