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.

Distinct from environment properties, FLAME GPU 2 introduces environment macro properties, these are intended for larger environment properties which may have upto four dimensions and can be updated by agents with a limited collection of atomic backed methods.

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.

For a full list of supported types, see Supported Types.

// 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

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.

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");

Defining a Directed Graph

FLAME GPU 2 introduces static directed graphs as a structure for storing organised data within the environment. The graph’s structure can be defined within a host function, with properties attached to vertices and/or edges.

Directed graphs can then be traversed by agents which can iterate either input or output edges to a given vertex.

Environment directed graphs are currently static, therefore resizing the number of vertices or edges requires all properties to be reinitialised.

// Fetch the model's environment
flamegpu::EnvironmentDescription env = model.Environment();
// Declare a new directed graph named 'fgraph'
EnvironmentDirectedGraphDescription fgraph = model.Environment().newDirectedGraph("fgraph");
// Attach an float[2] property 'bar' to vertices
fgraph.newVertexProperty<float, 2>("bar");
// Attach an int property 'foo' to edges
fgraph.newEdgeProperty<int>("foo");