Vars (variables)

Var is a piece of data which is accessible through a reference (based on idea of variable from computer science). This means each var is composed of two parts:

  • reference (in our case it's an address)
  • value (data, could be any of the types defined below, like a number or a string of characters)

Vars exist in the context of elements. Since the elements are static objects within the simulation vars are also static - they persist no matter what since simulation instance initialization.

Vars are mutable, meaning their value can be changed during simulation run. At the same time references to vars (their addresses) cannot be changed after initialization (persistence).

How are vars implemented?

Vars are key-value pairs that are persistent throughout the simulation. They are stored inside the Database object, which itself is a key-value store (listing).

Vars are declared and used within the context of elements and their system of states with sets of instructions (commands).

Address of a var is it's key, and the piece of data is it's value (whether a number, a string or other kind of data).

During initialization the vars as they appear in the module files are transformed into pointers to actual data stored in the Database that the program can understand. The exception here are vars referenced using dynamic addresses - these take longer time to retrieve because the program has to look up the database first (if it were a usual static reference it would already have the reference to the desired data).

# example of an element declaration with a var declaration included
element:
  - id: forest_coverage
    # lack of type specification means it's a generic element
    entity: region
    vars:
      # address for the following var could be
      # /reg/e01001/law/some_law/num/some_num_var
      - name: some_num_var
        type: number
        default: 5

Declaration and persistence

Vars need to be declared within an element declaration under vars entry.

Vars need to be registered at initialization, they can't be added after initialization.

info Remember: Var registration is a process of registering a var for an entity type, instead of for a specific entity. For example when registering a new var for the region level each region entity will receive an instance of this new var and will be able to use it.

Var types

There are several types of vars (based on different kinds of values they hold):

  • number
  • string
  • bool
  • number table
  • string table
  • bool table

Database object

Database is the key-value store for vars. It's an object relevant in the context of a single simulation run, as it's created on initialization and discarded after the simulation run is finished. At any point of it's existence after the initialization, the information inside the database object can be exported to a snapshot, allowing for later reconstruction.