Documentation

marl_factory_grid/modules/batteries/actions.py

@@ -11,6 +11,10 @@ from marl_factory_grid.utils import helpers as h
 class Charge(Action):
 
     def __init__(self):
+        """
+        Checks if a charge pod is present at the entity'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)
 
     def do(self, entity, state) -> Union[None, ActionResult]:

marl_factory_grid/modules/batteries/entitites.py

@@ -13,7 +13,12 @@ class Battery(Object):
         return True
 
     @property
-    def is_discharged(self):
+    def is_discharged(self) -> bool:
+        """
+        Indicates whether the Batteries charge level is at 0 or not.
+
+        :return: Whether this battery is empty.
+        """
         return self.charge_level == 0
 
     @property
@@ -24,12 +29,27 @@ class Battery(Object):
     def encoding(self):
         return self.charge_level
 
-    def __init__(self, initial_charge_level: float, owner: Entity, *args, **kwargs):
+    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.
+
+        :param initial_charge_level: The current charge level of the battery, ranging from 0 to 1.
+        :type initial_charge_level: float
+
+        :param owner: The entity to which the battery is bound.
+        :type owner: Entity
+        """
         super(Battery, self).__init__(*args, **kwargs)
         self.charge_level = initial_charge_level
         self.bind_to(owner)
 
-    def do_charge_action(self, amount):
+    def do_charge_action(self, amount) -> bool:
+        """
+        Updates the Battery's charge level accordingly.
+
+        :param amount: Amount added to the Battery's charge level.
+        :returns: whether the battery could be charged. if not, it was already fully charged.
+        """
         if self.charge_level < 1:
             # noinspection PyTypeChecker
             self.charge_level = min(1, amount + self.charge_level)
@@ -37,7 +57,10 @@ class Battery(Object):
         else:
             return c.NOT_VALID
 
-    def decharge(self, amount) -> float:
+    def decharge(self, amount) -> bool:
+        """
+        Decreases the charge value of a battery. Currently only riggered by the battery-decharge rule.
+        """
         if self.charge_level != 0:
             # noinspection PyTypeChecker
             self.charge_level = max(0, amount + self.charge_level)
@@ -57,13 +80,27 @@ class ChargePod(Entity):
     def encoding(self):
         return b.CHARGE_POD_SYMBOL
 
-    def __init__(self, *args, charge_rate: float = 0.4,
-                 multi_charge: bool = False, **kwargs):
+    def __init__(self, *args, charge_rate: float = 0.4, multi_charge: bool = False, **kwargs):
+        """
+        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.
+        :type charge_rate: float
+
+        :param multi_charge: Indicates whether the charging pod supports charging multiple batteries simultaneously.
+                        Default is False.
+        :type multi_charge: bool
+        """
         super(ChargePod, self).__init__(*args, **kwargs)
         self.charge_rate = charge_rate
         self.multi_charge = multi_charge
 
-    def charge_battery(self, entity, state):
+    def charge_battery(self, entity, state) -> bool:
+        """
+        Checks whether the battery can be charged. If so, triggers the charge action.
+
+        :returns: whether the action was successful (valid) or not.
+        """
         battery = state[b.BATTERIES].by_entity(entity)
         if battery.charge_level >= 1.0:
             return c.NOT_VALID
@@ -76,6 +113,6 @@ class ChargePod(Entity):
         return RenderEntity(b.CHARGE_PODS, self.pos)
 
     def summarize_state(self) -> dict:
-        summery = super().summarize_state()
-        summery.update(charge_rate=self.charge_rate)
-        return summery
+        summary = super().summarize_state()
+        summary.update(charge_rate=self.charge_rate)
+        return summary

marl_factory_grid/modules/batteries/groups.py

@@ -9,18 +9,32 @@ from marl_factory_grid.utils.results import Result
 class Batteries(Collection):
     _entity = Battery
 
-    var_has_position = False
-    var_can_be_bound = True
+    @property
+    def var_has_position(self):
+        return False
 
-    def __init__(self, size, initial_charge_level: float=1.0, *args, **kwargs):
+    @property
+    def var_can_be_bound(self):
+        return True
+
+    def __init__(self, size, initial_charge_level=1.0, *args, **kwargs):
+        """
+        A collection of batteries that can spawn batteries.
+
+        :param size: The maximum allowed size of the collection. Ensures that the collection does not exceed this size.
+        :type size: int
+
+        :param initial_charge_level: The initial charge level of the battery.
+        :type initial_charge_level: float
+        """
         super(Batteries, self).__init__(size, *args, **kwargs)
         self.initial_charge_level = initial_charge_level
 
-    def spawn(self, coords_or_quantity: Union[int, List[Tuple[(int, int)]]], agents, *entity_args, **entity_kwargs):
-        batteries = [self._entity(self.initial_charge_level, agent) for _, agent in enumerate(agents)]
+    def spawn(self, coords_or_quantity: Union[int, List[Tuple[(int, int)]]], *entity_args, **entity_kwargs):
+        batteries = [self._entity(self.initial_charge_level, agent) for _, agent in enumerate(entity_args[0])]
         self.add_items(batteries)
 
-    def trigger_spawn(self, state, *entity_args, coords_or_quantity=None,  **entity_kwargs):
+    def trigger_spawn(self, state, *entity_args, coords_or_quantity=None, **entity_kwargs):
         self.spawn(0, state[c.AGENT])
         return Result(identifier=f'{self.name}_spawn', validity=c.VALID, value=len(self))
 
@@ -29,6 +43,9 @@ class ChargePods(Collection):
     _entity = ChargePod
 
     def __init__(self, *args, **kwargs):
+        """
+         A collection of charge pods in the environment.
+        """
         super(ChargePods, self).__init__(*args, **kwargs)
 
     def __repr__(self):

marl_factory_grid/modules/batteries/rules.py

@@ -24,16 +24,16 @@ class BatteryDecharge(Rule):
                                  2. float: each action "costs" the same.
         ----                         
          !!! Does not introduce any Env.-Done condition. 
-         !!! Batterys can only be charged if agent posses the "Charge(Action.                 
-         !!! Batterys can only be charged if there are "Charpods" and they are spawned!                      
+         !!! Batteries can only be charged if agent posses the "Charge" Action.                 
+         !!! Batteries can only be charged if there are "Charge Pods" and they are spawned!                      
         ----                         
         :type initial_charge: float
         :param initial_charge: How much juice they have.
         :type battery_discharge_reward: float
-        :param battery_discharge_reward: Negativ reward, when agents let their batters discharge. 
+        :param battery_discharge_reward: Negative reward, when agents let their batters discharge. 
                                          Default: {b.REWARD_BATTERY_DISCHARGED}
         :type battery_failed_reward: float
-        :param battery_failed_reward: Negativ reward, when agent cannot charge, but do (overcharge, not on station).
+        :param battery_failed_reward: Negative reward, when agent cannot charge, but do (overcharge, not on station).
                                        Default: {b.Reward_CHARGE_FAIL}
         :type battery_charge_reward: float
         :param battery_charge_reward: Positive reward, when agent actually charge their battery.
@@ -48,7 +48,6 @@ class BatteryDecharge(Rule):
         self.initial_charge = initial_charge
 
     def tick_step(self, state) -> List[TickResult]:
-        # Decharge
         batteries = state[b.BATTERIES]
         results = []
 
@@ -104,13 +103,13 @@ class DoneAtBatteryDischarge(BatteryDecharge):
         :type initial_charge: float
         :param initial_charge: How much juice they have.
         :type reward_discharge_done: float
-        :param reward_discharge_done: Global negativ reward, when agents let their batters discharge. 
+        :param reward_discharge_done: Global negative reward, when agents let their batters discharge. 
                                          Default: {b.REWARD_BATTERY_DISCHARGED}
         :type battery_discharge_reward: float
-        :param battery_discharge_reward: Negativ reward, when agents let their batters discharge. 
+        :param battery_discharge_reward: Negative reward, when agents let their batters discharge. 
                                          Default: {b.REWARD_BATTERY_DISCHARGED}
         :type battery_failed_reward: float
-        :param battery_failed_reward: Negativ reward, when agent cannot charge, but do (overcharge, not on station).
+        :param battery_failed_reward: Negative reward, when agent cannot charge, but do (overcharge, not on station).
                                        Default: {b.Reward_CHARGE_FAIL}
         :type battery_charge_reward: float
         :param battery_charge_reward: Positive reward, when agent actually charge their battery.