Skip to content

Home

Jump to bottom
paatrickd edited this page Mar 23, 2021 · 35 revisions

C# Simulation Library (CSSL)

Discrete Event Simulation (DES)

The C# simulation library (CSSL) is a class library for discrete event simulation (abbreviated DES). Discrete event simulation is a technique to simulate the behavior and performance of systems. DES models a system as a series separate, discrete, events. This makes DES a highly efficient simulation technique when compared to alternatives such as, for example, discrete time interval simulation.

Overview

CSSL is a C# class library for .NET Core 3.1. On a high level, CSSL comprises the following components.

The starting point for any simulation is always the "Simulation" component, which by default contains instances of the "Experiment", "Executive", "Model" and "Observers" classes. Separately, CSSL contains the settings class and utilities namespace. The functionality of each of these elements is described in the respective sections. Furthermore, a walk-through example is provided to illustrate the capabilities of CSSL.

Jump to:

Experiment

In the Experiment class the user can design a simulation experiment by specifying the following properties:

  • LengthOfExperimentWallClock Sets a limit on the wall clock time for the complete experiment
  • LengthOfReplication Sets a limit on the simulated time for a single replication, includes LengthOfWarmUp
  • LengthOfReplicationWallClock Sets a limit on the wall clock time for a single replication, includes LengthOfWarmUp
  • LengthOfWarmUp Specifies the warm-up time for a simulation replication
  • NumberOfReplications Specifies the number of replications

Executive

Within DES the ability to schedule and execute events is a necessity. In CSSL the executive is responsible for the execution of events. The executive holds a data structure that implements the ICalendar interface that stores all scheduled events. In DES, this is sometimes also called the future event set (FES). By default, this is calendar based on a List<CSSLEvent>. The user can implement a custom calendar and provide an instance to the executive via the Executive.SetCalendar(ICalendar) method.

Model

The Model instance is a key component within CSSL since it contains the actual simulation model. It serves as a container for all instances derived from the ModelElementBase class.

ModelElementBase

Classes derived from ModelElementBase can be used to describe elements of the simulation model, e.g. machines, buffers, operators, dispatchers, ... To build and run a CSSL simulation model, the user must define its own classes derived from ModelElementBase to describe the modeling situation. This base class contains the following basic features:

  • A unique Id which is automatically generated
  • A required Name of the element
  • A reference to the parent ModelElementBase, Parent
  • The properties GetTime to retrieve the current simulation time, GetPreviousEventTime to retrieve the simulation time at which the previous event was executed and GetWallClockTime to retrieve the current wall clock time
  • It implements an observer design pattern which enables a class derived from ModelElementObserverBase to subscribe to the element, via the Subscribe(ModelElementObserverBase) method, and upon calling NotifyObservers(ModelElementBase) method all observer subscribed to the element receive notification from the element
  • OnExperimentStart(), OnReplicationStart(), OnReplicationEnd(), OnExperimentEnd() are empty methods in which standard recurring actions can be provided that every model element automatically executes prior to an experiment, prior to a replication, after a replication and after an experiment respectively

SchedulingElementBase : ModelElementBase

The SchedulingElementBase class is derived from ModelElementBase. It contains one additional feature, namely, access to the Executive class via the method ScheduleEvent(double,CSSLEventAction). The first parameter is a time and the second argument is a delegate of type CSSLEventAction. This method demands the Executive to create an instance of CSSLEvent and schedule it at the specified time. Additionally, this class contains a method ScheduleEndEvent(double), via which the user can schedule an event that ends the current replication at specified time.

EventGeneratorBase : SchedulingElementBase : ModelElementBase

The EventGeneratorBase class is derived from SchedulingElementBase. In addition, its constructor requires a class that is derived from Distribution, that specifies the inter event time. It also requires implementation of the HandleGeneration method. By default, the DoBeforeReplication() method ensures that the generation of events starts immediately at the start of a replication.

CSSLQueue : ModelElementBase and CSSLQueueObject

The CSSLQueue<T> class is derived from ModelElementBase and is intended to hold objects of type T that must wait within the simulation. The generic type T must be derived from the CSSLQueueObject<T> class, where T is the derived class itself. The synergy between CSSLQueue<T> and CSSLQueueObject<T> ensures that the property MyQueue in the CSSLQueueObject<T> is always set correctly. CSSLQueue<T> provides the following methods:

  • EnqueueLast(T) adds an item to the end of the queue.
  • DequeueAt(int) retrieves and removes an item T from a specified position in the queue
  • DequeueFirst() retrieves and removes the first item T from the queue

Furthermore, it contains a property Length which returns the current length of the queue. By default, a CSSLQueue<T> is automatically emptied at the start of a replication.

CSSLEvent

In CSSL an instance of the CSSLEvent class represents an event. Most importantly, it contains an action CSSLEventAction and the time at which this action must be executed. The CSSLEventAction is a delegate with the signature public void(CSSLEvent).

Observers

As stated above, ModelElementBase implements an observer design pattern which enables classes derived from ModelElementObserverBase to subscribe to the element. This is done via the Subscribe(ModelElementObserverBase) method.

Similar to ModelElementBase, the ModelElementObserverBase class has has the following basic features:

  • A unique Id which is automatically generated
  • A unique Name which is automatically generated
  • The properties GetTime to retrieve the current simulation time, GetPreviousEventTime to retrieve the simulation time at which the previous event was executed and GetWallClockTime to retrieve the current wall clock time
  • When Settings.LogObservers is set to true is contains an instance of StreamWriter called Writer that can be used within the class to write output to a .txt file named after the instance Name property
  • OnExperimentStart(), OnReplicationStart(), OnReplicationEnd(), OnExperimentEnd() are empty methods in which standard recurring actions can be provided that every observer automatically executes prior to an experiment, prior to a replication, after a replication and after an experiment respectively
  • Additionally, it contains the methods OnWarmUp(ModelElementBase), OnInitialized(ModelElementBase) and OnUpdate(ModelElementBase)

When the NotifyObservers(ModelElementBase) method is called from within a class derived from ModelElementBase, dependent on the current state of the simulation, a method is called in the class derived from ModelElementObserverBase, as illustrated in the image below.

For convenience, the CSSL.Observer namespace contains the Variable<T> class. This class takes track of a variable's current value, previous value, time of last update and time of previous update.

Settings

In the Settings class the following properties can be specified:

  • FixSeed ensures the same seed for all ExtendedRandom instances used in classes derived from Distribution
  • Verbose enables verbose output to the console
  • WriteOutput creates directories for output and initializes Writer and ExperimentWriter in all observers
  • NotifyObservers enables the notification of observers

Make sure that these settings are set before the model is build.

Utilities

The Utilities namespace contains:

  • Numerous classes derived from Distribution
  • The helper classes Statistic and WeightedStatistic for the collection of data and calculation of basic statistics, which implement the Collect(double) and Collect(double,double) methods respectively

Output

The output files are automatically saved in the specified directory under the name of the experiment, which both have to be specified in the constructor of the simulation. If the directory does not exist yet, the directory is created. If the directory already exists, a new directory with a _counter behind the original directory is created. Within this directory each replication has a separate folder.

For example, if one constructs following simulation

Simulation sim = new Simulation("SomeSimulation", @"C:\CSSL"),

and runs the simulation for 3 separate times, with each 3 replications, the directories shown below are created.

See also Settings.

Clone this wiki locally