This document shows how to use a Client Side Simulation Engine written in JavaScript.
The engine is based on the classical event approach. To control simulation there are two
primitives:
heap.js = heap implementation
engine.js = the simulation routines that use a heap as the Sequencing Set (SQS).
These files have to be listed by two SCRIPT tags in the HEAD in this order.
The user code can follow or (better) it can be placed into another JavaSript source file(s).
These are the basic ideas:
Events are represented by event notices created by the user and stored in the SQS.
Each event notice has a time of the event and any other user data. The time is set by the
Engine when the event is scheduled. From the user's point of view the SQS is a list of
event notices sorted by the event time in increasing order. In fact it is a heap
(a special balanced binary tree) to allow fast operatins. The Engine repeatedly removes
the first event notice, updates the model time, and activates a user routine that is
given the reference to the event notice. Simulation ends by the empty SQS or by any
user supplied condition. These are the Engine routines:
evnotice() is the event notice constructor. It returns an object with the time property. The user can add any other properties especially to distinguish between various types of events and to store any other model dependent data.
initialize_run(debug) is a routine that clears the SQS (the previous experiment may have finished with nonempty SQS) and sets the model time to zero. It should be called at the beginning of the model initialization. If the parameter is true, simulation starts in the debugging mode. Repeatedly, after some number of debugging messages, the debugging mode can be stopped and the rest of the experiment completed in the fast mode.
schedule(event,tim) schedules the event whose notice is the first parameter at the time given by the second parameter. The SQS contains the reference to the object instance, so the same reference variable can be used to schedule more events, but all event notices have to be created by the user. Scheduling is a fast insertion into a heap (SQS).
cancel(event) cancels a scheduled event. It first searches for the event notice sequentially. If it is not found, the function returns false. This operation can be rather slow if there are many event notices in the SQS, but cancelling events is much less frequent than scheduling.
simulation_run(stats,length) is the simulation experiment as such. This routine should be called after the model initialization that has to schedule at least one event. Other events can be scheduled later by another events. The two parameters just affect the progress reporting. If the first parameter is true, the time will be reported in the status bar of the browser. This is very time consuming, so turn it off for longer experiments. See the check boxes of the demo examples. The second parameter is the expected duration of the experiment. It is shown in the status bar together with time to see the relative progress of the experiment. Nevertheless the experiment can finish earlier or later. This routine ends by reaching an empty SQS or by the user supplied condition - see the routine finish_run().
The above routines are common to all simulation models. Model specific behavior is implemented by two routines that have to be supplied together with code (preferably also a routine) that starts simulation. These are the routines that represent the user part of simulation control:
finish_run() tests whether simulation should be terminated. It is called by the Engine after updating the model time just before activating the next user event. It can just test the time against the experiment duration, it can implement a more complicated terminating condition (for example finish after serving a certain number of customers, etc.) or it can be empty (just return false). In the last case the run will be finished by empty SQS.
eventroutine(event) is activated by the Engine. The routine is given the reference to the event notice that has been removed from the SQS. The rest is the user's responsibility. Typically there will be some properties created by the user used to switch between various types of events. It might be a good idea to keep this routine short and simple and to write routines for various types of events. These routines will then be called from a switch statement testing the event type property of the event notice.
Starting simulation also has to be programmed - see for example the routine TestSimulation() of the demo experiment #1 that is activated by pressing the button Run. This routine should perform these four activities in this order:
- initialization of the Engine by initialize_run(debug),
- model specific initialization,
- starting simulation by simulation_run(stats,length),
- model specific experiment evaluation.
Use of all these routines is shown by demo simulation examples. Use browser to open the source code that contains all user JavaScript code of the simulation models. You can download all files to experiment with JavaScript simulation locally. Note that there are other supporting JavaScript files that implement queues, transparent statistics, some random distributions, and various utilities.