simudyne.core.graph

Interface Graph<S extends simudyne.core.graph.BaseGlobalState>

All Superinterfaces:

JSONValue, java.io.Serializable, Value

All Known Implementing Classes:

BaseGraph

public interface Graph<S extends simudyne.core.graph.BaseGlobalState>
extends JSONValue, Value

An AgentSystem represents a system of interacting agents, which may have links between one another, forming a topology of relations between each other. Agents may be of heterogeneous types (represented as classes implementing Vertex) and contain state (stored as normal fields on the class instance). Agents can then interact with each other via message passing. An agent has no direct access to any other agent within the system, everything must occur via messaging. This choice means that systems can be transparently parallelized and distributed.

This approach to agent systems is heavily inspired by Pregel, a system developed by Google for large scale graph processing. A good introduction that may assist in understanding this approach is available here: https://blog.acolyer.org/2015/05/26/pregel-a-system-for-large-scale-graph-processing/

Method Summary

Modifier and Type	Method and Description
<T extends Vertex<S>> void	addVertices(java.lang.Class<T> vertexType, long vertexCount) Add a number of agents to the system.
<T extends Vertex<S>> void	addVertices(java.lang.Class<T> vertexType, long vertexCount, SerializableBiConsumer<InitContext,T> dataInjector) Add a number of agents to the system.
void	beginStep() reset all the accumulator that haven't been flagged as persistent
static <S extends simudyne.core.graph.BaseGlobalState> Graph<S>	create(S global, ModelContext context, Model model) Create a new AgentSystem instance.
DoubleAccumulator	createDoubleAccumulator(java.lang.String name, java.lang.String displayName) Create a new DoubleAccumulator on the AgentSystem.
DoubleAccumulator	createDoubleAccumulator(java.lang.String name, java.lang.String displayName, double initialValue) Create a new DoubleAccumulator on the AgentSystem.
LongAccumulator	createLongAccumulator(java.lang.String name, java.lang.String displayName) Create a new LongAccumulator on the AgentSystem.
LongAccumulator	createLongAccumulator(java.lang.String name, java.lang.String displayName, long initialValue) Create a new LongAccumulator on the AgentSystem.
DoubleAccumulator	getDoubleAccumulator(java.lang.String name) Get a previously created DoubleAccumulator
java.util.Map<java.lang.String,DoubleAccumulator>	getDoubleAccumulators() Get all previously created DoubleAccumulator as a read only map.
S	getGlobals() Get the value of the global state that can be read globally by agents.
LongAccumulator	getLongAccumulator(java.lang.String name) Get a previously created LongAccumulator
java.util.Map<java.lang.String,LongAccumulator>	getLongAccumulators() Get all previously created LongAccumulator as a read only map.
long	getNextVertexID() Returns the next agent ID that will be assigned via addVertices(java.lang.Class<T>, long).
boolean	hasProcessedMessages()
boolean	isSetup()
void	registerLinkTypes(java.lang.Class<? extends Link>... types) Register link types with the system for serialisation.
void	registerMessageTypes(java.lang.Class<? extends Message>... types) Register message types with the system for serialisation.
void	registerVertexTypes(java.lang.Class<? extends Vertex<S>>... types) Register agent types with the system for serialisation.
<T extends Vertex> VertexSelection<T>	selectVertices(java.lang.Class<T> clazz) Create a selection of agents from the system that can then be summarised.
void	setup() Initialise the agent system.
void	step(Message message) Run a messaging phase on the agents.

Methods inherited from interface simudyne.core.JSONValue

getSchema, getValues, receiveJSON

Methods inherited from interface simudyne.core.channel.Value

emitData, registerSchemas

Method Detail

create

static <S extends simudyne.core.graph.BaseGlobalState> Graph<S> create(S global,
                                                                       ModelContext context,
                                                                       Model model)

Create a new AgentSystem instance. The system can then be configured via , and others. The instance will only be fully initialised and agents created once setup() is called.

Parameters:

global - A global state object that can be read globally by agents. Values can be accessed by agents by Environment.getGlobals()

getGlobals

S getGlobals()

Get the value of the global state that can be read globally by agents.

Returns:

The global state object

registerVertexTypes

void registerVertexTypes(java.lang.Class<? extends Vertex<S>>... types)

Register agent types with the system for serialisation.

Parameters:

types - Agent classes to register. Must implement Agent.

registerMessageTypes

void registerMessageTypes(java.lang.Class<? extends Message>... types)

Register message types with the system for serialisation.

Parameters:

types -

registerLinkTypes

void registerLinkTypes(java.lang.Class<? extends Link>... types)

Register link types with the system for serialisation.

Parameters:

types -

setup

void setup()

Initialise the agent system.

This will choose a suitable backend implementation given the current configuration. Any agents defined via addVertices(Class, long) will then be created in the new instance.

Vertex.setEnvironment(Environment) will not be called when this method is used.

step

void step(Message message)

Run a messaging phase on the agents.

The given message will be broadcast to all agents, and a messaging super-step will be run using the Vertex.step(Environment) handler.

Parameters:

message - Initial message to broadcast to the agents.

addVertices

<T extends Vertex<S>> void addVertices(java.lang.Class<T> vertexType,
                                       long vertexCount)

Add a number of agents to the system.

Parameters:

vertexType -

vertexCount -

addVertices

<T extends Vertex<S>> void addVertices(java.lang.Class<T> vertexType,
                                       long vertexCount,
                                       SerializableBiConsumer<InitContext,T> dataInjector)

Add a number of agents to the system.

Parameters:

vertexType -

vertexCount -

dataInjector -

getNextVertexID

long getNextVertexID()

Returns the next agent ID that will be assigned via addVertices(java.lang.Class<T>, long).

Returns:

agent id

selectVertices

<T extends Vertex> VertexSelection<T> selectVertices(java.lang.Class<T> clazz)

Create a selection of agents from the system that can then be summarised.

Parameters:

clazz - Class of the agents to select.

createLongAccumulator

LongAccumulator createLongAccumulator(java.lang.String name,
                                      java.lang.String displayName)

Create a new LongAccumulator on the AgentSystem.

Parameters:

name - The accumulator name

displayName - The name shown by the console

Returns:

The created accumulator instance

createDoubleAccumulator

DoubleAccumulator createDoubleAccumulator(java.lang.String name,
                                          java.lang.String displayName)

Create a new DoubleAccumulator on the AgentSystem.

Parameters:

name - The accumulator name

displayName - The name shown by the console

Returns:

The created accumulator instance

createLongAccumulator

LongAccumulator createLongAccumulator(java.lang.String name,
                                      java.lang.String displayName,
                                      long initialValue)

Create a new LongAccumulator on the AgentSystem.

Parameters:

name - The accumulator name

displayName - The name shown by the console

initialValue - For populating with a default value at initial time step

Returns:

The created accumulator instance

createDoubleAccumulator

DoubleAccumulator createDoubleAccumulator(java.lang.String name,
                                          java.lang.String displayName,
                                          double initialValue)

Create a new DoubleAccumulator on the AgentSystem.

Parameters:

name - The accumulator name

displayName - The name shown by the console

initialValue - For populating with a default value at initial time step

Returns:

The created accumulator instance

getLongAccumulator

LongAccumulator getLongAccumulator(java.lang.String name)

Get a previously created LongAccumulator

Parameters:

name - The accumulator name

Returns:

The accumulator instance

Throws:

SimudyneSDKException - if no accumulator of this name exists

getDoubleAccumulator

DoubleAccumulator getDoubleAccumulator(java.lang.String name)

Get a previously created DoubleAccumulator

Parameters:

name - The accumulator name

Returns:

The accumulator instance

Throws:

SimudyneSDKException - if no accumulator of this name exists

getDoubleAccumulators

java.util.Map<java.lang.String,DoubleAccumulator> getDoubleAccumulators()

Get all previously created DoubleAccumulator as a read only map. Attempting to add accumulators to this map will not work, and the accumulators will not be available on the AgentSystem.

Returns:

(Read only) Map of accumulator names with their instance as a JSONValue object

getLongAccumulators

java.util.Map<java.lang.String,LongAccumulator> getLongAccumulators()

Get all previously created LongAccumulator as a read only map. Attempting to add accumulators to this map will not work, and the accumulators will not be available on the AgentSystem.

Returns:

(Read only) Map of accumulator names with their instance as a JSONValue object

isSetup

boolean isSetup()

Returns:

if the system has been initialised or not

hasProcessedMessages

boolean hasProcessedMessages()

Returns:

if the graph has ongoing messages

beginStep

void beginStep()

reset all the accumulator that haven't been flagged as persistent