Graph agents

1. What is Graph Agent library

Graph Agent Library is the tool that Amalgama Platform provides to support models that simulate agents living in some type of network, or a graph. This type of setting is typical for many commercial simulation models.

Graph is a network where the graph agents live. This network consists of nodes and arcs that connect nodes.

A node corresponds to a point in the 2D-space, i.e. a point with X and Y coordinates. An arc corresponds to a polyline connecting the respective nodes. Every arc has a direction. Bidirectional arcs are represented with two oppositely directed arcs.

The basic functionality of Graph Agent library includes:

  • Jumping the agents to any position at a node or an arc of some graph

  • Sending the agents to some specified position in the graph along the shortest or some custom path

  • Handling events of agents entering a node, an arc or reaching its destination

  • Handling collisions of agents with other agents

  • Providing access to agents' movement trajectories and paths

2. Creating a graph environment for agents

Below is an example of creating a simple graph environment with 3 nodes and 2 arcs:

// Create the environment
var environment = new GraphEnvironment<AgentGraphNodeImpl, AgentGraphArcImpl, GraphAgent<?, ?>>();

// Create three nodes and add them to the environment
var nodeA = environment.addNode(new AgentGraphNodeImpl(new Point(0, -100)));
var nodeB = environment.addNode(new AgentGraphNodeImpl(new Point(150, 0)));
var nodeC = environment.addNode(new AgentGraphNodeImpl(new Point(50, -200)));

// Create a polyline between the points of nodeA and nodeB
// Note how the first point of the polyline equals the point of nodeA,
// and its last point equals to the point of nodeB
var polylineAB = new Polyline(new Point(0, -100), new Point(100, 0), new Point(150, 0));

// Create a bi-directional arc between nodeA and nodeB
environment.addArc(nodeA.getValue(), nodeB.getValue(), new AgentGraphArcImpl(polylineAB), new AgentGraphArcImpl(polylineAB.getReversed()));

// Create a monodirectional arc between nodeA and nodeC
var polylineAC = new Polyline(new Point(0, -100), new Point(50, -200));
environment.addArc(nodeA.getValue(), nodeC.getValue(), new AgentGraphArcImpl(polylineAC));

In the example above, there is a bidirectional arc between nodes A and B, and a monodirectional arc from node A to node C.

Note how AgentGraphNodeImpl and AgentGraphArcImpl classes are used to represent nodes and arcs referencing 2D-space points and polylines. These classes implement AgentGraphNode and AgentGraphArc interfaces, respectively. Any classes implementing these interfaces can be contained in the nodes and arcs of agent graphs.

3. Creating an agent

Now that we have created a graph environment, let us create a graph agent and place it into the environment. Before we create our first agent, we need to create an instance of Engine class that will be used to simulate this agent. The code below demonstrates how to do it:

// Create a simulation engine instance
Engine engine = new Engine();

// Create a new instance of graph agent
var agent = new GraphAgent<AgentGraphNodeImpl, AgentGraphArcImpl>(engine);

// Place the agent into the graph environment
agent.setGraphEnvironment(environment);

// Jump the agent into the nodeA of the environment
agent.jumpTo(nodeA);

Note that after creation, the agent must be both added to its environment and jumped to some position inside a graph.

4. Making the agent move

The agent that we created is now located in the node A of our graph environment. This can be checked, for example, by calling its getCurrentNode:

// The code below will print true
System.out.println(agent.getCurrentNode() == nodeA);

The code below can be used to send it to node B with a velocity of 1 distance unit per time unit:

agent.moveTo(nodeB, 1);
Graph agent example