Accessing the Environment

As detailed in the earlier chapter detailing the defining of environmental properties, there are two types of environment property which can be interacted with in agent functions. The DeviceEnvironment instance can be accessed, to interact with both of these, via FLAMEGPU->environment (C++) or pyflamegpu.environment (Python).

Environment Properties

Agent functions can only read environmental properties. If you wish to modify an environmental property, this must be done via host functions.

Environmental properties are accessed, using DeviceEnvironment, as follows:

FLAMEGPU_AGENT_FUNCTION(ExampleFn, flamegpu::MessageNone, flamegpu::MessageNone) {
    // Get the value of environment property 'interaction_radius' and store it in local variable 'interaction_radius'
    float interaction_radius = FLAMEGPU->environment.getProperty<float>("interaction_radius");

    // Other behaviour code
    ...
}

Environment Macro Properties

Agent functions have much greater access to environmental macroscopic properties, however they still cannot be directly written to, or both updated and read in the same layer.

Environmental macro properties can be read, via the returned DeviceMacroProperty, as follows:

FLAMEGPU_AGENT_FUNCTION(ExampleFn, flamegpu::MessageNone, flamegpu::MessageNone) {
    // Get the single float from environment macro property 'float1' and store it in local variable 'test_float'
    float test_float = FLAMEGPU->environment.getMacroProperty<float>("float1");
    // Get the root of the 3x3x3x3 environment macro property 'big_prop' and store it in a variable of the same name
    auto bigprop = FLAMEGPU->environment.getMacroProperty<int, 3, 3, 3, 3>("big_prop");
    // Copy the value from location [1,1,1,1] to the variable t
    int t = big_prop[1][1][1][1];

    // Other behaviour code
    ...
}

They can also be updated with a selection of functions, which execute atomically. These functions will update a single variable and return information related to it’s old or new state. This can be useful, for simple actions such as conflict resolution and counting. However, if a basic read is subsequently required, a separate host or agent function in a following layer must be used (otherwise there would be a race condition). If running with FLAMEGPU_SEATBELTS error checking enabled, an exception should be thrown where potential race conditions are detected.

Macro properties support the normal +, -, +=, -=, ++ (only C++ supports pre and post increment), -- (only C++ supports pre and post decrement) operations. They also have access to a limited set of additional functions, explained in the table below.

Note

DeviceMacroProperty update support is limited to specific variable types. This varies between functions however uint32_t has the widest support, for full explanation check the API docs.

Method

Supported Types

Description

min(val)

int32_t, uint32_t, uint64_t

Update property according to val < old ? val : old and return it’s new value.

max(val)

int32_t, uint32_t, uint64_t

Update property according to val > old ? val : old and return it’s new value.

CAS(compare, val)

int32_t, uint32_t, uint64_t, uint16_t

Update property according to old == compare ? val : old and return old.

exchange(val)

int32_t, uint32_t, float

Update property to match val, and return old.

Example usage is shown below:

FLAMEGPU_AGENT_FUNCTION(ExampleFn, flamegpu::MessageNone, flamegpu::MessageNone) {
    // Get the root of the 3x3x3 environment macro property 'location' and store it in a variable of the same name
    auto location = FLAMEGPU->environment.getMacroProperty<unsigned int, 3, 3, 3>("location");
    // Notify our location, of our presence and store how many other agents were there before us in `location_count`
    unsigned int location_count = location[0][1][2]++;


    // Get the root of the float environment macro property 'swap' and store it in a variable of the same name
    auto swap = FLAMEGPU->environment.getMacroProperty<float>("swap");
    // Fetch and replace the value present in swap
    float location_count = swap.exchange(12.0f);

    // Directly accessing the value of either macro property now in the same agent function would cause a race condition
    // unsigned int location_val = location[0][0][0]; // DeviceError!
    // float swap_val = swap; // DeviceError!

    // Other behaviour code
    ...
}

Warning

Be careful when using DeviceMacroProperty. When you retrieve an element e.g. location[0][0][0] (from the example above), it is of type DeviceMacroProperty not unsigned int. Therefore you cannot pass it directly to functions which take generic arguments such as printf(), as it will be interpreted incorrectly. You must either store it in a variable of the correct type which you instead pass, or explicitly cast it to the correct type when passing it e.g. (unsigned int)location[0][0][0] or static_cast<unsigned int>(location[0][0][0]) (or numpy.uint(location[0][0][0]) in Python).

Environment Directed Graph

To access the graph on the device, vertex indexes are used rather than IDs, to minimise ID->index conversion for efficient access, methods are available to convert between ID and index.

If executing a model without FLAMEGPU_SEATBELTS? enabled, getVertexIndex() and getEdgeIndex() will return zero if the specified vertex or edge does not exist.

FLAMEGPU_AGENT_FUNCTION(GraphTestID, MessageNone, MessageNone) {
    DeviceEnvironmentDirectedGraph fgraph = FLAMEGPU->environment.getDirectedGraph("fgraph");

    // Fetch the ID of the vertex at index 0
    flamegpu::id_t vertex_id = fgraph.getVertexID(0);
    // Fetch the index of the vertex with ID 1
    unsigned int vertex_index = fgraph.getVertexIndex(1);

    // Access a property of vertex with ID 1
    float bar_0 = fgraph.getVertexProperty<float, 2>("bar", 0);

    // Fetch the source and destination indexes from the edge at index 0
    unsigned int source_index = fgraph.getEdgeSource(0);
    unsigned int destination_index = fgraph.getEdgeDestination(0);

    // Fetch the index of the edge from vertex ID 1 to vertex ID 2
    unsigned int edge_index = fgraph.getEdgeIndex(1, 2);

    // Access a property of edge with source ID 1, destination ID 2
    int foo = fgraph.getEdgeProperty<int>("foo", edge_index);

    return flamegpu::ALIVE;
}

Note

Edge indices should only be stored within agents if edges will not have their source or destinations updated on the host. Updating edge connectivity triggers a graph rebuild, this causes edges to be sorted (hence invalidating indexes).

Traversing Graphs

Agents are able to traverse the graph by iterating edges joining and leaving a specified vertex using the iterators provided by inEdges() and outEdges()<flamegpu::DeviceEnvironmentDirectedGraph::outEdges> respectively.

FLAMEGPU_AGENT_FUNCTION(GraphTestID, MessageNone, MessageNone) {
    DeviceEnvironmentDirectedGraph fgraph = FLAMEGPU->environment.getDirectedGraph("fgraph");

    // Fetch the index of the vertex with ID 1
    unsigned int vertex_index = fgraph.getVertexIndex(1);

    // Iterate the edges leaving the vertex with ID 1
    for (auto &edge : fgraph.outEdges(vertex_index)) {
        // Read the current edges' destination vertex index
        unsigned int dest_vertex_index = edge.getEdgeDestination();
        // Read a property from the edge
        int foo = edge.getProperty<int>("foo");
    }

    // Iterate the edges joining the vertex with ID 1
    for (auto &edge : fgraph.inEdges(vertex_index)) {
        // Read the current edges' source vertex index
        unsigned int src_vertex_index = edge.getEdgeSource();
        // Read a property from the edge
        int foo = edge.getProperty<int>("foo");
    }

    return flamegpu::ALIVE;
}

Note

The implementation of outEdges()() is more efficient than that of inEdges()().