Skip to content
This repository was archived by the owner on Apr 4, 2020. It is now read-only.

eismassim.md

Latest commit

 

History

History
343 lines (286 loc) · 13.5 KB

eismassim.md

File metadata and controls

343 lines (286 loc) · 13.5 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 XML-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": "city2017",
  "host": "localhost",
  "port": 12300,
  "scheduling": true,
  "timeout": 40000,
  "times": false,
  "notifications": false,
  "queued": false,
  "entities": [
    {
      "name": "connectionA1",
      "username": "agentA1",
      "password": "1",
      "iilang": false,
      "xml": true}
  ]
}

In the above example, only one entity is configured for the sake of readability. (Usually, way more entities are listed there.)

The main entries are:

  • scenario: the name of the MAPC scenario to handle (determines how XML messages are translated)
  • host: address of a MASSim server
  • port: port the MASSim server is listening on
  • scheduling: if true, an action can only be sent if a valid action-id is available; calls to performAction will also block until such an ID becomes available; it is recommended to not disable this
  • timeout: the timeout to use in combination with scheduling while waiting for performAction
  • queued: if enabled, getAllPercepts will only yield one collection of percepts for each call (i.e. one for all percepts from a SIM-START message, one for all percepts from a REQUEST-ACTION message, etc.) in the same order as they were received from the MASSim server
  • times: if enabled, percepts will be annotated with the time they were generated by the server
  • notifications: if enabled, percepts will be delivered as notifications; this is detailed in the description of EIS

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)
  • iilang: whether to print the IILang version of received percepts
  • xml: whether to print XML messages sent and received by the interface

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 2018 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("goto", new Identifier("shop1"));

Percepts

The following paragraphs describe how the XML 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:

  • id(simId)
    • simId : Identifier - name of the simulation
  • map(mapName)
    • mapName : Identifier - name of the current map
  • seedCapital(sc)
    • sc : Numeral - seed capital of any team in the simulation
  • steps(stepNumber)
    • stepNumber : Numeral - number of steps the simulation will take
  • team(name)
    • name : Identifier - name of the agent's team
  • role(name, baseSpeed, maxSpeed, baseLoad, maxLoad, baseSkill, maxSkill, baseVision, maxVision, baseBattery, maxBattery)
    • represents the agent's role
    • name : Identifier - name of the role
    • base/maxSpeed : Numeral - base/max speed of the role
    • base/maxLoad : Numeral - base/max carrying capacity of the role
    • base/maxSkill : Numeral - base/max skill of the role
    • base/maxVision : Numeral - base/max vision of the role
    • base/maxBattery : Numeral - base/maximum battery charge of the role
  • item(name, volume, roles([role1, ...]), parts([item1, ...]))
    • represents an item type in the simulation
    • name : Identifier - name of the item
    • volume : Numeral - the item's volume
    • roles : Function - all roles required to assemble the item
      • role1 : Identifier - one of the roles required for assembly
    • parts : Function - all items required for assembly
      • item1 : Identifier - one item required for assembly
  • upgrade(name, cost, step)
    • represents an upgrade agents can buy
    • name : Identifier - the name of the upgrade, i.e. the attribute to upgrade
    • cost : Numeral - how much the upgrade costs
  • wellType(name, cost, efficiency, initialIntegrity, integrity)
    • a type of well that can be built
    • name : Identifier - the name of the type
    • cost : Numeral - how much it costs to build a well of this type
    • efficiency : Numeral - how much points the well generates per step
    • initialIntegrity : Numeral - the well's integrity after the first build action
    • integrity : Numeral - the well's maximum integrity
  • {min,max,center}{Lat,Lon}(coordinate)
    • coordinate: Numeral - one of the 4 map bounds or the "center"
  • proximity(p)
  • cellSize(c)

REQUEST-ACTION percepts

The following percepts might be included in a REQUEST-ACTION message. Most of them should be self-explanatory.

  • 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 - timepoint at which the action must be available
  • step(number)
    • number : Numeral - the current step
  • charge(ch)
    • ch : Numeral - agent's current battery charge
  • load(cap)
    • cap : Numeral - agent's currently used capacity
  • speed(s)
    • s : Numeral - agent's current speed
  • maxLoad(cap)
    • cap : Numeral - agent's current carrying capacity
  • maxBattery(b)
    • b : Numeral - agent's current battery capacity
  • skill(s)
    • s : Numeral - agent's current skill value
  • vision(v)
    • v : Numeral - agent's current visibility range
  • lat(d)
    • d : Numeral - latitude of the agent's location
  • lon(d)
    • d : Numeral - longitude of the agent's location
  • routeLength(ln)
    • ln : Numeral - length of the agent's current route
  • massium(m)
    • m : Numeral - the agent's team's current massium
  • facility(f)
    • f : Identifier - name of the agent's current facility
  • lastAction(type)
    • type : Identifier - name of the last executed action
  • lastActionParams([param1, ...])
    • param1 : Identifier - first parameter of the last executed action (list might be empty)
  • lastActionResult(result)
    • result : Identifier - result of the last executed action
  • hasItem(name, qty)
    • name : Identifier - name of a carried item
    • qty : Numeral - carried quantity
  • route([wp(index, lat, lon), ...])
    • represents the agent's current route
    • wp : Function - a waypoint in the route
      • index : Numeral - index of the waypoint
      • lat : Numeral - latitude of the waypoint
      • lon : Numeral - longitude of the waypoint
  • entity(name, team, lat, lon, role)
    • name : Identifier - name of an entity/agent in the simulation
    • team : Identifier - name of that entity's team
    • lat : Numeral - latitude
    • lon : Numeral - longitude
    • role : Identifier - that entity's role
  • chargingStation(name, lat, lon, rate)
    • name : Identifier
    • lat : Numeral
    • lon : Numeral
    • rate : Numeral - the station's charging rate
  • dump(name, lat, lon)
    • name : Identifier
    • lat : Numeral
    • lon : Numeral
  • shop(name, lat, lon)
    • name : Identifier - the shop's name
    • lat : Numeral
    • lon : Numeral
  • storage(name, lat, lon, cap, used, [item(name1, stored1, delivered1), ...])
    • name : Identifier - the storage's name
    • lat : Numeral
    • lon : Numeral
    • cap : Numeral - the storage's total capacity
    • used : Numeral - the used capacity of the storage
    • item : Function - an item available in this storage
      • name1 : Identifier - that item's name
      • stored1 : Numeral - quantity stored by the agent's team
      • delivered1 : Numeral - quantity delivered by or for the agent's team (see Storage section)
  • workshop(name, lat, lon)
    • name : Identifier
    • lat : Numeral
    • lon : Numeral
  • resourceNode(name, lat, lon, resource)
    • name : Identifier
    • lat : Numeral
    • lon : Numeral
    • resource : Identifier - name of the item that can be gathered at the node
  • well(name, lat, lon, type, team, integrity)
    • name : Identifier
    • lat : Numeral
    • lon : Numeral
    • type : Identifier - the well's type
    • team : Identifier - the team that built the well
    • integrity : Numeral - the well's current integrity
  • job(id, storage, reward, start, end, [required(name1, qty1), ...])
    • represents a non-auction job (excluding those posted by the agent's team)
    • id : Identifier - the job's ID
    • storage : Identifier - name of the storage associated with this job
    • reward : Numeral
    • start : Numeral
    • end : Numeral
    • required : Function - an item required to complete the job
      • name1 : Identififer - name of that item
      • qty1 : Numeral - required quantity
  • auction(id, storage, reward, start, end, fine, bid, time, [required(name1, qty1), ...])
    • same parameters as job plus:
      • fine : Numeral - amount to pay if the auction is assigned but not completed
      • bid : Numeral - the current lowest bid; might update each step during auction time
      • time : Numeral - number of steps the auction phase will take
  • mission(id, storage, reward, start, end, fine, bid, time, [required(name1, qty1), ...])
    • same parameters as auction
      • reward and bid are the same

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