Concept at a glance

JSimpleSim makes the design of simulations simple but is also suited for complex models. There are three components:

  1. Agents – the “acting” entites
  2. Domains – giving structure to the model
  3. The simulator to run the model

Agents

Agents do the actual decisicon making and consist of four elements:

  1. Internal state containing all variables of the agent
  2. Ports to connect and communicate with other agents
  3. Local event queue listing all events of the agent
  4. Strategy to compute output and new events based on external input and the internal state

Ports can connect, so agents can send messages along these connections. So, each agent should have at least one inport (for incoming messages) and one outport (to send messages). Agents are always embedded in a domain.

Structure of a basic agent: state, event queue and messaging ports
Components of a basic agent: state, event queue and messaging ports

Domains

A domain is an important element to structure a model. It can contain agents as well as other subdomains. So, a model always has the form of a composite with a root domain at its top. The following picture shows a very basic model.

Structure of a simple model
Structure of a simple model: interconnected agents embedded in the root domain

So there are domains, agents and their connections. With these three building blocks you are able to create any model structure. In practice, there are hierarchical, intermeshed and grid models. Grid models are also called cellular automata.

Simulator

To run a simulation, a model has to be built first. The model is passed to the simulator that runs the actual simulation with a given time frame. The simulation is event-driven (discrete-event simulation), meaning there are events associated with a time stamp. The simulator has its own global event queue to activate agents at the given time stamp. When an event is due, the simulator calls the agent’s strategy method to do everything necessary.

There are various types of simulators, each suitable for specific use-cases:

  • Time-step simulators work with fixed time differences. The local event queue is ignored and all agents are called at the same time within every step.
  • Sequential simulators use the “time of next event” (tone) returned by the agents to schedule their next invocation.
  • Concurrent simulators act similar to sequential ones but they run agents with the same time stamp concurrently, often speeding up simulation runs with a huge agent population.
  • The dynamic decorator can wrap any simulator to enable model changes after a simulation step.

After this overview, have a look at the basic tutorial to learn how to implement this in code.