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.

See also

pysd.py_backend.model.Macro

initialize()[source]¶: Initializes the simulation model.

See also

pysd.py_backend.model.Macro.initialize(), pysd.py_backend.model.Model.reload()

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 and model elements as columns. More detailed information and examples of usage are available at Getting Started.

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. For more information, check the documentation of pysd.py_backend.model.Macro.set_components().
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’. For more information, check the documentation of pysd.py_backend.model.Model.set_initial_condition()
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")

set_stepper(output_obj, params=None, step_vars=[], return_columns=None, return_timestamps=None, initial_condition='original', final_time=None, time_step=None, saveper=None, cache_output=True)[source]¶

Configure the model stepping behavior. Examples of usage are available at Advanced Usage.

Parameters:

output_obj (ModelOutput) – Instance of ModelOutput where the simulation results will be stored.
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.
step_vars (list) – List of variable or parameter names whose values might be updated after one or more simulation steps.
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.
return_timestamps (list, numeric, ndarray (1D) (optional)) – Timestamps in model execution at which to return state information. Defaults to model-file specified timesteps.
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.
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.

See also

pysd.py_backend.model.Model.step()

step(num_steps=1, step_vars={})[source]¶

Run a model step. Updates model variables first (optional), and then runs any number of model steps. To collect the outputs after one or more steps, use the collect method of the ModelOutput class. Examples of usage are available at Advanced Usage

Parameters:

num_steps (int) – Number of steps that the iterator should run with the values of variables defined in step_vars argument.
step_vars (dict) – Varibale names that should be updated before running the step as keys, and the actual values of the variables as values.

Return type:

None

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

Select a submodel from the original model. After selecting a submodel only the necessary stateful objects for integrating this submodel will be computed. Examples of usage are available at Advanced Usage.

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.
inplace (bool (optional)) – If True it will modify current object and will return None. If False it will create a copy of the model and return it keeping the original model unchange. Default is True.

Returns:

If inplace=False it will return a modified copy of the original model.

Return type:

None or pysd.py_backend.model.Model

Note

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

Note

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

copy(reload=False)[source]¶

Create a copy of the current model.

Parameters:: reload (bool (optional)) – If True the model will be copied without applying to it any change, the copy will simply load the model again from the translated file. This would be equivalent to doing pysd.load() with the same arguments. Otherwise, it will apply the same changes that have been applied to the original model and update the states (faithful copy). Default is False.

Warning

The copy function will load a new model from the file and apply the same changes to it. If any of these changes have replaced a variable with a function that references other variables in the model, the copy will not work properly since the function will still reference the variables in the original model, in which case the function should be redefined.

See also

pysd.py_backend.model.Model.reload()

reload()[source]¶: Reloads the model from the translated model file, so that all the parameters are back to their original value.

See also

pysd.py_backend.model.Model.copy(), pysd.py_backend.model.Model.initialize()

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}))

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.

See also

pysd.py_backend.model.Model.export_pickle()

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.

See also

pysd.py_backend.model.Model

property doc: <Mock name='mock.DataFrame' id='139763329698608'>¶: 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: dict | None¶: The dictionary of modules of the model. If the model is not split by modules it returns None.

clean_caches()[source]¶: Clean the cache 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.

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.

Examples of usage are available at Advanced Usage.

Parameters:: externals (str or pathlib.Path (optional)) – Path to the netCDF file that contains the model external objects.
Return type:: None

Note

To load externals from a netCDF file you need to have installed the optional dependency netCDF4.

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).

Examples of usage are available at Advanced Usage.

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.

Return type:

None

Note

To run this function you need to have installed the optional dependency netCDF4.

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)[source]¶

Set the value of exogenous model elements. Element values should be passed with a dictionary in the function call. Values can be numeric type or pandas Series. Series will be interpolated by integrator.

Parameters:

params (dict) –

Dictionary with the name of the elements to modify and the value that they would take. If the passed value is a float or a xarray.DataArray (must be compatible with the dimensions of the variable). In this case, the variable will have a constant value, returning the past value and broadcasting to all dimensions, if necessary. If a pandas.Series is passed, the variable will be of type data and will use the time of the model to interpolate the result having as reference the indexes of the series. In this case, the series ‘data’ can also be a float or a xarray.DataArray, as with constant values. In the case of the target using a pysd.py_backend.lookups.Lookup object, it will modify the object values to use the original arguments when being call. More detailed information and examples of usage are available at Getting Started.

To write more complex relationships, which may or may not include other model variables, a callable, e.g. a function, can be passed that takes the same arguments as the original function and returns a float or a xarray.DataArray with exactly the same dimensions as the original function. More detailed information and examples of usage are available at Advanced Usage.

Note

This function is to modify the value or equations of the variables, it won’t work properly with Stateful objects, e.g. Integ, DelayFixed… In order to modify them it will be necessary to do it manually, if you have other inputs it is recommended to modify these ones. To change their initial value pysd.py_backend.model.Model.set_initial_condition() method could be used.

Examples

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

>>> br = pandas.Series(index=range(30), data=np.sin(range(30))
>>> model.set_components({'birth_rate': br})

set_initial_value(time, initial_value)[source]¶

Set the system initial value.

Parameters:

time (float or int) – The system intial time to be set.
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.