diff --git a/marl_factory_grid/modules/batteries/actions.py b/marl_factory_grid/modules/batteries/actions.py index 0c0c008..bdb6676 100644 --- a/marl_factory_grid/modules/batteries/actions.py +++ b/marl_factory_grid/modules/batteries/actions.py @@ -12,7 +12,7 @@ class Charge(Action): def __init__(self): """ - Checks if a charge pod is present at the entity's position. + Checks if a charge pod is present at the agent's position. If found, it attempts to charge the battery using the charge pod. """ super().__init__(b.ACTION_CHARGE, b.REWARD_CHARGE_VALID, b.Reward_CHARGE_FAIL) diff --git a/marl_factory_grid/modules/batteries/entitites.py b/marl_factory_grid/modules/batteries/entitites.py index c2bdb4b..6a7b23d 100644 --- a/marl_factory_grid/modules/batteries/entitites.py +++ b/marl_factory_grid/modules/batteries/entitites.py @@ -31,7 +31,7 @@ class Battery(Object): def __init__(self, initial_charge_level, owner, *args, **kwargs): """ - Represents a battery entity in the environment that can be bound to an agent and charged at chargepods. + Represents a battery entity in the environment that can be bound to an agent and charged at charge pods. :param initial_charge_level: The current charge level of the battery, ranging from 0 to 1. :type initial_charge_level: float @@ -45,7 +45,7 @@ class Battery(Object): def do_charge_action(self, amount) -> bool: """ - Updates the Battery's charge level accordingly. + Updates the Battery's charge level according to the passed value. :param amount: Amount added to the Battery's charge level. :returns: whether the battery could be charged. if not, it was already fully charged. @@ -59,7 +59,7 @@ class Battery(Object): def decharge(self, amount) -> bool: """ - Decreases the charge value of a battery. Currently only riggered by the battery-decharge rule. + Decreases the charge value of a battery. Currently only triggered by the battery-decharge rule. """ if self.charge_level != 0: # noinspection PyTypeChecker @@ -84,11 +84,11 @@ class ChargePod(Entity): """ Represents a charging pod for batteries in the environment. - :param charge_rate: The rate at which the charging pod charges batteries. Default is 0.4. + :param charge_rate: The rate at which the charging pod charges batteries. Defaults to 0.4. :type charge_rate: float :param multi_charge: Indicates whether the charging pod supports charging multiple batteries simultaneously. - Default is False. + Defaults to False. :type multi_charge: bool """ super(ChargePod, self).__init__(*args, **kwargs) @@ -97,7 +97,8 @@ class ChargePod(Entity): def charge_battery(self, entity, state) -> bool: """ - Checks whether the battery can be charged. If so, triggers the charge action. + Triggers the battery charge action if possible. Impossible if battery at full charge level or more than one + agent at charge pods' position. :returns: whether the action was successful (valid) or not. """ diff --git a/marl_factory_grid/modules/batteries/groups.py b/marl_factory_grid/modules/batteries/groups.py index 8a10fbc..4ecf3d6 100644 --- a/marl_factory_grid/modules/batteries/groups.py +++ b/marl_factory_grid/modules/batteries/groups.py @@ -19,7 +19,7 @@ class Batteries(Collection): def __init__(self, size, initial_charge_level=1.0, *args, **kwargs): """ - A collection of batteries that can spawn batteries. + A collection of batteries that is in charge of spawning batteries. (spawned batteries are bound to agents) :param size: The maximum allowed size of the collection. Ensures that the collection does not exceed this size. :type size: int diff --git a/marl_factory_grid/modules/clean_up/actions.py b/marl_factory_grid/modules/clean_up/actions.py index d319df9..9be8999 100644 --- a/marl_factory_grid/modules/clean_up/actions.py +++ b/marl_factory_grid/modules/clean_up/actions.py @@ -12,7 +12,7 @@ class Clean(Action): def __init__(self): """ - Attempts to reduce dirt amount on entity's position. + Attempts to reduce dirt amount on entity's position. Fails if no dirt is found at the at agents' position. """ super().__init__(d.CLEAN_UP, d.REWARD_CLEAN_UP_VALID, d.REWARD_CLEAN_UP_FAIL) diff --git a/marl_factory_grid/modules/clean_up/entitites.py b/marl_factory_grid/modules/clean_up/entitites.py index 2f6edf3..f7d41b6 100644 --- a/marl_factory_grid/modules/clean_up/entitites.py +++ b/marl_factory_grid/modules/clean_up/entitites.py @@ -18,7 +18,8 @@ class DirtPile(Entity): def __init__(self, *args, amount=2, max_local_amount=5, **kwargs): """ - Represents a pile of dirt at a specific position in the environment. + Represents a pile of dirt at a specific position in the environment that agents can interact with. Agents can + clean the dirt pile or, depending on activated rules, interact with it in different ways. :param amount: The amount of dirt in the pile. :type amount: float diff --git a/marl_factory_grid/modules/destinations/actions.py b/marl_factory_grid/modules/destinations/actions.py index 7ace423..f3e8800 100644 --- a/marl_factory_grid/modules/destinations/actions.py +++ b/marl_factory_grid/modules/destinations/actions.py @@ -10,7 +10,7 @@ class DestAction(Action): def __init__(self): """ - Attempts to wait at destination. + The agent performing this action attempts to wait at the destination in order to receive a reward. """ super().__init__(d.DESTINATION, d.REWARD_WAIT_VALID, d.REWARD_WAIT_FAIL) diff --git a/marl_factory_grid/modules/destinations/entitites.py b/marl_factory_grid/modules/destinations/entitites.py index e5ecf4a..a1c4ce9 100644 --- a/marl_factory_grid/modules/destinations/entitites.py +++ b/marl_factory_grid/modules/destinations/entitites.py @@ -38,7 +38,11 @@ class Destination(Entity): def has_just_been_reached(self, state): """ - Checks if the destination has just been reached based on the current state. + Checks if the destination has been reached in the last environment step. + + :return: the agent that has just reached the destination or whether any agent in the environment has + performed actions equal to or exceeding the specified limit + :rtype: Union[Agent, bool] """ if self.was_reached(): return False diff --git a/marl_factory_grid/modules/doors/actions.py b/marl_factory_grid/modules/doors/actions.py index aff01e1..817e83e 100644 --- a/marl_factory_grid/modules/doors/actions.py +++ b/marl_factory_grid/modules/doors/actions.py @@ -10,7 +10,8 @@ class DoorUse(Action): def __init__(self, **kwargs): """ - Attempts to interact with door (open/close it) and returns an action result if successful. + The agent performing this action attempts to interact with door (open/close it), returning an action result if + successful. """ super().__init__(d.ACTION_DOOR_USE, d.REWARD_USE_DOOR_VALID, d.REWARD_USE_DOOR_FAIL, **kwargs) diff --git a/marl_factory_grid/modules/doors/entitites.py b/marl_factory_grid/modules/doors/entitites.py index de323b4..275c5f5 100644 --- a/marl_factory_grid/modules/doors/entitites.py +++ b/marl_factory_grid/modules/doors/entitites.py @@ -19,7 +19,7 @@ class DoorIndicator(Entity): def __init__(self, *args, **kwargs): """ - Is added around a door for agents to see. + Is added as a padding around doors so agents can see doors earlier. """ super().__init__(*args, **kwargs) self.__delattr__('move') diff --git a/marl_factory_grid/modules/doors/rules.py b/marl_factory_grid/modules/doors/rules.py index 4b24470..b5c7730 100644 --- a/marl_factory_grid/modules/doors/rules.py +++ b/marl_factory_grid/modules/doors/rules.py @@ -9,7 +9,7 @@ class DoorAutoClose(Rule): def __init__(self, close_frequency: int = 10): """ - This rule closes doors, that have been opened automatically, when no entity is blocking the position. + This rule closes doors that have been opened automatically when no entity is blocking the position. :type close_frequency: int :param close_frequency: How many ticks after opening, should the door close? diff --git a/marl_factory_grid/modules/items/groups.py b/marl_factory_grid/modules/items/groups.py index bb264e6..fa34c50 100644 --- a/marl_factory_grid/modules/items/groups.py +++ b/marl_factory_grid/modules/items/groups.py @@ -62,7 +62,7 @@ class Inventory(IsBoundMixin, Collection): def __init__(self, agent, *args, **kwargs): """ - An inventory that can hold items picked up by the agent this is bound to. + An inventory that can hold items picked up by the agent it is bound to. :param agent: The agent this inventory is bound to and belongs to. :type agent: Agent @@ -96,7 +96,7 @@ class Inventory(IsBoundMixin, Collection): def clear_temp_state(self): """ - Entites need this, but inventories have no state. + Entities need this, but inventories have no state. """ pass @@ -123,7 +123,7 @@ class Inventories(Objects): def __init__(self, size: int, *args, **kwargs): """ - TODO + A collection of all inventories used to spawn an inventory per agent. """ super(Inventories, self).__init__(*args, **kwargs) self.size = size diff --git a/marl_factory_grid/modules/machines/actions.py b/marl_factory_grid/modules/machines/actions.py index 3d5729f..5ace4ff 100644 --- a/marl_factory_grid/modules/machines/actions.py +++ b/marl_factory_grid/modules/machines/actions.py @@ -11,7 +11,8 @@ class MachineAction(Action): def __init__(self): """ - Attempts to maintain the machine and returns an action result if successful. + When performing this action, the maintainer attempts to maintain the machine at his current position, returning + an action result if successful. """ super().__init__(m.MACHINE_ACTION, m.MAINTAIN_VALID, m.MAINTAIN_FAIL) diff --git a/marl_factory_grid/modules/machines/entitites.py b/marl_factory_grid/modules/machines/entitites.py index 1cc7e2c..83b6a77 100644 --- a/marl_factory_grid/modules/machines/entitites.py +++ b/marl_factory_grid/modules/machines/entitites.py @@ -14,7 +14,8 @@ class Machine(Entity): def __init__(self, *args, work_interval: int = 10, pause_interval: int = 15, **kwargs): """ - Represents a machine entity that the maintainer will try to maintain. + Represents a machine entity that the maintainer will try to maintain by performing the maintenance action. + Machines' health depletes over time. :param work_interval: How long should the machine work before pausing. :type work_interval: int @@ -31,7 +32,8 @@ class Machine(Entity): def maintain(self) -> bool: """ - Attempts to maintain the machine by increasing its health. + Attempts to maintain the machine by increasing its health, which is only possible if the machine is at a maximum + of 98/100 HP. """ if self.status == m.STATE_WORK: return c.NOT_VALID diff --git a/marl_factory_grid/modules/maintenance/entities.py b/marl_factory_grid/modules/maintenance/entities.py index 583fa36..b6c2625 100644 --- a/marl_factory_grid/modules/maintenance/entities.py +++ b/marl_factory_grid/modules/maintenance/entities.py @@ -16,8 +16,9 @@ from ..doors import DoorUse class Maintainer(Entity): def __init__(self, objective, action, *args, **kwargs): - """ - Represents the maintainer entity that aims to maintain machines. + self.action_ = """ + Represents the maintainer entity that aims to maintain machines. The maintainer calculates its route using nx + shortest path and restores the health of machines it visits to 100. :param objective: The maintainer's objective, e.g., "Machines". :type objective: str diff --git a/marl_factory_grid/modules/maintenance/groups.py b/marl_factory_grid/modules/maintenance/groups.py index 6dd088f..7a2e0a1 100644 --- a/marl_factory_grid/modules/maintenance/groups.py +++ b/marl_factory_grid/modules/maintenance/groups.py @@ -27,7 +27,7 @@ class Maintainers(Collection): def __init__(self, *args, **kwargs): """ - A collection of maintainers + A collection of maintainers that is used to spawn them. """ super().__init__(*args, **kwargs)