JASI SimKernel Framework User Guide

JASI - Java Event-Based Simulation Framework. This library provides an architecture based on a simulation kernel and elementary classes for simulation elements and event to build event-based simulation systems in Java.

Copyright (C) 2007 Thomas Rieth

Contact: Georg-Spillner-Weg 4, D-82223 Eichenau, Germany

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Abstract: This framework provides a simulation kernel for event-based simulations. The architecture of this simulation framework was designed in a way to allow any user to configure it for any application by simply extending basic functionalities, which are represented by interfaces and abstract super-classes or adapter classes.


  1. Introduction
    1. Simulation Framework
    2. Data Structures
    3. Condition Tables
    4. Simulation Models
    5. Organization of Simulation Framework
    6. The Simulation Kernel
  2. A Simple Simulation Application
    1. Elements
    2. Events
    3. Simulation
  3. Utilities
    1. Code Generators
    2. Accessing Collections
  4. An Air Traffic Simulation

1 Introduction

1.1 Simulation Framework

A simulation system consists of a simulation framework and a sometimes hierarchical structure of simulation models. A simulation framework contains a simulation kernel that manages the state of a simulation in a way that is very similar to a database, i.e., the framework with its kernel is responsible for changing, reading or writing the state of the simulation. The chronological ordered simulation states are called the archive of the simulation.

Use Cases

Figure: The use cases of the simulation framework.

A framework for event-based simulations should provide the following services:


Figure: The context of the simulation framework.

1.2 Data Structures

The jasi.sim.basic package provides an abstract simulation kernel and utility classes for basic simulation management.


Figure: The basic classes of the simulation framework.

The state of a simulation is generally represented by of a set of identifiable data containers, the simulation objects, whereby the simulation framework is responsible to provide unique identifiers for each individual simulation object. The simulation time introduces discrimination between persistent simulation elements and transient simulation events.


Figure: jasi.sim.basic.value - Some basic simulation values.

Persistent data structures, like simulation elements, exist for a certain period of time and their content usually will change over time. They experience state changes.


Figure: jasi.sim.basic.element - The classes for basic persistent simulation elements of the simulation framework.

Transient data structures, like simulation events, will be active only for a certain point in time and their content usually will not change over time. Their main purpose is to induce state changes of the simulation, therefore called event-based simulation.


Figure: jasi.sim.basic.event - The classes for basic transient simulation events of the simulation framework.

An individual identifier references all simulation objects for archiving purposes of the simulation.

Figure: - The identifiers of simulation objects.

1.3 Condition Tables

Condition tables provide data structures as a mapping of hierarchical keys to values, that can be accessed by the simulation process and stored in the simulation's archive. Whenever it is the case, that a key is missing during retrieving a value, condition tables possess the possibility to provide default values at each hierarchical key level.


Figure: jasi.sim.basic.table - Condition tables.

This simple table test provides the following result:

1.4 Simulation Models

Simulation models - here called simulation event listeners, too - manage the state changes of the simulation, by creation and handling of simulation events. They define interfaces, which are used by simulation models themselves. These interfaces are implemented by simulation elements, so that simulation models can change their state. This provides a component-based architecture for the simulation models and a behavior for simulation elements.

1.5 Organisation of the Simulation Framework


Figure: Some important packages of the simulation framework for basic simulation management.

1.6 The Simulation Kernel


Figure: jasi.sim.basic.control - Classes for interacting with and controling the simulation

A simulation kernel application is created by extension of the sim.basic.SimKernel class and implementing a run-method like this:

Time end = ...;
Time current = startSimulation();
try {
    while (isRunning()) {
        if (current.isGE(end)) {
            break; // The requested end time has been reached
        current = continueSimulation(current, end);
} finally {

Time Advance

Figure: Sequence for the continueSimulation method.

The simulation thread can be started and finished in the following way:

try {
} catch (InterruptedException e) {
} finally {

2 A Simple Simulation Application

The architecture of this framework avoids code changes or adaptations inside the simulation framework itself. The decission, which have to be made while developping simulation systems, like concerning the control of the simulation process and storage of the simulation's state, is enabled by interfaces and some standard utility classes. This framework allows simulation developers to choose and develop their own preferred formats and controls.

This simulation framework provides the following abilities:


Figure: The connection between the simulation framework and a special simulation features.

The packages of an example for a simulation: jasi.sim.user: A simple simulation application, jasi.sim.user.model.activity: A model for activities, jasi.sim.user.model.move: A movement model, jasi.sim.user.model.sense: A sensor and sensing model, jasi.sim.user.archive: A simulation archive for archive output in binary format and XML format, jasi.simple.model: A simple example of a simulation model, jasi.simple.defi: Definition of simple simulation elements.

2.1 Events

Simulation events are transient simulation objects, whose life cycle is strongly controlled by the simulation time. Their state usually does not change after creation. They contain an event time, when they are scheduled for execution by a simulation model. The simulation calendar represents a priority queue for events, and it controls the advancement of the simulation time. After pushing an event to the calendar the events are sorted according their scheduling time and a priority. Events are popped from the calendar when simulation times advanced to the event's scheduling time. After its execution by a simulation model an event usually ceases to exist.

Event Extension

Figure: A simple simulation model.,,,

Event States

Figure: The state changes of a basic simulation event.

Repeating events, which extend jasi.sim.basic.event.AbstractRepeatingEvent, can be popped several times from the simulation calendar, different to standard simulation events. Extending classes have to override the repeat method, which is called whenever the repeating event is pushed back to the calendar again.

Repeating Event States

Figure: The state changes of a repeating simulation event.

Simulation models are responsible for the dynamic evolution of simulation elements. During execution of a simulation event a simulation model might induce state changes of simulation elements. While the action of simulation models is invoked by use of events, they may create future events themselves. Models have to provide interfaces that can be implemented by simulation elements, so that models will be able to change their state.

Event Handling

Figure: The handling of events by the simulation process.

2.2 Elements

Simulation elements are persistent simulation objects, which might be deleted (destroyed) at some later time. The state of a simulation element is represented by its attributes. Although an element's state changes over time, its existence does not implicitly depend on the simulation time.

In addition to its state an element usually possesses a behavior. Implementing interfaces, where simulation models can act on, to change the element's state, represents the behavior. The main responsibility of these interfaces is the mapping of a simulation element's behavior to state changes as well as element's states to different kinds of behavior. In this framework the access to the element's state and the interfaces for their behavior are separated by use of class inheritance.


Figure: jasi.sim.basic.element.relation - The classes to represent relations of simulation elements.

Element Extension

Figure: Adaptation of simulation elements to models.


Basic abstract class for all simulation models.

An example for a simple model.


Interface for all simulation events.


Basic abstract class for all simulation events.

An example of an event that is handled by the simple model.

The interface for simulation elements, whose state is changed by the simple model.


Interface for all simulation elements.


Basic abstract class for all simulation elements.

The container of the state of a simple simulation element.

The interface to the behavior of the simple simulation elements, which provides an adapter for the objects of the simple model to simulation elements.

The container of the state of a simulation element with a record-type attribute.

The interface to the behavior of a simulation elements with a record-type attribute.

Element Access

Figure: The access to the properties of simulation elements.

Read Element Property

Figure: Reading the properties of simulation elements.

Write Element Property

Figure: Writing the properties of simulation elements.

2.3 Simulation

The jasi.sim.basic.AbstractSimulation controls the following actions of the simulation:


Figure: A simple simulation kernel.,, jasi.sim.user.Timer


Figure: The simulation process.

The simulation framework provides the jasi.sim.basic.control.SimController interface to control the progress of the simulation. This interception allows the configuration of the access to the simulation state individually for each simulation system. Further this intercept can used to connect this simulation to external systems, e.g.,


Figure: Connecting to external systems and user interfaces.

This simple simulation test provides the following result:

The results are based on the previously created archive which has been provided at input.

3 Utilities

3.1 Code Generators

(Not implemented yet)

The structure of the state of simulation elements possesses a generality that can be used to generate the class body of handler-type classes automatically. Whereas the complexity of the simulation elements' behavior only allows generating the elementary method heads required by the implemented interfaces.


Figure:Code generation of simulation elements.

3.2 Accessing collections


Figure: jasi.sim.user.util - Accessing collections with the visitor pattern.

4 An Air Traffic Simulation


Figure: jasi.airtraffic.model - A model for an air traffic simulation.

This package contains the model, i.e. the event listener, the definitions of the interfaces for the various functionalities, like the airplane, the airport, and a flight, and the implementations of the events that are used for the air traffic simulation.


Figure: jasi.airtraffic.defi - The data structures for an air traffic simulation.

This package contains the element beans that are used in the air traffic simulation.


Figure: jasi.airtraffic.kernel - The simulation kernel of the airtraffic application.

This package controls the simulation. It contains the kernel and the archive for the air traffic simulation.