Environmental Properties

The environment within a FLAME GPU model represents external properties which influence agent behaviour.

Environment properties are read-only to agents, but may be updated by host functions.

Although initial values must be specified for environment properties, they can be overridden at model runtime with various techniques.

FLAME GPU 2 introduces environment macro properties, these are intended for larger environment properties which may have upto four dimensions. Environment macro properties, unlike regular environment properties, can be updated by agents with a limited collection of atomic backed methods. However, they also have additional limitations; they always default to zero, cannot be logged, and cannot make use of experimental GLM support.

Accessing the EnvironmentDescription Object

A model’s EnvironmentDescription is retrieved from the ModelDescription using Environment(). This returns a reference to the model’s EnvironmentDescription.

// Define a new FLAME GPU model
flamegpu::ModelDescription model("My Model");
// Fetch the model's environment
flamegpu::EnvironmentDescription &env = model.Environment();

Note

As the EnvironmentDescription is owned by the ModelDescription, it is returned as a reference, so it’s type must take the form EnvironmentDescription& when using the C++ API.

Defining Properties

Environment properties are declared using the newProperty() methods.

The type, name and initial value of the property are all specified, array properties additionally require the length of the array to be specified.

// Fetch the model's environment
flamegpu::EnvironmentDescription &env = model.Environment();
// Declare an int property named 'foo', with a default value 12
env.newProperty<int>("foo", 12);
// Declare a float array property of length 3 named 'bar', with a default value [4.0, 5.0, 6.0]
env.newProperty<float, 3>("bar", {4.0f, 5.0f, 6.0f});

Note

Under the C/C++ API, the type and array length arguments are specified via template args. Under the Python API, the type is included in the method’s identifier, and the array length is normally not required to be explicitly specified. This pattern is a consistent difference between the two APIs, however code in agent functions follow the C/C++ format.

Defining Macro Properties

In contrast to regular environment properties, environment macro properties are declared using the newMacroProperty() method.

These may have upto 4 dimensions (unused dimensions if left unspecified, will default to length 1).

The type, dimensions and name of the macro property are all specified. The macro property will be initialised to a zero’d state, if a different initial value is required it should be populated by an initialisation function.

// Fetch the model's environment
flamegpu::EnvironmentDescription &env = model.Environment();
// Declare an int macro property named 'foobar', with array dimensions [5, 5, 5, 3]
env.newMacroProperty<int, 5, 5, 5, 3>("foobar");