Defining Host Functions

Unlike agent functions, host Functions are implemented natively, in C++ if using the C++ API, or in Python if using the Python API.

In the C++ API a host function is defined using the FLAMEGPU_HOST_FUNCTION macro, similarly a host condition is defined using the FLAMEGPU_HOST_CONDITION. This takes a single argument, a unique name identifying the function.

In the Python API a host function is defined as a subclass of HostFunctionCallback, similarly a host condition is defined as a subclass of HostFunctionConditionCallback.

// Define a host function called host_fn1
FLAMEGPU_HOST_FUNCTION(host_fn1) {
    // Behaviour goes here
}

// Define a host condition called host_cdn1
FLAMEGPU_HOST_CONDITION(host_cdn1) {
    // Behaviour goes here
    return flamegpu::CONTINUE;
}

Types of Host Function

FLAME GPU currently has 4 types of host function, they are all fundamentally the same besides at which point during a simulation they are executed.

Within the C++ API they have optional macro synonyms which can be used to improve the clarity of code.

Type

C++ Macro

Description

Initialisation

FLAMEGPU_INIT_FUNCTION

Execute once before the main simulation, useful for creating agents and initialising dynamic/derived agent variables.

Exit

FLAMEGPU_EXIT_FUNCTION

Execute once after the main simulation, useful for reducing the full simulation state to important data to be logged.

Step

FLAMEGPU_STEP_FUNCTION

Execute after each step of the main simulation, useful for updating the environment based on agent reductions.

Host-Layer

FLAMEGPU_HOST_FUNCTION

Execute anywhere specified during the main simulation, useful for updating the environment based on agent reductions.

FLAME GPU currently has 1 type of host condition, within the C++ API it’s macro synonym can optionally be used.

Type

C++ Macro

Description

Exit

FLAMEGPU_EXIT_CONDITION

Execute once each step of the main simulation, useful for controlling when a model or submodel should exit early. Must return either CONTINUE or EXIT.

Adding Host Functions to a Model

Host functions and conditions are predominantly added to a model via their respective methods on ModelDescription. They will execute in the order in which they are added. The exception to this rule are host-layer functions, details on how to specify their position in the execution order can be found here.

Type

C++ Method

Python Method

Initialisation Function

addInitFunction()

addInitFunctionCallback()

Exit Function

addStepFunction()

addStepFunctionCallback()

Step Function

addExitFunction()

addExitFunctionCallback()

Host-Layer Function

n/a

n/a

Exit Condition

addExitCondition()

addExitConditionCallback()

The below example shows how an init function would be added to a model:

// Define an init function called init_fn
FLAMEGPU_INIT_FUNCTION(init_fn) {
    ... // Behaviour goes here
}

int main() {
    // Define a new model
    flamegpu::ModelDescription model("Test Model");
    ... // Rest of model definition
    // Add the init function init_fn to Test Model
    model.addInitFunction(init_fn);
    ...
}