Python functions and stateful objects¶
Functions¶
The provided 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. They are provided in a structure that makes it easy for the model elements to call. The functions may be similar to the original functions given by Vensim or Stella, but sometimes the number or order of arguments may change.
- pysd.py_backend.functions.ramp(time, slope, start, finish=None)[source]¶
Implements vensim’s and xmile’s RAMP function.
- Parameters
- Returns
If prior to ramp start, returns zero. If after ramp ends, returns top of ramp.
- Return type
- pysd.py_backend.functions.step(time, value, tstep)[source]¶
” Implements vensim’s STEP function.
- Parameters
- Returns
- In range [-inf, tstep):
returns 0
- In range [tstep, +inf]:
returns value
- Return type
- pysd.py_backend.functions.pulse(time, start, repeat_time=0, width=None, magnitude=None, end=None)[source]¶
Implements Vensim’s PULSE and PULSE TRAIN functions and Xmile’s PULSE function.
- Parameters
time (callable) – Function that returns the current time.
start (float) – Starting time of the pulse.
repeat_time (float (optional)) – Time interval of the pulse repetition. If 0 it will return a single pulse. Default is 0.
width (float or None (optional)) – Duration of the pulse. If None only one-time_step pulse will be generated. Default is None.
magnitude (float or None (optional)) – The magnitude of the pulse. If None it will return 1 when the pulse happens, similar to magnitude=time_step(). Default is None.
end (float or None (optional)) – Final time of the pulse. If None there is no final time. Default is None.
- Returns
- In range [-inf, start):
returns 0
- In range [start + n*repeat_time, start + n*repeat_time + width):
returns magnitude/time_step or 1
- In range [start + n*repeat_time + width, start + (n+1)*repeat_time):
returns 0
- Return type
- 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 (callable) – Value to evaluate and return when condition is true.
val_if_false (callable) – Value to evaluate and return when condition is false.
- Returns
The value depending on the condition.
- Return type
- pysd.py_backend.functions.xidz(numerator, denominator, x)[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) – Numerator of the operation.
denominator (float or xarray.DataArray) – Denominator of the operation.
x (float or xarray.DataArray) – The value to return if the denominator is zero.
- Returns
numerator/denominator if denominator > small_vensim
value_if_denom_is_zero otherwise
- Return type
- 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
numerator/denominator if denominator > small_vensim
0 or 0s array otherwise
- Return type
- pysd.py_backend.functions.active_initial(stage, expr, init_val)[source]¶
Implements vensim’s ACTIVE INITIAL function
- Parameters
stage (str) – The stage of the model.
expr (callable) – Running stage value
init_val (float or xarray.DataArray) – Initialization stage value.
- Returns
inti_val if stage=’Initialization’
expr() otherwise
- Return type
- pysd.py_backend.functions.integer(x)[source]¶
Implements Vensim’s INTEGER function.
- Parameters
x (float or xarray.DataArray) – Input value.
- Returns
integer – Returns integer part of x.
- Return type
- 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
- 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
modulo – 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)
- Return type
- 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
sum – The result of the sum operation in the given dimensions.
- Return type
- 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
prod – The result of the product operation in the given dimensions.
- Return type
- 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
vmin – The result of the minimum value over the given dimensions.
- Return type
- 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
vmax – The result of the maximum value over the dimensions.
- Return type
- 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
- pysd.py_backend.functions.vector_sort_order(vector, direction)[source]¶
Implements Vensim’s VECTOR SORT ORDER function. Sorting is done on the complete vector relative to the last subscript. https://www.vensim.com/documentation/fn_vector_sort_order.html
- Parameters
vector (xarray.DataArray) – The vector to sort.
direction (float) – The direction to sort the vector. If direction > 1 it will sort the vector entries from smallest to biggest, otherwise from biggest to smallest.
- Returns
vector_sorted – The sorted vector.
- Return type
- pysd.py_backend.functions.vector_reorder(vector, svector)[source]¶
Implements Vensim’s VECTOR REORDER function. Reordering is done on the complete vector relative to the last subscript. https://www.vensim.com/documentation/fn_vector_reorder.html
- Parameters
vector (xarray.DataArray) – The vector to sort.
svector (xarray.DataArray) – The vector to specify the order.
- Returns
vector_sorted – The sorted vector.
- Return type
- pysd.py_backend.functions.vector_rank(vector, direction)[source]¶
Implements Vensim’s VECTOR RANK function. Ranking is done on the complete vector relative to the last subscript. https://www.vensim.com/documentation/fn_vector_rank.html
- Parameters
vector (xarray.DataArray) – The vector to sort.
direction (float) – The direction to sort the vector. If direction > 1 it will rank the vector entries from smallest to biggest, otherwise from biggest to smallest.
- Returns
vector_rank – The rank of the vector.
- Return type
Statefuls¶
The Stateful objects are used and updated each time step with an update method. This include Integs, Delays, Forecasts, Smooths, and Trends, between others. The Macro class and Model class are also Stateful type. However, they are defined appart as they are more complex.
- class pysd.py_backend.statefuls.Integ(ddt, initial_value, py_name)[source]¶
Implements INTEG function.
- Parameters
ddt (callable) – Derivate to integrate.
initial_value (callable) – Initial value.
py_name (str) – Python name to identify the object.
- state¶
Current state of the object. Value of the stock.
- Type
- class pysd.py_backend.statefuls.Delay(delay_input, delay_time, initial_value, order, tstep, py_name)[source]¶
Implements DELAY function.
- Parameters
delay_input (callable) – Input of the delay.
delay_time (callable) – Delay time.
initial_value (callable) – Initial value.
order (callable) – Delay order.
tsetp (callable) – The time step of the model.
py_name (str) – Python name to identify the object.
- state¶
Current state of the object. Array of the delays values multiplied by their corresponding average time.
- Type
numpy.array or xarray.DataArray
- class pysd.py_backend.statefuls.DelayN(delay_input, delay_time, initial_value, order, tstep, py_name)[source]¶
Implements DELAY N function.
- Parameters
delay_input (callable) – Input of the delay.
delay_time (callable) – Delay time.
initial_value (callable) – Initial value.
order (callable) – Delay order.
tsetp (callable) – The time step of the model.
py_name (str) – Python name to identify the object.
- state¶
Current state of the object. Array of the delays values multiplied by their corresponding average time.
- Type
numpy.array or xarray.DataArray
- times¶
Array of delay times used for computing the delay output. If delay_time is constant, this array will be constant and DelayN will behave ad Delay.
- Type
numpy.array or xarray.DataArray
- class pysd.py_backend.statefuls.DelayFixed(delay_input, delay_time, initial_value, tstep, py_name)[source]¶
Implements DELAY FIXED function.
- Parameters
delay_input (callable) – Input of the delay.
delay_time (callable) – Delay time.
initial_value (callable) – Initial value.
tsetp (callable) – The time step of the model.
py_name (str) – Python name to identify the object.
- state¶
Current state of the object, equal to pipe[pointer].
- Type
- class pysd.py_backend.statefuls.Forecast(forecast_input, average_time, horizon, initial_trend, py_name)[source]¶
Implements FORECAST function.
- Parameters
forecast_input (callable) – Input of the forecast.
average_time (callable) – Average time.
horizon (callable) – Forecast horizon.
initial_trend (callable) – Initial trend of the forecast.
py_name (str) – Python name to identify the object.
- state¶
Current state of the object. AV value by Vensim docs.
- Type
- class pysd.py_backend.statefuls.Smooth(smooth_input, smooth_time, initial_value, order, py_name)[source]¶
Implements SMOOTH function.
- Parameters
smooth_input (callable) – Input of the smooth.
smooth_time (callable) – Smooth time.
initial_value (callable) – Initial value.
order (callable) – Delay order.
py_name (str) – Python name to identify the object.
- state¶
Current state of the object. Array of the inputs having the value to return in the last position.
- Type
numpy.array or xarray.DataArray
- class pysd.py_backend.statefuls.Trend(trend_input, average_time, initial_trend, py_name)[source]¶
Implements TREND function.
- Parameters
trend_input (callable) – Input of the trend.
average_time (callable) – Average time.
initial_trend (callable) – Initial trend.
py_name (str) – Python name to identify the object.
- state¶
Current state of the object. AV value by Vensim docs.
- Type
- class pysd.py_backend.statefuls.SampleIfTrue(condition, actual_value, initial_value, py_name)[source]¶
Implements SAMPLE IF TRUE function.
- Parameters
condition (callable) – Condition for sample.
actual_value (callable) – Value to update if condition is true.
initial_value (callable) – Initial value.
py_name (str) – Python name to identify the object.
- state¶
Current state of the object. Last actual_value when condition was true or the initial_value if condition has never been true.
- Type