.. SPDX-License-Identifier:  MIT

.. _ln-cosm-usage-xml-controllers:

============================
Controller XML Configuration
============================

The following root XML tags are defined for all controller types:

.. list-table::
   :widths: 25,50
   :header-rows: 1

   * - Root XML Tag

     - Description

   * - ``output``

     - Parameters for simulation outputs generated by controllers within a
       simulation run. This includes debugging logs as well as gather metrics.

   * - ``strategy``

     - Parameters for different behaviors that robots can execute.

   * - ``perception``

     - Parameters for discretization of the continuous world into a grid, and/or
       the objects it tracks within it.

   * - ``task_executive``

     - Parameters for the task executive (the entitity responsible for
       managing/running tasks after they have been allocated), which are mainly
       configuration for *HOW* tasks are run once they are allocated.

   * - ``task_alloc``

     - Parameters for task allocation.

   * - ``sensing_subsystem``

     - Parameters for robot sensing subsystem.

   * - ``actuation_subsystem``

     - Parameters for robot actuation subsystem.

   * - ``flocking``

     - Parameters for swarms performing flocking.

``output``
==========

- Required by: All controllers.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

XML configuration:

.. code-block:: XML

   <output
       output_root="output"
       output_dir="__current_date__"
   />

- ``output_root`` - The root output directory in which the directories of
  different simulation runs will be placed. The path specified can be relative
  or absolute, and will be created if it does not exist.

- ``output_dir`` - The output directory for the current simulation under
  ``output_root``. If you put the special field ``__current_date__`` here, the
  simulation will get a unique output directory in the form YYYY-MM-DD:HH-MM.

``strategy``
============

- Required by: all.
- Required child attributes if present: [ ``nest_acq``, ``nest_exit`` ].
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: [ ``blocks`` ].

XML configuration:

  .. code-block:: XML

     <strategy>
       <nest_acq>
         ...
       </nest_acq>
       <nest_exit>
         ...
       </nest_exit>
       <blocks>
         ...
       </blocks>
   />

``strategy/explore``
---------------------------

- Required child attributes if present: [  ``strategy`` ].
- Required child tags if present: [ ``min_duration`` ].
- Optional child tags: none.
- Optional child attributes: none.


XML configuration:

  .. code-block:: XML

     <strategy>
       ...
       <explore
          strategy="crw"
          min_duration="INT">
         ...
       </explore>
       ...
   />

- ``strategy`` - The strategy robots should use when exploring for SOMETHING
  (unspecified at this level). Valid values are:

  - ``CRW`` - Correlated Random Walk.

- ``min_duration`` - How long to perform the selected strategy for. Valid for: [
  ``CRW`` ].

``strategy/nest``
-----------------

- Required child attributes if present: none.
- Required child tags if present: [ ``acq``, ``exit`` ].
- Optional child tags: none.
- Optional child attributes: none.


XML configuration:

  .. code-block:: XML

     <strategy>
       ...
       <nest>
         <acq>
           ..
         </acq>
         <exit>
           ..
         </exit>
       </nest>
       ...
   />


``strategy/nest/acq``
^^^^^^^^^^^^^^^^^^^^^

- Required by: All controllers.
- Required child attributes if present: ``strategy``.
- Required child tags if present: None.
- Optional child attributes: None.
- Optional child tags: None.

XML configuration:

.. code-block:: XML

   <nest>
       <acq
          strategy="wander|random_thresh|wander_random_thresh"
          duration="INT"/>
       ...
   </nest>


- ``strategy`` - The strategy robots should use once they have entered the nest
  with an object to choose a precise location to drop it at. Valid values are:

  - ``wander`` - Perform phototaxis+wander, avoiding collisions as needed, for a
    random number of timesteps before acquiring the nest.

  - ``random_thresh`` - Perform phototaxis+collision avoidance, choosing a
    random point along the vector pointing from where the robot enters the nest
    to the center to treat as the center/use as the nest acquisition point, and
    phototaxis to that point.

  - ``wander_random_thresh`` - ``random_thresh`` + ``wander``.

- ``duration`` - How long to perform the strategy for. Valid for: [ ``wander``
  ].

``strategy/nest/exit``
^^^^^^^^^^^^^^^^^^^^^^

- Required by: All controllers.
- Required child attributes if present: ``strategy``.
- Required child tags if present: None.
- Optional child attributes: None.
- Optional child tags: None.

XML configuration:

.. code-block:: XML

   <nest>
       <acq strategy="wander|anti_phototaxis"/>
       ...
   </nest>


- ``strategy`` - The strategy robots should use once they have entered the nest
  with an object to choose a precise location to drop it at. Valid values are:

  - ``wander`` - Perform wander, avoiding collisions as needed, until the robot
    exits the nest or gets pushed out.

  - ``anti_phototaxis`` - Perform anti-phototaxis+collision avoidance until the
    robot exits the nest.

``strategy/blocks``
-------------------

- Required child attributes if present: none.
- Required child tags if present: none.
- Optional child tags: [ ``drop`` ].
- Optional child attributes: none.


XML configuration:

  .. code-block:: XML

     <strategy>
       ...
       <blocks>
         <drop>
           ..
         </drop>
       </blocks>
       ...
   />

``strategy/blocks/drop``
^^^^^^^^^^^^^^^^^^^^^^^^

- Required child attributes if present: [  ``strategy`` ].
- Required child tags if present: none.
- Optional child tags: [ ``duration`` ].
- Optional child attributes: none.


XML configuration:

  .. code-block:: XML

     <blocks>
       ...
       <drop
          strategy="backup|backup_pivot"
          duration="INT">
         ...
       </drop>
       ...
   />

- ``strategy`` - The strategy robots should use to drop blocks. Valid values
  are:

  - ``backup`` - Backup for ``duration`` timesteps. Useful when robots are
    pushing blocks to "carry" them.

  - ``backup_pivot`` - Backup for ``duration``/2 timesteps, then pivot for
    ``duration/2`` timesteps. Useful when robots are pushing blocks to "carry"
    them.

- ``duration`` - How long to perform the selected strategy for. Valid for: [
  ``backup``, ``backup_pivot`` ].

``perception``
==============

- Required child attributes if present: [  ``type`` ].
- Required child tags if present: none.
- Optional child tags: [ ``rlos`` ]
- Optional child attributes: none.

XML configuration:

.. code-block:: XML

   <perception
     type="STRING">
     <rlos>
        ...
     </rlos>
   </perception>

- ``type`` - The perception type to use.

``perception/rlos``
-------------------

- Required child attributes if present: [  ``los_dim`` ].
- Required child tags if present: none.
- Optional child tags: [ ``arena`` ].
- Optional child attributes: none.

XML configuration:

.. code-block:: XML

   <perception>
     ...
     <rlos
       dim="FLOAT">
       <grid2D>
         ...
       </grid2D>
     </rlos>
     ...
   </perception>

- ``dim`` - The dimension of robot LOS (LOS is a square).
- ``grid2D`` - The dimensions of the arena (optional).

``perception/rlos/grid2D``
^^^^^^^^^^^^^^^^^^^^^^^^^^

- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

XML configuration:

.. code-block:: XML

   <rlos>
     ...
     <grid2D resolution="FLOAT"
             dims="FLOAT, FLOAT, FLOAT"/>
     ...
   </rlos>

- ``resolution`` - The size of the cells the arena is broken up (discretized)
  into. Should probably be the same as whatever the block size is, to make
  things easy.

- ``dims`` - The size of the arena, specified as "X, Y, Z" (the spaces are
  mandatory).

``task_executive``
==================

- Required by: None. Used by all task based controllers with the default values
  shown below if it is omitted.
- Required child attributes if present: none.
- Required child tags if present: none.
- Optional child attributes: [``update_exec_ests``, ``update_interface_ests`` ]
- Optional child tags: none.

XML configuration:

.. code-block:: XML

   <task_executive
       update_exec_ests="false"
       update_interface_ests="false"/>

- ``update_exec_ests`` - If *true*, then the executive will use the elapsed
  time since a task started to update the task time estimate. Estimate is
  updated on both abort an completion. Default if omitted: *false*.

- ``update_interface_ests`` - If *true*, then the executive will use the
  calculated interface time for a task to update the interface estimate for the
  task. Estimate is updated on both abort and completion. Default if omitted: *false*.

``task_alloc``
==============

- Required by: None. Used by all task based controllers with the default values
  shown below if it is omitted.
- Required child attributes if present: all.
- Required child tags if present: ``task_abort``.
- Optional child attributes: none.
- Optional child tags: [``stoch_nbhd1``, ``task_exec_estimates``,
  ``epsilon_greedy`` ].

XML configuration:

.. code-block:: XML

   <task_alloc
       policy="random|epsilon_greedy|strict_greedy|stoch_nbhd1|ucb1">
       <matroid_stoch_nbhd>
       ...
       </matroid_stoch_nbhd>
       <task_exec_estimates>
   	...
   	</task_exec_estimates>
       <task_abort>
   	...
   	</task_abort>
   </task_alloc>

- ``policy`` - When performing task allocation, how should tasks be
  selected?

    - ``random`` - Choose a random task each time.

    - ``epsilon_greedy`` - Choose the greedy best with probability 1 - epsilon,
      otherwise choose a random task. Has provably bounds on regret, treating
      task allocation as a multi-armed bandit problem.

    - ``strict_greedy`` - A pure greedy matroid optimization approach.

    - ``stoch_nbhd1`` - A stochastic greedy approach within the
      neighborhood of the most recently executed task (max distance is 1).

    - ``UCB1`` - A deterministic greedy approach based on regret minimization
      (has provable logarithmic bound).

Many child tags in ``<task_alloc>`` use sigmoid-based functions for choosing
between alternatives, with the input src and sigmoid method varying. For such
tags, all child attributes and tags are required unless specified otherwise.

XML configuration:

.. code-block:: XML

   ...
   <src_sigmoid_sel
       input_src="exec|interface">
       <sigmoid_sel
       method="harwell2018">
           <sigmoid reactivity="FLOAT"
                    offset="FLOAT"
                    gamma="FLOAT"/>
       <sigmoid_sel/>
   </src_sigmoid_sel>
   ...

- ``input_src`` - Can be ``exec`` or ``interface``, indicating that estimates of
  execution/interface times should be used in the selection process.

- ``method`` - The method used to calculate a probability using the selected
  input source.

- ``reactivty`` - Once the ``offset`` is tripped, this parameter controls how
  fast the probability a robot aborts its current task grows.

- ``offset`` - A positive proportition indicating what ratio of measured
  execution time to the robot's best estimate of the actual execution time of
  the task is considered to be the threshold for a task taking too long, and
  should be aborted.

- ``gamma`` - A scaling factor that is applied to the overall calculated
  probability.

``task_alloc/task_abort``
-------------------------

Parameters governing task abort calculations.

- Required by: All task based controllers.
- Required child attributes if present: none.
- Required child tags if present: ``src_sigmoid_sel``.
- Optional child attributes: none.
- Optional child tags: none.

``method=harwell2018`` is required.

XML configuration:

.. code-block:: XML

   <task_alloc>
       ...
       <task_abort>
           <src_sigmoid_sel
               input_src="exec|interface">
               <sigmoid_sel
                   method="harwell2018">
                   <sigmoid reactivity="FLOAT"
                            offset="FLOAT"
                            gamma="FLOAT"/>
               <sigmoid_sel/>
           </src_sigmoid_sel>
       </task_abort>
       ...
   </task_alloc>

``task_alloc/task_exec_estimates``
----------------------------------

Parameters governing how/if task execution cost estimates (time costs) will be
seeded and updated.

- Required by: None.
- Required child attributes if present: None.
- Required child tags if present: ``ema`` (only if ``seed_enabled`` is *true*).
- Optional child attributes: all. Only the task names used by the loaded task
  decomposition graph are required; others are ignored.
- Optional child tags: none.

XML configuration:

.. code-block:: XML

    <task_alloc>
        ...
        <task_exec_estimates
            seed_enabled="false"
            task_name="2000:4000">
                <ema alpha="FLOAT"/>
        </task_exec_estimates>
        ...
    </task_alloc>

- ``seed_enabled`` - If *true*, then all estimates of task execution times are
  initialized randomly within the specified ranges, rather than with zero, in
  order to avoid any possibly weird behavior on system
  startup. Default if omitted: *false*.

- ``<task name>`` - Takes a pair like so: ``100:200`` specifying the range of
  the uniform random distribution over which a robots' initial estimation of the
  duration of the specified task will be drawn. Only used if ``seed_enabled`` is
  *true*. Valid values for ``<task_name>`` are project-specific.

``task_alloc/task_exec_estimates/ema``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The exponential moving average (EMA) parameters for task execution estimate
updating.

- Required by: None.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

XML configuration:

.. code-block:: XML

   <task_exec_estimates>
       ...
       <ema alpha="FLOAT"/>
       ...
   </task_exec_estimates>

- ``alpha`` - Parameter for exponential weighting of a moving time estimate of
  the true execution/interface time of a task. Must be < 1.0.

``task_alloc/epsilon_greedy``
-----------------------------

Parameters for the epsilon-greedy method described in :xref:`Auer2002`.

- Required by: Task based controllers if the selected policy is
  ``epsilon_greedy``.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

.. code-block:: XML

    <task_alloc>
        ...
        <epsilon_greedy
            epsilon="FLOAT"
            regret_bound="log|linear"/>
        ...
    </task_alloc>

- ``epsilon`` - Used to control exploration of the method. Must be between 0.0 and
  1.0.

- ``regret_bound`` - What is the provable bound on regret?

  - ``log`` - Logarithmic bounded.
  - ``linear`` - Linearly bounded (more regret).

``task_alloc/ucb1``
-------------------

Parameters for the UCB1 method described in :xref:`Auer2002`.

- Required by: Task based controllers if the selected policy is ``ucb1``.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

.. code-block:: XML

    <task_alloc>
        ...
        <ucb1 gamma="FLOAT"/>
        ...
    </task_alloc>

- ``gamma`` - Weighting factor to control how much exploration of the
  method. Must be between 0.0 and 1.0.

``task_alloc/stoch_nbhd1``
--------------------------

Parameters for the stochastic task allocation neighborhood  method described in
:xref:`Harwell2020a-demystify`.

- Required by: Task based controllers if the selected policy is ``stoch_nbhd1``.
- Required child attributes if present: all.
- Required child tags if present: [ ``task_partition``, ``subtask_sel`` ].
- Optional child attributes: none.
- Optional child tags: [ ``tab_sel`` ].

XML configuration:

.. code-block:: XML

    <task_alloc>
        ...
        <stoch_nbhd1
            tab_init_policy="root|max_depth|random">
        	<task_partition>
        	...
        	</task_partition>
        	<subtask_sel>
        	...
        	</subtask_sel>
        	<tab_sel>
        	...
        	</tab_sel>
        </stoch_nbhd1>
        ...
    </task_alloc>

- ``tab_init_policy`` - When performing initial task allocation, how should the
  initial Task Allocation Block (TAB), consisting of a root has and two
  sequentially interdependent subtasks, be selected. Valid values are:

    - ``root`` - Use the root TAB as the initially active TAB.

    - ``random`` - Choose a random TAB as the initially active TAB.

    - ``max_depth`` - Choose a random TAB from among those at the greatest depth
      within the task decomposition graph that is passed to the executive.


``task_alloc/stoch_nbhd1/task_partition``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Task partitioning parameters for the STOCH-NBHD1 method. Based on the work in
:xref:`Pini2011`.

- Required by: Task based controllers.
- Required child attributes if present: none.
- Required child tags if present: ``src_sigmoid_sel``.
- Optional child attributes: [``always_partition``, ``never_partition`` ].
- Optional child tags: none.

XML configuration:

.. code-block:: XML

    <stoch_nbhd1>
        ...
        <task_partition
            always_partition="false"
            never_partition="false">
            <src_sigmoid_sel
                input_src="exec|interface">
                <sigmoid_sel
                    method="pini2011">
                    <sigmoid reactivity="FLOAT"
                             offset="FLOAT"
                             gamma="FLOAT"/>
                <sigmoid_sel/>
            </src_sigmoid_sel>
        </task_partition>
    </stoch_nbhd1>


- ``always_partition`` - If *true*, then robots will always choose to
  partition a task, given the chance. Default if omitted: *false*.

- ``never_partition`` - If *true*, then robots will never choose to partition a
  task, given the chance. Default if omitted: *false*.

``method`` tag can be one of [ ``pini2011`` ] for performing the stochastic
partitioning decision. Calculated once upon each task allocation, after the
previous task is finished or aborted.

``task_alloc/stoch_nbhd1/subtask_sel``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Task partitioning parameters for the STOCH-NBHD1 method. Based on the work in
:xref:`Pini2011`, :xref:`Brutschy2014`.

- Required by: Task based controllers.
- Required child attributes if present: none.
- Required child tags if present: ``src_sigmoid_sel``.
- Optional child attributes: none.
- Optional child tags: none.

XML configuration:

.. code-block:: XML

    <stoch_nbhd1>
        ...
        <subtask_sel>
            <src_sigmoid_sel
                input_src="exec|interface">
                <sigmoid_sel
                    method="harwell2018|random">
                    <sigmoid reactivity="FLOAT"
                             offset="FLOAT"
                             gamma="FLOAT"/>
                <sigmoid_sel/>
            </src_sigmoid_sel>
        </subtask_sel>
        ...
    </stoch_nbhd1>

``method`` tag can be one of [``harwell2018``, ``random`` ] to perform stochastic
subtask selection if partitioning is employed.

``task_alloc/stoch_nbhd1/tab_sel``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Parameters for Task Allocation Block (TAB) selection in recursive task
decomposition graphs used in the STOCH-NBHD1 method described in
:xref:`Harwell2020a-demystify`.

- Required child attributes if present: ``src_sigmoid_sel``.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

XML configuration:

.. code-block:: XML

    <stoch_nbhd1>
        ...
        <tab_sel>
            <src_sigmoid_sel
                input_src="exec|interface">
                <sigmoid_sel
                    method="harwell2019">
                    <sigmoid reactivity="FLOAT"
                             offset="FLOAT"
                             gamma="FLOAT"/>
                <sigmoid_sel/>
            </src_sigmoid_sel>
        </tab_sel>
        ...
    </stoch_nbhd1>


``method`` tag that can be one of [ ``harwell2019`` ].

``sensing_subsystem``
========================

- Required by: All controllers.
- Required child attributes if present: none.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: [ ``proximity_sensor``, ``env_sensor`` ].

XML configuration:

.. code-block:: XML

   <sensing_subsystem>
       <proximity_sensor>
       ...
       </proximity_sensor>
       <env_sensor>
       ...
       </env_sensor>
   </sensing_subsystem>


``sensing_subsystem/proximity_sensor``
-----------------------------------------

Parameters for proximity sensor configuration.

- Required by: All controllers.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: [ ``exp_decay`` ].
- Optional child tags: none.

.. code-block:: XML

    <sensing_subsystem>
        ...
        <proximity_sensor
            fov="FLOAT:FLOAT"
            delta="FLOAT"
            exp_decay="BOOL"/>
        ...
    </sensing_subsystem>

- ``fov`` - The angle range to the left/right of center in which obstacles are
  not ignored (outside of this range they are ignored, assuming the robot will
  be able to drive by them). Takes a pair like so: ``-1:1``. Specified in
  radians.

- ``delta`` - Tripping threshold for calculations for obstacle
  detection. Dependent on the value of ``exp_decay``.

- ``exp_decay`` - If ``true``, then apply :math:`e^{-x}` to all distance values
  before returning them to the robot controller. Only used if COSM is built for
  ROS; for compatibility of ROS robot controller code with ARGoS robot
  controller code, which does this by default.

``sensing_subsystem/ground_sensor``
--------------------------------------

Parameters for ground sensor configuration.

- Required by: All controllers.
- Required child attributes if present: none.
- Required child tags if present: [ ``nest``, ``block``, ``cache`` ].
- Optional child attributes: none.
- Optional child tags: none.

XML configuration:

.. code-block:: XML

    <sensing_subsystem>
        ...
        <ground_sensor>
          <nest range="FLOAT:FLOAT"
                consensus="INTEGER"/>
          <block range="FLOAT:FLOAT"
                consensus="INTEGER"/>
          <cache range="FLOAT:FLOAT"
                consensus="INTEGER"/>
        </ground_sensor>
        ...
    </sensing_subsystem>

For each of [``nest``, ``block``, ``cache``], the following child attributes are
required:

- ``range`` - The range of ground sensor values used to detect the
  object. Should be unique among all the types of objects to detect.

- ``consensus`` - How many of the ground sensors must have readings within the
  specified range in order for a detection to be triggered.

``actuation_subsystem``
=======================

- Required by: All controllers.
- Required child attributes if present: none.
- Required child tags if present: [ ``apf_manager``, ``diff_drive`` ]
- Optional child attributes: none.
- Optional child tags: none.

XML configuration:

.. code-block:: XML

   <actuation_subsystem>
       <apf_manager>
       ...
       </apf_manager>
       <diff_drive>
       ...
       </diff_drive>
   </actuation_subsystem>


``actuation_subsystem/apf_manager``
-----------------------------------

Parameters for the virtual forces used to control robot movement, based on the
original paper :xref:`Arkin1987` and the tutorial in :xref:`SteeringTutorial`.

- Required by: All controllers.
- Required child attributes if present: none.
- Required child tags: [ ``nav`` ].
- Optional child attributes: none.
- Optional child tags if present: [ ``flocking`` ].

XML configuration:

.. code-block:: XML

    <actuation_subsystem>
        ...
        <apf_manager>
          <nav>
            ...
          </nav>
          <flocking>
            ...
          </flocking>
        </apf_manager>
        ...
    </actuation_subsystem>


``actuation_subsystem/apf_manager/nav``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Parameters for the virtual forces used to control robot movement, based on the
original paper :xref:`Arkin1987` and the tutorial in :xref:`SteeringTutorial`.

- Required by: All controllers.
- Required child attributes if present: none.
- Required child tags: none.
- Optional child attributes: none.
- Optional child tags if present: [ ``avoidance_force``, ``arrival_force``,
  ``wander_force``, ``phototaxis_force``, ``path_following_force`` ].

XML configuration:

.. code-block:: XML

    <apf_manager>
        ...
        <nav>
          <avoidance_force>
            ...
          </avoidance_force>
          <arrival_force>
            ...
          </arrival_force>
          <wander_force>
            ...
          </wander_force>
          <phototaxis_force>
            ...
          </phototaxis_force>
          <path_following_force>
            ...
          </path_following_force>
        </nav>
        ...
    </apf_manager>


``actuation_subsystem/apf_manager/nav/avoidance_force``
"""""""""""""""""""""""""""""""""""""""""""""""""""""""

The force which repels robots from other nearby robots and obstacles (robots do
not distinguish between these two cases).

- Required by: none.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

.. code-block:: XML

    <nav>
      ...
      <avoidance_force lookahead="FLOAT"
                       max="FLOAT"/>
      ...
    </nav>

- ``lookahead`` - How far ahead of the robot to look for obstacles. Currently
  unused, but may be used in the future.

- ``max`` - Max value for the force, in m/s.

``actuation_subsystem/apf_manager/nav/arrival_force``
"""""""""""""""""""""""""""""""""""""""""""""""""""""

The force which attracts robots towards a goal and gets them to it.

- Required by: none.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

.. code-block:: XML

    <nav>
      ...
      <arrival_force slowing_radius="FLOAT"
                     slowing_speed_min="FLOAT"
                     max="FLOAT"/>
      ...
    </nav>

- ``slowing_radius`` - Radius around target inside which robots will slow down
  linearly to not overshoot their target.

- ``slowing_speed_min`` - The minimum speed robotics will linearly ramp down
  to. Should be > 0.

- ``max`` - Max value for the force, in m/s.

``actuation_subsystem/apf_manager/nav/wander_force``
""""""""""""""""""""""""""""""""""""""""""""""""""""

The force which causes robots to wander randomly in the environment in a
correlated random walk.

- Required by: none.
- Required child attributes if present: all.
- Required child tags if present: [ ``bias_angle`` ].
- Optional child attributes: none.
- Optional child tags: none.

.. code-block:: XML

    <nav>
      ...
      <wander_force circle_distance="FLOAT"
                    circle_radius_min="FLOAT"
                    max="FLOAT"
                    interval="INTEGER">
         <bias_angle>
         ...
         </bias_angle>
      </wander_force>
      ...
    </nav>

- ``circle_distance`` - Scaling factor for force; applied to current velocity.

- ``circle_radius`` - Displacement (i.e. wander) circle radius; placed at
  ``circle_distance`` from the robot.

- ``max`` - Max value for the force, in m/s.

- ``interval`` - How many timesteps to skip between applying the force.

``actuation_subsystem/apf_manager/nav/wander_force/bias_angle``
###############################################################

Configuration for how the wander/bias angle should be calculated if the wander
force is employed.

- Required by: none.
- Required child attributes if present: [ ``src`` ].
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

.. code-block:: XML

    <wander_force>
      ...
      <bias_angle src="normal|uniform|custom"
                    max_delta="FLOAT"
                    angles="FLOAT,FLOAT,FLOAT,..."/>
      ...
    </wander_force>

- ``src`` - The bias angle distribution source.

  - ``normal`` - Use a normal distribution, truncated at 3 std deviations
    from 0 and wrapped into  [-``max_delta``, ``max_delta`` ].

  - ``uniform`` - Use a uniform distribution [-``max_delta``, ``max_delta`` ].

  - ``custom`` - Specify a custom distribution via a list of specific angles
    which will be drawn from uniformly.

- ``max_delta`` -  +/- Maximum amount of heading change for the wander angle
  (a random value is chosen in this range). Specified in radians. Only affects
  ``normal`` and ``uniform`` sources.

- ``angles`` - A comma separated list of angles specified in radians defining
  the custom bias angle distribution to draw from.

``actuation_subsystem/apf_manager/nav/phototaxis_force``
""""""""""""""""""""""""""""""""""""""""""""""""""""""""

The force which attracts/repels robots towards/away from light sources.

- Required by: none.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

.. code-block:: XML

    <nav>
      ...
      <phototaxis_force max="FLOAT"/>
      ...
    </nav>

- ``max`` - Max value for the force, in m/s.

``actuation_subsystem/apf_manager/nav/path_following_force``
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

The force which guides robots along a specified path.

- Required by: none.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

.. code-block:: XML

    <nav>
      ...
      <arrival_force slowing_radius="FLOAT"
                     slowing_speed_min="FLOAT"
                     max="FLOAT"/>
      ...
    </nav>

- ``max`` - Max value for the force, in m/s.

- ``radius`` - Radius around each point along the path to consider at part of
  the point; i.e., reaching any point inside the radius is equivalent to
  reaching the exact location of the point.

``actuation_subsystem/apf_manager/flocking``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Parameters for the virtual forces used to control robot movement during
flocking. These are distinct from navigation forces which are forces that
individual robots use to accomplish things--flocking forces relate to how robots
*interact* with each other.

- Required by: All controllers.
- Required child attributes if present: none.
- Required child tags: none.
- Optional child attributes: none.
- Optional child tags if present: [ ``alignment_force``,
  ``constant_speed_force`` ].

XML configuration:

.. code-block:: XML

    <apf_manager>
        ...
        <flocking>
          <alignment_force>
            ...
          </alignment_force>
          <constant_speed_force>
            ...
          </constant_speed_force>
        </flocking>
        ...
    </apf_manager>

``actuation_subsystem/apf_manager/flocking/alignment_force``
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

The force which aligns an agent's trajectory with the average of one or more
neighbors. Originally from :xref:`FLOCK:Bagarti2018-stochfov`.

- Required by: none.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

.. code-block:: XML

    <flocking>
      ...
      <alignment_force max="FLOAT"/>
      ...
    </flocking>

- ``max`` - Max value for the force, in m/s.

``actuation_subsystem/apf_manager/flocking/constant_speed_force``
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

The force which aligns an agent's trajectory with the average of one or more
neighbors. Originally from :xref:`FLOCK:Bagarti2018-stochfov`.

- Required by: none.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

.. code-block:: XML

    <flocking>
      ...
      <constant_speed_force max="FLOAT"/>
      ...
    </flocking>

- ``max`` - Max value for the force, in m/s.

``actuation_subsystem/diff_drive``
----------------------------------

Parameters for robot differential drive.

- Required by: All controllers.
- Required child attributes if present: all.
- Required child tags if present: none.
- Optional child attributes: none.
- Optional child tags: none.

XML configuration:

.. code-block:: XML

    <actuation_subsystem>
        ...
        <diff_drive soft_turn_max="FLOAT"
                    max_speed="FLOAT"/>
        ...
    </actuation_subsystem>


- ``soft_turn_max`` - If actuators are told to change to a heading within a
  difference greater than the one specified by this parameter to the current
  heading, a hard turn is executed (spin in place). Specified in radians.

- ``max_speed`` - The maximimum speed of the robot, in m/s.

``flocking``
============

- Required by: none.
- Required child attributes if present: [ ``strategy`` ].
- Required child tags if present: none.
- Optional child attributes: [ ``leader_sel_prob`` ].
- Optional child tags: [ ``stoch_fov`` ].

XML configuration:

.. code-block:: XML

   <flocking
      strategy="stoch_fov"
      leader_sel_prob="FLOAT">

       <stoch_fov>
       ...
       </stoch_fov>

   </flocking>


- ``strategy`` - The flocking strategy to employ. Options are:

  - ``stoch_fov`` - A Stochastic Field Of View (FOV) method from
    :xref:`FLOCK:Bagarti2018-stochfov`.

- ``leader_sel_prob`` - The probability that a given agent will be selected as
  a leader. Can be 0.

``flocking/stoch_fov``
----------------------

Parameters for Stochastic Field Of View (FOV) flocking method from the
:xref:`FLOCK:Bagarti2018-stochfov` paper.

- Required by: none.
- Required child attributes if present: [ ``theta_max``,
  ``mean_interaction_dist`` ].
- Required child tags: none.
- Optional child attributes: none.
- Optional child tags if present: none.

XML configuration:

.. code-block:: XML

    <flocking>
        ...
        <stoch_fov theta_max="FLOAT"
                   mean_interaction_dist="FLOAT"/>

        ...
    </flocking>

- ``theta_max`` - The bearing angle defining the wedge FOV in which an agent
  looks to find another agent to interact with.

- ``mean_interaction_dist`` - The distance which agents should try to be from
  those which they interact with. Steering forces increase/decrease to try to
  maintain this distance at all times.

``flocking/trajectory``
-----------------------

Parameters for specifying trajectories which the swarm should follow during
flocking.

- Required by: none.
- Required child attributes if present: none.
- Required child tags: [ ``point`` ].
- Optional child attributes: [ ``loop`` ].
- Optional child tags if present: none.

XML configuration:

.. code-block:: XML

    <flocking>
       ...
       <trajectory loop="BOOL">
          <point position="FLOAT,FLOAT,FLOAT"/>
          <point position="FLOAT,FLOAT,FLOAT"/>
          ...
       </trajectory>

       ...
    </flocking>

- ``loop`` - Whether or not the trajectory is a loop and should be repeated
  indefinitely.

- ``point`` - Each point along the trajectory. At least 2 points must be
  specified.