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’)
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.
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(dimension=‘*’) | The arithmetic mean |
| arr_median(dimension=‘*’) | The median |
| arr_prod(dimension=‘*’) | The product |
| arr_stddev(dimension=‘*’) | The standard deviation |
| arr_size() | The number of entries |
| arr_rank(rank) | The entry of the given rank |
| dot(other) | The dot product with another arrayed element |
The aggregations are the one part of the SD DSL the Rust engine cannot take: a model that uses them falls back to the Python engine. See Execution Backends.