Model Interface

The Model is the main abstraction in the Simudyne SDK. It incorporates all the elements required to build and run a simulation from setup to teardown.

The Model Interface below outlines three stages. Let's describe them as well as the model flow in more detail.

Model Lifecycle

The lifecycle of a model is organized through four different functions:

• the initialization of the model through Model#init
• the setup of the simulation through Model#setup
• the core logic of your simulation called through Model#step
• the tear-down of the simulation through Model#done

Except for Model#step, each of these function is only called once during the entire simulation. Model#step will be called as many time as you would have requested. Each step will run after the previous one has been completed, creating a discrete series of events.

Models can easily be controlled through the console, the GUI provided by the SimudyneSDK. However other method are also available:

• using the REST API (documentation is available here)
• using the CLI (documentation is available here)
• using the ModelRunner API (documentation is available here)

init() - initializing your model

The Model interface has an init phase, which gets executed when the model is initialised, this is where you should register your Links, Agents and create your Accumulators, if your Model is an AgentBasedModel. To execute code during model initialisation, the Model#init() method should be overridden with specific initialisation operations.

The Model#init() method can also be used to setup model variables.

Nothing happens in this init phase by default but you can trigger a specific init by overriding the Model#init() method to define initialisation operations here.

When creating Agent Based Models, the init phase is where accumulators are created, and agents and links are registered. For more information on this see Model Initialisation.

setup() - defining pre-simulation calculations and operations

The Model interface has optional setup phase. In the Model Interface diagram this occurs when the console calls setup() on the model.

Nothing happens in this setup phase by default but you can trigger a specific setup by overriding the Model#setup() method and defining calculations and operations here.

Specifying a setup (Java)

public class MyModel implements Model {
  @Variable double myVariable;

  @Override
  public void setup() {
    myVariable = ModelContext.get(this).getPRNG().uniform(-1, 1).sample();
  }

}

step() - defining computations and operations at each step

One iteration in your simulation involves a set of steps. At this stage, you need to specify calculations in your model to form a step. These are then run in order to complete one iteration of your simulation.

Defining a step (Java)

public class MyModel implements Model {
  @Variable double myVariable = 1;

  @Override
  public void step() {
    myVariable *= 1.1;
  }
}

done() - specifying a tear-down

On completion of your simulation, you may want to save results as a file or to perform specific tear-down operations. This can be done by defining done() in your model.

If you wish to in another section tell your model to complete (say if a variable condition is reached) you can call the finish() function. This will start the process of the teardown and call the done function.

This will also call any enabled output channel to post their final results and in conjunction with a ModelRunner a user can make usage of the awaitOutput function before either calling additional Java code or System.exit(0);

Introducing the Agent Based flavour

To create Agent Based Models, extend AgentBasedModel.

Accessing the Context and the Configuration

From the AgentBasedModel, you can get access to the ModelContext using the getContext() method. This ModelContext contains the PRNG of your model, as well as the Tick value, the Configuration, and more. The Configuration contains the set of values for the parameters of the model. These specific settings within your simulation are important especially when it comes to distributing your model.

More on Model Config

AgentBasedModels (Java)

public class MyModel extends AgentBasedModel<GlobalState> {
  @Variable int myVariable;

  @Override
  public void init() {
    registerAgentTypes(AgentA.class, AgentB.class);
    registerLinkTypes(LinkA.class, LinkB.class);
    createDoubleAccumulator("accA");
    createDoubleAccumulator("accB");
  }


  @Override
  public void setup() {
    SeededRandom ran = getContext().getPRNG(); // accessing the prng of the model through the Context
    myVariable = ran.uniform(-1,1).sample();
  }

  @Override
  public void step() {
    myVariable += getContext().getTick(); // accessing the current Tick of the Model
  }
}

Several setup operations are required for AgentBasedModel at the first stage of building the simulation model. These have to be defined at setup().

More on Agent Based Models