pymasep.common ============== .. py:module:: pymasep.common Subpackages ----------- .. toctree:: :maxdepth: 1 /autoapi/pymasep/common/exception/index /autoapi/pymasep/common/initializer/index /autoapi/pymasep/common/math/index /autoapi/pymasep/common/template/index Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/pymasep/common/action/index /autoapi/pymasep/common/agent/index /autoapi/pymasep/common/base_object/index /autoapi/pymasep/common/belief/index /autoapi/pymasep/common/characteristic/index /autoapi/pymasep/common/container/index /autoapi/pymasep/common/controller/index /autoapi/pymasep/common/environment/index /autoapi/pymasep/common/game/index /autoapi/pymasep/common/intention/index /autoapi/pymasep/common/object/index /autoapi/pymasep/common/object_state/index /autoapi/pymasep/common/state/index Classes ------- .. autoapisummary:: pymasep.common.Environment pymasep.common.Action pymasep.common.BaseObject pymasep.common.State pymasep.common.Characteristic pymasep.common.ObjectState pymasep.common.Container pymasep.common.Object pymasep.common.Agent pymasep.common.Game pymasep.common.Controller pymasep.common.Intention pymasep.common.Belief Package Contents ---------------- .. py:class:: Environment(id_env = None, cfg = None) Represents the environment of the game. This object keeps all dynamic value of the game. :param id_env: the id of the environment. If None, a new uuid will be set :parm cfg: the configuration of the environment .. py:attribute:: id :type: str Environment id. .. py:attribute:: config configuration of the environment. .. py:attribute:: end_episode :type: bool :value: False the current episode is finished .. py:attribute:: current_step :type: int :value: 0 current step of the environment .. py:attribute:: current_episode :type: int :value: 0 current episode of the environment .. py:attribute:: current_state :type: Optional[pymasep.common.state.State] :value: None current state of the environment .. py:attribute:: current_additional_info :type: dict current additional information of the environment, related to the current state. Sort of meta information on the current state .. py:attribute:: agents :type: Set[pymasep.common.agent.Agent] set of agents in the current state .. py:attribute:: controllers :type: Dict[str, pymasep.common.controller.Controller] set of controllers that can be used in the environment .. py:attribute:: _game :type: Optional[pymasep.common.game.Game] :value: None .. py:attribute:: next_action :type: Dict[str, pymasep.common.action.Action] next action to be executed in the current state .. py:attribute:: _level_logger .. py:attribute:: logger logger for the environment tasks .. py:method:: __del__() .. py:property:: game :type: pymasep.common.game.Game Game of the environment. .. py:method:: get_current_coord_method(state = None) Return the current coordination method according to the current game phase in the state :param state: State to check the coordination method. If None, take the current state of the environment. :return: The current coordinate method .. py:method:: get_observation_for_agent(agent) Get the current observation. Current state at the moment :param agent: The agent to get the observation for :return: The current observation .. py:method:: get_additional_info_for_agent() Get the current additional information. Could be filtered in the future (by agent) :return: The current additional information .. py:method:: get_reward_for_agent(agent) Get the current reward for an agent. :param agent: The agent to get the reward :return: The current reward of the agent .. py:method:: get_controller(agent_name, class_controller_) Get the controller of an agent. If the controller is not created, create it. (Maybe I should change the name of this method...) :param agent_name: The agent's name :param class_controller_: the class of the controller to create if it is not created :return: the instance of the agent's controller .. py:method:: calculate_end_episode() Calculate the end of the episode. Modify self.end_episode if the conditions of the episode's end are met. .. py:method:: calculate_next_state() Calculate the next state of the environment. Change the current state. Increase the step .. py:method:: calculate_reward() Calculate the reward from the current_state and add the result to additional info with key 'reward'. For MDP point of view, support only (at the moment) :math:`R(s)` and neither :math:`R(s,a)` nor :math:`R(s,a,s')` .. py:method:: create_base_object(name = None, template = None, xml_node = None, parent = None) Create a base object from a string represent the type :param name: The identification name of the BaseObject. :param template: Template of the created object. If None and no XML is specified, will be the default template for this bo_type :param xml_node: XML node used for creating the base object :param parent: the parent of the current object. May be None. :return: The BaseObject instance .. py:method:: get_type_controller(xml_node = None, template = None, control = None) Get the type of controller according to a template or (exclusive) an XML node. :param xml_node: XML node used to get the controller type. Use the attribute "controller". :param template: The template used to get the controller type. :param control: 'Interface' if the agent is controlled by interface (only inside engine, and if template is used) :return: the class of the controller to use .. py:method:: create_object(name = None, template = None, xml_node = None, parent = None, control = None) Create an object. Add it into the object dictionary (if not already exists) and agent set if the object is Agent :param name: The identification name of the object. Not used if xml_node is used :param template: the template of the class to create the object. Not used if xml_node is used :param xml_node: XML node describing the object to create :param parent: the parent of the current object. Maybe None :param control: 'interface' if the agent is controlled by interface (only inside engine and if template is used) :return: the object instance .. py:method:: create_action(action_type = None, xml_node = None) Create an action :param action_type: The type of the action (Constants in Action class) :param xml_node: XML to create Action :return: The Action created from XML or with just a type .. py:method:: choose_action() Tell all agents to choose their action .. py:method:: clear_all_state_elements() Clear all in the environment .. py:class:: Action(environment, action_type = None, xml_node = None, src_copy = None) This class represents an action that can be done by an agent. :param environment: the environment where the action is created. :param action_type: Type of the action. None, if xml_node. :param xml_node: XML used to create the Action. :param src_copy: The Action will be copied. See copy_obs(). :exception pymasep.common.exception.CreationException: Raised when xml_node, action_type and src_copy are None. .. py:attribute:: environment .. py:attribute:: type :type: Optional[int] type of the action. May be initialized later if the action is created from xml .. py:attribute:: params parameters of the actions .. py:method:: add_parameter(name, value) Add a parameter to the action. :param name: Name of the parameter. :param value: Value of the parameter. Must be XML serializable. .. py:method:: id_str() Create a string unique ID of the Action. Depends on the content of the Action (parameters). :return: The string unique ID .. py:method:: to_xml() Transform the Action to XML. See :ref:`serialization` for more information. :return: XML version of the Action .. py:method:: from_xml(environment, xml_node) Transform an XML to an Action. The instance must be created before. See :ref:`serialization` for more information. :param environment: The environment where the Action is created. :param xml_node: The XML node that contains the Action values and parameters. .. py:method:: __str__() .. py:method:: copy_obs(params) Deep copy an action into a new instance (with its parameters). :param params: Not directly used in this method but passed to the action parameters copy. .. py:class:: BaseObject(environment, name = None, parent = None, xml_node = None, template=None, src_copy = None) Base class for all functional objects for pymasep that running into an environment. Any BaseObject can be created from template or XML. Name can be omitted if created with XML. :param environment: an Environment instance :param name: name of the BaseObject. :param xml_node: XML used to create the object. :param template: Template of the base object. Needed if no xml_node or src_copy :param parent: parent object (see objects hierarchy) :param src_copy: The BaseObject to copy. Needed if no xml_node or template. The copy is not made into the constructor. :raise pymasep.common.exception.CreationException: If no XML or no template or src_copy is present .. py:attribute:: __slots__ :value: ['environment', 'name', 'nature', 'parent', 'template', '_state', 'initializer'] .. py:attribute:: environment .. py:attribute:: parent parent of the base object (see objects hierarchy) .. py:attribute:: name :type: Optional[str] name of the base object .. py:attribute:: _state :type: Optional[str] :value: None .. py:attribute:: initializer :value: None initializer of the base object .. py:attribute:: template template of the base object .. py:attribute:: nature :type: Optional[str] :value: None nature of the base object .. py:property:: state :type: str State of the BaseObject. None if the object is just created. "Init" if it misses something (input from user) to finish the creation. "Run" is the BaseObject is operational. :return: The state of the BaseObject .. py:method:: id_str() Create a string unique ID of the BaseObject. Depends on the content of the BaseObject. :return: The string unique ID .. py:method:: get_fullname() Return the full name of the base object including the parent name : greatparentname.parentname.name. :return: The full name .. py:method:: to_xml() Transform the BaseObject to XML. See :ref:`serialization` for more information. :return: XML version of the BaseObject .. py:method:: from_xml(environment, xml_node) Transform an XML to a BaseObject. The instance must be created before (with __init__(), passing the xml_node). See :ref:`serialization` for more information. :param environment: The environment where the BaseObject is created. :param xml_node: The XML node containing the BaseObject data. .. py:method:: __str__() Transform the BaseObject to a string of its XML representation. See: ref:`serialization` for more information. :return: A string containing the XML representation of the object. .. py:method:: copy_obs(params) Deep copy the BaseObject to a new instance. Template and initializer stay as the same reference as in the original. :param params: Parameters for the copy of a BaseObject. See each Baseobject for more information. Note : this method copy the reference of the parent. The parent should do the parent copy and assignment. .. py:class:: State(environment, name = None, parent = None, xml_node = None, template=None, src_copy = None) Bases: :py:obj:`pymasep.common.base_object.BaseObject` State or Observation of the environment :param environment: an Environment instance :param name: name of the Agent. :param xml_node: XML used to create the state. :param template: Template of the state. Needed if no xml_node. :param parent: Parent object (see objects hierarchy) :param src_copy: The State to copy. Needed if no xml_node or template. The copy is not made into the constructor. :raise pymasep.common.exception.CreationException: If no XML or no template or src_copy is present .. py:attribute:: agents :type: Set[pymasep.common.agent.Agent] set of agent in the state. Can be different from the environment if the state is a partial observation .. py:attribute:: objects Objects in the state .. py:attribute:: is_final :type: bool :value: False is the state final of an episode? .. py:attribute:: step :type: int :value: 0 current step of the episode. .. py:method:: state() State of the State (hum...). "Init" if one of its objects is in init state. :return: The state of the Object .. py:method:: id_str() Create a string unique ID of the State. Depends on the content of the base object and the id_str of all objects in the state :return: The string unique ID .. py:method:: __eq__(other) Test the equality of two states. Two states are equals if they have the same type and their id_str() are equals. Note : in some extreme cases, two different states can have the same id_str() but should not be equals. This case may occur, for example, with characteristic name `Name` and `Name0` with `Name='00'` and `Name0='0'`. But you have to have a twisted mind to model the state this way. Please don't :) The code will remain simpler :) .. py:method:: add_object(obj) Add an object into the state. The object is added in self.agents if the object is an Agent :param obj: Object to add into state. .. py:method:: to_xml() Transform the State to XML.z See :ref:`serialization` for more information. :return: XML version of the State .. py:method:: from_xml(environment, xml_node) Transform an XML to a State. The instance must be created before (with __init__(), passing the xml_node). See :ref:`serialization` for more information. :param environment: The environment where the State is created. :param xml_node: The XML node that contains the State data. :raise pymasep.common.exception.CreationException: SubElement must be present if initializer is not present. At creation, Initializer must be present for all characteristics if initializer is not present for ObjectState .. py:method:: copy_obs(params) Deep copy the State to a new instance. :param params: Not used in this method. .. py:class:: Characteristic(environment, name = None, parent = None, xml_node = None, template=None, src_copy = None) Bases: :py:obj:`pymasep.common.BaseObject` Object to handle characteristic of an Object :param environment: an Environment instance :param name: name of the BaseObject. :param xml_node: XML used to create the object. :param template: Template of the base object. Needed if no xml_node. If the template is present, must include a value_type (see :ref:`templates`) :param parent: parent object (see objects hierarchy) :param src_copy: Characteristic to copy. See copy_obs() :raise pymasep.common.exception.CreationException: If no XML or no template is present .. py:attribute:: _value :type: Any :value: None .. py:attribute:: value_type :type: type type of the characteristic value .. py:property:: value :type: Any Value of the characteristic. The type is defined in self.value_type :return: The value of the characteristic .. py:method:: id_str() Create a string unique ID of the Characteristic. Depends on the content of the BaseObject and the value of the Characteristic :return: The string unique ID .. py:method:: to_xml() Transform the Characteristic to XML. See :ref:`serialization` for more information. :return: XML version of the Characteristic .. py:method:: from_xml(environment, xml_node) Transform an XML to a Characteristic. The instance must be created before (with __init__(), passing the xml_node). See :ref:`serialization` for more information. :param environment: The environment where the BaseObject is created. :param xml_node: The XML node that contains Characteristic data. :raise pymasep.common.exception.CreationException: Initializer or SubElement must be present. If state is 'init', the initializer must be an Interface Initializer if state is 'init', SubElement value must be None. If state is 'run', no template or initializer is allowed. .. py:method:: copy_obs(params) Deep copy the Characteristic to a new instance. :param params: Not used for a Characteristic Note : this method copy the reference of the parent. The parent should do the parent copy and assignment .. py:class:: ObjectState(environment, name = None, parent = None, xml_node = None, template=None, src_copy = None) Bases: :py:obj:`pymasep.common.BaseObject` Class to handle an ObjectState of an Object :param environment: an Environment instance :param name: name of the ObjectState. Not used in this case, 'state' is set for ObjectState :param xml_node: XML used to create the object. :param template: Template of the object. Needed if no xml_node. If the template is present, must include a value_type (see :ref:`templates`) :param src_copy: The ObjectState to copy. Needed if no xml_node or template. The copy is not made into the constructor. :raise pymasep.common.exception.CreationException: If no XML or no template or src_copy is present .. py:attribute:: name :value: 'state' name of the object state .. py:attribute:: characteristics Characteristics of the object state .. py:method:: state() State of the ObjectState. "Init" if the ObjectState or one of its characteristics is in init state. :return: The state of the ObjectState .. py:method:: add_characteristic(characteristic) Adding a characteristic object inside the ObjectState. The key id of the characteristic is its name attribute :param characteristic: Characteristic to add. .. py:method:: id_str() Create a string unique ID of the ObjectState. Return a concatenation of the id_str of the base object and the id_str of all characteristics :return: The string unique ID .. py:method:: to_xml() Transform the ObjectState to XML including all Characteristics. See :ref:`serialization` for more information. :return: XML version of the ObjectState .. py:method:: from_xml(environment, xml_node) Transform an XML to an ObjectState. The instance must be created before (with __init__(), passing the xml_node). See :ref:`serialization` for more information. :param environment: The environment where the ObjectState is created. :param xml_node: The XML node that contains the ObjectState data. :raise pymasep.common.exception.CreationException: SubElement must be present if initializer is not present. At creation, Initializer must be present for all characteristics if initializer is not present for ObjectState .. py:method:: check_all_init_charac_have_initializer(initializer) DEPRECATED ? .. py:method:: copy_obs(params) Deep copy the ObjectState to a new instance. :param params: Not used in this method. Note : this method copy the reference of the parent. The parent should do the parent copy and assignment .. py:class:: Container(environment, name = None, parent = None, xml_node = None, template=None, src_copy = None) Bases: :py:obj:`pymasep.common.BaseObject` Container class containing other objects. A container is not an object itself, it is more an object property. :param environment: an Environment instance :param name: name of the Container. :param xml_node: XML used to create the Container. :param template: Template of the container. Needed if no xml_node. :param parent: Parent object (see objects hierarchy) :param src_copy: Container to copy. See copy_obs() .. py:attribute:: __slots__ :value: ['_container'] .. py:attribute:: _container .. py:method:: state() state of the Container. 'init' if the object is just created or if one contained object is in 'init' state. :return: the state of the Container .. py:method:: set_run() Set the state of a container to run. A container must be explicitly set to run. .. py:method:: add(obj) add an object to the container. :param pymasep.common.Object obj: the object to add .. py:method:: remove(obj) remove an object from the container. :param pymasep.common.Object obj: the object to remove .. py:method:: __iter__() .. py:method:: __next__() .. py:method:: __len__() .. py:method:: __getitem__(item) .. py:method:: id_str() Create a string unique ID of the Container. Return a concatenation of the id_str of the base object and the id_str of all contained objects :return: The string unique ID .. py:method:: to_xml() Transform the Container to XML with all objects contained in the Container. See :ref:`serialization` for more information. :return: XML version of the Container :raise pymasep.common.exception.ConstraintException: A container not initialized must have an initializer before streaming to XML .. py:method:: from_xml(environment, xml_node) Transform an XML to a Container. The instance must be created before (with __init__(), passing the xml_node). See :ref:`serialization` for more information. :param environment: The environment where the ObjectState is created. :param xml_node: The XML node that contains the container information. :raise pymasep.common.exception.CreationException: A container must be empty or containing only an initialized object. .. py:method:: copy_obs(params) Deep copy the Container to a new instance. :param params: Not used for a Container Note : this method copy the reference of the parent. The parent should do the parent copy and assignment .. py:class:: Object(environment, name = None, parent = None, xml_node = None, template=None, src_copy = None) Bases: :py:obj:`pymasep.common.base_object.BaseObject` Object inside the environment :param environment: an Environment instance :param name: name of the Object. :param xml_node: XML used to create the object. :param template: Template of the object. Needed if no xml_node. :param parent: Parent object (see objects hierarchy) :param src_copy: The Intention to copy. Needed if no xml_node or template. The copy is not made into the constructor. :raise pymasep.common.exception.CreationException: If no XML or no template or src_copy is present .. py:attribute:: __slots__ :value: ['object_state', 'containers'] .. py:attribute:: object_state :value: None the ObjectState of the object .. py:attribute:: containers all the containers of the object. .. py:method:: state() State of the Object. "Init" if the ObjectState or one of its containers is in init state. "Run" if the Object is operational. :return: The state of the Object .. py:method:: id_str() Create a string unique ID of the Object. Depends on the content of the base object and the id_str of all characteristics in object_state :return: The string unique ID .. py:method:: to_xml() Transform the Object to XML with ObjectState content See :ref:`serialization` for more information. :return: XML version of the ObjectState .. py:method:: from_xml(environment, xml_node) Transform an XML to an Object. The instance must be created before (with __init__(), passing the xml_node). See :ref:`serialization` for more information. :param environment: The environment where the Object is created. :param xml_node: The XML node that contains the object information. :raise pymasep.common.exception.CreationException: SubElement must be present if initializer is not present. At creation, Initializer must be present for all characteristics if initializer is not present for ObjectState .. py:method:: add_object_in_container(obj, container) Add an Object to a container. This method is currently not used, and some works need to be done to avoid the duplication of objects in state :param obj: The object to be added. :param container: The name of the container. .. py:method:: remove_object_from_container(obj) Remove an Object from its container. Warning: after this method, the object is not attached to anything. Should not be used at the moment. See MDV-72 .. py:method:: copy_obs(params) Deep copy the Object to a new instance. :param params: Not used in this method. Note : this method copy the reference of the parent. The parent should do the parent copy and assignment .. py:class:: Agent(environment, name = None, parent=None, template=None, xml_node = None, src_copy = None) Bases: :py:obj:`pymasep.common.object.Object` Agent that act inside the environment :param environment: an Environment instance :param name: name of the Agent. :param xml_node: XML used to create the agent. :param template: Template of the agent. Needed if no xml_node. :param parent: Parent object (see objects hierarchy) :param src_copy: The Agent to copy. Needed if no xml_node or template. The copy is not made into the constructor, see copy_obs() :raise pymasep.common.exception.CreationException: If no XML or no template is present .. py:attribute:: action :value: None next action of the agent .. py:attribute:: observation :value: None current observation of the agent .. py:attribute:: reward :value: None current reward of the agent, if pertinent .. py:attribute:: controller :value: None controller of the agent .. py:attribute:: control :value: None sub app id that control the agent (an interface or the engine) .. py:attribute:: intention :value: None current intention of the agent .. py:attribute:: belief belief of the agent .. py:method:: choose_action() Choose the next action of the agent using its controller .. py:method:: set_observation_reward(observation, reward = None) Set the observation and the reward of the agent. :param observation: Observation of the agent (as a State) :param reward: reward of the agent. .. py:method:: id_str() Create a string unique ID of the Agent. Depends on the content of the base object and the id_str of all characteristics in object_state, and the intention of the agent :return: The string unique ID .. py:method:: to_xml() Transform the Agent to XML. See :ref:`serialization` for more information. :return: XML version of the Agent .. py:method:: from_xml(environment, xml_node) Transform an XML to an Agent. The instance must be created before (with __init__(), passing the xml_node). See :ref:`serialization` for more information. :param environment: The environment where the Agent is created. :param xml_node: The XML node containing the Agent content. :raise pymasep.common.exception.CreationException: SubElement must be present if initializer is not present. At creation, Initializer must be present for all characteristics if initializer is not present for ObjectState .. py:method:: copy_obs(params) Deep copy the agent into a new instance (with sub BaseObjects, except the Belief) :param params: The agent needs the full name of the agent that observes (key: obs_agt_fname) Note : this method copy the reference of the parent. The parent should do the parent copy and assignment. Belief is the same (same reference) in the observation (for the agent that observes) and in the state. .. py:class:: Game(cfg = None) Represents the rules of the game. A game contains templates and initializers. :param cfg: DictConfig containing the configuration. See :ref:`config` for more information. .. py:attribute:: ACTION_NO_ACTION :value: 0 No action .. py:attribute:: ACTION_INIT_OBJECT :value: 1000 Action for initializing object from interface .. py:attribute:: ACTION_INTENTION :value: 2000 The agent wants to validate an intention .. py:attribute:: ACTION_VIDEO_ENDED :value: 10000 The interface agent wants to stop a video. See CutSceneInterfaceState .. py:attribute:: MULTIPLAYER_COORDINATION_TURN :value: 1 Turn by turn game .. py:attribute:: MULTIPLAYER_COORDINATION_WAITING_ALL :value: 2 Waiting all action before next state. Not implemented for interface agents at the moment. .. py:attribute:: MULTIPLAYER_COORDINATION_FREE_FOR_ALL :value: 3 Execute action when it arrives. .. py:attribute:: config configuration of the game .. py:attribute:: initializers initializers available in the game .. py:attribute:: templates templates available in the game .. py:attribute:: default_templates default templates for nature of object. Not used at the moment. .. py:attribute:: root_path root path of the game .. py:attribute:: data_path data path of the game .. py:attribute:: is_rewarded :type: Optional[bool] :value: None is the game rewards agents ? .. py:attribute:: nb_episodes :value: 1 number of episodes of the game. Usually one except for learning/simulation games. .. py:attribute:: max_nb_players maximum number of players (human) in the game .. py:attribute:: possible_players list of possible players names .. py:attribute:: coord_method possible coordinates methods according to the game phase (see State.system object, GamePhase) .. py:method:: define_coord_methods() Define the dictionary of coordination methods according to the game phase .. py:method:: add_templates() Add default templates to the game .. py:method:: add_initializers() This method adds definitions of initializers to the game. .. py:method:: init_state(environment) Create the initial state of the game. Can be reimplemented in subclasses. :param environment: The environment. :return: The initial state .. py:method:: initialize_state(environment) Create the initial state of the game. :param environment: The environment. :return: The initial state .. py:method:: set_system_value(state, key, value) :staticmethod: Set a value to a system characteristic. The charac is set to "State.system" object. :param state: The state where the characteristic have to be set. The state is modified :param key: the name of the characteristic :param value: the value of the characteristic :return: the state modified .. py:method:: get_system_value(state, key) :staticmethod: Get the value of a system characteristic. :param state: The state where to read the value. :param key: The name of the characteristic. The name must exist. :return: The value of the characteristic .. py:method:: create_external_agent(env, external_id) Create an agent for an external thread. Initialized as best as can the game do without external inputs :param env: The environment :param external_id: uuid of the external thread/sub_app :return: the agent .. py:method:: next_state(current_state, actions) :abstractmethod: Calculates the new state according to the current state and the action of the agent. Must be reimplemented in subclasses. :param current_state: The current state :param actions: action of the agents :return: the new state and the additional information about the state (may be None). .. py:method:: reward(previous_state, actions, next_state) :abstractmethod: Return the reward for all agents depending on the previous_state, actions and the next state. This is the general form, but each game can implement it as they want. :param previous_state: The previous state before actions. :param actions: Actions of the agents :param next_state: next state usually calculated by next_state() :return: a dictionary of the reward by agent. .. py:method:: is_final(state) Is the state final? :param state: The state. :return: True if final, False if not .. py:method:: observe_state(state, agent_fname) :classmethod: State Observation function. Calculate the al state according to d from state pS :param state: The state of the environment. :param agent_fname: The agent full name that observes the state :return: the observed state. The result is a state (possibly partial and noisy) and not a general observation. .. py:method:: update_belief(agent_fname, observation, state) :classmethod: The belief of the agent is updated according to the observation and the state and is updated in the state and the observation. Normally, the copy made a reference to the belief so the belief is shared between state and observation for the agent agent_fname. :param agent_fname: Fullname of the agent this method updates the belief for :param observation: the observation used to update the belief. :param state: The state of the environment used to update the belief. .. py:method:: add_initializer(initializer) Add an initializer into the initializer dictionary of the game :param initializer: The test_initializer to add .. py:method:: add_template(template) Add a template into the initializer dictionary of the game :param template: The template to add .. py:method:: add_default_template(object_nature, template_name) Add a default template into the initializer dictionary of the game :param object_nature: The type of object to associate :param template_name: the template to associate (must exist in game.templates) .. py:method:: order_agents(current_order, new_agent) :staticmethod: Implement rules to determine the order of playing agent. Usefull only for MULTIPLAYER_COORDINATION_TURN. At the moment, first in, first out order is implemented :param current_order: The current order of agent :param new_agent: the new agent to add :return: an ordered list of agents' names that can be used by next_state() to set the next agent that can play .. py:class:: Controller(environment) Abstract controller to control an agent in the environment :param environment: environment for the controller .. py:attribute:: environment .. py:method:: action_choice(observation, agent) Choose the action. :param pymasep.common.State observation: The observation used to choose the action. :param pymasep.common.Agent agent: The agent who chooses the action. :return: The action (pymasep.common.Action) chose for the agent. .. py:method:: on_observe(observation, reward = None) Do something when the agent observes the state and possibly a reward. Useful for learning controllers. :param pymasep.common.State observation: The observation used to choose the action. :param reward: The reward obtained. .. py:class:: Intention(environment, name = None, parent=None, xml_node = None, template=None, src_copy = None) Bases: :py:obj:`pymasep.common.base_object.BaseObject` An intention is a desired action. This class stores all intentions of an agent The intention is attached to the agent when it has been validated by the game rules. :param environment: the environment :param name: name of the BaseObject :param xml_node: XML used to create the object. :param template: Template of the base object. Needed if no xml_node. :param parent: Parent object (see objects hierarchy) :param src_copy: The Intention to copy. Needed if no xml_node or template. The copy is not made into the constructor. :raise pymasep.common.exception.CreationException: If no XML or no template or src_copy is present .. py:attribute:: name :type: str :value: 'intention' the name of the object intention .. py:attribute:: intentions :value: [] list of intentions. The order reflects the desired order of the agent .. py:attribute:: state :type: str :value: 'run' State of the BaseObject. None if the object is just created. "Init" if it misses something (input from user) to finish the creation. "Run" is the BaseObject is operational. :return: The state of the BaseObject .. py:method:: add_intention(intention) add an intention to the agent intentions list :param intention: the intention (an action) to add .. py:method:: id_str() Create an str unique ID of the Intention. :return: the string unique ID .. py:method:: to_xml() Transform the Intention to XML. See :ref:`serialization` for more information. :return: XML version of the Intention .. py:method:: from_xml(environment, xml_node) Transform an XML to an Intention. The instance must be created before (with __init__(), passing the xml_node). See :ref:`serialization` for more information. :param environment: The environment where the BaseObject is created. :param xml_node: The XML node that contains the intention data. .. py:method:: copy_obs(params) Deep copy the Intention to a new instance. :param params: Not used in this method. Note : this method copy the reference of the parent. The parent should do the parent copy and assignment .. py:class:: Belief(environment, name = None, template=None, xml_node = None, parent=None) Bases: :py:obj:`pymasep.common.BaseObject` The Belief of an agent is all the agent knows about the world and that could have an influence on their actions. Here, the concept of Belief is more inspired by the BDI agent architecture than by the belief of a DEC-POMDP. Beliefs are based on Conceptual Graphs :cite:`sowa_conceptual_1984` :cite:`chein_graph-based_2008`. This version is limited to a simpler version of conceptual graphs. It has been tested with belief of three nodes (concept-relation-concept) See test_belief.py for more details. NOTE: Contrary to other BaseObjects, src_copy is not used for Belief since Belief instances are never copied but stay as the same reference in the current state :param environment: An Environment instance :param name: name of the Belief. :param xml_node: XML used to create the object. :param template: Template of the Belief. Needed if no xml_node or src_copy :param parent: parent object (see objects hierarchy) .. py:attribute:: beliefs beliefs data as a conceptual graph .. py:method:: state() State of the Belief. Always 'run' :return: The state of Belief .. py:method:: id_str() Create an str unique ID of the Belief :return: the string unique ID .. py:method:: node_id(g, c = None, cr = None) Get or create the node id of a node in the Belief. :param g: The graph to create the node id for :param c: the tuple of attribute of the node id to search if the node already exists :param cr: if c is a relation, this parameter represents the concepts linked to the relation .. py:method:: add(c1, r, c2) Adding two concepts linked with one relation into the belief :param c1: First concept as a tuple (concept, instance of the concept) :param r: relation between concepts. :param c2: Second concept as a tuple (concept, instance of the concept) .. py:method:: _create_request(c1, r, c2) .. py:method:: query(query) Query in a Belief :param query: Query as a graph. Use \* as an instance query. Example of a query [Agent:\*]-[Tell]-[Sentence:s1] will return a graph containing all agents that tell the sentence s1 in the agent belief. .. py:method:: to_xml() Transform the Belief to XML. See :ref:`serialization` for more information. :return: XML version of the BaseObject .. py:method:: from_xml(environment, xml_node) Transform an XML to a Belief. The instance must be created before (with __init__(), passing the xml_node). See :ref:`serialization` for more information. :param environment: The environment where the BaseObject is created. :param xml_node: The XML node that contains the Belief data.