The library should be installed following the Installation Guide. Minimum requirements for that are Microsoft Windows 2000 operating system (or later versions) and Microsoft Visual Studio .NET (version 1.0), with .NET Framework.

The library is a Dynamic Link Library (DLL) and should be used with other .NET components. Interoperability with other component interfaces such as Component Object Model (COM) is possible respecting .NET principles and it will depend exclusively on the user’s design decisions.

The user of this library should be either a simulation modeller with .NET programming knowledge or a developer with good knowledge of discrete-event simulation modelling using three-phase approach.

Contents

  • Build a simulation model
  • Use of simulation class
  • Set simulation parameters
  • Retrieve simulation variables
  • Entities and Resources
    • Extending functionality
    • Adding to simulation collection
  • B Events and C Activities
    • Setting specific code
    • Adding events to simulation collection
    • Scheduling B Events
  • Control simulation
    • Running
    • Pausing
    • Resetting
    • Using Step Mode
  • Catching events from simulation
  • Validate simulation model through logging
  • Exceptions thrown during execution run-time

Build a simulation model

Since the library is a component of a simulation model, it requires the latter to be built in first place. A demonstration of such models withis included on the installation (a simple Critical Care Unit Model).

This User Guide does not aim to give instructions on how to design and build a conceptual model that can be simulated using three-phase, but only how the library can be used with a simulation model.

Use of simulation class

A usual set-up after referencing the library in a simulation model is to have a class where the Simulation class is contained. This class could be called Model, for example, and should contain also all other elements of the model. Below there is a snippet of C# code that exemplify this. It defines a class called Model and a Simulation class as a public field (theSimulation) of this class.

class Model
{
   public Simulation theSimulation = new Simulation();
}

Set simulation parameters

Parameters of the simulation should be set easily using the class properties. Below there is an example where some parameters (run duration = 365 days, number of runs = 10 runs, warm-up time = 100 days) are changed and the base unit for simulation time is in hours. The user of the library just has to remember that simulation has to be in an idle
state for the parameters to be changed. Otherwise, the library will throw a ConfigurationCannotBeChanged exception.

theSimulation.Duration = 8760; // eg.: 365 days = 8760 hours
theSimulation.NumberOfRuns = 10;
theSimulation.WarmUpTime = 2400; // eg.: 100 days = 2400 hours

Retrieve simulation variables

Retrieving parameters or simulation variables are also done using class properties. Below there is an example where simulation is running and the user displays (in the console) current variables values.

Console.WriteLine ("Current Simulation Time: {0}", theSimulation.Time);
Console.WriteLine ("Current Run: {0}", theSimulation.CurrentRun);

Entities and Resources

Entities and Resources should be derived from the base classes offered by the library. These are, respectively, EntityBase and ResourceBase.

Classes derived are generally extended in their functionality. Both classes (EntityBase and ResourceBase) have an Utilisation field, where results from the simulation should be stored, but the mechanism to update the Utilisation in the ResourceBase is not provided. Other fields and operations that would collect results from simulation runs should be added to the derived classes.

Extending functionality

Tlasses have some functionality already built in, but usually they will be extended to suit user needs. Below there is an example of an entity that generates arrivals in a simulation. The number of arrivals is a public variable (unsigned integer type) added to the basic entity. A similar implementation should work for the ResourceBase class.

public class ArrivalMachine : EntityBase
{
   public uint NumberOfArrivals;
}

Adding to simulation collection

In the process of setting a simulation model, entities and resources defined are added to the collections held by the Simulation class in the library. These entities and resources will be used when the user is running the simulation. Below it is shown the operation of adding an entity (previously defined) to simulation through the AddEntity method (the AddResource method should be applied if a resource is added).

ArrivalMachine Emergency = new ArrivalMachine();
theSimulation.AddEntity (Emergency);

B Events and C Activities

The user in the simulation model must define B Events and C Activities. Those are not proper classes but delegates, which are methods that have a specific signature. B Events in the user code must be public static void with no arguments, and C Activities must return a Boolean value (if specific C Activity had started or not), with the signature public static bool without arguments.

Setting specific code

Example below shows a B Event (EmergencyArrival) contained in the user’s simulation model.

public static void EmergencyArrival()
{
  // adding arrival to entity number of arrivals
  Emergency.NumberOfArrivals += 1;
  // adding arrival to entity queue
  Emergency.NumberOfPatientsInQueue += 1;
  // scheduling next arrival to occur within 8 hours
  theSimulation.Schedule (ref Emergency, EmergencyArrival, 8);
}

Example below shows a C Activity (BeginOccupyBed) that would happen in the C Phase for the same model.

public static bool BeginOccupyBed()
{
  //defines a variable to flag if C Activitiy has started
  bool activityStarted = false;
  //loops until there's no patients in queue
  while (Emergency.NumberOfPatientsInQueue > 0)
  {
    //check if there are beds available
    if (CCUBeds.Count > 0)
    {
       //decrement the number of beds available
       CCUBeds.Count -=1;
       //decrement the number of patients in queue
       Emergency.NumberOfPatientsInQueue -= 1;
      //schedule a B Event (EndOccupyBed) to occur within 24 hours
      theSimulation.Schedule (ref Emergency, EndOccupyBed, 24);
      //set flag to true (activity has started)
      activityStarted = true;
    }
  }
  //return value of flag variable
  return (activityStarted);
}

Adding events to simulation collection

Adding B Events and C Activities to the simulation collection is very similar to adding Resources and Entities. The difference here is that B Events and C Activities are not declared as classes but as delegates. The methods created by the user should then be passed to the Simulation class in the library. Below there is an example of previously defined B Event (EmergencyArrival) and a C Activity (BeginOccupyBed) being added to the Simulation object.

theSimulation.AddBEvent (Model.EmergencyArrival);
theSimulation.AddCActivity (Model.BeginOccupyBed);

Scheduling B Events

B Events are defined by the user of the library and scheduled to occur with a particular entity at some time in the future through a method in the Simulation class. This method (Schedule) takes three arguments: a reference to an object derived from the EntityBase class, a reference to the method that contains code of the B Event, and the portion of time (added to current simulation time) that B Event will occur.

The Schedule operation will usually appears inside the B Events and C Activities code. Example below shows how the Schedule operation was executed.

//schedule a B Event (EndOccupyBed) to occur within 24 hours
theSimulation.Schedule (Emergency, EndOccupyBed, 24);

Control simulation

After configuring the simulation parameters and objects used by the model, the user is able to control the simulation through Simulation class methods and properties.

Running

The operation of running a simulation model is done by the Run method. In the approach used by the library, this method will cycle through the three-phases (A, B and C) until user has paused (or reset) the simulation or the defined number of runs had elapsed. Below it is shown how to execute the Run command.

theModel.theSimulation.Run(); // runs the simulation model

Pausing

Pausing the simulation model is done by the Pause method. There is nothing special about this command, but just a change of the simulation state, from running to paused.
Below it is shown how to execute this command.

theModel.theSimulation.Pause(); // pauses the simulation model

Resetting

Resetting the simulation is the operation of putting back simulation variables to its initial values and simulation state becomes idle. This operation is performed by a method named Reset. Below it is shown how this can be implemented.

theModel.theSimulation.Reset(); // resets the simulation model

Using Step Mode

The Step Mode is used to pause model automatically at each completion of the three phases when simulation is running. The Run command should be executed again if user wants to resume the simulation. Step Mode is switched on or off using the Step property to either true or false, respectively. Below it is shown how to switch on the Step Mode.

theModel.theSimulation.Step = true; // switching ON the Step Mode in the model

Catching events from simulation

When simulation is running, the library sends events that can be captured by the simulation model. The user can then write code that will be executed when those events occur. Seven library events are sent: OnStartSimulation, OnStartRun, OnStartWarmUpTime, OnCompleteThreePhases, OnFinishWarmUpTime, OnFinishRun, and OnFinishSimulation. The user should write his own code to be
executed when one of these events happen in the simulation. Belot there is an example of a routine that is performed each time the simulation completes the three phases. This routine will display current time and current run to the standard console.

class Model
{
    //default constructor
    public Model()
    {
        //assigning OnCompleteThreePhases event/handler from simulation to a method in the model class
       theSimulation.OnCompleteThreePhases 
          += new Simulation.CompleteThreePhasesHandler (TimeHasChanged);
    }
    //method that is invoked whenever the OnCompleteThreePhases event occur
    public void TimeHasChanged(object theSimulationObject, Simulation.SimulationInfoEventArgs si)
    {
        //SimulationInfoEventArgs is a class that contains two attributes: current time, current run
       Console.WriteLine ("Current Simulation Time: {0} - Current Run: {1}", si.time, si.currentRun);
    }
}

Validate simulation model through logging

The library has a Log Mode that can be switched on/off if the property Log in the Simulation class is either true or false, respectively. The default value is false, so the actions are not logged to a text file. This file (when the Log Mode is active) is created each time the simulation completes the cycle of states, from idle to finished. The file is saved on current project directory and it is named with current real date and time.

Messages are logged from almost all operations in the library. For example, if the user changes a simulation parameter, the log will tell which parameter was changed, the previous and current value. In the same way, all the schedule operations are written to the log file.

The simulation modeller or the user can validate his/her model through these log files, in a sense that the library is performing actions in desired arrangement. It is very likely that the user will have another log file to the simulation model and he/she can analyse both in order to correct and adjust model inner work. Below it is shown how to switch on the Log Mode (by default, Log Mode is off).

theModel.theSimulation.Log = true; // switching ON the Log Mode in the model

Exceptions thrown during execution run-time

The simulation library throws three specific types of exception if things do not go quite well during run-time. These are:

  • ValueOutOfRangeException – If user tries to change a value of a simulation parameter, and this happens to be out of allowed range, the library throws this exception.
  • ConfigurationCannotBeChangedException – If user tries to add simulation objects or change parameters when the simulation is not in idle state, an exception of this type is thrown.
  • ThreePhaseInfiniteLoopException – If user specific code for B Events and C Activities are not correct, and simulation time is not being advanced in the A Phase, the library throws this kind of exception.

Last edited Mar 25, 2013 at 9:43 PM by axcosta, version 8

Comments

No comments yet.