Merge pull request #259 from matrx-software/continuous_bug_fixing

Continuous bug fixing

docs/source/index.rst

@@ -11,7 +11,7 @@
    :width: 150%
 
 MATRX documentation
-======================
+======================================
 
 Welcome! This is the class and function reference documentation for the huMan-Agent Teaming; Rapid eXperimentation Software (MATRX).
 
@@ -26,8 +26,9 @@ After having installed MATRX (|matrx_install_guide|) and having tried out one or
     <a href="https://matrx-software.com/tutorials/" target="_blank">MATRX website</a>
 
 .. _Reference by Category:
+
 Reference by Category
-================================
+================================================================
 .. The image ratio is: width: 350px; height: 350/4 + (2x5) ~= 98px
 .. toctree::
    :maxdepth: 2
@@ -40,8 +41,9 @@ Reference by Category
    sections/objects.rst
    sections/simgoals.rst
    sections/api.rst
-   sections/scenarios.rst
-   sections/utils.rst
+   sections/cases.rst
+   sections/logging.rst
+   sections/messages.rst
 
 
 

docs/source/reference_by_category.rst

@@ -1,8 +1,8 @@
 .. _Reference:
 
-================
+================================
 Reference by category
-================
+================================
 
 .. The image ratio is: width: 350px; height: 350/4 + (2x5) ~= 98px
 .. toctree::

docs/source/sections/actions.rst

@@ -1,8 +1,8 @@
 .. _Actions:
 
-=======
+=============
 Actions
-=======
+=============
 
 Agents can change (or mutate) the world through performing actions. When an
 agent decides on an action it will communicate the action name and potential

docs/source/sections/agents.rst

@@ -1,8 +1,8 @@
 .. _Agents:
 
-======
+============
 Agents
-======
+============
 
 To implement the desired behaviour of agents, the classes below can be used. Usually, human agents are controlled by
 user input, while the autonomous system uses a brain implemented by the user via its own class. See the tutorials on how

docs/source/sections/api.rst

@@ -1,8 +1,8 @@
 .. _API:
 
-=======
+=============
 API
-=======
+=============
 
 The API connects a frontend to MATRX core. By default, the MATRX visualizer is used. Click below to view the various
 API functions and their documentation.

docs/source/sections/cases.rst

@@ -4,7 +4,7 @@
 Scenarios
 ==============
 
-
+Defining a world containing objects, agents, actions, and simulation goals.
 
 .. autosummary::
    :toctree: _generated_autodoc

docs/source/sections/logging.rst

@@ -1,8 +1,8 @@
 .. _Logging:
 
-======
+============
 Logging
-======
+============
 
 The MATRX simulation can be logged every tick, with results written to csv files. By default a number of loggers are
 already implemented and ready to use:
@@ -14,4 +14,5 @@ already implemented and ready to use:
     matrx.logger.log_agent_actions.LogActions
     matrx.logger.log_idle_agents.LogIdleAgents
     matrx.logger.log_tick.LogDuration
+    matrx.logger.log_messages.MessageLogger
     matrx.logger.logger.GridWorldLogger

docs/source/sections/messages.rst

@@ -1,8 +1,8 @@
 .. _Messages:
 
-======
+============
 Messages
-======
+============
 
 Agents can communicate with eachother by sending and receiving messages, containing a variety of possible contents.
 

docs/source/sections/objects.rst

@@ -1,8 +1,8 @@
 .. _Objects:
 
-================
-Object placement
-================
+================================
+Objects
+================================
 
 The world of MATRX can contain a various amount of objects. Below such object classes can be found.
 

docs/source/sections/simgoals.rst

@@ -1,10 +1,10 @@
 .. _Goals:
 
-================
+================================
 Simulation goals
-================
-
+================================
 
+Simulation goals can be specified that track progress and determine when the simulation should end.
 
 .. autosummary::
    :toctree: _generated_autodoc

docs/source/sections/worlds.rst

@@ -1,8 +1,8 @@
 .. _Worlds:
 
-======
+============
 Worlds
-======
+============
 
 The MATRX simulation needs worlds in which certain properties are set in order to simulate the desired events. The classes
 below ensure such worlds can be built.

matrx/actions/action.py

@@ -12,11 +12,21 @@ class Action:
     Parameters
     ----------
     duration_in_ticks : int
-        The default duration of the action in ticks during which the
-        GridWorld blocks the Agent performing other actions. By default
-        this is 1, meaning that the action will take both the tick in which
-        it was decided upon and the subsequent tick. When creating your
-        own Action, you can override this default value.
+        Optional, default: ``1``. Should be zero or larger.
+
+        The default duration of this action in ticks during which the
+        :class:`matrx.grid_world.GridWorld` blocks the agent performing other
+        actions. By default this is 1, meaning that all actions of this type will take
+        both the tick in which it was decided upon and the subsequent tick.
+        When the agent is blocked / busy with an action, only the
+        :meth:`matrx.agents.agent_brain.AgentBrain.filter_observations` method is called for that agent, and the
+        :meth:`matrx.agents.agent_brain.AgentBrain.decide_on_action` method is skipped.
+        This means that agents that are busy with an action can only perceive the world but not decide on
+        a new action untill the action has completed.
+
+        An agent can overwrite the duration of an action by returning the ``action_duration`` in the ``action_kwargs``
+        in the :meth:`matrx.agents.agent_brain.AgentBrain.decide_on_action` method, as so:
+        ``return >action_name<, {'action_duration': >ticks<}``
 
     """
 

matrx/actions/door_actions.py

@@ -5,26 +5,31 @@
 
 
 class OpenDoorAction(Action):
-    """ Action that opens doors. """
+    """ Action that opens doors.
 
-    def __init__(self, duration_in_ticks=0):
-        """ Action that opens doors.
-
-        The action that opens a specific door within a given range from the agent.
-
-        Parameters
-        ----------
-        duration_in_ticks : int
-            Optional, default: ``1``. Should be zero or larger.
-
-            The default duration of this action in ticks during which the
-            :class:`matrx.grid_world.GridWorld` blocks the
-            :class:`matrx.agents.agent.Agent` performing other actions. By default
-            this is 1, meaning that this action  will take both the tick in which
-            it was decided upon and the subsequent tick.
+    The action that opens a specific door within a given range from the agent.
 
-        """
+    Parameters
+    ----------
+    duration_in_ticks : int
+        Optional, default: ``1``. Should be zero or larger.
+
+        The default duration of this action in ticks during which the
+        :class:`matrx.grid_world.GridWorld` blocks the agent performing other
+        actions. By default this is 1, meaning that all actions of this type will take
+        both the tick in which it was decided upon and the subsequent tick.
+        When the agent is blocked / busy with an action, only the
+        :meth:`matrx.agents.agent_brain.AgentBrain.filter_observations` method is called for that agent, and the
+        :meth:`matrx.agents.agent_brain.AgentBrain.decide_on_action` method is skipped.
+        This means that agents that are busy with an action can only perceive the world but not decide on
+        a new action untill the action has completed.
+
+        An agent can overwrite the duration of an action by returning the ``action_duration`` in the ``action_kwargs``
+        in the :meth:`matrx.agents.agent_brain.AgentBrain.decide_on_action` method, as so:
+        ``return >action_name<, {'action_duration': >ticks<}``
+    """
 
+    def __init__(self, duration_in_ticks=0):
         super().__init__(duration_in_ticks)
 
     def mutate(self, grid_world, agent_id, **kwargs):
@@ -125,24 +130,31 @@ def is_possible(self, grid_world, agent_id, **kwargs):
 
 
 class CloseDoorAction(Action):
-    """ Action that closes doors. """
+    """ Action that closes doors.
 
-    def __init__(self, duration_in_ticks=0):
-        """ Action that closes doors.
-
-        The action that closes a specific door within a given range from the agent.
-
-        Parameters
-        ----------
-        duration_in_ticks : int
-            Optional. Default: ``1``. Should be zero or larger.
+    The action that closes a specific door within a given range from the agent.
 
-            The default duration of this action in ticks during which the
-            :class:`matrx.grid_world.GridWorld` blocks the agent performing
-            other actions. By default this is 1, meaning that this action will take
-            both the tick in which it was decided upon and the subsequent tick.
+    Parameters
+    ----------
+    duration_in_ticks : int
+        Optional, default: ``1``. Should be zero or larger.
+
+        The default duration of this action in ticks during which the
+        :class:`matrx.grid_world.GridWorld` blocks the agent performing other
+        actions. By default this is 1, meaning that all actions of this type will take
+        both the tick in which it was decided upon and the subsequent tick.
+        When the agent is blocked / busy with an action, only the
+        :meth:`matrx.agents.agent_brain.AgentBrain.filter_observations` method is called for that agent, and the
+        :meth:`matrx.agents.agent_brain.AgentBrain.decide_on_action` method is skipped.
+        This means that agents that are busy with an action can only perceive the world but not decide on
+        a new action untill the action has completed.
+
+        An agent can overwrite the duration of an action by returning the ``action_duration`` in the ``action_kwargs``
+        in the :meth:`matrx.agents.agent_brain.AgentBrain.decide_on_action` method, as so:
+        ``return >action_name<, {'action_duration': >ticks<}``
+    """
 
-        """
+    def __init__(self, duration_in_ticks=0):
         super().__init__(duration_in_ticks)
 
     def mutate(self, grid_world, agent_id, **kwargs):

matrx/actions/move_actions.py

@@ -206,10 +206,19 @@ class Move(Action):
     duration_in_ticks : int
         Optional. Default: ``1``. Should be zero or larger.
 
-        The default duration of Move in ticks during which the
+        The default duration of this action in ticks during which the
         :class:`matrx.grid_world.GridWorld` blocks the agent performing other
-        actions. By default this is 1, meaning that all Move actions will take
+        actions. By default this is 1, meaning that all actions of this type will take
         both the tick in which it was decided upon and the subsequent tick.
+        When the agent is blocked / busy with an action, only the
+        :meth:`matrx.agents.agent_brain.AgentBrain.filter_observations` method is called for that agent, and the
+        :meth:`matrx.agents.agent_brain.AgentBrain.decide_on_action` method is skipped.
+        This means that agents that are busy with an action can only perceive the world but not decide on
+        a new action untill the action has completed.
+
+        An agent can overwrite the duration of an action by returning the ``action_duration`` in the ``action_kwargs``
+        in the :meth:`matrx.agents.agent_brain.AgentBrain.decide_on_action` method, as so:
+        ``return >action_name<, {'action_duration': >ticks<}``
 
     Attributes
     ----------
@@ -297,7 +306,7 @@ def mutate(self, grid_world, agent_id, **kwargs):
 class MoveNorth(Move):
     """ Moves the agent North.
 
-    Inherits from :class:`matrx.actions.move_action.Move` and sets the delta-x
+    Inherits from :class:`matrx.actions.move_actions.Move` and sets the delta-x
     and delta-y as follows:
 
     * delta-x = 0
@@ -318,7 +327,7 @@ def __init__(self):
 class MoveNorthEast(Move):
     """ Moves the agent North-East.
 
-    Inherits from :class:`matrx.actions.move_action.Move` and sets the delta-x
+    Inherits from :class:`matrx.actions.move_actions.Move` and sets the delta-x
     and delta-y as follows:
 
     * delta-x = 1
@@ -339,7 +348,7 @@ def __init__(self):
 class MoveEast(Move):
     """ Moves the agent East.
 
-    Inherits from :class:`matrx.actions.move_action.Move` and sets the delta-x
+    Inherits from :class:`matrx.actions.move_actions.Move` and sets the delta-x
     and delta-y as follows:
 
     * delta-x = 1
@@ -360,7 +369,7 @@ def __init__(self):
 class MoveSouthEast(Move):
     """ Moves the agent South-East.
 
-    Inherits from :class:`matrx.actions.move_action.Move` and sets the delta-x
+    Inherits from :class:`matrx.actions.move_actions.Move` and sets the delta-x
     and delta-y as follows:
 
     * delta-x = 1
@@ -381,7 +390,7 @@ def __init__(self):
 class MoveSouth(Move):
     """ Moves the agent South.
 
-    Inherits from :class:`matrx.actions.move_action.Move` and sets the delta-x
+    Inherits from :class:`matrx.actions.move_actions.Move` and sets the delta-x
     and delta-y as follows:
 
     * delta-x = 0
@@ -402,7 +411,7 @@ def __init__(self):
 class MoveSouthWest(Move):
     """ Moves the agent South-West.
 
-    Inherits from :class:`matrx.actions.move_action.Move` and sets the delta-x
+    Inherits from :class:`matrx.actions.move_actions.Move` and sets the delta-x
     and delta-y as follows:
 
     * delta-x = -1
@@ -423,7 +432,7 @@ def __init__(self):
 class MoveWest(Move):
     """ Moves the agent West.
 
-    Inherits from :class:`matrx.actions.move_action.Move` and sets the delta-x
+    Inherits from :class:`matrx.actions.move_actions.Move` and sets the delta-x
     and delta-y as follows:
 
     * delta-x = -1
@@ -444,7 +453,7 @@ def __init__(self):
 class MoveNorthWest(Move):
     """ Moves the agent North-West.
 
-    Inherits from :class:`matrx.actions.move_action.Move` and sets the delta-x
+    Inherits from :class:`matrx.actions.move_actions.Move` and sets the delta-x
     and delta-y as follows:
 
     * delta-x = -1