From f35944cc5580bb1c53bd8b61a91f1be3f4ffb91d Mon Sep 17 00:00:00 2001 From: Joel Friedrich Date: Fri, 5 Jan 2024 14:26:09 +0100 Subject: [PATCH] added documentation for environment entity and factory --- .../environment/entity/entity.py | 156 +++++++++--------- .../environment/entity/object.py | 51 +++--- marl_factory_grid/environment/entity/util.py | 37 +++-- marl_factory_grid/environment/entity/wall.py | 5 +- marl_factory_grid/environment/factory.py | 37 +++-- 5 files changed, 146 insertions(+), 140 deletions(-) diff --git a/marl_factory_grid/environment/entity/entity.py b/marl_factory_grid/environment/entity/entity.py index 42a52eb..60e62f9 100644 --- a/marl_factory_grid/environment/entity/entity.py +++ b/marl_factory_grid/environment/entity/entity.py @@ -13,30 +13,28 @@ class Entity(Object, abc.ABC): @property def state(self): """ - TODO - - - :return: + Get the current status of the entity. Not to be confused with the Gamestate. + :return: status """ return self._status or State(entity=self, identifier=c.NOOP, validity=c.VALID) @property def var_has_position(self): """ - TODO + Check if the entity has a position. - - :return: + :return: True if the entity has a position, False otherwise. + :rtype: bool """ return self.pos != c.VALUE_NO_POS @property def var_is_blocking_light(self): """ - TODO + Check if the entity is blocking light. - - :return: + :return: True if the entity is blocking light, False otherwise. + :rtype: bool """ try: return self._collection.var_is_blocking_light or False @@ -46,10 +44,10 @@ class Entity(Object, abc.ABC): @property def var_can_move(self): """ - TODO + Check if the entity can move. - - :return: + :return: True if the entity can move, False otherwise. + :rtype: bool """ try: return self._collection.var_can_move or False @@ -59,10 +57,10 @@ class Entity(Object, abc.ABC): @property def var_is_blocking_pos(self): """ - TODO + Check if the entity is blocking a position when standing on it. - - :return: + :return: True if the entity is blocking a position, False otherwise. + :rtype: bool """ try: return self._collection.var_is_blocking_pos or False @@ -72,10 +70,10 @@ class Entity(Object, abc.ABC): @property def var_can_collide(self): """ - TODO + Check if the entity can collide. - - :return: + :return: True if the entity can collide, False otherwise. + :rtype: bool """ try: return self._collection.var_can_collide or False @@ -85,39 +83,40 @@ class Entity(Object, abc.ABC): @property def x(self): """ - TODO + Get the x-coordinate of the entity's position. - - :return: + :return: The x-coordinate of the entity's position. + :rtype: int """ return self.pos[0] @property def y(self): """ - TODO + Get the y-coordinate of the entity's position. - - :return: + :return: The y-coordinate of the entity's position. + :rtype: int """ return self.pos[1] @property def pos(self): """ - TODO + Get the current position of the entity. - - :return: + :return: The current position of the entity. + :rtype: tuple """ return self._pos def set_pos(self, pos) -> bool: """ - TODO + Set the position of the entity. - - :return: + :param pos: The new position. + :type pos: tuple + :return: True if setting the position is successful, False otherwise. """ assert isinstance(pos, tuple) and len(pos) == 2 self._pos = pos @@ -126,10 +125,10 @@ class Entity(Object, abc.ABC): @property def last_pos(self): """ - TODO + Get the last position of the entity. - - :return: + :return: The last position of the entity. + :rtype: tuple """ try: return self._last_pos @@ -141,22 +140,49 @@ class Entity(Object, abc.ABC): @property def direction_of_view(self): """ - TODO + Get the current direction of view of the entity. - - :return: + :return: The current direction of view of the entity. + :rtype: int """ if self._last_pos != c.VALUE_NO_POS: return 0, 0 else: return np.subtract(self._last_pos, self.pos) + def __init__(self, pos, bind_to=None, **kwargs): + """ + Abstract base class representing entities in the environment grid. + + :param pos: The initial position of the entity. + :type pos: tuple + :param bind_to: Entity to which this entity is bound (Default: None) + :type bind_to: Entity or None + """ + super().__init__(**kwargs) + self._view_directory = c.VALUE_NO_POS + self._status = None + self._pos = pos + self._last_pos = pos + self._collection = None + if bind_to: + try: + self.bind_to(bind_to) + except AttributeError: + print(f'Objects of class "{self.__class__.__name__}" can not be bound to other entities.') + exit() + def move(self, next_pos, state): """ - TODO + Move the entity to a new position. + :param next_pos: The next position to move the entity to. + :type next_pos: tuple + :param state: The current state of the environment. + :type state: marl_factory_grid.environment.state.Gamestate - :return: + :return: True if the move is valid, False otherwise. + :rtype: bool """ next_pos = next_pos curr_pos = self._pos @@ -172,43 +198,22 @@ class Entity(Object, abc.ABC): # Bad naming... Was the same was the same pos, not moving.... return not_same_pos - def __init__(self, pos, bind_to=None, **kwargs): - """ - Full Env Entity that lives on the environment Grid. Doors, Items, DirtPile etc... - TODO - - - :return: - """ - super().__init__(**kwargs) - self._view_directory = c.VALUE_NO_POS - self._status = None - self._pos = pos - self._last_pos = pos - self._collection = None - if bind_to: - try: - self.bind_to(bind_to) - except AttributeError: - print(f'Objects of class "{self.__class__.__name__}" can not be bound to other entities.') - exit() - def summarize_state(self) -> dict: """ - TODO + Summarize the current state of the entity. - - :return: + :return: A dictionary containing the name, x-coordinate, y-coordinate, and can_collide property of the entity. + :rtype: dict """ return dict(name=str(self.name), x=int(self.x), y=int(self.y), can_collide=bool(self.var_can_collide)) @abc.abstractmethod def render(self): """ - TODO + Abstract method to render the entity. - - :return: + :return: A rendering entity representing the entity's appearance in the environment. + :rtype: marl_factory_grid.utils.utility_classes.RenderEntity """ return RenderEntity(self.__class__.__name__.lower(), self.pos) @@ -223,19 +228,22 @@ class Entity(Object, abc.ABC): @property def encoding(self): """ - TODO + Get the encoded representation of the entity. - - :return: + :return: The encoded representation. + :rtype: int """ return c.VALUE_OCCUPIED_CELL def change_parent_collection(self, other_collection): """ - TODO + Change the parent collection of the entity. + :param other_collection: The new parent collection. + :type other_collection: marl_factory_grid.environment.collections.Collection - :return: + :return: True if the change is successful, False otherwise. + :rtype: bool """ other_collection.add_item(self) self._collection.delete_env_object(self) @@ -245,9 +253,9 @@ class Entity(Object, abc.ABC): @property def collection(self): """ - TODO + Get the parent collection of the entity. - - :return: + :return: The parent collection. + :rtype: marl_factory_grid.environment.collections.Collection """ return self._collection diff --git a/marl_factory_grid/environment/entity/object.py b/marl_factory_grid/environment/entity/object.py index c81f622..5688ee0 100644 --- a/marl_factory_grid/environment/entity/object.py +++ b/marl_factory_grid/environment/entity/object.py @@ -12,17 +12,15 @@ class Object: @property def bound_entity(self): """ - TODO + Returns the entity to which this object is bound. - - :return: + :return: The bound entity. """ return self._bound_entity @property def var_can_be_bound(self) -> bool: """ - TODO Indicates if it is possible to bind this object to another Entity or Object. :return: Whether this object can be bound. @@ -35,30 +33,27 @@ class Object: @property def observers(self) -> set: """ - TODO + Returns the set of observers for this object. - - :return: + :return: Set of observers. """ return self._observers @property def name(self): """ - TODO + Returns a string representation of the object's name. - - :return: + :return: The name of the object. """ return f'{self.__class__.__name__}[{self.identifier}]' @property def identifier(self): """ - TODO + Returns the unique identifier of the object. - - :return: + :return: The unique identifier. """ if self._str_ident is not None: return self._str_ident @@ -67,23 +62,19 @@ class Object: def reset_uid(self): """ - TODO + Resets the unique identifier counter for this class. - - :return: + :return: True if the reset was successful. """ self._u_idx = defaultdict(lambda: 0) return True def __init__(self, str_ident: Union[str, None] = None, **kwargs): """ - Generell Objects for Organisation and Maintanance such as Actions etc... + General Objects for Organisation and Maintenance such as Actions, etc. - TODO - - :param str_ident: - - :return: + :param str_ident: A string identifier for the object. + :return: None """ self._status = None self._bound_entity = None @@ -147,28 +138,28 @@ class Object: def bind_to(self, entity): """ - TODO + Binds the object to a specified entity. - - :return: + :param entity: The entity to bind to. + :return: The validity of the binding. """ self._bound_entity = entity return c.VALID def belongs_to_entity(self, entity): """ - TODO + Checks if the object belongs to a specified entity. - - :return: + :param entity: The entity to check against. + :return: True if the object belongs to the entity, False otherwise. """ return self._bound_entity == entity def unbind(self): """ - TODO + Unbinds the object from its current entity. - :return: + :return: The entity that the object was previously bound to. """ previously_bound = self._bound_entity self._bound_entity = None diff --git a/marl_factory_grid/environment/entity/util.py b/marl_factory_grid/environment/entity/util.py index 6961aec..2dcf191 100644 --- a/marl_factory_grid/environment/entity/util.py +++ b/marl_factory_grid/environment/entity/util.py @@ -4,7 +4,7 @@ from marl_factory_grid.environment.entity.object import Object ########################################################################## -# ####################### Objects and Entitys ########################## # +# ####################### Objects and Entities ########################## # ########################################################################## @@ -12,10 +12,11 @@ class PlaceHolder(Object): def __init__(self, *args, fill_value=0, **kwargs): """ - TODO + A placeholder object that can be used as an observation during training. It is designed to be later replaced + with a meaningful observation that wasn't initially present in the training run. - - :return: + :param fill_value: The default value to fill the placeholder observation (Default: 0) + :type fill_value: Any """ super().__init__(*args, **kwargs) self._fill_value = fill_value @@ -23,20 +24,20 @@ class PlaceHolder(Object): @property def var_can_collide(self): """ - TODO + Indicates whether this placeholder object can collide with other entities. Always returns False. - - :return: + :return: False + :rtype: bool """ return False @property def encoding(self): """ - TODO + Get the fill value representing the placeholder observation. - - :return: + :return: The fill value + :rtype: Any """ return self._fill_value @@ -54,10 +55,10 @@ class GlobalPosition(Object): @property def encoding(self): """ - TODO + Get the encoded representation of the global position based on whether normalization is enabled. - - :return: + :return: The encoded representation of the global position + :rtype: tuple[float, float] or tuple[int, int] """ if self._normalized: return tuple(np.divide(self._bound_entity.pos, self._shape)) @@ -66,10 +67,14 @@ class GlobalPosition(Object): def __init__(self, agent, level_shape, *args, normalized: bool = True, **kwargs): """ - TODO + A utility class representing the global position of an entity in the environment. - - :return: + :param agent: The agent entity to which the global position is bound. + :type agent: marl_factory_grid.environment.entity.agent.Agent + :param level_shape: The shape of the environment level. + :type level_shape: tuple[int, int] + :param normalized: Indicates whether the global position should be normalized (Default: True) + :type normalized: bool """ super(GlobalPosition, self).__init__(*args, **kwargs) self.bind_to(agent) diff --git a/marl_factory_grid/environment/entity/wall.py b/marl_factory_grid/environment/entity/wall.py index 439bb39..e02ce66 100644 --- a/marl_factory_grid/environment/entity/wall.py +++ b/marl_factory_grid/environment/entity/wall.py @@ -7,10 +7,7 @@ class Wall(Entity): def __init__(self, *args, **kwargs): """ - TODO - - - :return: + A class representing a wall entity in the environment. """ super().__init__(*args, **kwargs) diff --git a/marl_factory_grid/environment/factory.py b/marl_factory_grid/environment/factory.py index 9b0420a..a223427 100644 --- a/marl_factory_grid/environment/factory.py +++ b/marl_factory_grid/environment/factory.py @@ -24,47 +24,48 @@ class Factory(gym.Env): @property def action_space(self): """ - TODO + The action space defines the set of all possible actions that an agent can take in the environment. - - :return: + :return: Action space + :rtype: gym.Space """ return self.state[c.AGENT].action_space @property def named_action_space(self): """ - TODO + Returns the named action space for agents. - - :return: + :return: Named action space + :rtype: dict[str, dict[str, list[int]]] """ return self.state[c.AGENT].named_action_space @property def observation_space(self): """ - TODO + The observation space represents all the information that an agent can receive from the environment at a given + time step. - - :return: + :return: Observation space. + :rtype: gym.Space """ return self.obs_builder.observation_space(self.state) @property def named_observation_space(self): """ - TODO + Returns the named observation space for the environment. - - :return: + :return: Named observation space. + :rtype: (dict, dict) """ return self.obs_builder.named_observation_space(self.state) @property def params(self) -> dict: """ - FIXME LAGEGY + FIXME LEGACY :return: @@ -80,10 +81,14 @@ class Factory(gym.Env): def __init__(self, config_file: Union[str, PathLike], custom_modules_path: Union[None, PathLike] = None, custom_level_path: Union[None, PathLike] = None): """ - TODO + Initializes the marl-factory-grid as Gym environment. - - :return: + :param config_file: Path to the configuration file. + :type config_file: Union[str, PathLike] + :param custom_modules_path: Path to custom modules directory. (Default: None) + :type custom_modules_path: Union[None, PathLike] + :param custom_level_path: Path to custom level file. (Default: None) + :type custom_level_path: Union[None, PathLike] """ self._config_file = config_file self.conf = FactoryConfigParser(self._config_file, custom_modules_path)