Element
system dynamics, bptk, bptk-py, python, business prototyping
Element
Element Constructor
Element(model, name, function_string=None)
Generic element in a SD DSL model.
Concrete elements are Biflows, Flows, Constants and Converters.
In general elements are created via an instance of the Model class, using the appropriate methods.
Parameters
Model – Model. The model the element belongs to.
Name – String. The name of the model.
Function_string – String (Default=None) The function string of the element. This is set by the framework.
Element.equation
property equation()
Returns the equation as originally set.
Returns
The equation, either a SD DSL Element or Operator.
Element.function_string
property function_string()
Returns a string representation of the underlying function. Useful for debugging purposes.
Element.plot
plot(starttime=None, stoptime=None, dt=None, return_df=False, format=‘plot’, matplotlib_rc_settings=None)
Plot the equation or return a dataframe with the simulated data.
Parameters
starttime – Integer (Default None). The timestep where to begin the plot. If set to None the plot starts at the Models starttime.
stoptime – Integer (Default None) The timestep when to end the plot.
dt – Fraction of 1 (Default None) The timestep to plot. If set to None, then the plot uses the Models dt.
return_df – Boolean (Default False). Whether to plot the equation or return the underlying dataframe. Equivalent to format=‘df’, which it overrides when set.
format – String (Default ‘plot’). What to return: ‘plot’ draws the diagram and returns nothing, ‘axes’ returns the matplotlib Axes, ‘df’ returns the underlying dataframe. ‘plot’ relies on the notebook displaying the figure as a side effect, which only Jupyter’s inline backend does — in marimo, and in a plain script, use ‘axes’. Every example in this documentation does.
matplotlib_rc_settings – Dict (Default None). matplotlib settings for this one plot, laid over the central plotting configuration rather than replacing it. The central configuration is left alone, so the next plot is styled centrally again.
Returns
Nothing for format=‘plot’, the matplotlib Axes for format=‘axes’, or a Pandas dataframe for format=‘df’ (or return_df=True).
Arrayed elements
Any element can hold a vector or a matrix instead of a scalar. The Multidimensional SD DSL chapter works through this in depth; these are the methods it uses.
Setting an element up as an array
setup_vector(size, default_value=0.0, set_stack_equation=False)
Turn the element into a vector of size entries, each initialised to default_value. Pass a list as default_value to give the entries different values.
setup_matrix(size, default_value=0.0, set_stack_equation=False)
The same for a matrix. size is a two-element list, [rows, columns].
setup_named_vector(values, set_stack_equation=False)
A vector whose entries are addressed by name rather than by index, from a dict {name: value}. Subscripting then reads element["young"] instead of element[0].
setup_named_matrix(names, set_stack_equation=False)
The same for a matrix, from a nested dict.
set_stack_equation governs whether the element’s own equation is built from its entries. Leave it at False when you set the equation yourself.
Aggregating over an array
Each of these returns an expression, so it can be used inside another equation.
| Method | Returns |
|---|---|
| arr_sum(dimension=‘*’) | The sum over the given dimension |
| arr_mean() | The arithmetic mean |
| arr_median() | The median |
| arr_prod(dimension=‘*’) | The product |
| arr_stddev() | The standard deviation |
| arr_max() | The largest entry |
| arr_min() | The smallest entry |
| arr_size() | The number of entries |
| arr_rank(rank) | The entry of the given rank |
| dot(other) | The dot product with another arrayed element |
dimension on arr_sum and arr_prod accepts '*' or the array’s full depth, which both aggregate every entry; a partial aggregation would have to return an array and is rejected. The aggregations run on the Rust engine as well - they become engine-side functions over the sub-elements. See Execution Backends.