Defining Arrayed Components

How to give an SD DSL element a shape - vectors, matrices, named indices - and how to plot it
Keywords

system dynamics, systemdynamics, sd dsl, arrays, bptk, bptk-py, python, business simulation

Defining Arrayed Components

The examples on this page share one model, set up here:

There are two options for arrayed components:

  • Vectors (one dimensional arrays)
  • Matrices (two dimensional arrays)

Moreover, both types of arrays - Vectors and Matrices - can be setup:

  • using numerical indices
  • using string-valued indices (named arrays)

Lets have a look at some examples:

As can be seen, we need two parameters for setting up a Vector using numerical indices. Moreover, there is one optional parameter.

Parameter Type Meaning
size Integer Defines the length of the Vector
values List of Float/Integer Defines the values of the Vector elements
set_stack_equation Boolean (optional) If the element is a stock, the initial value is set (False) or the equation is set (True). Default is False.

And we need one parameter (+ one optional parameter) for setting up a Vector using string indices:

Parameter Type Meaning
values Dictionary Defines the string-values indices and their values
set_stack_equation Boolean (optional) If the element is a stock, the initial value is set (False) or the equation is set (True). Default is False.

values is either one value per index, or a single value that every index gets - setup_vector(2, 3.0) above is the short form of setup_vector(2, [3.0, 3.0]). set_stack_equation has a section of its own below.

For matrices, we can proceed completely similar.

As can be seen, we need two parameters (+ one optional parameter) for setting up a Matrix using numerical indices:

Parameter Type Meaning
size List (tuple) of Integer Defines the size of the Matrix
values List of Lists of Float/Integer Defines the values of the Matrix elements
set_stack_equation Boolean (optional) If the element is a stock, the initial value is set (False) or the equation is set (True). Default is False.

And we need one parameter (+ one optional parameter) for setting up a Matrix using string-valued indices:

Parameter Type Meaning
values Dictionary Defines the string-values indices and their values
set_stack_equation Boolean (optional) If the element is a stock, the initial value is set (False) or the equation is set (True). Default is False.

A matrix takes a single value as well: setup_matrix([2, 2], 3.0) gives a 2x2 matrix whose four cells all hold 3.0.

What set_stack_equation does

For every element except a stock, the values handed to setup_vector and its three siblings are simply the sub-elements’ values, and set_stack_equation changes nothing.

A stock is the one case where those values could mean two different things, and this is the flag that decides which:

  • False, the default: each value is the initial value of its sub-stock. The sub-stock starts there and then accumulates whatever flows you give it.
  • True: each value becomes the sub-stock’s equation, that is its net change per unit of time. The sub-stock starts at 0.0 and adds that value at every step.

So the same call means “start at 10 and 20” or “grow by 10 and 20 per period”:

set_stack_equation=False (initial values, plus a flow of 1.0 and 2.0):
  index 0: [10.0, 11.0, 12.0, 13.0]
  index 1: [20.0, 22.0, 24.0, 26.0]
set_stack_equation=True (the values are the stock's equation):
  index 0: [0.0, 10.0, 20.0, 30.0]
  index 1: [0.0, 20.0, 40.0, 60.0]

Plotting arrayed Components

Similar to one-dimensional SD DSL elements, we can also plot these elements. Lets have a look:

As can be seen, both elements of the Vector are plotted.

If you want to plot the values of the Matrix, you need to specify the first index.