Expand agent state transition coverage.

Add redirect so old page URL redirects to new page.

guide/agent-functions/conditional-behaviours to guide/agent-functions/agent-state-transitions

Closes #169

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"

requirements.txt

@@ -6,3 +6,4 @@ sphinx_rtd_theme
 sphinx_tabs
 sphinx-copybutton
 sphinxcontrib-mermaid
+sphinxext-rediraffe

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'
+}

src/guide/agent-functions/conditional-behaviours.rst → 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()<flamegpu::AgentFunctionDescription::setInitialState>` and :func:`setEndState()<flamegpu::AgentFunctionDescription::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<int>("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<int>("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<Defining Agents>`
 * User Guide Page: :ref:`Defining Agent Functions<Defining Agent Functions>`
 * Full API documentation for :class:`AgentFunctionDescription<flamegpu::AgentFunctionDescription>`
 * Full API documentation for :c:macro:`FLAMEGPU_AGENT_FUNCTION_CONDITION`

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::

src/guide/defining-agents/index.rst

@@ -91,13 +91,15 @@ States can be defined through the :class:`AgentDescription<flamegpu::AgentDescri
     # Create two new states, resting and hunting
     predator.newState("resting")
     predator.newState("hunting")
-
+
+:ref:`Agent State Transitions<Agent State Transitions>` are then used to transfer agents between states.
 
 Related Links
 ^^^^^^^^^^^^^
 
 * User Guide Section: :ref:`Supported Types<Supported Types>`
 * User Guide Chapter: :ref:`Agent Functions<Agent Functions>`
 * User Guide Page: :ref:`Agent Operations<Host Agent Operations>` (Host Functions)
+* User Guide Page: :ref:`Agent State Transitions<Agent State Transitions>`
 * Full API documentation for :class:`AgentDescription<flamegpu::AgentDescription>`
 * Full API documentation for :class:`ModelDescription<flamegpu::ModelDescription>`