Web-Based Simulation with OESjs

As discussed above, the simplest model for the service desk problem with maximum queue length statistics (available in the Sim4edu library as ServiceDesk-0) has only one global variable: queueLength, a non-negative integer, and a global function for computing the random service duration, but no object type.

In addition to an information model, which captures the system's state structure, we also need to make a process model that captures the dynamics of the service desk system. The dynamics of a system consists of events triggering state changes and follow-up events. A process model can be expressed with the help of event rules, which define what happens when an event (of a certain type) occurs, or, more specifically, which state changes and which follow-up events are caused by an event of that type.

Event rules can be expressed with the help of pseudo-code or in process diagrams, or in a simulation or programming language. The following table shows the two event rules defining the transition logic of a service desk system, expressed in pseudo-code.

INCREMENT queueLength
IF queueLength = 1 
THEN
  sTime = serviceDuration() 
  SCHEDULE CustomerDeparture @ (t + sTime)

DECREMENT queueLength
IF queueLength > 0
THEN 
  sTime = serviceDuration() 
  SCHEDULE CustomerDeparture @ (t + sTime)

In our extended model (ServiceDesk-1) we represent the state variable queueLength as an attribute of an object type ServiceDesk. This results in a model with three classes, the object class ServiceDesk with an attribute queueLength, and the event classes CustomerArrival and CustomerDeparture, both with a reference property serviceDesk for referencing the service desk at which an event occurs. When we also want to compute the service utilization statistics, we need to add an attribute serviceTime to the CustomerDeparture class for being able to update the service utilization statistics when a customer departs.

Both event types, CustomerArrival and CustomerDeparture, now have a many-to-one association with the object type ServiceDesk. This expresses the fact that any such event occurs at a particular service desk, which participates in the event. This association is implemented in the form of a reference property serviceDesk in each of the two event types, as shown in the following diagram:

In addition to an information model, we need to make a process model, which captures the dynamics of the service desk system consisting of arrival and departure events triggering state changes and follow-up events.

The following table shows the two event rules, which now account for the fact that both types of events occur at a particular service desk that is referenced by the event expression parameter sd.

INCREMENT sd.queueLength
IF sd.queueLength = 1 
THEN
  sTime = ServiceDesk.serviceDuration() 
  SCHEDULE CustomerDeparture( sTime, sd) @(t + sTime)

DECREMENT sd.queueLength
IF sd.queueLength > 0
THEN 
  sTime = ServiceDesk.serviceDuration() 
  SCHEDULE CustomerDeparture( sTime, sd) @(t + sTime)

In the next section, we discuss how to implement this simple model of a service desk system with the OESjs simulation framework.

When a simulation model is based on continuous time, it is possible to control the time granularity (the time delay until the next moment) in one of two ways:

The model parameter nextMomentDeltaT is used by the simulator for scheduling next events with a minimal delay.

An important issue in simulation is the question how the simulation time is advanced by the simulator. The OES paradigm supports fixed-increment time progression and next-event time progression, and their combination.

An OESjs model with pure fixed-increment time progression defines an OnEachTimeStep procedure and a timeIncrement parameter, but no event types. Such a model can be used

A simulation model with pure next-event time progression, representing a classical DES model, defines event types and event rules, but no timeIncrement parameter.

It is also possible to combine both time progression mechanisms, e.g., in a "hybrid" model that supports both discrete and continuous state changes, or in a social science model based on "ticks" and explicit events.

Real-time simulation means to run an observable simulation model in such a way that the speed of its state changes is close to the speed of the state changes in the simulated real-world system. This is only possible if the simulator is able to run the simulation at least as fast as the real-world system is running. If this is the case, the running simulator can be slowed down to real-time speed.

Real-time simulation requires fixed-increment time progression by setting the model parameter timeIncrement. In the case of a model with a timeUnit and real-time simulation turned on (by setting the scenario parameter realtimeFactor to 1), the simulator delays each simulation step such that its real duration is equal to its simulation time, which is timeIncrement [timeUnit].

In the case of a model without a timeUnit (that is, with abstract time), the simulator cannot automatically run in real-time, but the scenario parameter stepDuration (for specifying the real duration of a simulation step) can be set to a suitable value for making the simulation observable in real-time.

In the simple model of a service desk discussed in the previous section, we define one (global) model variable, queueLength, one model function, serviceDuration(), and two event types, as shown in the following class diagram:

Figure 1. The simple service desk model with queueLength as a global variable.

Notice that this model does not define any object type, which implies that the system state does not consist of any object, but only of one state variable, queueLength. The model can be coded with OESjs in the following way:

// (global) model variable
sim.model.v.queueLength = {
  range:"NonNegativeInteger", 
  label:"Queue length", 
  shortLabel:"qLen", 
  initialValue: 0
};
// global function
sim.model.f.serviceDuration = function () {
  var r = rand.uniformInt( 0, 99);
  if ( r < 30) return 2;         // probability 0.30
  else if ( r < 80) return 3;    // probability 0.50
  else return 4;                 // probability 0.20
};

When a model variable is defined like sim.model.v.queueLength = ..., its value can be accessed at simulation runtime with the expression sim.v.queueLength. A variable is shown in the user interface for model variables, whenever a label is defined for it. A variable's value is shown in the simulation log, whenever a shortLabel is defined for it. By default, the size of the variable's input field is 7. It can be changed by setting the property inputFieldSize in the variable definition.

You can run this simulation model and download its code from the sim4edu.com website.

Object types are defined in the form of classes. More precisely, they are defined as instances of the meta-class cLASS. Consider the object type ServiceDesk defined in the following model:

Figure 2. The service desk model with queueLength as an attribute.

The object type ServiceDesk is defined with an attribute queueLength:

var ServiceDesk = new cLASS({
  Name: "ServiceDesk",
  supertypeName: "oBJECT",
  properties: {
    "queueLength": { range: "NonNegativeInteger", 
        label: "Queue length", shortLabel: "qlen"}
  }
});

Notice that, in OESjs, object types are defined as subtypes of the pre-defined class oBJECT, from which they inherit an integer-valued id attribute and an optional name attribute. A property may have both a label and a shortLabel. The label is used for user interface fields, while the shortLabel is used in the simulation log, which only logs those objects and properties that do have a shortLabel.

The discrete random variable for modeling random service durations, which samples integers between 2 and 4 from the empirical probability distribution Emp{2:0.3, 3:0.5, 4:0.2}, is implemented as a class-level function serviceDuration in the ServiceDesk class:

ServiceDesk.serviceDuration = function () {
  var r = rand.uniformInt( 0, 99);
  if ( r < 30) return 2;         // probability 0.30
  else if ( r < 80) return 3;    // probability 0.50
  else return 4;                 // probability 0.20
};

You can run this simulation model and download its code from the sim4edu.com website.

We distinguish between two kinds of events:

Here is an example of an exogenous event type definition:

var CustomerArrival = new cLASS({
  Name: "CustomerArrival",
  supertypeName: "eVENT",
  properties: {
    "serviceDesk": {range: "ServiceDesk"}
  },
  methods: {
    "onEvent": function () {
      ...
    }
  }
});

Notice that the event type includes a reference property serviceDesk, which is used for referencing the service desk object at which an event occurs. Each event type needs to define an onEvent method, which implements the event rule for events of the defined type. Event rules are discussed below.

Exogenous events occur periodically. They are therefore defined with a recurrence function, which provides the time in-between two events (often in the form of a random variable). The recurrence function is defined as a class-level method:

CustomerArrival.recurrence = function () {
  return rand.uniformInt( 1, 6); 
};

Notice that the recurrence method of CustomerArrival is coded with the library method rand.uniformInt, which allows sampling discrete uniform probability distribution functions (the rand library provides several other PDF sampling methods as explained below). The OESjs simulator automatically creates the next CustomerArrival event by invoking the recurrence function for setting its ocurrenceTime and by copying all participant references (such as the serviceDesk reference). Only if an exogenous event type has additional properties, a createNextEvent method has to be defined for assigning all properties and returning the next event of that type. Whenever the simulator finds such a method, it will be invoked for creating corresponding exogenous events.

In our example model of a service desk system, any customer departure event is caused, either by a customer arrival event or by a preceding service start event.

var CustomerDeparture = new cLASS({
  Name: "CustomerDeparture",
  supertypeName: "eVENT",
  properties: {
    "serviceTime": {range: "NonNegativeInteger"},
    "serviceDesk": {range: "ServiceDesk"}
  },
  methods: {
    "onEvent": function () {
      ...
  }
});

An event rule for an event type defines what happens when an event of that type occurs, by specifying the caused state changes and follow-up events. In OESjs, an event rule for an event type is defined as a method onEvent of the class that implements the event type. This method, which is also called event routine, returns a set of events (more precisely, a set of JS objects representing events).

The following event rule method is defined in the CustomerArrival class.

// CustomerArrival event rule
"onEvent": function () {
  var srvTm=0, changes = [], events = [];
  this.serviceDesk.queueLength++;
  sim.stat.arrivedCustomers++;
  // if the service desk is not busy
  if (this.serviceDesk.queueLength === 1) {
    srvTm = ServiceDesk.serviceDuration();
    events.push( new CustomerDeparture({
      occTime: this.occTime + srvTm,
      serviceTime: srvTm,
      serviceDesk: this.serviceDesk
    }));
  }
  return events;
}

The context of this event rule method is the event that triggers the rule, that is, the variable this references a JS object that represents the triggering event. Thus, the expression this.serviceDesk refers to the service desk object associated with the current customer arrival event, and the statement this.serviceDesk.queueLength++ increments the queueLength attribute of this service desk object (as an immediate state change).

The following event rule method is defined in the CustomerDeparture class.

// CustomerDeparture event rule
"onEvent": function () {
  var changes = [], events = [], srvTm=0;
  // remove customer from queue
  this.serviceDesk.queueLength--;
  // if there are still customers waiting
  if (this.serviceDesk.queueLength > 0) {
    // start next service and schedule its end/departure
    srvTm = ServiceDesk.serviceDuration();
    events.push( new CustomerDeparture({
      occTime: this.occTime + srvTm,
      serviceTime: srvTm,
      serviceDesk: this.serviceDesk
    }));
  }
  sim.stat.departedCustomers++;
  sim.stat.totalServiceTime += this.serviceTime;
  return events;
}

An OES model may imply the possibility of several events occurring at the same time. Consequently, a simulator (like OESjs) must be able to process simultaneous events. In particular, simulation models based on discrete time may create simulation states where two or more events occur at the same time, but the model's logic requires them to be processed in a certain order. Defining priorities for events of a certain type helps to control the processing order of simultaneous events.

Consider an example model based on discrete time with three exogenous event types StartOfMonth, EachDay and EndOfMonth, where the recurrence of StartOfMonth and EndOfMonth is 21, and the recurrence of EachDay is 1. In this example we want to control that on simulation time 1 + i * 21 both a StartOfMonth and an EachDay event occur simultaneously, but StartOfMonth should be processed before EachDay, and on simulation time 21 + i * 21 both an EndOfMonth and an EachDay event occur simultaneously, but EndOfMonth should be processed after EachDay. This can be achieved by defining a high priority, say 2, to StartOfMonth, a middle priority, say 1, to StartOfMonth, and a low priority, say 0, to EndOfMonth.

Event priorities are defined as class-level properties of event classes in the event type definition file. Thus, we would define in StartOfMonth.js:

StartOfMonth.priority = 2;

and in EachDay.js:

EachDay.priority = 1;

and finally in EndOfMonth.js:

EndOfMonth.priority = 0;

Random variables are implemented as methods that sample specific probability distribution functions (PDFs). Simulation frameworks typically provide a library of predefined parametrized PDF sampling methods, which can be used with one or several (possibly seeded) streams of pseudo-random numbers.

The OESjs simulator provides the following predefined parametrized PDF sampling methods:

The OESjs library rand.js supports both unseeded and seeded random number streams. By default, its PDF sampling methods are based on an unseeded stream, using Marsaglia’s high-performance random number generator xorshift that is built into the Math.random function of modern JavaScript engines.

A seeded random number stream, based on the slower Mersenne Twister algorithm, can be obtained by setting the scenario parameter sim.scenario.randomSeed to a positive integer value.

Additional streams can be defined and used in the following way:

var stream1 = new Random( 1234);
var stream2 = new Random( 6789);
var service1Duration = stream1.exponential( 0.5);
var service2Duration = stream2.exponential( 1.5);

Warning: Avoid using JavaScript's built-in Math.random in simulation code. Always use rand.uniform, or one of the other probability distribution functions from the rand library described above, for generating random numbers.

A few simulation parameters are pre-defined as attributes of the simulation scenario. The most important ones are:

Both the model and the scenario can be documented and described by providing various metadata in a separate metadata.js file: a name, a title and a shortDescription, as well as meta data like creator, a created date, a (last) modified date and a copyright license, like so

sim.model.name = "...";
sim.model.title = "...";
sim.model.shortDescription = "...";
sim.model.license = "CC BY-NC";

It is recommended to use an attribution share-alike Creative Commons license by specifying its abbreviated name "CC BY-SA" (or "CC BY-NC" for non-commercial use).

The mandatory model attribute systemNarrative has to be used for providing a brief description of the system under investigation, as opposed to the design-specific model description provided by shortDescription:

sim.model.systemNarrative = "...";

Defining an initial state means:

A scenario must include an initial state definition, which consists of a set of initial object definitions and a set of initial event definitions. An initial state object is defined as an entry in the map initialState.objects such that the object's id value is the map entry's key, and the map entry's value is a set of property-value slots, including a slot for the special attribute typeName defining the object's type, as shown in the following example:

sim.scenario.initialState.objects = {
  "1": {typeName:"ServiceDesk", name:"serviceDesk1", queueLength:0}
};

Notice that object IDs are positive integers, but when used as keys in a map, they are converted to strings.

An initial event is defined as an element of the array list initialState.events in the form of a set of property-value slots, including a slot for the special attribute typeName defining the event's type, as shown in the following example:

sim.scenario.initialState.events = [
  {typeName: "CustomerArrival", occTime:1, serviceDesk:1}
];

When initial events (or objects) are parametrized with model variables, they can be defined by moving the sim.scenario.initialState.events definition to the sim.scenario.setupInitialState function because this function is executed after the model variables are assigned.

For being able to observe a simulation run, some form of visualization has to be defined. OESjs supports both the visualization of spatial models and of non-spatial models. In a visualization of a non-spatial model, such as the ServiceDesk-1 model, all object views have to be explicitly positioned in an observation canvas. Rich two-dimensional visualizations can be obtained by using the web technology of Scalable Vector Graphics (SVG) in the definition of the observation user interface (UI).

In the case of our ServiceDesk-1 model, we may, for instance, visualize the service desk using either an image or simply a fixed-size rectangle, and its queue in the form of a growing and shrinking bar.

For defining an observation UI with SVG-based visualization, the following settings have to be made:

sim.scenario.observationUI.type = "SVG";
sim.scenario.observationUI.canvas.width = 600;
sim.scenario.observationUI.canvas.height = 300;

Then we first define the fixed elements of the visualization, giving each one a name (here: "desk") and defining an SVG shape with attributes and a CSS style:

sim.scenario.observationUI.fixedElements = {
  "desk": {
    shapeName: "rect",
    shapeAttributes: { x: 350, y: 200, width: 50, height: 30},
    style: "fill:brown; stroke-width:0"
  }
};

For learning more about SVG shapes and their attributes, see the book chapter Basic Shapes & Paths by Joni Trythall. For learning more about CSS styling of SVG elements, see Styling And Animating SVGs With CSS by Sara Soueidan.

The main issue in visualization is to map the state variables of interest to suitable visual parameters such as colors, shape size, etc. For instance, we may want to map the queueLength attribute to the width of a rectangle, as in the following object view definition:

sim.scenario.observationUI.objectViews = {
  "serviceDesk1": [  // a view of the queue
    { shapeName: "rect",  // a rectangle defined by 
      shapeAttributes: {  // left-upper corner (x,y) as well as width and height
        x: function (sd) {return Math.max( 0, 330 - sd.queueLength * 20);},
        width: function (sd) {return Math.min( 300, sd.queueLength * 20);},
        y: 150, height: 80
      },
      style:"fill:yellow; stroke-width:0"
    },
    { shapeName: "text",
      shapeAttributes: {x: 325, y: 250,
          textContent: function (sd) {return sd.queueLength;}},
      style:"font-size:14px; text-anchor:middle"
    }
  ]
};

The OESjs simulator can generate a simulation log, which allows to inspect the evolving states of a simulation run. Inspecting the simulation log can help to understand the dynamics of a model, or it can be used for finding logical flaws in it.

The contents of the simulation log can be controlled by defining short labels for those objects and object properties as well as event types that we want to see in the log, using the shortLabel attribute. For instance, in the case of the service desk model, defining the short labels "sd1" for the service desk object, "qLen" for the queueLength property, "Arr" for the CustomerArrival event type and "Dep" for the CustomerDeparture event type leads to the following simulation log:

In Section 2.3.3, we have shown how to create initial objects for the initial state of a simulation scenario using the map sim.scenario.initialState.objects. Whenever the initial state has to be populated with a larger set of objects, we can define a sim.scenario.setupInitialState procedure, as in the following example where we create 100 ServiceDesk objects, each with an associated CustomerArrival event:

sim.scenario.setupInitialState = function () {
  var i=1;
  for (i=1; i <= 100; i++) {
    sim.addObject( new ServiceDesk({
      id: i,
      typeName: "ServiceDesk",
      name: "sd" + i,
      queueLength: 0
    }));
    sim.scheduleEvent( new CustomerArrival( {
      occTime: 1,
      serviceDesk: i
    }));
  }
}

The objects defined in the initial state, or created during a simulation run, can be accessed either by their ID number or by their name, if they have a name. For instance, the object {typeName:"ServiceDesk", id: 1, name:"serviceDesk1", queueLength: 0} defined above, has the ID number 1 and the name "serviceDesk1". It can be retrieved from the simulator map sim.objects in the following way:

var object1 = sim.objects["1"];

It can also be retrieved by name from the simulator map sim.namedObjects in the following way:

var object1 = sim.namedObjects["serviceDesk1"];

For looping over all simulation objects, we can loop over the simulator map sim.objects in the following way:

Object.keys( sim.objects).forEach( function (objIdStr) {
  var obj = sim.objects[objIdStr];
  ...  // do something with obj
});

We can loop over all simulation objects of a specific type, say ServiceDesk, in the following way:

Object.keys( cLASS["ServiceDesk"].instances).forEach( function (objIdStr) {
  var obj = cLASS["ServiceDesk"].instances[objIdStr];
  ...  // do something with obj
});

If a simulation has to deal with a large number of objects, using a for loop may be faster than a forEach loop.

There are use cases which require to construct a history of the changing values of a certain attribute for a specific object and evaluate or simply display this history. For example, we may define a history for the attribute queueLength of service desks using the historySize parameter:

var ServiceDesk = new cLASS({
  Name: "ServiceDesk",
  supertypeName: "oBJECT",
  properties: {
    "queueLength": { range: "NonNegativeInteger", historySize: 7,
        label: "Queue length", shortLabel: "qlen"}
  }
});

In such a case, the OESjs simulator automatically constructs a history buffer of the specified size, which can, for instance, be converted to a string with the expression

sim.namedObjects["serviceDesk1"].history.queueLength.toString()

A history buffer is a ring buffer, having a limited size and an add operation for adding new items to the buffer as in:

sim.namedObjects["serviceDesk1"].history.queueLength.add( this.queueLength);

Notice that the oldest item may get lost when the (fixed-size) buffer is already full and a new item is added.