Internal Functions

This section documents the functions that are going on behaind the scenes, for the benefit of developers.

Special functions needed for model execution

Model components and time managing classes.

class pysd.py_backend.components.Components(py_model_file, set_components)[source]
Workaround class to let the user do:
model.components.var = value
_load(py_model_file)[source]

Load model components.

Parameters:py_model_file (str) – Model file to be loaded.
Returns:components – The imported file content.
Return type:module
_set_component(name, value)[source]

Replaces the previous setter.

class pysd.py_backend.components.Time[source]
add_return_timestamps(return_timestamps)[source]

Add return timestamps

in_bounds()[source]

Check if time is smaller than current final time value.

Returns:True if time is smaller than final time. Otherwise, returns Fase.
Return type:bool
in_return()[source]

Check if current time should be returned

reset()[source]

Reset time value to the initial

set_control_vars(**kwargs)[source]

Set the control variables valies

Parameters:**kwards
initial_time: float, callable or None
Initial time.
final_time: float, callable or None
Final time.
time_step: float, callable or None
Time step.
saveper: float, callable or None
Saveper.
update(value)[source]

Update current time value

The stateful objects are used and updated each time step with an update method. This include from basic Integ class objects until the Model class objects.

class pysd.py_backend.statefuls.Delay(delay_input, delay_time, initial_value, order, tstep, py_name)[source]

Implements DELAY function

ddt()[source]
export()[source]
initialize(init_val=None)[source]
class pysd.py_backend.statefuls.DelayFixed(delay_input, delay_time, initial_value, tstep, py_name)[source]

Implements DELAY FIXED function

ddt()[source]
export()[source]
initialize(init_val=None)[source]
update(state)[source]
class pysd.py_backend.statefuls.DelayN(delay_input, delay_time, initial_value, order, tstep, py_name)[source]

Implements DELAY N function

ddt()[source]
export()[source]
initialize(init_val=None)[source]
class pysd.py_backend.statefuls.DynamicStateful[source]
update(state)[source]
class pysd.py_backend.statefuls.Forecast(forecast_input, average_time, horizon, py_name)[source]

Implements FORECAST function

ddt()[source]
export()[source]
initialize(init_val=None)[source]
class pysd.py_backend.statefuls.Initial(initial_value, py_name)[source]

Implements INITIAL function

export()[source]
initialize(init_val=None)[source]
class pysd.py_backend.statefuls.Integ(ddt, initial_value, py_name)[source]

Implements INTEG function

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

The Model class implements a stateful representation of the system, and contains the majority of methods for accessing and modifying model 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.

_add_constant_cache()[source]
_assign_cache(element)[source]

Assigns the cache type to the given element and its dependencies if needed.

Parameters:element (str) – Element name.
Returns:
Return type:None
_assign_cache_type()[source]

Assigns the cache type to all the elements from the namespace.

_constant_component(value, dims, args=[])[source]

Internal function for creating a constant model element

_count_calls(element)[source]
_get_data(data_files)[source]
_get_elements_to_initialize(modified_statefuls)[source]
_get_full_dependencies(element, dep_set, stateful_deps)[source]

Get all dependencies of an element, i.e., also get the dependencies of the dependencies. When finding an stateful element only dependencies for initialization are considered.

Parameters:
  • element (str) – Element to get the full dependencies.
  • dep_set (set) – Set to include the dependencies of the element.
  • stateful_deps ("initial" or "step") – The type of dependencies to take in the case of stateful objects.
Returns:

Return type:

None

_get_initialize_order()[source]

Get the initialization order of the stateful elements and their the full dependencies.

_isdynamic(dependencies)[source]
Parameters:dependencies (iterable) – List of dependencies.
Returns:isdynamic – True if ‘time’ or a dynamic stateful objects is in dependencies.
Return type:bool
_remove_constant_cache()[source]
_timeseries_component(series, dims, args=[])[source]

Internal function for creating a timeseries model element

clean_caches()[source]
ddt()[source]
doc()[source]

Formats a table of documentation strings to help users remember variable names, and understand how they are translated into python safe names.

Returns:docs_df
Dataframe with columns for the model components:
  • Real names
  • Python safe identifiers (as used in model.components)
  • Units string
  • Documentation strings from the original model file
Return type:pandas dataframe
export(file_name)[source]

Export stateful values to pickle file.

Parameters:file_name (str) – Name of the file to export the values.
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_pysd_compiler_version()[source]

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

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']
import_pickle(file_name)[source]

Import stateful values from pickle file.

Parameters:file_name (str) – Name of the file to import the values from.
initialize()[source]

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

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.
state
class pysd.py_backend.statefuls.Model(py_model_file, data_files, initialize, missing_values)[source]
_add_run_elements(df, capture_elements)[source]

Adds constant elements to a dataframe.

Parameters:
  • df (pandas.DataFrame) – Dataframe to add elements.
  • capture_elements (list) – List of constant elements
Returns:

Return type:

None

_default_return_columns(which)[source]

Return a list of the model elements tha change on time that does not include lookup other functions that take parameters or run-cached functions.

Parameters:which (str or None) – If it is ‘step’ only cache step elements will be returned. Else cache ‘step’ and ‘run’ elements will be returned. Default is None.
Returns:return_columns – List of columns to return
Return type:list
_euler_step(dt)[source]

Performs a single step in the euler integration, updating stateful components

Parameters:dt (float) – This is the amount to increase time by this step
_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:

  • c_vars (set) – Set of all selected model variables.
  • d_deps (dict of sets) – Dictionary of dependencies nedded to run vars and modules.
  • s_deps (set) – Set of stateful objects to update when integrating selected model variables.

_integrate(capture_elements)[source]

Performs euler integration.

Parameters:capture_elements (set) – Which model elements to capture - uses pysafe names.
Returns:outputs – Output capture_elements data.
Return type:pandas.DataFrame
_split_capture_elements(capture_elements)[source]

Splits the capture elements list between those with run cache and others.

Parameters:capture_elements (list) – Captured elements list
Returns:capture_dict – Dictionary of sets with keywords step and run.
Return type:dict
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 – Set of dependencies nedded to run vars.

Return type:

set

Notes

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

Examples

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

Initializes the simulation model

reload()[source]

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

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=False, cache_output=True)[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 False.
  • 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.

Examples

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

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()
set_initial_condition(initial_condition)[source]

Set the initial conditions of the integration.

Parameters:initial_condition (str or (float, dict)) – 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()

class pysd.py_backend.statefuls.SampleIfTrue(condition, actual_value, initial_value, py_name)[source]
ddt()[source]
export()[source]
initialize(init_val=None)[source]
update(state)[source]
class pysd.py_backend.statefuls.Smooth(smooth_input, smooth_time, initial_value, order, py_name)[source]

Implements SMOOTH function

ddt()[source]
export()[source]
initialize(init_val=None)[source]
class pysd.py_backend.statefuls.Stateful[source]
state
class pysd.py_backend.statefuls.Trend(trend_input, average_time, initial_trend, py_name)[source]

Implements TREND function

ddt()[source]
export()[source]
initialize(init_val=None)[source]

These functions have no direct analog in the standard python data analytics stack, or require information about the internal state of the system beyond what is present in the function call. We provide them in a structure that makes it easy for the model elements to call.

pysd.py_backend.functions.active_initial(time, expr, init_val)[source]

Implements vensim’s ACTIVE INITIAL function :param time: The current time function :type time: function :param expr: :param init_val:

pysd.py_backend.functions.bounded_normal(minimum, maximum, mean, std, seed)[source]

Implements vensim’s BOUNDED NORMAL function

pysd.py_backend.functions.if_then_else(condition, val_if_true, val_if_false)[source]

Implements Vensim’s IF THEN ELSE function. https://www.vensim.com/documentation/20475.htm

Parameters:
  • condition (bool or xarray.DataArray of bools) –
  • val_if_true (function) – Value to evaluate and return when condition is true.
  • val_if_false (function) – Value to evaluate and return when condition is false.
Returns:

Return type:

The value depending on the condition.

pysd.py_backend.functions.incomplete(*args)[source]
pysd.py_backend.functions.integer(x)[source]

Implements Vensim’s INTEGER function.

Parameters:x (float or xarray.DataArray) – Input value.
Returns:
Return type:Returns integer part of x.
pysd.py_backend.functions.invert_matrix(mat)[source]

Implements Vensim’s INVERT MATRIX function.

Invert the matrix defined by the last two dimensions of xarray.DataArray.

Parameters:mat (xarray.DataArray) – The matrix to invert.
Returns:mat1 – Inverted matrix.
Return type:xarray.DataArray
pysd.py_backend.functions.log(x, base)[source]

Implements Vensim’s LOG function with change of base.

Parameters:
  • x (float or xarray.DataArray) – Input value.
  • base (float or xarray.DataArray) – Base of the logarithm.
Returns:

The log of ‘x’ in base ‘base’.

Return type:

float

pysd.py_backend.functions.logical_and(*args)[source]

Implements Vensim’s :AND: method for two or several arguments.

Parameters:*args (arguments) – The values to compare with and operator
Returns:result – The result of the comparison.
Return type:bool or xarray.DataArray
pysd.py_backend.functions.logical_or(*args)[source]

Implements Vensim’s :OR: method for two or several arguments.

Parameters:*args (arguments) – The values to compare with and operator
Returns:result – The result of the comparison.
Return type:bool or xarray.DataArray
pysd.py_backend.functions.lookup(x, xs, ys)[source]

Intermediate values are calculated with linear interpolation between the intermediate points. Out-of-range values are the same as the closest endpoint (i.e, no extrapolation is performed).

pysd.py_backend.functions.lookup_discrete(x, xs, ys)[source]

Intermediate values take on the value associated with the next lower x-coordinate (also called a step-wise function). The last two points of a discrete graphical function must have the same y value. Out-of-range values are the same as the closest endpoint (i.e, no extrapolation is performed).

pysd.py_backend.functions.lookup_extrapolation(x, xs, ys)[source]

Intermediate values are calculated with linear interpolation between the intermediate points. Out-of-range values are calculated with linear extrapolation from the last two values at either end.

pysd.py_backend.functions.modulo(x, m)[source]

Implements Vensim’s MODULO function.

Parameters:
  • x (float or xarray.DataArray) – Input value.
  • m (float or xarray.DataArray) – Modulo to compute.
Returns:

  • Returns x modulo m, if x is smaller than 0 the result is given in
  • the range (-m, 0] as Vensim does. x - quantum(x, m)

pysd.py_backend.functions.not_implemented_function(*args)[source]
pysd.py_backend.functions.prod(x, dim=None)[source]

Implements Vensim’s PROD function.

Parameters:
  • x (xarray.DataArray) – Input value.
  • dim (list of strs (optional)) – Dimensions to apply the function over. If not given the function will be applied over all dimensions.
Returns:

The result of the product operation in the given dimensions.

Return type:

xarray.DataArray or float

pysd.py_backend.functions.pulse(time, start, duration)[source]

Implements vensim’s PULSE function.

Parameters:
  • time (function) – Function that returns the current time.
  • start (float) – Starting time of the pulse.
  • duration (float) – Duration of the pulse.
Returns:

  • In range [-inf, start):
    returns 0
  • In range [start, start + duration):
    returns 1
  • In range [start + duration, +inf]:
    returns 0

Return type:

float

pysd.py_backend.functions.pulse_magnitude(time, magnitude, start, repeat_time=0)[source]

Implements xmile’s PULSE function. Generate a one-DT wide pulse at the given time.

Parameters:
  • time (function) – Function that returns the current time.
  • magnitude – Magnitude of the pulse.
  • start (float) – Starting time of the pulse.
  • repeat_time (float (optional)) – Time interval of the pulse repetition. Default is 0, only one pulse will be generated.

Notes

PULSE(time(), 20, 12, 5) generates a pulse value of 20/DT at time 12, 17, 22, etc.

Returns:
  • In rage [-inf, start):
    returns 0
  • In range [start + n*repeat_time, start + n*repeat_time + dt):
    returns magnitude/dt
  • In rage [start + n*repeat_time + dt, start + (n+1)*repeat_time):
    returns 0
Return type:float
pysd.py_backend.functions.pulse_train(time, start, duration, repeat_time, end)[source]

Implements vensim’s PULSE TRAIN function.

Parameters:
  • time (function) – Function that returns the current time.
  • start (float) – Starting time of the pulse.
  • duration (float) – Duration of the pulse.
  • repeat_time (float) – Time interval of the pulse repetition.
  • end (float) – Final time of the pulse.
Returns:

  • In range [-inf, start):

    returns 0

  • In range [start + n*repeat_time, start + n*repeat_time + duration):

    returns 1

  • In range [start + n*repeat_time + duration,

    start + (n+1)*repeat_time):

    returns 0

Return type:

float

pysd.py_backend.functions.quantum(a, b)[source]

Implements Vensim’s QUANTUM function.

Parameters:
  • a (float or xarray.DataArray) – Input value.
  • b (float or xarray.DataArray) – Input value.
Returns:

quantum – If b > 0 returns b * integer(a/b). Otherwise, returns a.

Return type:

float or xarray.DataArray

pysd.py_backend.functions.ramp(time, slope, start, finish=0)[source]

Implements vensim’s and xmile’s RAMP function.

Parameters:
  • time (function) – The current time of modelling.
  • slope (float) – The slope of the ramp starting at zero at time start.
  • start (float) – Time at which the ramp begins.
  • finish (float) – Optional. Time at which the ramp ends.
Returns:

response – If prior to ramp start, returns zero. If after ramp ends, returns top of ramp.

Return type:

float

pysd.py_backend.functions.step(time, value, tstep)[source]

” Implements vensim’s STEP function.

Parameters:
  • value (float) – The height of the step.
  • tstep (float) – The time at and after which result equals value.
Returns:

  • In range [-inf, tstep):
    returns 0
  • In range [tstep, +inf]:
    returns value

Return type:

float

pysd.py_backend.functions.sum(x, dim=None)[source]

Implements Vensim’s SUM function.

Parameters:
  • x (xarray.DataArray) – Input value.
  • dim (list of strs (optional)) – Dimensions to apply the function over. If not given the function will be applied over all dimensions.
Returns:

The result of the sum operation in the given dimensions.

Return type:

xarray.DataArray or float

pysd.py_backend.functions.vmax(x, dim=None)[source]

Implements Vensim’s VMAX function.

Parameters:
  • x (xarray.DataArray) – Input value.
  • dim (list of strs (optional)) – Dimensions to apply the function over. If not given the function will be applied over all dimensions.
Returns:

The result of the maximum value over the dimensions.

Return type:

xarray.DataArray or float

pysd.py_backend.functions.vmin(x, dim=None)[source]

Implements Vensim’s Vmin function.

Parameters:
  • x (xarray.DataArray) – Input value.
  • dim (list of strs (optional)) – Dimensions to apply the function over. If not given the function will be applied over all dimensions.
Returns:

The result of the minimum value over the given dimensions.

Return type:

xarray.DataArray or float

pysd.py_backend.functions.xidz(numerator, denominator, value_if_denom_is_zero)[source]

Implements Vensim’s XIDZ function. https://www.vensim.com/documentation/fn_xidz.htm

This function executes a division, robust to denominator being zero. In the case of zero denominator, the final argument is returned.

Parameters:
  • numerator (float or xarray.DataArray) –
  • denominator (float or xarray.DataArray) – Components of the division operation
  • value_if_denom_is_zero (float or xarray.DataArray) – The value to return if the denominator is zero
Returns:

  • numerator / denominator if denominator > 1e-6
  • otherwise, returns value_if_denom_is_zero

pysd.py_backend.functions.zidz(numerator, denominator)[source]

This function bypasses divide-by-zero errors, implementing Vensim’s ZIDZ function https://www.vensim.com/documentation/fn_zidz.htm

Parameters:
  • numerator (float or xarray.DataArray) – value to be divided
  • denominator (float or xarray.DataArray) – value to devide by
Returns:

  • result of division numerator/denominator if denominator is not zero,
  • otherwise zero.

These are general utilities used by the builder.py, functions.py or the model file. Vensim’s function equivalents should not go here but in functions.py

class pysd.py_backend.utils.ProgressBar(maxval=None)[source]

Progress bar for integration

finish()[source]

Finish progress bar

update()[source]

Update progress bar

pysd.py_backend.utils._add_flat(savedict, name, values)[source]

Add float lists from a list of xarrays to a provided dictionary.

Parameters:
  • savedict (dict) – Dictionary to save the data on.
  • name (str) – The base name of the variable to save the data.
  • values (list) – List of xarrays to convert to split in floats.
Returns:

Return type:

None

pysd.py_backend.utils.compute_shape(coords, reshape_len=None, py_name='')[source]

Computes the ‘shape’ of a coords dictionary. Function used to rearange data in xarrays and to compute the number of rows/columns to be read in a file.

Parameters:
  • coords (dict) – Ordered dictionary of the dimension names as a keys with their values.
  • reshape_len (int (optional)) – Number of dimensions of the output shape. The shape will ony compute the corresponent table dimensions to read from Excel, then, the dimensions with length one will be ignored at first. Lately, it will complete with 1 on the left of the shape if the reshape_len value is bigger than the length of shape. Will raise a ValueError if we try to reshape to a reshape_len smaller than the initial shape.
  • py_name (str) – Name to print if an error is raised.
Returns:

shape – Shape of the ordered dictionary or of the desired table or vector.

Return type:

list

Note

Dictionaries in Python >= 3.7 are ordered, which means that we could remove dims if there is a not backward compatible version of the library which only works in Python 3.7+. For now, the dimensions list is passed to make it work properly for all the users.

pysd.py_backend.utils.detect_encoding(filename)[source]

Detects the encoding of a file.

Parameters:filename (str) – Name of the file to detect the encoding.
Returns:encoding – The encoding of the file.
Return type:str
pysd.py_backend.utils.get_key_and_value_by_insensitive_key_or_value(key, dict)[source]

Providing a key or value in a dictionary search for the real key and value in the dictionary ignoring case sensitivity.

Parameters:
  • key (str) – Key or value to look for in the dictionary.
  • dict (dict) – Dictionary to search in.
Returns:

real key, real value – The real key and value that appear in the dictionary or a tuple of Nones if the input key is not in the dictionary.

Return type:

(str, str) or (None, None)

pysd.py_backend.utils.get_return_elements(return_columns, namespace)[source]

Takes a list of return elements formatted in vensim’s format Varname[Sub1, SUb2] and returns first the model elements (in python safe language) that need to be computed and collected, and secondly the addresses that each element in the return columns list translates to

Parameters:
  • return_columns (list of strings) –
  • namespace (dict) –
Returns:

  • capture_elements
  • return_addresses

pysd.py_backend.utils.load_model_data(root, model_name)[source]

Used for models split in several files. Loads subscripts_dic, namespace and modules dictionaries

Parameters:
  • root (pathlib.Path or str) – Path to the model file.
  • model_name (str) – Name of the model without file type extension (e.g. “my_model”).
Returns:

  • namespace (dict) – Translation from original model element names (keys) to python safe function identifiers (values).
  • subscripts (dict) – Dictionary describing the possible dimensions of the stock’s subscripts.
  • modules (dict) – Dictionary containing view (module) names as keys and a list of the corresponding variables as values.

pysd.py_backend.utils.load_modules(module_name, module_content, work_dir, submodules)[source]

Used to load model modules from the main model file, when split_views=True in the read_vensim function. This function is used to iterate over the different layers of the nested dictionary that describes which model variables belong to each module/submodule.

Parameters:
  • module_name (str) – Name of the module to load.
  • module_content (dict or list) – Content of the module. If it’s a dictionary, it means that the module has submodules, whereas if it is a list it means that that particular module/submodule is a final one.
  • work_dir (str) – Path to the module file.
  • submodules (list) – This list gets updated at every recursive iteration, and each element corresponds to the string representation of each module/submodule that is read.
Returns:

String representations of the modules/submodules to execute in the main model file.

Return type:

str

pysd.py_backend.utils.load_outputs(file_name, transpose=False, columns=None, encoding=None)[source]

Load outputs file

Parameters:
  • file_name (str) – Output file to read. Must be csv or tab.
  • transpose (bool (optional)) – If True reads transposed outputs file, i.e. one variable per row. Default is False.
  • columns (list or None (optional)) – List of the column names to load. If None loads all the columns. Default is None. NOTE: if transpose=False, the loading will be faster as only selected columns will be loaded. If transpose=True the whole file must be read and it will be subselected later.
  • encoding (str or None (optional)) – Encoding type to read output file. Needed if the file has special characters. Default is None.
Returns:

A pandas.DataFrame with the outputs values.

Return type:

pandas.DataFrame

pysd.py_backend.utils.make_flat_df(df, return_addresses, flatten=False)[source]

Takes a dataframe from the outputs of the integration processes, renames the columns as the given return_adresses and splits xarrays if needed.

Parameters:
  • df (Pandas.DataFrame) – Output from the integration.
  • return_addresses (dict) – Keys will be column names of the resulting dataframe, and are what the user passed in as ‘return_columns’. Values are a tuple: (py_name, {coords dictionary}) which tells us where to look for the value to put in that specific column.
  • flatten (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 False.
Returns:

new_df – Formatted dataframe.

Return type:

pandas.DataFrame

pysd.py_backend.utils.print_objects_format(object_set, text)[source]

Return a printable version of the variables in object_sect with the header given with text.

pysd.py_backend.utils.rearrange(data, dims, coords)[source]

Returns a xarray.DataArray object with the given coords and dims

Parameters:
  • data (float or xarray.DataArray) – The input data to rearrange.
  • dims (list) – Ordered list of the dimensions.
  • coords (dict) – Dictionary of the dimension names as a keys with their values.
Returns:

Return type:

xarray.DataArray

pysd.py_backend.utils.xrmerge(*das)[source]

Merges xarrays with different dimension sets.

Parameters:*das (xarray.DataArrays) – The data arrays to merge.
Returns:da – Merged data array.
Return type:xarray.DataArray

References

Thanks to @jcmgray https://github.com/pydata/xarray/issues/742#issue-130753818

In the future, we may not need this as xarray may provide the merge for us.

pysd.py_backend.utils.xrsplit(array)[source]

Split an array to a list of all the components.

Parameters:array (xarray.DataArray) – Array to split.
Returns:sp_list – List of shape 0 xarray.DataArrays with coordinates.
Return type:list of xarray.DataArrays

Building the python model file

These elements are used by the translator to construct the model from the interpreted results. It is technically possible to use these functions to build a model from scratch. But - it would be rather error prone.

This is code to assemble a pysd model once all of the elements have been translated from their native language into python compatible syntax. There should be nothing here that has to know about either vensim or xmile specific syntax.

class pysd.translation.builder.Imports[source]

Class to save the imported modules information for intelligent import

_data = {}
_external = {}
_external_libs = {'numpy': 'np', 'xarray': 'xr'}
_functions = {}
_internal_libs = ['functions', 'statefuls', 'external', 'data', 'utils']
_numpy = False
_statefuls = {}
_subs = False
_utils = {}
_xarray = False
classmethod add(module, function=None)[source]

Add a function from module.

Parameters:
  • module (str) – module name.
  • function (str or None) – function name. If None module will be set to true.
classmethod get_header(outfile)[source]

Returns the importing information to print in the model file

Parameters:outfile (str) – Name of the outfile to print in the header.
Returns:text – Header of the translated model file.
Return type:str
classmethod reset()[source]

Reset the imported modules

pysd.translation.builder._build_main_module(elements, subscript_dict, file_name)[source]

Constructs and writes the python representation of the main model module, when the split_views=True in the read_vensim function.

Parameters:
  • elements (list) – Elements belonging to the main module. Ideally, there should only be the initial_time, final_time, saveper and time_step, functions, though there might be others in some situations. Each element is a dictionary, with the various components needed to assemble a model component in python syntax. This will contain multiple entries for elements that have multiple definitions in the original file, and which need to be combined.
  • subscript_dict (dict) – A dictionary containing the names of subscript families (dimensions) as keys, and a list of the possible positions within that dimension for each value.
  • file_name (str) – Path of the file where the main module will be stored.
Returns:

None or text – If file_name=”return” it will return the content of the output file instead of saving it. It is used for testing.

Return type:

None or str

pysd.translation.builder._build_separate_module(elements, subscript_dict, module_name, module_dir)[source]

Constructs and writes the python representation of a specific model module, when the split_views=True in the read_vensim function

Parameters:
  • elements (list) – Elements belonging to the module module_name. Each element is a dictionary, with the various components needed to assemble a model component in python syntax. This will contain multiple entries for elements that have multiple definitions in the original file, and which need to be combined.
  • subscript_dict (dict) – A dictionary containing the names of subscript families (dimensions) as keys, and a list of the possible positions within that dimension for each value.
  • module_name (str) – Name of the module
  • module_dir (str) – Path of the directory where module files will be stored.
Returns:

Return type:

None

pysd.translation.builder._build_variables(elements, subscript_dict)[source]

Build model variables (functions) and separate then in control variables and regular variables.

Parameters:
  • elements (list) – Model elements.
  • subscript_dict
Returns:

control_vars, regular_vars – control_vars is a tuple of length 2. First element is the dictionary of original control vars. Second is the string to add the control variables’ functions. regular_vars is the string to add the regular variables’ functions.

Return type:

tuple, str

pysd.translation.builder._generate_functions(elements, subscript_dict)[source]

Builds all model elements as functions in string format. NOTE: this function calls the build_element function, which updates the import_modules. Therefore, it needs to be executed before the_generate_automatic_imports function.

Parameters:
  • elements (dict) – Each element is a dictionary, with the various components needed to assemble a model component in python syntax. This will contain multiple entries for elements that have multiple definitions in the original file, and which need to be combined.
  • subscript_dict (dict) – A dictionary containing the names of subscript families (dimensions) as keys, and a list of the possible positions within that dimension for each value.
Returns:

funcs – String containing all formated model functions

Return type:

str

pysd.translation.builder._get_control_vars(control_vars)[source]

Create the section of control variables

Parameters:control_vars (str) – Functions to define control variables.
Returns:text – Control variables section and header of model variables section.
Return type:str
pysd.translation.builder._merge_dependencies(current, new)[source]

Merge two dependencies dicts of an element.

Parameters:
  • current (dict) – Current dependencies of the element. It will be mutated.
  • new (dict) – New dependencies to add.
Returns:

Return type:

None

pysd.translation.builder.add_delay(identifier, delay_input, delay_time, initial_value, order, subs, merge_subs, deps)[source]

Creates code to instantiate a stateful ‘Delay’ object, and provides reference to that object’s output.

The name of the stateful object is based upon the passed in parameters, so if there are multiple places where identical delay functions are referenced, the translated python file will only maintain one stateful object, and reference it multiple times.

Parameters:
  • identifier (str) – The python-safe name of the delay.
  • delay_input (str) – Reference to the model component that is the input to the delay.
  • delay_time (str) – Can be a number (in string format) or a reference to another model element which will calculate the delay. This is calculated throughout the simulation at runtime.
  • initial_value (str) – This is used to initialize the stocks that are present in the delay. We initialize the stocks with equal values so that the outflow in the first timestep is equal to this value.
  • order (str) – The number of stocks in the delay pipeline. As we construct the delays at build time, this must be an integer and cannot be calculated from other model components. Anything else will yield a ValueError.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output.
  • merge_subs (list of strings) – List of the final subscript range of the python array after merging with other objects.
  • deps (dict) – The dictionary with all the denpendencies in the expression.
Returns:

  • reference (str) – Reference to the delay object __call__ method, which will return the output of the delay process.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_delay_f(identifier, delay_input, delay_time, initial_value, deps)[source]

Creates code to instantiate a stateful ‘DelayFixed’ object, and provides reference to that object’s output.

The name of the stateful object is based upon the passed in parameters, so if there are multiple places where identical delay functions are referenced, the translated python file will only maintain one stateful object, and reference it multiple times.

Parameters:
  • identifier (str) – The python-safe name of the delay.
  • delay_input (str) – Reference to the model component that is the input to the delay.
  • delay_time (str) – Can be a number (in string format) or a reference to another model element which will calculate the delay. This is calculated throughout the simulation at runtime.
  • initial_value (str) – This is used to initialize the stocks that are present in the delay. We initialize the stocks with equal values so that the outflow in the first timestep is equal to this value.
  • deps (dict) – The dictionary with all the denpendencies in the expression.
Returns:

  • reference (str) – Reference to the delay object __call__ method, which will return the output of the delay process.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_ext_constant(identifier, file_name, tab, cell, subs, subscript_dict, merge_subs)[source]

Constructs a external object for handling Vensim’s GET XLS CONSTANT and GET DIRECT CONSTANT functionality.

Parameters:
  • identifier (str) – The python-safe name of the external values.
  • file_name (str) – Filepath to the data.
  • tab (str) – Tab where the data is.
  • cell (str) – Cell identifier where the data starts.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output.
  • subscript_dict (dict) – Dictionary describing the possible dimensions of the stock’s subscripts.
  • merge_subs (list of strings) – List of the final subscript range of the python array after merging with other objects.
Returns:

  • reference (str) – Reference to the ExtConstant object __call__ method, which will return the read value of the data.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_ext_data(identifier, file_name, tab, time_row_or_col, cell, subs, subscript_dict, merge_subs, keyword)[source]

Constructs a external object for handling Vensim’s GET XLS DATA and GET DIRECT DATA functionality.

Parameters:
  • identifier (str) – The python-safe name of the external values.
  • file_name (str) – Filepath to the data.
  • tab (str) – Tab where the data is.
  • time_row_or_col (str) – Identifier to the starting point of the time dimension.
  • cell (str) – Cell identifier where the data starts.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output.
  • subscript_dict (dict) – Dictionary describing the possible dimensions of the stock’s subscripts.
  • merge_subs (list of strings) – List of the final subscript range of the python array after merging with other objects.
  • keyword (str) – Data retrieval method (‘interpolate’, ‘look forward’, ‘hold backward’).
Returns:

  • reference (str) – Reference to the ExtData object __call__ method, which will return the retrieved value of data for the current time step.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_ext_lookup(identifier, file_name, tab, x_row_or_col, cell, subs, subscript_dict, merge_subs)[source]

Constructs a external object for handling Vensim’s GET XLS LOOKUPS and GET DIRECT LOOKUPS functionality.

Parameters:
  • identifier (str) – The python-safe name of the external values.
  • file_name (str) – Filepath to the data.
  • tab (str) – Tab where the data is.
  • x_row_or_col (str) – Identifier to the starting point of the lookup dimension.
  • cell (str) – Cell identifier where the data starts.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output.
  • subscript_dict (dict) – Dictionary describing the possible dimensions of the stock’s subscripts.
  • merge_subs (list of strings) – List of the final subscript range of the python array after merging with other objects.
Returns:

  • reference (str) – Reference to the ExtLookup object __call__ method, which will return the retrieved value of data after interpolating it.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_forecast(identifier, forecast_input, average_time, horizon, subs, merge_subs, deps)[source]

Constructs Forecast object.

Parameters:
  • identifier (str) – The python-safe name of the forecast.
  • forecast_input (str) – Input of the forecast.
  • average_time (str) – Average time of the forecast.
  • horizon (str) – Horizon for the forecast.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output.
  • merge_subs (list of strings) – List of the final subscript range of the python array after merging with other objects.
  • deps (dict) – The dictionary with all the denpendencies in the expression.
Returns:

  • reference (str) – Reference to the forecast object __call__ method, which will return the output of the forecast process.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_incomplete(var_name, dependencies)[source]

Incomplete functions don’t really need to be ‘builders’ as they add no new real structure, but it’s helpful to have a function in which we can raise a warning about the incomplete equation at translate time.

Parameters:
  • var_name (str) – The python-safe name of the incomplete variable.
  • dependencies (list) – The list of the dependencies in the variable.
Returns:

Inclompete funcion call.

Return type:

str

pysd.translation.builder.add_initial(identifier, value, deps)[source]

Constructs a stateful object for handling vensim’s ‘Initial’ functionality.

Parameters:
  • identifier (str) – The python-safe name of the initial.
  • value (str) – The expression which will be evaluated, and the first value of which returned.
  • deps (dict) – The dictionary with all the denpendencies in the expression.
Returns:

  • reference (str) – Reference to the Initial object __call__ method, which will return the first calculated value of identifier.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_macro(identifier, macro_name, filename, arg_names, arg_vals, deps)[source]

Constructs a stateful object instantiating a ‘Macro’.

Parameters:
  • identifier (str) – The python-safe name of the element that calls the macro.
  • macro_name (str) – Python safe name for macro.
  • filename (str) – Filepath to macro definition.
  • func_args (dict) – Dictionary of values to be passed to macro, {key: function}.
Returns:

  • reference (str) – Reference to the Initial object __call__ method, which will return the first calculated value of initial_input.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_n_delay(identifier, delay_input, delay_time, initial_value, order, subs, merge_subs, deps)[source]

Creates code to instantiate a stateful ‘DelayN’ object, and provides reference to that object’s output.

The name of the stateful object is based upon the passed in parameters, so if there are multiple places where identical delay functions are referenced, the translated python file will only maintain one stateful object, and reference it multiple times.

Parameters:
  • identifier (str) – The python-safe name of the delay.
  • delay_input (str) – Reference to the model component that is the input to the delay.
  • delay_time (str) – Can be a number (in string format) or a reference to another model element which will calculate the delay. This is calculated throughout the simulation at runtime.
  • initial_value (str) – This is used to initialize the stocks that are present in the delay. We initialize the stocks with equal values so that the outflow in the first timestep is equal to this value.
  • order (str) – The number of stocks in the delay pipeline. As we construct the delays at build time, this must be an integer and cannot be calculated from other model components. Anything else will yield a ValueError.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output.
  • merge_subs (list of strings) – List of the final subscript range of the python array after merging with other objects.
  • deps (dict) – The dictionary with all the denpendencies in the expression.
Returns:

  • reference (str) – Reference to the delay object __call__ method, which will return the output of the delay process.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_n_smooth(identifier, smooth_input, smooth_time, initial_value, order, subs, merge_subs, deps)[source]

Constructs stock and flow chains that implement the calculation of a smoothing function.

Parameters:
  • identifier (str) – The python-safe name of the smooth.
  • smooth_input (str) – Reference to the model component that is the input to the smoothing function.
  • smooth_time (str) – Can be a number (in string format) or a reference to another model element which will calculate the delay. This is calculated throughout the simulation at runtime.
  • initial_value (str) – This is used to initialize the stocks that are present in the delay. We initialize the stocks with equal values so that the outflow in the first timestep is equal to this value.
  • order (str) – The number of stocks in the delay pipeline. As we construct the delays at build time, this must be an integer and cannot be calculated from other model components. Anything else will yield a ValueError.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output
  • merge_subs (list of strings) – List of the final subscript range of the python array after.
  • deps (dict) – The dictionary with all the denpendencies in the expression.
Returns:

  • reference (str) – Reference to the smooth object __call__ method, which will return the output of the smooth process.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_n_trend(identifier, trend_input, average_time, initial_trend, subs, merge_subs, deps)[source]

Constructs Trend object.

Parameters:
  • identifier (str) – The python-safe name of the trend.
  • trend_input (str) – Input of the trend.
  • average_time (str) – Average time of the trend.
  • trend_initial (str) – This is used to initialize the trend.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output.
  • merge_subs (list of strings) – List of the final subscript range of the python array after merging with other objects.
  • deps (dict) – The dictionary with all the denpendencies in the expression.
Returns:

  • reference (str) – Reference to the trend object __call__ method, which will return the output of the trend process.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_sample_if_true(identifier, condition, actual_value, initial_value, subs, merge_subs, deps)[source]

Creates code to instantiate a stateful ‘SampleIfTrue’ object, and provides reference to that object’s output.

Parameters:
  • identifier (str) – The python-safe name of the sample if true.
  • condition (str) – Reference to another model element that is the condition to the ‘sample if true’ function.
  • actual_value (str) – Can be a number (in string format) or a reference to another model element which is calculated throughout the simulation at runtime.
  • initial_value (str) – This is used to initialize the state of the sample if true function.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output.
  • merge_subs (list of strings) – List of the final subscript range of the python array after merging with other objects.
  • deps (dict) – The dictionary with all the denpendencies in the expression.
Returns:

  • reference (str) – Reference to the sample if true object __call__ method, which will return the output of the sample if true process.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.add_stock(identifier, expression, initial_condition, subs, merge_subs, deps)[source]

Creates new model element dictionaries for the model elements associated with a stock.

Parameters:
  • identifier (str) – The python-safe name of the stock.
  • expression (str) – The formula which forms the derivative of the stock.
  • initial_condition (str) – Formula which forms the initial condition for the stock.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output.
  • merge_subs (list of strings) – List of the final subscript range of the python array after merging with other objects.
  • deps (dict) – The dictionary with all the denpendencies in the expression.
Returns:

  • reference (str) – a string to use in place of the ‘INTEG…’ pieces in the element expression string, a reference to the stateful object.
  • new_structure (list) – List of additional model element dictionaries. When there are subscripts, constructs an external ‘init’ and ‘ddt’ function so that these can be appropriately aggregated.

pysd.translation.builder.add_tab_data(identifier, real_name, subs, subscript_dict, merge_subs, keyword)[source]

Constructs an object for handling Vensim’s regular DATA components.

Parameters:
  • identifier (str) – The python-safe name of the external values.
  • real_name (str) – The real name of the variable.
  • subs (list of strings) – List of strings of subscript indices that correspond to the list of expressions, and collectively define the shape of the output.
  • subscript_dict (dict) – Dictionary describing the possible dimensions of the stock’s subscripts.
  • merge_subs (list of strings) – List of the final subscript range of the python array after merging with other objects.
  • keyword (str) – Data retrieval method (‘interpolate’, ‘look forward’, ‘hold backward’).
Returns:

  • reference (str) – Reference to the TabData object __call__ method, which will return the retrieved value of data for the current time step.
  • new_structure (list) – List of element construction dictionaries for the builder to assemble.

pysd.translation.builder.build(elements, subscript_dict, namespace, dependencies, outfile_name)[source]

Constructs and writes the python representation of the model, when the the split_modules is set to False in the read_vensim function. The entire model is put in a single python file.

Parameters:
  • elements (list) – Each element is a dictionary, with the various components needed to assemble a model component in python syntax. This will contain multiple entries for elements that have multiple definitions in the original file, and which need to be combined.
  • subscript_dict (dict) – A dictionary containing the names of subscript families (dimensions) as keys, and a list of the possible positions within that dimension for each value.
  • namespace (dict) – Translation from original model element names (keys) to python safe function identifiers (values).
  • dependencies (dict) – Dependencies dictionary. Variables as keys and set of called values or objects, objects as keys and a dictionary of dependencies for initialization and dependencies for run.
  • outfile_name (str) – The name of the file to write the model to.
Returns:

None or text – If outfile_name=”return” it will return the content of the output file instead of saving it. It is used for testing.

Return type:

None or str

pysd.translation.builder.build_active_initial_deps(identifier, arguments, deps)[source]

Creates new model element dictionaries for the model elements associated with a stock.

Parameters:
  • identifier (str) – The python-safe name of the stock.
  • expression (str) – Formula which forms the regular value for active initial.
  • initial (str) – Formula which forms the initial value for active initial.
  • deps (dict) – The dictionary with all the denpendencies in the expression.
Returns:

  • reference (str) – A reference to the gost variable that defines the dependencies.
  • new_structure (list) – List of additional model element dictionaries.

pysd.translation.builder.build_dependencies(deps, exps)[source]
pysd.translation.builder.build_element(element, subscript_dict)[source]

Returns a string that has processed a single element dictionary.

Parameters:
  • element (dict) –

    A dictionary containing at least the elements: - kind: [‘constant’, ‘setup’, ‘component’, ‘lookup’]

    Different types of elements will be built differently
    • py_expr: str
      An expression that has been converted already into python syntax
    • subs: list of lists
      Each sublist contains coordinates for initialization of a particular part of a subscripted function, the list of subscripts vensim attaches to an equation
  • subscript_dict (dict) – A dictionary containing the names of subscript families (dimensions) as keys, and a list of the possible positions within that dimension for each value.
Returns:

func – The function to write in the model file.

Return type:

str

pysd.translation.builder.build_function_call(function_def, user_arguments, dependencies={})[source]

Build a function call using the arguments from the original model.

Parameters:
  • function_def (dict) –

    Function definition map with following keys: - name: name of the function. - parameters: list with description of all parameters of this function

    • name
    • optional?
    • type: [
      “expression”, - provide converted expression as parameter for
      runtime evaluating before the method call
      ”lambda”, - provide lambda expression as parameter for
      delayed runtime evaluation in the method call
      ”time”, - provide access to current instance of
      time object
      ”scope”, - provide access to current instance of
      scope object (instance of Macro object)
      ”predef” - provide an invariant argument. Argument not
      given in Vensim/Xmile but needed for python.
      ”ignore” - ignore an user argument. Argument given in
      Vensim/Xmile but not needed for python.
      ”subs_range_to_list”
      • provides the list of subscripts in a given subscript range

    ]

  • user_arguments (list) – Arguments provided from model.
  • dependencies (set (optional)) – Set to update dependencies if needed.
Returns:

Function call.

Return type:

str

pysd.translation.builder.build_modular_model(elements, subscript_dict, namespace, dependencies, main_filename, elements_per_view)[source]

This is equivalent to the build function, but is used when the split_views parameter is set to True in the read_vensim function. The main python model file will be named as the original model file, and stored in the same folder. The modules will be stored in a separate folder named modules + original_model_name. Three extra json files will be generated, containing the namespace, subscripts_dict and the module names plus the variables included in each module, respectively.

Setting split_views=True is recommended for large models with many different views.

Parameters:
  • elements (list) – Each element is a dictionary, with the various components needed to assemble a model component in python syntax. This will contain multiple entries for elements that have multiple definitions in the original file, and which need to be combined.
  • subscript_dict (dict) – A dictionary containing the names of subscript families (dimensions) as keys, and a list of the possible positions within that dimension for each value.
  • namespace (dict) – Translation from original model element names (keys) to python safe function identifiers (values).
  • main_filename (str) – The name of the file to write the main module of the model to.
  • elements_per_view (dict) – Contains the names of the modules and submodules as keys and the variables in each specific module inside a list as values.
pysd.translation.builder.merge_partial_elements(element_list)[source]

Merges model elements which collectively all define the model component, mostly for multidimensional subscripts

Parameters:element_list (list) – List of all the elements.
Returns:List of merged elements.
Return type:list

External data reading

These classes are a collection of the needed tools to read external data. The External type objects created by these classes are initialized before the Stateful objects by functions.Model.initialize.

class pysd.py_backend.external.Excels[source]

Class to save the read Excel files and thus avoid double reading

_Excels = {}
_Excels_opyxl = {}
classmethod clean()[source]

Clean the dictionary of read files

classmethod read(file_name, sheet_name)[source]

Read the Excel file or return the previously read one

classmethod read_opyxl(file_name)[source]

Read the Excel file using OpenPyXL or return the previously read one

class pysd.py_backend.external.ExtConstant(file_name, sheet, cell, coords, root, py_name)[source]

Class for Vensim GET XLS CONSTANTS/GET DIRECT CONSTANTS

_get_constant_data(data_across, cell, shape)[source]

Function thar reads data from excel file for CONSTANT

Parameters:
  • data_across ("cell" or "name") – The way to read data file.
  • cell (int or str) – If data_across is “cell” the lefttop split cell value where the data is. If data_across is “name” the cell range name where the data is.
  • shape – The shape of the data in 2D.
Returns:

data – The values of the data.

Return type:

float/ndarray(1D/2D)

_initialize()[source]

Initialize one element

add(file_name, sheet, cell, coords)[source]

Add information to retrieve new dimension in an already declared object

initialize()[source]

Initialize all elements and create the self.data xarray.DataArray

class pysd.py_backend.external.ExtData(file_name, sheet, time_row_or_col, cell, interp, coords, root, py_name)[source]

Class for Vensim GET XLS DATA/GET DIRECT DATA

add(file_name, sheet, time_row_or_col, cell, interp, coords)[source]

Add information to retrieve new dimension in an already declared object

initialize()[source]

Initialize all elements and create the self.data xarray.DataArray

class pysd.py_backend.external.ExtLookup(file_name, sheet, x_row_or_col, cell, coords, root, py_name)[source]

Class for Vensim GET XLS LOOKUPS/GET DIRECT LOOKUPS

_call(data, x)[source]
add(file_name, sheet, x_row_or_col, cell, coords)[source]

Add information to retrieve new dimension in an already declared object

initialize()[source]

Initialize all elements and create the self.data xarray.DataArray

class pysd.py_backend.external.ExtSubscript(file_name, sheet, firstcell, lastcell, prefix, root)[source]

Class for Vensim GET XLS SUBSCRIPT/GET DIRECT SUBSCRIPT

class pysd.py_backend.external.External(py_name)[source]

Main class of external objects

py_name

The python name of the object

Type:str
missing

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.

Type:str (“warning”, “error”, “ignore”, “keep”)
file

File name from which the data is read.

Type:str
sheet

Sheet name from which the data is read.

Type:str
static _col_to_num(col)[source]

Transforms the column name to int

Parameters:col (str) – Column name
Returns:Column number
Return type:int
_file_sheet

Returns file and sheet name in a string

_fill_missing(series, data)[source]

Fills missing values in excel read data. Mutates the values in data.

Parameters:
  • series – the time series without missing values
  • data – the data with missing values
Returns:

Return type:

None

_get_data_from_file(rows, cols)[source]

Function to read data from excel file using rows and columns

Parameters:
  • rows (list of len 2) – first row and last row+1 to be read, starting from 0
  • cols (list of len 2) – first col and last col+1 to be read, starting from 0
Returns:

data – depending on the shape of the requested data

Return type:

pandas.DataFrame, pandas.Series or float

_get_data_from_file_opyxl(cellname)[source]

Function to read data from excel file using cell range name

Parameters:cellname (str) – the cell range name
Returns:data – depending on the shape of the requested data
Return type:numpy.ndarray or float
_get_series_data(series_across, series_row_or_col, cell, size)[source]

Function thar reads series and data from excel file for DATA and LOOKUPS.

Parameters:
  • series_across ("row", "column" or "name") – The way to read series file.
  • series_row_or_col (int or str) – If series_across is “row” the row number where the series data is. If series_across is “column” the column name where the series data is. If series_across is “name” the cell range name where the series data is.
  • cell – If series_across is not “name, the top left cell where the data table starts. Else the name of the cell range where the data is.
  • size – The size of the 2nd dimension of the data.
Returns:

series, data – The values of the series and data.

Return type:

ndarray (1D), ndarray(1D/2D)

_initialize_data(element_type)[source]

Initialize one element of DATA or LOOKUPS

Parameters:element_type (str) – “lookup” for LOOKUPS, “data” for data.
Returns:data – Dataarray with the time or interpolation dimension as first dimension.
Return type:xarray.DataArray
_interpolate_missing(x, xr, yr)[source]

Interpolates a list of missing values from _fill_missing

Parameters:
  • x – list of missing values interpolate
  • xr – non-missing x values
  • yr – non-missing y values
Returns:

Result after interpolating x with self.interp method

Return type:

y

static _reshape(data, dims)[source]

Reshapes an pandas.DataFrame, pandas.Series, xarray.DataArray or np.ndarray in the given dimensions.

Parameters:
  • data (xarray.DataArray/numpy.ndarray) – Data to be reshaped
  • dims (tuple) – The dimensions to reshape.
Returns:

reshaped array

Return type:

numpy.ndarray

_resolve_file(root)[source]

Resolve input file path. Joining the file with the root and checking if it exists.

Parameters:root (pathlib.Path or str) – The root path to the model file.
Returns:
Return type:None
_series_selector(x_row_or_col, cell)[source]

Selects if a series data (DATA/LOOKUPS), should be read by columns, rows or cellrange name. Based on the input format of x_row_or_col and cell. The format of the 2 variables must be consistent.

Parameters:
  • x_row_or_col (str) – String of a number if series is given in a row, letter if series is given in a column or name if the series is given by cellrange name.
  • cell (str) – Cell identificator, such as “A1”, or name if the data is given by cellrange name.
Returns:

series_across – “row” if series is given in a row “column” if series is given in a column “name” if series and data are given by range name

Return type:

str

_split_excel_cell(cell)[source]

Splits a cell value given in a string. Returns None for non-valid cell formats.

Parameters:cell (str) – Cell like string, such as “A1”, “b16”, “AC19”… If it is not a cell like string will return None.
Returns:row number, column number – If the cell input is valid. Both numbers are given in Python enumeration, i.e., first row and first column are 0.
Return type:int, int
missing = 'warning'

Decorators used in the model file

These are the decorators used by the functions in the model file. functions.py

class pysd.py_backend.decorators.Cache[source]

This is the class for the chache. Several cache types can be saved in dictionaries and acces using cache.data[cache_type].

clean()[source]

Cleans the cache

pysd.py_backend.decorators.constant_cache(function, *args)[source]

Constant cache decorator for all the run The original function is saved in ‘function’ attribuite so we can recover it later.

pysd.py_backend.decorators.subs(dims, subcoords)[source]

This decorators returns the python object with the correct dimensions xarray.DataArray. The algorithm is a simple version of utils.rearrange