Host Functions & Conditions

Not all model behaviours can be achieved with agent functions. Some behaviours need to operate over at a level above agents, host functions provide this functionality. If you need to perform a reduction over an agent population, sort agents or update environment properties a host function can deliver.

Host functions, as suggested by their name, execute on the host rather than the GPU. As such, they have access to the whole simulation state via the HostAPI, however there is an inherent latency to copying data between host and device. So it is often preferable to minimise agent interactions from host functions as much as feasible.

In prior versions of FLAME GPU, host functions were restricted to executing as initialisation functions (once before the simulation), exit functions (once after the simulation) or step functions (once at the end of each step). FLAME GPU 2 now additionally allows host functions to execute among agent functions during a step.

Host functions when not used as init, exit or step functions, are added to either layers or a dependency graph to control when they execute similar to agent functions. They cannot be dynamically started from agent functions, rather in this case the host function should execute each iteration and perform a reduction of an agent population to check whether a condition passes.

Host conditions are host functions with a return value. Currently, their usage is limited to a model’s exit conditions, for example if a model can fully resolve before the number of time steps specified. All content that refers to host functions in this chapter applies to host conditions too.

This chapter has been broken up into several sections:

• Defining Host Functions
• Accessing the Environment
• Agent Operations
• Random Numbers
• Miscellaneous Methods

Note

Currently custom reductions and transformations of agent variables are not supported via the Python API.