Definition of Agents

Along with layers, agents are the main part of every model. Once the layers have been created, agent types can be specified. For this step, the modeler needs to know what each agent type is going to be, what attributes define it, and what its actions will look like. Once this has been established, the agent type creation can be started.

Agents are the central part of the MARS simulation, which can be viewed as an information system with three phases. First, there is some kind of input data that is integrated in the model, either in layer or agent. The model execution is then performed and generates output data in different formats for analyzation.

A more detailed view on the system emphasises that the input files are described in the Simulation Config. The input data is used to initialize certain properties of the agent, which may afterwards finalize the initialization process with model code. The model execution ticks the agent in every time step. The output is created automatically by the system. Output formats as well as filter criteria need to be defined in the simulation config. To analyze the results, as for now, external tools are required.

Implementation of Agents

Agent types are defined by implementing the IAgent<TLayer> interface. The IAgent<TLayer> interface expects the implementation of the Init(TLayer) and the Tick() method as well as a unique identifier in form of a UUID (Guid) which has to be assigned by the ID property.

The agent and entity contract is structured as follows:

In the model code a using import for the namespace Mars.Components.Agents must be added:

using Mars.Components.Agents;

An agent definition may look like this.

using Mars.Components.Agents;

public class MyAgentType : IAgent<MyLayer> 
{
    [PropertyDescription]
    public double InputProperty { get; set; }
    // is initialized by the system if possible (data available)

    public override void Init(MyLayer layer) 
    {
        // finalize the init process
    }

    public override void Tick() 
    {
        // define your logic here
    }

    public Guid ID { get; set; }
}

Agent types must be registered in the ModelDescription for the considered scenario in order to be able to parameterize them afterwards by an externally given simulation configuration. In MARS agents are created and managed by a layer. The method AddAgent<TAgentType, TLayerType>() expects therefore the connection of the agents to its responsible layer:

// Define the description is not already happened
// var description = new ModelDescription();

description.AddAgent<MyAgentType, MyLayerType>()

Several agents can be managed by one layer.

Definition of Entities

In contrast to agents, entities are pure objects without a Tick() method. However, entities are also identified by a UUID (Guid) ID and can be included in the model to enter other data that is not directly part of the agent parameterization. Entity are versioned and snapshots are persisted just the same as with agents.

An entity can be defined by implementing the IEntity interface or by inheriting from the existing abstract implementation ``AbstractEntity''.

In the model code a using import for the namespace Mars.Components.Agents must be added to the own model file.

using Mars.Components.Agents;

public class MyEntityType : AbstractEntity 
{

}

Entities must be made known in the model, so that they can be initialized by a given simulation configuration. In the entry point Main(), the newly defined entity type must be registered within the ModelDescription.

// Define the description is not already happened
// var description = new ModelDescription();

description.AddEntity<MyEntityType>()

Entities can be loaded into the model by using the IEntityManager component to create instances by a given key attribute name and the corresponding value.

The IEntityManager component can be resolved using the global simulation container ISimulationContainer. When the AbstractLayer implementation is used (as described in layer definition) the IEntityManager is already accessible. Otherwise the components needs to be resolved as follows:

var manager = container.Resolve<IEntityManager>();

An agent can create concrete entities directly and bind them to itself:

var entity = manager.Create<MyAgentType>("keyField", "keyValue");