Addresses (references)

Many simulation objects can be referenced using addresses. Addresses look similar to the urls you know from your browser (or the file paths from your operating system) - multiple parts are separated by / dashes. Here are a few examples of different addresses:

# path to prop element, which points (redirects) directly to it's main var
/region/e_01001/prop/immigration_rate_daily
# explicit path to the above prop's var
/region/e_01001/prop/immigration_rate_daily/var/main
# path
/org/GER/policy/immigration_policy_1/current_state
# relative path to an element (entity is inferred from current context)
# notice lack of the dash at the front
prop/population
# dynamic path with curly brackets
/org/{prop/master_org}/prop/

Building addresses we follow this scheme:

/[entity_type]/[entity_id]/[element_type]/[element_id]/[var_type]/[var_id]

Relative address

Dash at the beginning suggests an absolute path, while no dash suggests a relative path. Relative path means that the first part of the path is omitted because it’s the same as the first part of the path of the entity where the current execution is happening (context). For example we might currently be executing instructions (commands) on some region entity m_01012 and we specify some path like “prop/population” somewhere. In such case the path will be rewritten behind the scenes to become “/region/m_01012/prop/population”.

Dynamic address

Curly braces can be used to insert some other variable’s value into the path by referencing the path to that other variable.

Synonyms

Synonym in an address is basically an item within that address that is rewritten on initial processing.

There are a few synonyms that can be used to shorten the addresses.

Examples:

reg -> region

org -> organization

prop -> property

The addresses are parsed at initialization and any recognized synonyms are treated the same as the basic (longer) variants. So for example:

# this
/org/org_id/prop/prop_id
# is the same as this
/organization/org_id/property/prop_id

Address persistence

Since the objects that can be referenced using addresses are all static, meaning they can't be added or removed after initialization, addresses themselves also don't change during the simulation run.

What can be referenced using an address

Addresses can be used to point to:

  • entities
  • elements
  • element states
  • element vars