Skip to content

Latest commit

 

History

History
317 lines (249 loc) · 11.6 KB

eismassim.md

File metadata and controls

317 lines (249 loc) · 11.6 KB
Raw

EISMASSim Documentation

EISMASSim is based on the Environment Interface Standard (EIS), a proposed standard for agent-environment interaction.

It maps the communication between agents and the MASSim server, (i.e. sending and receiving JSON messages), to Java method calls. Also, it automatically establishes and maintains connections to a specified MASSim server.

In other words, EISMASSim is a proxy environment on the client side which handles communication with the MASSim server completely by itself.

Using EISMASSim

Include the library

EISMASSim is packaged as a jar file eismassim-X.Y-jar-with-dependencies.jar which already includes the EIS package. The easiest way would be to include the jar with dependencies in your classpath. If you want to manage dependencies yourself, use eismassim-X.Y.jar. You can get the required EIS version (0.5.0) from the eishub.

Create and start the Environment Interface instance

EnvironmentInterfaceStandard ei = new EnvironmentInterface();

The environment interface needs a configuration file to know how many entities it has to create. In the above case, an eismassimconfig.json file is expected in the working directory. Alternatively, the path to a configuration file can be given to the constructor.

try {
  ei.start();
} catch (ManagementException e) {
  // TODO handle the exception
}

This sets the state of the interface to RUNNING.

Register your agents

Each agent you want to connect needs to be registered with the interface.

try {
  ei.registerAgent(agentName);
} catch (AgentException e) {
  // TODO handle the exception
}

Associate agents with entities

Entities are the corporeal parts used for perceiving and acting, i.e. the vehicles in the simulation. The available entities are specified in the eismassimconfig.json file which needs to match the MASSim scenario requirements.

try {
  ei.associateEntity(agentName, entityName);
} catch (RelationException e) {
  // TODO handle the exception
}

This part automatically triggers authentication of the associated entity with the MASSim server.

Perceive the environment

Percepts can either be polled or received as notifications.

try {
  eis.getAllPercepts(agentName);
} catch (PerceiveException e) {
  // TODO handle the exception
}

This would retrieve all percepts for the agent named agentName. The return value is a map, since the agent could be associated with more than one entity.

Execute actions

Action action = new Action(...);
try {
  ei.performAction(agentName, action);
} catch (ActException e) {
  // TODO handle the exception
}

To execute an action, the name of the agent executing the action and the action itself need to be passed. All entities associated with the agent will perform this action (if possible).

Configuration

The configuration of EISMASSim is now realized with JSON files, matching the configuration of the MASSim server.

Configuration example:

{
  "scenario": "assemble2022",
  "host": "localhost",
  "port": 12300,
  "scheduling": true,
  "timeout": 4000,
  "notifications": false,
  "exceptions": false,
  "entities": [
    {
      "name": "connectionA28",
      "username": "agentA28",
      "password": "1",
      "print-iilang": false,
      "print-json": true
    },
    ...
  ],
  "multi-entities": [
    {
      "name-prefix": "connectionA",
      "username-prefix": "agentA",
      "password": "1",
      "print-iilang": false,
      "print-json": false,
      "count": 28,
      "start-index": 0
    },

    "status-entity": {
      "name": "statusConnection"
    },
    ...
  ]
}

In the above example, one entity and one set of entities are configured at the same time. Usually, only one of these options needs to be chosen.

The main entries are:

  • scenario: the name of the MAPC scenario to handle - it isn't used but may identify the origin of the config later :)
  • host: address of a MASSim server
  • port: port the MASSim server is listening on
  • scheduling: if true:
    • calls to performAction will block until an ID becomes available (or time out)
    • calls to getPercepts will block until new percepts are available (or time out)
  • timeout: the timeout to use in combination with scheduling while waiting for performAction or getPercepts
  • notifications: if enabled, percepts will be delivered as notifications; this is detailed in the description of EIS

Previous options (not available anymore):

  • only-once: Due to changes in EIS, this is more or less default now. The PerceptUpdate contains a list of added and removed percepts each.
  • queued: There is only one set of current percepts ever.

Further, there is an object for each entity in the entities array, containing

  • name: the name of the entity
  • username: the name to authenticate with
  • password: the password to authenticate with (both as configured in the MASSim server)
  • print-iilang: whether to print the IILang version of received percepts
  • print-json: whether to print JSON messages sent and received by the interface

To simplify the creation of many similar entities, you can now specify a multi-entity array. Each object in this array contains

  • name-prefix: the prefix of the entity names
  • username_prefix: the prefix for the usernames
  • password: the password for all entities
  • print-iilang: see above
  • print-json: see above
  • count: the number of entities to create from this data (if count is -1 or missing, EISMASSim will try to retrieve the number of entities from the MASSim server)
  • start-index: the first index to append to the prefixes

If you do not specify the count for the multi-entities block (or set it to -1), EISMASSim will query the running MASSim server for the maximum number of entities required for any simulation.

You can also specify a status-entity to be created. This status-entity queries the current server status and gets the following percepts:

  • teams(l)
    • l : List of Identifiers - names of the teams that are currently playing
  • teamSizes(l)
    • l : List of Numerals - number of agents per simulation (e.g. [10,20,30] for three simulations with 10, 20 and 30 agents per team)
  • currentSim(n)
    • n : Numeral - index of the simulation that is currently running. -1 if the match hasn't started yet
  • currentTeamSize(n)
    • n : Numeral - number of agents required per team in the current simulation
  • error
    • Indicates that no StatusResponse could be retrieved from the server.

Example usage

EISMASSim is exemplarily used in the javaagents package.

IILang

Actions and percepts in EISMASSim use the Interface Intermediate Language (IILang) as provided by EIS. The IILang defines the following concepts:

  • DataContainer: consists of a name and a number of Parameters
    • Action: used for acting
    • Percept: used to perceive changes in the environment
  • Parameter: argument to DataContainers
    • Identifier: contains a string value
    • Numeral: contains any number value
    • TruthValue: contains a boolean value
    • ParameterList: strangely, a list of parameters
    • Function: has the same structure as a DataContainer, but can be used as a Parameter

Thus, any IILang DataContainer forms a tree structure that can also be represented with Prolog-like syntax. For example, car(red, 2007, [ac, radio], wheels(4)) could be a Percept with the name car, an Identifier (parameter) red, a Numeral 2007, a ParameterList containing 2 Identifiers and a Function named wheels containing a final Numeral.

MAPC 2022 scenario

Actions

The actions for the current scenario can be reviewed in scenario.md. An IILang action takes a name and a number of parameters. Just pass the required parameters in the same order as described in scenario.md.

Example:

Action a = new Action("move", new Identifier("n"));

Percepts

The following paragraphs describe how the JSON messages described in protocol.md and scenario.md are translated into IILang percepts.

[XYZ, ...] denotes a ParameterList of arbitrary length

SIM-START percepts

The following percepts might be included in a SIM-START message:

  • name(s)
    • s : Identifier - name of the agent
  • team(s)
    • s : Identifier - name of the agent's team
  • teamSize(n)
    • n : Numeral - number of agents in the agent's team in the current round
  • steps(n)
    • n : Numeral - number of steps
  • role(name, vision, [action1, action2, ...], [speed1, speed2, ...], clearChance, clearMaxDistance)
    • name : Identifier
    • vision : Numeral
    • action[N] : Identifier
    • speed[N] : Numeral
    • clearChance : Numeral (0-1)
    • clearMaxDistance : Numeral

REQUEST-ACTION percepts

The following percepts might be included in a REQUEST-ACTION message. See also scenario.md for the original JSON format and explanations these percepts are derived from.

  • actionID(id)
    • id : Numeral - current action-id to reply with
  • timestamp(time)
    • time : Numeral - server time the message was created at
  • deadline(time)
    • time : Numeral - when the server expects the action
  • step(number)
    • number : Numeral - the current step
  • lastAction(type)
    • type : Identifier - name of the last executed action
  • lastActionResult(result)
    • result : Identifier - result of the last executed action
  • lastActionParams([p1, ...])
    • p1 : Identifier - first parameter of the last executed action
  • score(n)
    • n : Numeral - the team's current score
  • thing(x, y, type, details)
    • x/y : Numeral - relative position of a thing
    • type : Identifier - the type of the thing
    • details : Identifier - possibly more information about the thing (see scenario doc)
  • task(name, deadline, reward, [req(x,y,type),...])
    • name : Identifier
    • deadline : Numeral - the last step the task can be completed
    • reward : Numeral
    • req : Function - a required block for the task
      • x/y : Numeral - the relative position of the required block
      • type : the type of the block
  • attached(x, y)
    • x/y : Numeral - relative position of a thing that is attached to some entity
  • energy(n)
    • n : Numeral - the agent's energy level
  • deactivated(b)
    • b : Identifier - true if the agent is deactivated (else false)
  • role(name)
    • name : Identifier - the agent's current role
  • roleZone(x, y)
    • x : Numeral
    • y : Numeral
  • goalZone(x, y)
    • x : Numeral
    • y : Numeral
  • violation(id)
    • id : Identifier - ID of a norm the agent has violated
  • norm(id, start, end, [requirement(type, name, quantity, details), ...], fine)
    • id : Identifier - ID of the norm
    • start : Numeral - first step the norm holds
    • end : Numeral - last step the norm holds
      • requirement:
        • type : the subject of the norm
        • name : the precise name the subject refers to, e.g., the role constructor
        • quantity : the maximum quantity that can be carried/adopted
        • details : possibly additional details
    • fine : Numeral - the energy cost of violating the norm (per step)
  • surveyed("agent", name, role, energy)
    • name : Identifier
    • role : Identifier
    • energy : Numeral
  • surveyed("dispenser"/"goal"/"role", distance)
    • distance : Numeral
  • hit(x, y)
    • x : Numeral
    • y : Numeral

SIM-END percepts

The following percepts might be included in a SIM-END message:

  • ranking(r)
    • r : Numeral - the final ranking of the agent's team
  • score(s)
    • s : Numeral - the final score of the agent's team