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;
}

# Define a host function called host_fn1
class host_fn1(pyflamegpu.HostFunctionCallback):
  '''
     The explicit __init__() is optional, however if used the superclass __init__() must be called
  '''
  def __init__(self):
    super().__init__()

  def run(self,FLAMEGPU):
    # Behaviour goes here


# Define a host condition called host_cdn1
class host_cdn1(pyflamegpu.HostFunctionConditionCallback):
  '''
     The explicit __init__() is optional, however if used the superclass __init__() must be called
  '''
  def __init__(self):
    super().__init__()

  def run(self, FLAMEGPU):
    # Behaviour goes here
    return pyflamegpu.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);
    ...
}

# Define a host function called init_fn
class init_fn(pyflamegpu.HostFunctionCallback):
  '''
     The explicit __init__() is optional, however if used the superclass __init__() must be called
  '''
  def __init__(self):
    super().__init__()

  def run(self, FLAMEGPU):
    # Behaviour goes here



# Define a new model
model = pyflamegpu.ModelDescription("Test Model")
... # Rest of model definition
# Add the exit function init_fn to Test Model
model.addInitFunctionCallback(init_fn().__disown__())
...

Warning

The above Python example calls __disown__() on the instance of init_fn created inline. Python host functions are created and owned by Python, only a reference to them is passed to the C++ internals. Calling __disown__() ensures that the Python owned host function will not go out of scope and be deallocated during the program’s lifetime. Failing to call __disown__() can lead to undefined behaviour.

For updates on this see the issue on GitHub <https://github.com/FLAMEGPU/FLAMEGPU2/issues/498>

Defining Host Functions

Types of Host Function

Adding Host Functions to a Model

Related Links