SimJava
v2.0

eduni.simjava
Class Sim_system

java.lang.Object
  |
  +--eduni.simjava.Sim_system

public class Sim_system
extends java.lang.Object

The SimJava simulation kernel.

This class is responsible for managing all aspects of the simulation. Instantiated entities are added to Sim_system which is responsible for synchronising their behaviour. Time progresses on the basis of event scheduling times. These events are held in two queues, instances of Evqueue, the future queue and the deferred queue. All the runtime functionality available to entities is managed by Sim_system.

In the previous versions of SimJava, users would use Sim_system only to initialise the simulation, add the entities, link their ports, and finally run the simulation. In version 2.0 Sim_system makes a lot more functionality available to the modeller.

Three new aspects of Sim_system are the definition of a transient condition, a termination condition, and the selection of an output analysis method to apply. All these are managed internally by Sim_system so the user is not required to include relevant code in the simulation's entities. To set the transient condition for the simulation the user uses a set_transient_condition method. The simulation's termination condition is set by using a set_termination_condition method. Finally, an output analysis method is selected with one of the set_output_analysis methods.

Available transient conditions are:

Available termination conditions are:

Entities may use the running method to check whether the simulation has completed.

Finally, the available output analysis methods are:

Since version 2.0 of SimJava, Sim_system also allows the modeller greater control over the seeding of the random number generators. The simulation's generators can be created in such a way to allow Sim_system to automatically seed them, ensuring well spaced sample sequences for the generators. The original seed to be used as well as the seed spacing desired can be set with the set_seed_sequence method. If this method is not used, the default seed of 4851 is used to produce seeds spaced by 100000 samples. If independent replications are used as an output analysis method and reseeding of the generators is desired in each subsequent replication, the generators need to be added to their entities. This is accomplished with the entities' add_generator method. Otherwise the previous replication's last seed is used as the next one's initial seed.

Sim_system also provides control over the simulation's output. The trace file (sim_trace) can be managed with more detail. The set_trace_detail method can be used to specify whether or not to add the default trace , trace generated by the entities, or trace for specific event types. In this last case, the event tags of interest can be supplied to Sim_system with a track_event method. The level of entity trace included in the trace file can be managed with the set_trace_level method. Finally, tracing can be switched off alltogether with the set_auto_trace method. The default is not to produce a trace file.

Another major aspect of the simulation's output is the simulation's report. The report is automatically produced by Sim_system and includes information on the simulation depending on the specified conditions and parameters. The detail level of the report file (sim_report) can be modified with the set_report_detail method. The default information included are the total obtained measurements obtained as well as general information about the simulation run. In the case of no output analysis method having been used, the steady state sample measurements are presented in place of the total measurements. If an output analysis method has been used, set_report_detail can be used to include the sample measurements for each replication (for independent replications), or the sample measurements for each batch (for batch means). Finally, the original seeds used in the random number generators of the simulation can also be included in the report. Since version 2.0, the simulation's report is also available to animated simulations.

A generate_graphs method may also be used to generate graphs for the simulation. Graphs are generated for all detailed measures and present the progress of each measure's sample average over the progress of the simulation. Several additional information may also be displayed for each graph such as the mean confidence interval, the transient period, the batches etc. The simulation will produce a ".sjg" file containing the simulation data. This file may then be opened with the SimJava Graph Viewer, a graph viewing utility for SimJava simulations.

More information on the definition of simulations and the use of Sim_system can be found at the SimJava Tutorial.

See Also:
Sim_entity, Anim_applet

Field Summary
static int BATCH_MEANS
          A constant representing the output analysis method of batch means.
static int EVENTS_COMPLETED
          A constant representing a condition based on event completions.
static int IND_REPLICATIONS
          A constant representing the output analysis method of independent replications.
static int INTERVAL_ACCURACY
          A constant representing a termination condition based on a confidence interval's accuray.
static int MIN_MAX
          A constant representing the minimum-maximum method for transient period identification.
static int NONE
          A constant representing no condition.
static Sim_any_p SIM_ANY
          A standard predicate that matches any event.
static Sim_none_p SIM_NONE
          A standard predicate that does not match any events.
static int TIME_ELAPSED
          A constant representing a condition based on a time period.
 
Constructor Summary
Sim_system()
           
 
Method Summary
static Sim_entity current_ent()
          Get the currently running entity.
static void generate_graphs(boolean generate_graphs)
          Specify that graphs are to be generated in the default graph file.
static void generate_graphs(java.lang.String filename)
          Specify that graphs are to be generated in a user specified graph file.
static int get_entity_id(java.lang.String name)
          Get the id of an entity with a given name.
static Sim_entity get_entity(int id)
          Get the entity with a given id.
static Sim_entity get_entity(java.lang.String name)
          Get the entity with a given name.
static int get_num_entities()
          Get the current number of entities in the simulation.
static long get_root_seed()
          Get the sample generator's root seed.
static int get_spacing()
          Get the sample generators' seed spacing.
static int get_trace_level()
          Get the current trace level (initially 0xff), which controls trace output.
static java.text.NumberFormat getNumberFormat()
          Get the number format used for generating times in trace lines.
static void initialise()
          Initialise the simulation for standalone simulations.
static void initialise(Sim_output out, java.lang.Thread sim)
          Initialise the system to draw simdiag diagrams.
static void link_ports(java.lang.String ent1, java.lang.String port1, java.lang.String ent2, java.lang.String port2)
          Link the ports of two entities so that events can be scheduled.
static long next_seed()
          Generate the next seed based on the root seed and the seed spacing.
static void run()
          Start the simulation running.
static boolean running()
          Check if the simulation is still running.
static void set_auto_trace(boolean on)
          Switch the trace messages on and off.
static void set_output_analysis(int type)
          Specify an output analysis method for the simulation.
static void set_output_analysis(int type, double level)
          Specify an output analysis method to produce confidence intervals of a given confidence level.
static void set_output_analysis(int type, int replications, double level)
          Specify independent replications as an output analysis method.
static void set_output_analysis(int type, int min_batches, int max_batches, double level)
          Specify batch means as the simulation's output analysis method.
static void set_report_detail(boolean detailed, boolean seeds)
          Set the detail required in the simulation's report.
static void set_seed_sequence(int seed_spacing, long root_seed)
          Set the sample generators' seed sequence.
static void set_seed(long new_seed)
          Set the sample generators' root seed.
static void set_spacing(int new_spacing)
          Set the sample generators' seed spacing.
static void set_termination_condition(int type, double time, boolean include_transient)
          Specify a termination condition based on the simulation time elapsed.
static void set_termination_condition(int type, int output_analysis_type, double level, double accuracy, java.lang.String entity, int measure)
          Specify a termination condition based on the confidence interval accuracy obtained for a default measure.
static void set_termination_condition(int type, int output_analysis_type, double level, double accuracy, java.lang.String entity, java.lang.String measure)
          Specify a termination condition based on the confidence interval accuracy obtained for a custom measure.
static void set_termination_condition(int type, java.lang.String entity, int event_type, long count, boolean include_transient)
          Specify a termination condition based on event completions at a specific entity.
static void set_trace_detail(boolean default_trace, boolean entity_trace, boolean event_trace)
          Set the desired contents of the trace file.
static void set_trace_level(int level)
          Set the trace level which controls entity trace output.
static void set_transient_condition(int type, double time)
          Specify a transient condition based on the elapsed simulation time.
static void set_transient_condition(int type, java.lang.String entity, int measure)
          Specify a transient condition using the minimum-maximum method for a default measure.
static void set_transient_condition(int type, java.lang.String entity, int event_type, long count)
          Specify a transient condition based on event completions at a specific entity.
static void set_transient_condition(int type, java.lang.String entity, java.lang.String measure)
          Specify a transient condition using the minimum-maximum method for a custom measure.
static double sim_clock()
          Get the current simulation time, as a runtime method for entities.
static void track_event(int tag)
          Generate trace for a specific event type.
static void track_events(int[] tags)
          Generate trace for a set of specific event types
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NONE

public static final int NONE
A constant representing no condition.

EVENTS_COMPLETED

public static final int EVENTS_COMPLETED
A constant representing a condition based on event completions.

TIME_ELAPSED

public static final int TIME_ELAPSED
A constant representing a condition based on a time period.

MIN_MAX

public static final int MIN_MAX
A constant representing the minimum-maximum method for transient period identification.

IND_REPLICATIONS

public static final int IND_REPLICATIONS
A constant representing the output analysis method of independent replications.

BATCH_MEANS

public static final int BATCH_MEANS
A constant representing the output analysis method of batch means.

INTERVAL_ACCURACY

public static final int INTERVAL_ACCURACY
A constant representing a termination condition based on a confidence interval's accuray.

SIM_ANY

public static Sim_any_p SIM_ANY
A standard predicate that matches any event.

SIM_NONE

public static Sim_none_p SIM_NONE
A standard predicate that does not match any events.
Constructor Detail

Sim_system

public Sim_system()
Method Detail

initialise

public static void initialise()
Initialise the simulation for standalone simulations. This function should be called at the start of the simulation.

initialise

public static void initialise(Sim_output out,
                              java.lang.Thread sim)
Initialise the system to draw simdiag diagrams. This method should be used directly only by expert users.
Parameters:
out - The Sim_output instance that will receive the simulation trace
sim - The simulation thread.

getNumberFormat

public static java.text.NumberFormat getNumberFormat()
Get the number format used for generating times in trace lines.
Returns:
The number format

sim_clock

public static double sim_clock()
Get the current simulation time, as a runtime method for entities.
Returns:
The simulation time

get_num_entities

public static int get_num_entities()
Get the current number of entities in the simulation.
Returns:
The number of entities

get_trace_level

public static int get_trace_level()
Get the current trace level (initially 0xff), which controls trace output.
Returns:
The trace level

get_entity

public static Sim_entity get_entity(int id)
Get the entity with a given id.
Parameters:
id - The entity's unique id number
Returns:
The entity, or null if it could not be found
Throws:
Sim_exception - If the entity was not found. This error can be left unchecked.

get_entity

public static Sim_entity get_entity(java.lang.String name)
Get the entity with a given name.
Parameters:
name - The entity's name
Returns:
The entity
Throws:
Sim_exception - If the entity was not found. This error can be left unchecked.

get_entity_id

public static int get_entity_id(java.lang.String name)
Get the id of an entity with a given name.
Parameters:
name - The entity's name
Returns:
The entity's unique id number
Throws:
Sim_exception - If the entity was not found. This error can be left unchecked.

current_ent

public static Sim_entity current_ent()
Get the currently running entity.
Returns:
The entity, or null if none are running

set_trace_level

public static void set_trace_level(int level)
Set the trace level which controls entity trace output.
Parameters:
level - The new level

set_auto_trace

public static void set_auto_trace(boolean on)
Switch the trace messages on and off.
Parameters:
on - If true then the messages are switched on, if false they are switched off.

link_ports

public static void link_ports(java.lang.String ent1,
                              java.lang.String port1,
                              java.lang.String ent2,
                              java.lang.String port2)
Link the ports of two entities so that events can be scheduled.
Parameters:
ent1 - The name of the first entity
port1 - The name of the port on the first entity
ent2 - The name of the second entity
port2 - The name of the port on the second entity

set_seed_sequence

public static void set_seed_sequence(int seed_spacing,
                                     long root_seed)
Set the sample generators' seed sequence. If this method is not called the defaults are 4851 as the root seed and 100000 as the desired sample spacing.
Parameters:
seed_specing - The seed spacing
root_seed - The seed used to generate all the simulation's seeds

set_spacing

public static void set_spacing(int new_spacing)
Set the sample generators' seed spacing.
Parameters:
new_spacing - The new seed spacing

get_spacing

public static int get_spacing()
Get the sample generators' seed spacing.
Returns:
The seed spacing

set_seed

public static void set_seed(long new_seed)
Set the sample generators' root seed. This is the seed used to generate the initial seeds for the simulation's sample generators.
Parameters:
new_seed - The new root seed

get_root_seed

public static long get_root_seed()
Get the sample generator's root seed.
Returns:
The root seed

next_seed

public static long next_seed()
Generate the next seed based on the root seed and the seed spacing. This method is automatically called and doesn't need to be included on user simulations.
Returns:
The next well spaced seed

set_termination_condition

public static void set_termination_condition(int type,
                                             java.lang.String entity,
                                             int event_type,
                                             long count,
                                             boolean include_transient)
Specify a termination condition based on event completions at a specific entity.
Parameters:
type - The termination condition type. This must be set to EVENTS_COMPLETED.
entity - The name of the entity whose events will be used for the termination condition
event_type - The event tag of the events to be counted towards the termination condition
count - The event completion count that when reached, will satisfy the termination condition
include_transient - true if the number of completions provided should only apply to completions in steady state. false if they should apply to the entire run length.

set_termination_condition

public static void set_termination_condition(int type,
                                             double time,
                                             boolean include_transient)
Specify a termination condition based on the simulation time elapsed.
Parameters:
type - The termination condition type. This must be set to TIME_ELAPSED.
time - The simulated time after which the termination condition will be satisfied
include_transient - true if the condition's time period should be considered only after steady state has been reached, false if it should be considered from the beginning of the simulation.

set_termination_condition

public static void set_termination_condition(int type,
                                             int output_analysis_type,
                                             double level,
                                             double accuracy,
                                             java.lang.String entity,
                                             java.lang.String measure)
Specify a termination condition based on the confidence interval accuracy obtained for a custom measure. This condition is considered only once the transient period has elapsed. The accuracy is the ratio of the confidence interval's halfwidth over the measure's total mean.
Parameters:
type - The termination condition type. This must be set to INTERVAL_ACCURACY.
output_analysis_type - The output analysis method to be used as a variance reduction technique
level - The confidence level for which the confidence interval will be calculated
accuracy - The accuracy that is required to satisfy the termination condition
entity - The name of the entity that contains the measure upon which the termination condition is based
measure - The name of the custom measure upon which the termination condition is based

set_termination_condition

public static void set_termination_condition(int type,
                                             int output_analysis_type,
                                             double level,
                                             double accuracy,
                                             java.lang.String entity,
                                             int measure)
Specify a termination condition based on the confidence interval accuracy obtained for a default measure. This condition is considered only once the transient period has elapsed. The accuracy is the ratio of the confidence interval's halfwidth over the measure's total mean.
Parameters:
type - The termination condition type. This must be set to INTERVAL_ACCURACY.
output_analysis_type - The output analysis method to be used as a variance reduction technique
level - The confidence level for which the confidence interval will be calculated
accuracy - The accuracy that is required to satisfy the termination condition
entity - The name of the entity that contains the measure upon which the termination condition is based
measure - The int constant that represents the default measure upon which the termination condition is based

set_transient_condition

public static void set_transient_condition(int type,
                                           java.lang.String entity,
                                           java.lang.String measure)
Specify a transient condition using the minimum-maximum method for a custom measure. The minimum-maximum method considers the simulation to have entered steady state after the first observation of the given measure is found that is neither the minimum nor the maximum of the remaining observations.
Parameters:
type - The transient condition type. This must be set to MIN_MAX.
entity - The name of the entity that contains the measure upon which the minimum-maximum method will be applied
measure - The name of the custom measure upon which the minimum-maximum method will be applied

set_transient_condition

public static void set_transient_condition(int type,
                                           java.lang.String entity,
                                           int measure)
Specify a transient condition using the minimum-maximum method for a default measure. The minimum-maximum method considers the simulation to have entered steady state after the first observation of the given measure is found that is neither the minimum nor the maximum of the remaining observations.
Parameters:
type - The transient condition type. This must be set to MIN_MAX.
entity - The name of the entity that contains the measure upon which the minimum-maximum method will be applied
measure - The int constant that represents the default measure upon which the minimum-maximum method will be applied

set_transient_condition

public static void set_transient_condition(int type,
                                           java.lang.String entity,
                                           int event_type,
                                           long count)
Specify a transient condition based on event completions at a specific entity.
Parameters:
type - The transient condition type. This must be set to EVENTS_COMPLETED.
entity - The name of the entity whise event completions will be counted towards this condition
event_type - The event tag of the events whose completions will be counted towards this condition
count - The number of event completions after which the condition will be satisfied

set_transient_condition

public static void set_transient_condition(int type,
                                           double time)
Specify a transient condition based on the elapsed simulation time.
Parameters:
type - The transient condition type. This must be set to TIME_ELAPSED.
time - The time period after which the condition will be satisfied

set_output_analysis

public static void set_output_analysis(int type)
Specify an output analysis method for the simulation. The default, if this method is not used is NONE. If independent replications is selected, 10 replications will be performed. If batch means is selected, the observations will be batched into 10 to 20 batches. The actual number of batches used will be the one that gives the least serial correlation among the batch means.

The confidence level that will be used for calculating the simulation's measures' confidence intervals is 0.90 (90%).

Parameters:
type - The output analysis method

set_output_analysis

public static void set_output_analysis(int type,
                                       double level)
Specify an output analysis method to produce confidence intervals of a given confidence level.
Parameters:
type - The output analysis method.
level - The confidence level to be used to produce the confidence intervals for the simulations' measures

set_output_analysis

public static void set_output_analysis(int type,
                                       int min_batches,
                                       int max_batches,
                                       double level)
Specify batch means as the simulation's output analysis method. The observation will be batched into min_batches batches up to max_batches batches. The number of batches that will actually be used to produce the confidence intervals will be the one that gives the least serial correlation among the batch means.
Parameters:
type - The output analysis method. This must be set to BATCH_MEANS.
min_batches - The minimum number of batches that the observations will be batched into
max_batches - The maximum number of batches that the observations will be batched into
level - The confidence level to be used to produce the confidence intervals for the simulations' measures

set_output_analysis

public static void set_output_analysis(int type,
                                       int replications,
                                       double level)
Specify independent replications as an output analysis method.
Parameters:
type - The output analysis method. This must be set to IND_REPLICATIONS.
replications - The number of replications to perform
level - The confidence level that will be used to produce the simulation's measures' confidence intervals

set_report_detail

public static void set_report_detail(boolean detailed,
                                     boolean seeds)
Set the detail required in the simulation's report. The default is to include only the total measurements and the general simulation information.
Parameters:
detailed - If set to true the report will include the sample measurements from each replication (if independent replications has been used as an output analysis method), or the sample measurements from each batch (if batch means has been used). Setting this to false will only include the total measurements and general simulation information.
seeds - If set to true the report will include the original seeds used in the entities' random number generators

generate_graphs

public static void generate_graphs(boolean generate_graphs)
Specify that graphs are to be generated in the default graph file. The name of the graph file will be sim_graphs.sjg.
Parameters:
generate_graphs - Set to true if graphs are to be generated, false otherwise

generate_graphs

public static void generate_graphs(java.lang.String filename)
Specify that graphs are to be generated in a user specified graph file.
Parameters:
filename - The name of the graph file

running

public static boolean running()
Check if the simulation is still running. This method should be used by entities to check if they should continue executing.
Returns:
true if the simulation is still running, false otherwise

run

public static void run()
Start the simulation running. This should be called after all the entities have been setup and added, and their ports linked.

set_trace_detail

public static void set_trace_detail(boolean default_trace,
                                    boolean entity_trace,
                                    boolean event_trace)
Set the desired contents of the trace file. The default is to include all trace, if tracing is switched on.
Parameters:
default_trace - If set to true the default trace will be included in the trace file, if false it will not
entity_trace - If set to true the trace generated by the entities will be included in the trace file, if false it will not
event_trace - If set to true the trace file will include trace for the selected event types, if false it will not

track_event

public static void track_event(int tag)
Generate trace for a specific event type.
Parameters:
tag - The event type

track_events

public static void track_events(int[] tags)
Generate trace for a set of specific event types

SimJava
v2.0

The University of Edinburgh, 2002