Environment

This module holds Enviroment-class, an universe where the agents live. Environment holds methods for inter-agent communication and some utilities that are usually needed when implementing creative multi-agent systems.

All implementations should subclass Environment in order to provide basic functionality for the system to operate.

Environments are used by defining their address at the instantation time, and adding agents to their container.

class creamas.core.environment.Environment(base_url, loop, clock, connect_kwargs)

Base environment class inherited from aiomas.Container.

add_artifact(artifact)

Add artifact with given framing to the environment.

Parameters

artifact (object) – Artifact to be added.

add_artifacts(artifacts)

Add artifacts to artifacts.

Parameters

artifacts – list of Artifact objects

clear_connections()

Clear all connections from the agents in the environment.

close(folder=None, as_coro=False)

Close the environment.

Does the following:

1. calls save_info()

2. for each agent: calls close()

3. Shuts down its RPC-service.

create_connections(connection_map)

Create agent connections from a given connection map.

Parameters

connection_map (dict) – A map of connections to be created. Dictionary where keys are agent addresses and values are lists of (addr, attitude)-tuples suitable for add_connections().

Only connections for agents in this environment are made.

create_random_connections(n=5)

Create random connections for all agents in the environment.

Parameters

n (int) – the number of connections for each agent

Existing agent connections that would be created by chance are not doubled in the agent’s connections, but count towards connections created.

destroy(folder=None, as_coro=False)

Close the environment.

Deprecated since version 0.4.0: Use close() instead

get_agents(addr=True, agent_cls=None, include_manager=False)

Get agents in the environment.

Parameters

• addr (bool) – If True, returns only addresses of the agents.

• agent_cls – Optional, if specified returns only agents belonging to that particular class.

• include_manager (bool) – If True includes the environment’s manager, i.e. the agent in the address tcp://environment-host:port/0, to the returned list if the environment has attribute manager. If environment does not have manager, then the parameter does nothing.

Returns

A list of agents in the environment.

Return type

list

Note

Manager agents are excluded from the returned lists of agents by default.

async get_artifacts(agent=None)

Return artifacts published to the environment.

Parameters

agent – If not None, then returns only artifacts created by the agent.

Returns

All artifacts published (by the agent).

Return type

list

If environment has a manager agent, e.g. it is a slave environment in MultiEnvironment, then the manager’s get_artifacts() is called.

get_connections(data=True)

Return connections from all the agents in the environment.

Parameters

data (bool) – If True return also the dictionary associated with each connection

Returns

A list of (addr, connections)-tuples, where connections is a list of addresses agent in addr is connected to. If data parameter is True, then the connections list contains tuples of (nb_addr, data)-pairs , where data is a dictionary.

Return type

dict

Note

Environment’s manager agent is excluded from the returned list.

get_random_agent(agent)

Return random agent that is not the same as the agent given as a parameter.

Parameters

agent (CreativeAgent) – Agent that is not wanted to return

Returns

random, non-connected, agent from the environment

Return type

CreativeAgent

is_ready()

Check if the environment is fully initialized.

The function is mainly used by the multiprocessing environment managers and distributed environments to ensure that the environment has been correctly initialized before any other preparations are done for the environments or the simulation is started.

Override the function in the subclasses which need more time consuming initialization routines. The function should return True when the environment is ready be used in a simulation, or when any cross-environment initialization routines can be run. That is, the environment is inherently in a coherent state, and can execute orders from managers or simulations.

Return type

bool

Returns

This basic implementation returns always True.

save_info(folder, *args, **kwargs)

Save information accumulated during the environments lifetime.

Called from destroy(). Override in subclass.

Parameters

folder (str) – root folder to save information

async trigger_act(*args, addr=None, agent=None, **kwargs)

Trigger agent to act.

If agent is None, then looks the agent by the address.

Raises

ValueError – if both agent and addr are None.

async trigger_all(*args, **kwargs)

Trigger all agents in the environment to act asynchronously.

Returns

A list of agents’ act() return values.

Given arguments and keyword arguments are passed down to each agent’s creamas.core.agent.CreativeAgent.act().

Note

The environment’s manager agent, i.e. if the environment has manager, is excluded from acting.

property age

Age of the environment.

property artifacts

Published artifacts for all agents.

property log_folder

Logging folder for the environment. If set, will create py:class:creamas.logging.ObjectLogger for that folder.

property logger

Logger for the environment.

property name

Name of the environment.