Element
system dynamics, bptk, bptk-py, python, business prototyping
Element
Element Constructor
Element(model, name, function_string=None)
Generic element in an 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 element.
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 an 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 Model’s 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 Model’s 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’). ‘plot’, ‘axes’ or ‘df’, as for bptk.plot_scenarios.
matplotlib_rc_settings – Dict (Default None). matplotlib settings for this one plot - see Styling a single plot.
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 - see What set_stack_equation does.
An array needs at least one entry: a size of 0, or an empty dict, raises ValueError.
Parts of an array
Square brackets take a range or a pair of keys as well as a single one, and a range includes its end, as in Stella - see Parts of an Array.
Element.transpose
transpose()
The matrix with its rows and columns swapped, as an expression - see Transposing a Matrix.
Aggregating over an array
Each of these returns an expression, so it can be used inside another equation. They work on an arrayed element and on any expression that is an array, such as (a * b).arr_sum() or a[0:2].arr_mean().
| Method | Returns |
|---|---|
| arr_sum(dimension=‘*’, over=None) | The sum |
| arr_mean(over=None) | The arithmetic mean |
| arr_median(over=None) | The median |
| arr_prod(dimension=‘*’, over=None) | The product |
| arr_stddev(over=None) | The standard deviation |
| arr_max(over=None) | The largest entry |
| arr_min(over=None) | The smallest entry |
| arr_size(over=None) | The length of the first dimension: 2 for a \(2 \times 3\) matrix |
| arr_largest(rank) | The entry of the given rank, counted from the largest |
| arr_rank(rank, tiebreak=None) | The position, counting from 1, of the rank-th smallest entry of a vector - XMILE’s RANK |
| arr_interpolate(*weights) | A value between the entries, one weight from 0 to 1 per dimension - Stella’s INTERPOLATE |
| arr_percentile(percentile, lower=None, weights=None) | The value below which percentile percent of the entries lie, by Stella’s rules - Stella’s PERCENTILE |
| dot(other) | The dot product with another arrayed element |
over aggregates a matrix along one dimension - see Aggregating Along One Dimension. dimension on arr_sum and arr_prod accepts '*' or the array’s full depth, which both aggregate every entry. What each function computes: Array Functions.