Layers

If you are a returning user, familiar with FLAME GPU 1, then you should already be familiar with the concept of layers.

The execution of a model can be broken down into several layers. The layers execute in order, each represented by a LayerDescription, with functions within the same layer having the ability to execute concurrently.

FLAME GPU enforces limitations on which model components can be placed in the same layer, to ensure safe concurrency within a layer.

Manually specified layers cannot be mixed with dependency specification introduced in the previous section.

Manual Layer Specification

newLayer() is called on the ModelDescription to create a new LayerDescription. Layers will execute in the order that they are created.

Agent functions, host functions, and submodels can then be added to layers via their respective methods: addAgentFunction(), addHostFunction() (Python: addHostFunction()) and addSubModel(). To each of these you pass the respective description object, alternatively for agent and host functions you can pass their raw function handles that were used to create the functions (this won’t work for agent function definitions used by multiple agents).

The below example demonstrates adding an agent and host function to separate layers.

FLAMEGPU_AGENT_FUNCTION(outputdata, flamegpu::MessageNone, flamegpu::MessageSpatial3D) {
    // Do something
    return flamegpu::ALIVE;
}
FLAMEGPU_HOST_FUNCTION(validation) {
    // Do something
}

flamegpu::ModelDescription model("Layers Example");
    flamegpu::AgentDescription agent = model.newAgent("agent");
    flamegpu::AgentFunctionDescription outputdata_fn = agent.newFunction("outputdata_fn", outputdata);
... // Remainder of the full model definition

// Create a new layer for the model 'model'
flamegpu::LayerDescription layer = model.newLayer();
// Add the agent function 'outputdata' to the layer, by FLAMEGPU_AGENT_FUNCTION
layer.addAgentFunction(outputdata);
// Add the agent function 'outputdata' to the layer, by AgentFunctionDescription instance
layer.addAgentFunction(outputdata_fn);
// Add the agent function 'outputdata' to the layer, by agent and function name
layer.addAgentFunction("agent", "outputdata_fn");

// Create a new layer for the host function 'validation'
model.newLayer().addHostFunction(validation);

Note

If you use the same FLAMEGPU_AGENT_FUNCTION multiple times, either with multiple or the same agent, you must add it to layers using either the AgentFunctionDescription instance or agent and function name. Adding it via the FLAMEGPU_AGENT_FUNCTION will fail as it is not possible to identify the correct instance.

Layer Specification Rules

The below rules are enforced, to ensure functions and submodels placed in the same layer can operate concurrently. If you attempt to break these rules an exception will be raised.

  • An agent function and a host function may not exist in the same layer.

  • An agent function cannot be added to a layer containing an agent function for the same agent (which shares an input or output state) with another agent function.

  • An agent function cannot be added to a layer containing an agent function which outputs new agents which share the type (and input or output state) with another agent function.

  • An agent function which outputs to a message list cannot be in the same layer as an agent function which inputs/outputs to/from the same message list.

  • A host function may only exist in a layer by itself.

  • A submodel may only exist in a layer by itself.