Skip to content

Commit

Permalink
add init/step/exit fn info to model structure synopsis
Browse files Browse the repository at this point in the history
  • Loading branch information
Robadob committed Sep 26, 2023
1 parent 6f3dff2 commit 94bc222
Show file tree
Hide file tree
Showing 2 changed files with 7 additions and 2 deletions.
7 changes: 5 additions & 2 deletions src/guide/creating-a-model/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ The hierarchy of a :class:`ModelDescription<flamegpu::ModelDescription>` is show
Model-->Message;
Model-->Environment;
Model-->Layer;
Model-->e["Init/Step/Exit Function"];
Message-->Variable;
Agent-->a["Variable"];
Agent-->b["Agent Function"];
Expand All @@ -33,14 +34,16 @@ The hierarchy of a :class:`ModelDescription<flamegpu::ModelDescription>` is show
Layer-->d[Host Function];
Layer-->SubModel;

:ref:`Agents<Defining Agents>` are the executors of primary model behaviour. All agents of the same type and state execute in parallel, where they can updated their internal variables based on the environment's properties and messages from other agents.
:ref:`Agents<Defining Agents>` are the executors of primary model behaviour. All agents of the same type and state execute in parallel, where they can update their internal variables based on messages from other agents and the environment's properties.

:ref:`Messages<Defining Messages>` are what agents share and read to communicate with one another. Due to the parallel nature of a FLAME GPU model, they must be input in a separate agent function to the one they are output from. There are a wide range of message types supported, to enable the most efficient communication strategy for each purpose.
:ref:`Messages<Defining Messages>` are what agents share to communicate with one another. Due to the parallel nature of a FLAME GPU model, they must be input in a separate agent function to the one they are output from. There are a wide range of message types supported, to enable the most efficient communication strategy for any purpose.

:ref:`The Environment<defining environmental properties>` holds global state information in the form of properties and macro properties. The environment is primarily mutated via :ref:`host functions<Defining Host Functions>`, which execute serially at the global level. New to FLAME GPU 2, :ref:`macro properties<Define Macro Environmental Properties>` support upto 4-dimensional arrays and provide a limited set of mutators so that they can be updated during agent functions.

:ref:`Layers<Layers>` are FLAME GPUs original method of defining the control flow of a model, layers are each executed in sequence and all functions within a layer may execute in parallel. FLAME GPU 2 alternatively provides a new intuitive :ref:`dependency graph API<Dependency Graph>`, where instead dependencies between functions are defined, the layers are then automatically generated based on the dependencies. Additionally, FLAME GPU 2 introduces the concept of :ref:`submodels<Defining a Submodel>` which allow iterative algorithms (typically parallel conflict resolution) to be modelled within a single model step by nesting a model with shared agents.

:ref:`Init, Step and Exit functions<Types of Host Function>` are host functions which execute either at the start of the simulation, end of each step or after the simulation has finished. Otherwise, they are exactly the same as host functions attached to layers or the dependency graph. Additionally, FLAME GPU 2 provides a specialised :ref:`Exit Condition<Exit Conditions>` host function, which can end a simulation early if a user-defined condition is met.

Once the :class:`ModelDescription<flamegpu::ModelDescription>` has been completely described, it is used to construct either a :class:`CUDASimulation<flamegpu::CUDASimulation>` or :class:`CUDAEnsemble<flamegpu::CUDAEnsemble>` to execute simulations of the model.


Expand Down
2 changes: 2 additions & 0 deletions src/guide/host-functions/defining-host-functions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ In the Python API a host function is defined as a subclass of :class:`HostFuncti
Although python Host functions and conditions are classes, the class should not utilise any additional stateful information (e.g. `self`). When executed via ensembles, Python host function instances are shared between concurrent simulation runs, which may lead to race conditions where stateful information is present.


.. _Types of Host Function:

Types of Host Function
----------------------

Expand Down

0 comments on commit 94bc222

Please sign in to comment.