diff --git a/src/guide/creating-a-model/index.rst b/src/guide/creating-a-model/index.rst index d3a61f350..fdc635499 100644 --- a/src/guide/creating-a-model/index.rst +++ b/src/guide/creating-a-model/index.rst @@ -22,6 +22,7 @@ The hierarchy of a :class:`ModelDescription` is show Model-->Message; Model-->Environment; Model-->Layer; + Model-->e["Init/Step/Exit Function"]; Message-->Variable; Agent-->a["Variable"]; Agent-->b["Agent Function"]; @@ -33,14 +34,16 @@ The hierarchy of a :class:`ModelDescription` is show Layer-->d[Host Function]; Layer-->SubModel; -:ref:`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` 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` 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` 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` holds global state information in the form of properties and macro properties. The environment is primarily mutated via :ref:`host functions`, which execute serially at the global level. New to FLAME GPU 2, :ref:`macro properties` support upto 4-dimensional arrays and provide a limited set of mutators so that they can be updated during agent functions. :ref:`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`, 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` 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` 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` host function, which can end a simulation early if a user-defined condition is met. + Once the :class:`ModelDescription` has been completely described, it is used to construct either a :class:`CUDASimulation` or :class:`CUDAEnsemble` to execute simulations of the model. diff --git a/src/guide/host-functions/defining-host-functions.rst b/src/guide/host-functions/defining-host-functions.rst index 31b018334..4f96fb9b4 100644 --- a/src/guide/host-functions/defining-host-functions.rst +++ b/src/guide/host-functions/defining-host-functions.rst @@ -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 ----------------------