diff --git a/CMakeLists.txt b/CMakeLists.txt index 85c1d1709..f42930463 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -41,7 +41,7 @@ endif() set(DOCS_SRC_FILES "${CMAKE_CURRENT_SOURCE_DIR}/src/guide/agent-functions/agent-birth-death.rst" "${CMAKE_CURRENT_SOURCE_DIR}/src/guide/agent-functions/agent-communication.rst" - "${CMAKE_CURRENT_SOURCE_DIR}/src/guide/agent-functions/conditional-behaviours.rst" + "${CMAKE_CURRENT_SOURCE_DIR}/src/guide/agent-functions/agent-state-transitions.rst" "${CMAKE_CURRENT_SOURCE_DIR}/src/guide/agent-functions/defining-agent-functions.rst" "${CMAKE_CURRENT_SOURCE_DIR}/src/guide/agent-functions/index.rst" "${CMAKE_CURRENT_SOURCE_DIR}/src/guide/agent-functions/interacting-with-environment.rst" diff --git a/requirements.txt b/requirements.txt index 03c3cb5ae..30056cc07 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,3 +6,4 @@ sphinx_rtd_theme sphinx_tabs sphinx-copybutton sphinxcontrib-mermaid +sphinxext-rediraffe diff --git a/src/conf.py.in b/src/conf.py.in index 7c1b3f272..5bbe0eafd 100644 --- a/src/conf.py.in +++ b/src/conf.py.in @@ -39,7 +39,8 @@ extensions = [ 'sphinx_tabs.tabs', 'sphinx_copybutton', 'sphinx.ext.graphviz', - 'sphinxcontrib.mermaid' + 'sphinxcontrib.mermaid', + 'sphinxext.rediraffe' ] # If the @@ -148,3 +149,8 @@ html_js_files = [ # Config params passed to mermaid mermaid_init_js = "mermaid.initialize({startOnLoad:true,theme: 'neutral'});" + +# Specify deleted page redirects +rediraffe_redirects = { + 'guide/agent-functions/conditional-behaviours.rst':'guide/agent-functions/agent-state-transitions.rst' +} \ No newline at end of file diff --git a/src/guide/agent-functions/conditional-behaviours.rst b/src/guide/agent-functions/agent-state-transitions.rst similarity index 76% rename from src/guide/agent-functions/conditional-behaviours.rst rename to src/guide/agent-functions/agent-state-transitions.rst index 2cd5554b1..2316e91e7 100644 --- a/src/guide/agent-functions/conditional-behaviours.rst +++ b/src/guide/agent-functions/agent-state-transitions.rst @@ -1,3 +1,49 @@ +.. _Agent State Transitions: + +Agent State Transitions +======================= + +Models which utilise agent states require a means of moving agents between states. In FLAME GPU this is handled by configuring the initial and end state of an agent function, via :func:`setInitialState()` and :func:`setEndState()` respectively. + +Example definition of controlling an agent function's initial and end states: + +.. tabs:: + + .. code-tab:: cpp C++ + + // A model is defined + ModelDescription m("model"); + // It contains an agent with 'variable 'x' and two states 'foo' and 'bar' + AgentDescription a = m.newAgent("agent"); + a.newVariable("x"); + a.newState("foo"); + a.newState("bar"); + // The agent has an agent function which transitions agents from state 'foo' to 'bar' + AgentFunctionDescription af1 = a.newFunction("example_function", ExampleFn); + af1.setInitialState("foo"); + af1.setEndState("bar"); + + .. code-tab:: py Python + + # A model is defined + m = pyflamegpu.ModelDescription("model") + # It contains an agent with 'variable 'x' and two states 'foo' and 'bar' + a = m.newAgent("agent") + a.newVariableInt("x") + a.newState("foo") + a.newState("bar") + # The agent has an agent function which transitions agents from state 'foo' to 'bar' + af1 = a.newRTCFunction("example_function", ExampleFn_source) + af1.setInitialState("foo") + af1.setEndState("bar") + +The above example however moves all agents from state `foo` to state `bar`. This can be useful if you wish to emulate an agent initialisation function which agents execute once in an initial state (`foo` in this case), before transferring to the main state (`bar`) that agents remain in for the remainder of the simulation. All remaining agent functions would be defined with initial and end state `bar`. + +If you wish to split agent population, such that only a subset move between statements, you should make use of agent function conditions. + + +.. _Agent Function Conditions: + Agent Function Conditions (Conditional Behaviours) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -37,14 +83,7 @@ Example definition of how the above agent function condition would be attached t .. tabs:: .. code-tab:: cpp C++ - - // A model is defined - ModelDescription m("model"); - // It contains an agent with 'variable 'x' and two states 'foo' and 'bar' - AgentDescription a = m.newAgent("agent"); - a.newVariable("x"); - a.newState("foo"); - a.newState("bar"); + // The agent has an agent function which transitions agents from state 'foo' to 'bar' AgentFunctionDescription af1 = a.newFunction("example_function", ExampleFn); af1.setInitialState("foo"); @@ -54,13 +93,6 @@ Example definition of how the above agent function condition would be attached t .. code-tab:: py Python - # A model is defined - m = pyflamegpu.ModelDescription("model") - # It contains an agent with 'variable 'x' and two states 'foo' and 'bar' - a = m.newAgent("agent") - a.newVariableInt("x") - a.newState("foo") - a.newState("bar") # The agent has an agent function which transitions agents from state 'foo' to 'bar' af1 = a.newRTCFunction("example_function", ExampleFn_source) af1.setInitialState("foo") @@ -71,13 +103,6 @@ Example definition of how the above agent function condition would be attached t .. code-tab:: py Python (with Agent C++ Strings) - # A model is defined - m = pyflamegpu.ModelDescription("model") - # It contains an agent with 'variable 'x' and two states 'foo' and 'bar' - a = m.newAgent("agent") - a.newVariableInt("x") - a.newState("foo") - a.newState("bar") # The agent has an agent function which transitions agents from state 'foo' to 'bar' af1 = a.newRTCFunction("example_function", ExampleFn_source) af1.setInitialState("foo") @@ -91,6 +116,7 @@ Example definition of how the above agent function condition would be attached t Related Links ------------- +* User Guide Page: :ref:`Defining Agents` * User Guide Page: :ref:`Defining Agent Functions` * Full API documentation for :class:`AgentFunctionDescription` * Full API documentation for :c:macro:`FLAMEGPU_AGENT_FUNCTION_CONDITION` diff --git a/src/guide/agent-functions/index.rst b/src/guide/agent-functions/index.rst index 04f7b1cd3..7698b6feb 100644 --- a/src/guide/agent-functions/index.rst +++ b/src/guide/agent-functions/index.rst @@ -26,7 +26,7 @@ This chapter has been broken up into several sections: agent-communication.rst agent-birth-death.rst random-numbers.rst - conditional-behaviours.rst + agent-state-transitions.rst miscellaneous.rst .. note:: diff --git a/src/guide/defining-agents/index.rst b/src/guide/defining-agents/index.rst index 066f4d38e..2e332d212 100644 --- a/src/guide/defining-agents/index.rst +++ b/src/guide/defining-agents/index.rst @@ -91,7 +91,8 @@ States can be defined through the :class:`AgentDescription` are then used to transfer agents between states. Related Links ^^^^^^^^^^^^^ @@ -99,5 +100,6 @@ Related Links * User Guide Section: :ref:`Supported Types` * User Guide Chapter: :ref:`Agent Functions` * User Guide Page: :ref:`Agent Operations` (Host Functions) +* User Guide Page: :ref:`Agent State Transitions` * Full API documentation for :class:`AgentDescription` * Full API documentation for :class:`ModelDescription`