pymasep.common

Subpackages

Submodules

Classes

`Environment`	Represents the environment of the game. This object keeps all dynamic value of the game.
`Action`	This class represents an action that can be done by an agent.
`BaseObject`	Base class for all functional objects for pymasep that running into an environment.
`State`	State or Observation of the environment
`Characteristic`	Object to handle characteristic of an Object
`ObjectState`	Class to handle an ObjectState of an Object
`Container`	Container class containing other objects. A container is not an object itself, it is more an object property.
`Object`	Object inside the environment
`Agent`	Agent that act inside the environment
`Game`	Represents the rules of the game.
`Controller`	Abstract controller to control an agent in the environment
`Intention`	An intention is a desired action. This class stores all intentions of an agent
`Belief`	The Belief of an agent is all the agent knows about the world and that could have an influence on their actions.

Package Contents

class pymasep.common.Environment(id_env=None, cfg=None)

Represents the environment of the game. This object keeps all dynamic value of the game.

Parameters:

id_env (str) – the id of the environment. If None, a new uuid will be set
cfg (omegaconf.DictConfig)

Parm cfg:

the configuration of the environment

id: str: Environment id.

config: configuration of the environment.

end_episode: bool = False: the current episode is finished

current_step: int = 0: current step of the environment

current_episode: int = 0: current episode of the environment

current_state: pymasep.common.state.State | None = None: current state of the environment

current_additional_info: dict: current additional information of the environment, related to the current state. Sort of meta information on the current state

agents: Set[pymasep.common.agent.Agent]: set of agents in the current state

controllers: Dict[str, pymasep.common.controller.Controller]: set of controllers that can be used in the environment

_game: pymasep.common.game.Game | None = None

next_action: Dict[str, pymasep.common.action.Action]: next action to be executed in the current state

_level_logger

logger: logger for the environment tasks

__del__()

property game: pymasep.common.game.Game

Game of the environment.

Return type:: pymasep.common.game.Game

get_current_coord_method(state=None)

Return the current coordination method according to the current game phase in the state

Parameters:: state (Optional[pymasep.common.state.State]) – State to check the coordination method. If None, take the current state of the environment.
Returns:: The current coordinate method
Return type:: str

get_observation_for_agent(agent)

Get the current observation. Current state at the moment

Parameters:: agent (pymasep.common.agent.Agent) – The agent to get the observation for
Returns:: The current observation
Return type:: pymasep.common.state.State

get_additional_info_for_agent()

Get the current additional information. Could be filtered in the future (by agent)

Returns:: The current additional information
Return type:: dict

get_reward_for_agent(agent)

Get the current reward for an agent.

Parameters:: agent (pymasep.common.agent.Agent) – The agent to get the reward
Returns:: The current reward of the agent
Return type:: dict

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…)

Parameters:

agent_name (str) – The agent’s name
class_controller – the class of the controller to create if it is not created
class_controller_ (Type[pymasep.common.controller.Controller])

Returns:

the instance of the agent’s controller

Return type:

pymasep.common.controller.Controller

calculate_end_episode()

Calculate the end of the episode. Modify self.end_episode if the conditions of the episode’s end are met.

Return type:: None

calculate_next_state()

Calculate the next state of the environment. Change the current state. Increase the step

Return type:: None

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) \(R(s)\) and neither \(R(s,a)\) nor \(R(s,a,s')\)

Return type:: None

create_base_object(name=None, template=None, xml_node=None, parent=None)

Create a base object from a string represent the type

Parameters:

name (Optional[str]) – The identification name of the BaseObject.
template (Optional[pymasep.common.template.Template]) – Template of the created object. If None and no XML is specified, will be the default template for this bo_type
xml_node (Optional[xml.etree.ElementTree.Element]) – XML node used for creating the base object
parent (Optional[pymasep.common.base_object.BaseObject]) – the parent of the current object. May be None.

Returns:

The BaseObject instance

get_type_controller(xml_node=None, template=None, control=None)

Get the type of controller according to a template or (exclusive) an XML node.

Parameters:

xml_node (Optional[xml.etree.ElementTree.Element]) – XML node used to get the controller type. Use the attribute “controller”.
template (Optional[pymasep.common.template.Template]) – The template used to get the controller type.
control (Optional[str]) – ‘Interface’ if the agent is controlled by interface (only inside engine, and if template is used)

Returns:

the class of the controller to use

Return type:

Type[pymasep.common.controller.Controller]

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

Parameters:

name (Optional[str]) – The identification name of the object. Not used if xml_node is used
template (Optional[pymasep.common.template.Template]) – the template of the class to create the object. Not used if xml_node is used
xml_node (Optional[xml.etree.ElementTree.Element]) – XML node describing the object to create
parent (Optional[pymasep.common.base_object.BaseObject]) – the parent of the current object. Maybe None
control (Optional[str]) – ‘interface’ if the agent is controlled by interface (only inside engine and if template is used)

Returns:

the object instance

create_action(action_type=None, xml_node=None)

Create an action

Parameters:

action_type (Optional[int]) – The type of the action (Constants in Action class)
xml_node (xml.etree.ElementTree.Element) – XML to create Action

Returns:

The Action created from XML or with just a type

Return type:

pymasep.common.action.Action

choose_action()

Tell all agents to choose their action

Return type:: None

clear_all_state_elements()

Clear all in the environment

Return type:: None

class pymasep.common.Action(environment, action_type=None, xml_node=None, src_copy=None)

This class represents an action that can be done by an agent.

Parameters:

environment – the environment where the action is created.
action_type (Optional[int]) – Type of the action. None, if xml_node.
xml_node (xml.etree.ElementTree.Element) – XML used to create the Action.
src_copy (Optional[Action]) – The Action will be copied. See copy_obs().

Raises:

pymasep.common.exception.CreationException – Raised when xml_node, action_type and src_copy are None.

environment

type: int | None: type of the action. May be initialized later if the action is created from xml

params: parameters of the actions

add_parameter(name, value)

Add a parameter to the action.

Parameters:

name (str) – Name of the parameter.
value (Any) – Value of the parameter. Must be XML serializable.

Return type:

None

id_str()

Create a string unique ID of the Action. Depends on the content of the Action (parameters).

Returns:: The string unique ID
Return type:: str

to_xml()

Transform the Action to XML. See Serialization for more information.

Returns:: XML version of the Action
Return type:: xml.etree.ElementTree.Element

from_xml(environment, xml_node)

Transform an XML to an Action. The instance must be created before. See Serialization for more information.

Parameters:

environment – The environment where the Action is created.
xml_node (xml.etree.ElementTree.Element) – The XML node that contains the Action values and parameters.

Return type:

None

__str__()

Return type:: str

copy_obs(params)

Deep copy an action into a new instance (with its parameters).

Parameters:: params (dict) – Not directly used in this method but passed to the action parameters copy.

class pymasep.common.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.

Parameters:

environment – an Environment instance
name (Optional[str]) – name of the BaseObject.
xml_node (Optional[xml.etree.ElementTree.Element]) – XML used to create the object.
template – Template of the base object. Needed if no xml_node or src_copy
parent (Optional[BaseObject]) – parent object (see objects hierarchy)
src_copy (Optional[BaseObject]) – The BaseObject to copy. Needed if no xml_node or template. The copy is not made into the constructor.

Raises:

pymasep.common.exception.CreationException – If no XML or no template or src_copy is present

__slots__ = ['environment', 'name', 'nature', 'parent', 'template', '_state', 'initializer']

environment

parent: parent of the base object (see objects hierarchy)

name: str | None: name of the base object

_state: str | None = None

initializer = None: initializer of the base object

template: template of the base object

nature: str | None = None: nature of the base object

property state: 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.

Returns:: The state of the BaseObject
Return type:: str

id_str()

Create a string unique ID of the BaseObject. Depends on the content of the BaseObject.

Returns:: The string unique ID
Return type:: str

get_fullname()

Return the full name of the base object including the parent name : greatparentname.parentname.name.

Returns:: The full name
Return type:: str

to_xml()

Transform the BaseObject to XML. See Serialization for more information.

Returns:: XML version of the BaseObject
Return type:: xml.etree.ElementTree.Element

from_xml(environment, xml_node)

Transform an XML to a BaseObject. The instance must be created before (with __init__(), passing the xml_node). See Serialization for more information.

Parameters:

environment – The environment where the BaseObject is created.
xml_node (xml.etree.ElementTree.Element) – The XML node containing the BaseObject data.

Return type:

None

__str__()

Transform the BaseObject to a string of its XML representation. See: ref:serialization for more information.

Returns:: A string containing the XML representation of the object.
Return type:: str

copy_obs(params)

Deep copy the BaseObject to a new instance. Template and initializer stay as the same reference as in the original.

Parameters:: params (dict) – 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.

class pymasep.common.State(environment, name=None, parent=None, xml_node=None, template=None, src_copy=None)

Bases: pymasep.common.base_object.BaseObject

State or Observation of the environment

Parameters:

environment – an Environment instance
name (Optional[str]) – name of the Agent.
xml_node (Optional[xml.etree.ElementTree.Element]) – XML used to create the state.
template – Template of the state. Needed if no xml_node.
parent (Optional[pymasep.common.base_object.BaseObject]) – Parent object (see objects hierarchy)
src_copy (Optional[State]) – The State to copy. Needed if no xml_node or template. The copy is not made into the constructor.

Raises:

pymasep.common.exception.CreationException – If no XML or no template or src_copy is present

agents: Set[pymasep.common.agent.Agent]: set of agent in the state. Can be different from the environment if the state is a partial observation

objects: Objects in the state

is_final: bool = False: is the state final of an episode?

step: int = 0: current step of the episode.

state()

State of the State (hum…). “Init” if one of its objects is in init state.

Returns:: The state of the Object
Return type:: str

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

Returns:: The string unique ID
Return type:: str

__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 :)

add_object(obj)

Add an object into the state. The object is added in self.agents if the object is an Agent

Parameters:: obj – Object to add into state.
Return type:: None

to_xml()

Transform the State to XML.z See Serialization for more information.

Returns:: XML version of the State
Return type:: xml.etree.ElementTree.Element

from_xml(environment, xml_node)

Transform an XML to a State. The instance must be created before (with __init__(), passing the xml_node). See Serialization for more information.

Parameters:

environment – The environment where the State is created.
xml_node (xml.etree.ElementTree.Element) – The XML node that contains the State data.

Raises:

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

Return type:

None

copy_obs(params)

Deep copy the State to a new instance.

Parameters:: params (dict) – Not used in this method.

class pymasep.common.Characteristic(environment, name=None, parent=None, xml_node=None, template=None, src_copy=None)

Bases: pymasep.common.BaseObject

Object to handle characteristic of an Object

Parameters:

environment – an Environment instance
name (str) – name of the BaseObject.
xml_node (Optional[xml.etree.ElementTree.Element]) – XML used to create the object.
template – Template of the base object. Needed if no xml_node. If the template is present, must include a value_type (see Templates)
parent (Optional[pymasep.common.BaseObject]) – parent object (see objects hierarchy)
src_copy (Optional[Characteristic]) – Characteristic to copy. See copy_obs()

Raises:

pymasep.common.exception.CreationException – If no XML or no template is present

_value: Any = None

value_type: type: type of the characteristic value

property value: Any

Value of the characteristic. The type is defined in self.value_type

Returns:: The value of the characteristic
Return type:: Any

id_str()

Create a string unique ID of the Characteristic. Depends on the content of the BaseObject and the value of the Characteristic

Returns:: The string unique ID
Return type:: str

to_xml()

Transform the Characteristic to XML. See Serialization for more information.

Returns:: XML version of the Characteristic
Return type:: xml.etree.ElementTree.Element

from_xml(environment, xml_node)

Transform an XML to a Characteristic. The instance must be created before (with __init__(), passing the xml_node). See Serialization for more information.

Parameters:

environment – The environment where the BaseObject is created.
xml_node (xml.etree.ElementTree.Element) – The XML node that contains Characteristic data.

Raises:

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.

Return type:

None

copy_obs(params)

Deep copy the Characteristic to a new instance.

Parameters:: params (dict) – Not used for a Characteristic

Note : this method copy the reference of the parent. The parent should do the parent copy and assignment

class pymasep.common.ObjectState(environment, name=None, parent=None, xml_node=None, template=None, src_copy=None)

Bases: pymasep.common.BaseObject

Class to handle an ObjectState of an Object

Parameters:

environment – an Environment instance
name (Optional[str]) – name of the ObjectState. Not used in this case, ‘state’ is set for ObjectState
xml_node (Optional[xml.etree.ElementTree.Element]) – XML used to create the object.
template – Template of the object. Needed if no xml_node. If the template is present, must include a value_type (see Templates)
src_copy (Optional[ObjectState]) – The ObjectState to copy. Needed if no xml_node or template. The copy is not made into the constructor.
parent (Optional[pymasep.common.BaseObject])

Raises:

pymasep.common.exception.CreationException – If no XML or no template or src_copy is present

name = 'state': name of the object state

characteristics: Characteristics of the object state

state()

State of the ObjectState. “Init” if the ObjectState or one of its characteristics is in init state.

Returns:: The state of the ObjectState
Return type:: str

add_characteristic(characteristic)

Adding a characteristic object inside the ObjectState. The key id of the characteristic is its name attribute

Parameters:: characteristic – Characteristic to add.
Return type:: None

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

Returns:: The string unique ID
Return type:: str

to_xml()

Transform the ObjectState to XML including all Characteristics. See Serialization for more information.

Returns:: XML version of the ObjectState
Return type:: xml.etree.ElementTree.Element

from_xml(environment, xml_node)

Transform an XML to an ObjectState. The instance must be created before (with __init__(), passing the xml_node). See Serialization for more information.

Parameters:

environment – The environment where the ObjectState is created.
xml_node (xml.etree.ElementTree.Element) – The XML node that contains the ObjectState data.

Raises:

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

Return type:

None

check_all_init_charac_have_initializer(initializer)

DEPRECATED ?

Return type:: None

copy_obs(params)

Deep copy the ObjectState to a new instance.

Parameters:: params (dict) – Not used in this method.

Note : this method copy the reference of the parent. The parent should do the parent copy and assignment

class pymasep.common.Container(environment, name=None, parent=None, xml_node=None, template=None, src_copy=None)

Bases: pymasep.common.BaseObject

Container class containing other objects. A container is not an object itself, it is more an object property.

Parameters:

environment – an Environment instance
name (Optional[str]) – name of the Container.
xml_node (Optional[xml.etree.ElementTree.Element]) – XML used to create the Container.
template – Template of the container. Needed if no xml_node.
parent (Optional[pymasep.common.BaseObject]) – Parent object (see objects hierarchy)
src_copy (Optional[Container]) – Container to copy. See copy_obs()

__slots__ = ['_container']

_container

state()

state of the Container. ‘init’ if the object is just created or if one contained object is in ‘init’ state.

Returns:: the state of the Container
Return type:: str

set_run(): Set the state of a container to run. A container must be explicitly set to run.

add(obj)

add an object to the container.

Parameters:: obj (pymasep.common.Object) – the object to add

remove(obj)

remove an object from the container.

Parameters:: obj (pymasep.common.Object) – the object to remove

__iter__()

__next__()

__len__()

__getitem__(item)

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

Returns:: The string unique ID
Return type:: str

to_xml()

Transform the Container to XML with all objects contained in the Container. See Serialization for more information.

Returns:: XML version of the Container
Raises:: pymasep.common.exception.ConstraintException – A container not initialized must have an initializer before streaming to XML
Return type:: xml.etree.ElementTree.Element

from_xml(environment, xml_node)

Transform an XML to a Container. The instance must be created before (with __init__(), passing the xml_node). See Serialization for more information.

Parameters:

environment – The environment where the ObjectState is created.
xml_node (xml.etree.ElementTree.Element) – The XML node that contains the container information.

Raises:

pymasep.common.exception.CreationException – A container must be empty or containing only an initialized object.

Return type:

None

copy_obs(params)

Deep copy the Container to a new instance.

Parameters:: params (dict) – Not used for a Container

Note : this method copy the reference of the parent. The parent should do the parent copy and assignment

class pymasep.common.Object(environment, name=None, parent=None, xml_node=None, template=None, src_copy=None)

Bases: pymasep.common.base_object.BaseObject

Object inside the environment

Parameters:

environment – an Environment instance
name (Optional[str]) – name of the Object.
xml_node (Optional[xml.etree.ElementTree.Element]) – XML used to create the object.
template – Template of the object. Needed if no xml_node.
parent (Optional[pymasep.common.base_object.BaseObject]) – Parent object (see objects hierarchy)
src_copy (Optional[Object]) – The Intention to copy. Needed if no xml_node or template. The copy is not made into the constructor.

Raises:

pymasep.common.exception.CreationException – If no XML or no template or src_copy is present

__slots__ = ['object_state', 'containers']

object_state = None: the ObjectState of the object

containers: all the containers of the object.

state()

State of the Object. “Init” if the ObjectState or one of its containers is in init state. “Run” if the Object is operational.

Returns:: The state of the Object
Return type:: str

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

Returns:: The string unique ID
Return type:: str

to_xml()

Transform the Object to XML with ObjectState content See Serialization for more information.

Returns:: XML version of the ObjectState
Return type:: xml.etree.ElementTree.Element

from_xml(environment, xml_node)

Transform an XML to an Object. The instance must be created before (with __init__(), passing the xml_node). See Serialization for more information.

Parameters:

environment – The environment where the Object is created.
xml_node (xml.etree.ElementTree.Element) – The XML node that contains the object information.

Raises:

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

Return type:

None

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

Parameters:

obj – The object to be added.
container (str) – The name of the container.

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

copy_obs(params)

Deep copy the Object to a new instance.

Parameters:: params (dict) – Not used in this method.

Note : this method copy the reference of the parent. The parent should do the parent copy and assignment

class pymasep.common.Agent(environment, name=None, parent=None, template=None, xml_node=None, src_copy=None)

Bases: pymasep.common.object.Object

Agent that act inside the environment

Parameters:

environment – an Environment instance
name (str) – name of the Agent.
xml_node (Optional[xml.etree.ElementTree.ElementTree]) – XML used to create the agent.
template – Template of the agent. Needed if no xml_node.
parent – Parent object (see objects hierarchy)
src_copy (Optional[Agent]) – The Agent to copy. Needed if no xml_node or template. The copy is not made into the constructor, see copy_obs()

Raises:

pymasep.common.exception.CreationException – If no XML or no template is present

action = None: next action of the agent

observation = None: current observation of the agent

reward = None: current reward of the agent, if pertinent

controller = None: controller of the agent

control = None: sub app id that control the agent (an interface or the engine)

intention = None: current intention of the agent

belief: belief of the agent

choose_action()

Choose the next action of the agent using its controller

Return type:: None

set_observation_reward(observation, reward=None)

Set the observation and the reward of the agent.

Parameters:

observation – Observation of the agent (as a State)
reward (Optional[pymasep.utils.Any]) – reward of the agent.

Return type:

None

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

Returns:: The string unique ID
Return type:: str

to_xml()

Transform the Agent to XML. See Serialization for more information. :return: XML version of the Agent

Return type:: xml.etree.ElementTree.Element

from_xml(environment, xml_node)

Transform an XML to an Agent. The instance must be created before (with __init__(), passing the xml_node). See Serialization for more information.

Parameters:

environment – The environment where the Agent is created.
xml_node (xml.etree.ElementTree.Element) – The XML node containing the Agent content.

Raises:

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

Return type:

None

copy_obs(params)

Deep copy the agent into a new instance (with sub BaseObjects, except the Belief)

Parameters:: params (dict) – 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.

class pymasep.common.Game(cfg=None)

Represents the rules of the game. A game contains templates and initializers.

Parameters:: cfg (omegaconf.DictConfig) – DictConfig containing the configuration. See Configuration for more information.

ACTION_NO_ACTION = 0: No action

ACTION_INIT_OBJECT = 1000: Action for initializing object from interface

ACTION_INTENTION = 2000: The agent wants to validate an intention

ACTION_VIDEO_ENDED = 10000: The interface agent wants to stop a video. See CutSceneInterfaceState

MULTIPLAYER_COORDINATION_TURN = 1: Turn by turn game

MULTIPLAYER_COORDINATION_WAITING_ALL = 2: Waiting all action before next state. Not implemented for interface agents at the moment.

MULTIPLAYER_COORDINATION_FREE_FOR_ALL = 3: Execute action when it arrives.

config: configuration of the game

initializers: initializers available in the game

templates: templates available in the game

default_templates: default templates for nature of object. Not used at the moment.

root_path: root path of the game

data_path: data path of the game

is_rewarded: bool | None = None: is the game rewards agents ?

nb_episodes = 1: number of episodes of the game. Usually one except for learning/simulation games.

max_nb_players: maximum number of players (human) in the game

possible_players: list of possible players names

coord_method: possible coordinates methods according to the game phase (see State.system object, GamePhase)

define_coord_methods(): Define the dictionary of coordination methods according to the game phase

add_templates()

Add default templates to the game

Return type:: None

add_initializers(): This method adds definitions of initializers to the game.

init_state(environment)

Create the initial state of the game. Can be reimplemented in subclasses.

Parameters:: environment – The environment.
Returns:: The initial state
Return type:: pymasep.common.state.State

initialize_state(environment)

Create the initial state of the game.

Parameters:: environment – The environment.
Returns:: The initial state
Return type:: pymasep.common.state.State

static set_system_value(state, key, value)

Set a value to a system characteristic. The charac is set to “State.system” object.

Parameters:

state (pymasep.common.state.State) – The state where the characteristic have to be set. The state is modified
key (str) – the name of the characteristic
value (Any) – the value of the characteristic

Returns:

the state modified

Return type:

pymasep.common.state.State

static get_system_value(state, key)

Get the value of a system characteristic.

Parameters:

state (pymasep.common.state.State) – The state where to read the value.
key (str) – The name of the characteristic. The name must exist.

Returns:

The value of the characteristic

Return type:

Any

create_external_agent(env, external_id)

Create an agent for an external thread. Initialized as best as can the game do without external inputs

Parameters:

env – The environment
external_id (str) – uuid of the external thread/sub_app

Returns:

the agent

Return type:

pymasep.common.agent.Agent

abstract next_state(current_state, actions)

Calculates the new state according to the current state and the action of the agent. Must be reimplemented in subclasses.

Parameters:

current_state (pymasep.common.state.State) – The current state
actions (Dict[str, pymasep.common.action.Action]) – action of the agents

Returns:

the new state and the additional information about the state (may be None).

Return type:

Tuple[pymasep.common.state.State, Dict]

abstract reward(previous_state, actions, next_state)

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.

Parameters:

previous_state (Optional[pymasep.common.state.State]) – The previous state before actions.
actions (Optional[Dict[str, pymasep.common.action.Action]]) – Actions of the agents
next_state (pymasep.common.state.State) – next state usually calculated by next_state()

Returns:

a dictionary of the reward by agent.

Return type:

Dict

is_final(state)

Is the state final?

Parameters:: state (pymasep.common.state.State) – The state.
Returns:: True if final, False if not
Return type:: bool

classmethod observe_state(state, agent_fname)

State Observation function. Calculate the al state according to d from state pS

Parameters:

state (pymasep.common.state.State) – The state of the environment.
agent_fname (str) – The agent full name that observes the state

Returns:

the observed state. The result is a state (possibly partial and noisy) and not a general observation.

Return type:

pymasep.common.state.State

classmethod update_belief(agent_fname, observation, state)

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.

Parameters:

agent_fname (str) – Fullname of the agent this method updates the belief for
observation (pymasep.common.state.State) – the observation used to update the belief.
state (pymasep.common.state.State) – The state of the environment used to update the belief.

Return type:

None

add_initializer(initializer)

Add an initializer into the initializer dictionary of the game

Parameters:: initializer (pymasep.common.initializer.Initializer) – The test_initializer to add
Return type:: None

add_template(template)

Add a template into the initializer dictionary of the game

Parameters:: template (pymasep.common.template.Template) – The template to add
Return type:: None

add_default_template(object_nature, template_name)

Add a default template into the initializer dictionary of the game

Parameters:

object_nature (str) – The type of object to associate
template_name (str) – the template to associate (must exist in game.templates)

Return type:

None

static order_agents(current_order, new_agent)

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

Parameters:

current_order (List[str]) – The current order of agent
new_agent – the new agent to add

Returns:

an ordered list of agents’ names that can be used by next_state() to set the next agent that can play

Return type:

List[str]

class pymasep.common.Controller(environment)

Abstract controller to control an agent in the environment

Parameters:: environment – environment for the controller

environment

action_choice(observation, agent)

Choose the action.

Parameters:

observation (pymasep.common.State) – The observation used to choose the action.
agent (pymasep.common.Agent) – The agent who chooses the action.

Returns:

The action (pymasep.common.Action) chose for the agent.

on_observe(observation, reward=None)

Do something when the agent observes the state and possibly a reward.

Useful for learning controllers.

Parameters:

observation (pymasep.common.State) – The observation used to choose the action.
reward (Optional[Any]) – The reward obtained.

class pymasep.common.Intention(environment, name=None, parent=None, xml_node=None, template=None, src_copy=None)

Bases: 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.

Parameters:

environment – the environment
name (Optional[str]) – name of the BaseObject
xml_node (Optional[xml.etree.ElementTree.Element]) – XML used to create the object.
template – Template of the base object. Needed if no xml_node.
parent – Parent object (see objects hierarchy)
src_copy (Optional[Intention]) – The Intention to copy. Needed if no xml_node or template. The copy is not made into the constructor.

Raises:

pymasep.common.exception.CreationException – If no XML or no template or src_copy is present

name: str = 'intention': the name of the object intention

intentions = []: list of intentions. The order reflects the desired order of the agent

state: str = '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.

Returns:: The state of the BaseObject

add_intention(intention)

add an intention to the agent intentions list

Parameters:: intention (pymasep.common.action.Action) – the intention (an action) to add
Return type:: None

id_str()

Create an str unique ID of the Intention.

Returns:: the string unique ID
Return type:: str

to_xml()

Transform the Intention to XML. See Serialization for more information.

Returns:: XML version of the Intention
Return type:: xml.etree.ElementTree.Element

from_xml(environment, xml_node)

Transform an XML to an Intention. The instance must be created before (with __init__(), passing the xml_node). See Serialization for more information.

Parameters:

environment – The environment where the BaseObject is created.
xml_node (xml.etree.ElementTree.Element) – The XML node that contains the intention data.

Return type:

None

copy_obs(params)

Deep copy the Intention to a new instance.

Parameters:: params (dict) – Not used in this method.

Note : this method copy the reference of the parent. The parent should do the parent copy and assignment

class pymasep.common.Belief(environment, name=None, template=None, xml_node=None, parent=None)

Bases: 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 [Sow84] [CM08]. 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

Parameters:

environment – An Environment instance
name (str) – name of the Belief.
xml_node (Optional[xml.etree.ElementTree.Element]) – XML used to create the object.
template – Template of the Belief. Needed if no xml_node or src_copy
parent – parent object (see objects hierarchy)

beliefs: beliefs data as a conceptual graph

state()

State of the Belief. Always ‘run’

Returns:: The state of Belief
Return type:: str

id_str()

Create an str unique ID of the Belief

Returns:: the string unique ID
Return type:: str

node_id(g, c=None, cr=None)

Get or create the node id of a node in the Belief.

Parameters:

g (networkx.Graph) – The graph to create the node id for
c (Optional[Tuple[str] | Tuple[str, str]]) – the tuple of attribute of the node id to search if the node already exists
cr (Optional[List[Tuple[str, str]]]) – if c is a relation, this parameter represents the concepts linked to the relation

Return type:

int

add(c1, r, c2)

Adding two concepts linked with one relation into the belief

Parameters:

c1 (Tuple[str, str]) – First concept as a tuple (concept, instance of the concept)
r (Tuple[str]) – relation between concepts.
c2 (Tuple[str, str]) – Second concept as a tuple (concept, instance of the concept)

Return type:

None

_create_request(c1, r, c2)

Parameters:: c1 (Tuple[str, str])

query(query)

Query in a Belief

Parameters:: query (networkx.Graph) – Query as a graph. Use * as an instance query.
Return type:: networkx.Graph

Example of a query [Agent:*]-[Tell]-[Sentence:s1] will return a graph containing all agents that tell the sentence s1 in the agent belief.

to_xml()

Transform the Belief to XML. See Serialization for more information.

Returns:: XML version of the BaseObject
Return type:: xml.etree.ElementTree.Element

from_xml(environment, xml_node)

Transform an XML to a Belief. The instance must be created before (with __init__(), passing the xml_node). See Serialization for more information.

Parameters:

environment – The environment where the BaseObject is created.
xml_node (xml.etree.ElementTree.Element) – The XML node that contains the Belief data.