Package jsl.simulation

Class Simulation

  • All Implemented Interfaces:
    ObservableIfc, ExperimentGetIfc, IterativeProcessIfc, GetNameIfc
    public class Simulation
extends java.lang.Object
implements ObservableIfc, IterativeProcessIfc, ExperimentGetIfc
    Simulation represents a model and experiment that can be run. It encapsulates a model to which model elements can be attached. It allows an experiment and its run parameters to be specified. It allows reporting of results to text files via a SimulationReporter. If you want to store simulation results in a database, then use the JSLDatabaseObserver class to observe the simulation with an instance of the JSLDatabase class.

    • Field Detail

      • LOGGER

        public static final org.slf4j.Logger LOGGER
        for logging

      • myModel

        protected final Model myModel
        The model to simulate

    • Constructor Detail

      • Simulation

        public Simulation()
        Creates a simulation within a default name using the default executive

      • Simulation

        public Simulation​(java.lang.String simName)
        Creates a simulation to run a model using the default scheduling executive.
        Parameters:
        simName - the name of the simulation

      • Simulation

        public Simulation​(java.lang.String simName,
                  java.nio.file.Path pathToOutputDirectory)
        Creates a simulation to run a model using the default scheduling executive.
        Parameters:
        simName - the name of the simulation
        pathToOutputDirectory - the path to the output directory for the simulation files

      • Simulation

        public Simulation​(java.lang.String simName,
                  java.nio.file.Path pathToOutputDirectory,
                  Executive executive)
        Creates a simulation to run a model using the supplied scheduling executive.
        Parameters:
        simName - the name of the simulation
        pathToOutputDirectory - the path to the output directory for the simulation files
        executive - the executive, if null the default executive is used

    • Method Detail

      • getOutputDirectory

        public final OutputDirectory getOutputDirectory()
        Returns:
        the defined OutputDirectory for the simulation

      • getOutputDirectoryPath

        public final java.nio.file.Path getOutputDirectoryPath()
        Returns:
        the path to the simulation's output directory

      • out

        public final LogPrintWriter out()
        Returns:
        the pre-defined default text output file for the simulation

      • getName

        public final java.lang.String getName()
        Specified by:
        getName in interface GetNameIfc
        Returns:
        a string representing the name of the object

      • getId

        public final long getId()

      • getExperiment

        public final ExperimentGetIfc getExperiment()
        The Experiment associated with the simulation
        Returns:
        the experiment

      • getModel

        public final Model getModel()
        The Model associated with the simulation
        Returns:
        the model

      • getExecutive

        public final Executive getExecutive()
        The Executive associated with the simulation
        Returns:
        the Executive

      • turnOnStatisticalBatching

        public final StatisticalBatchingElement turnOnStatisticalBatching()
        A StatisticalBatchingElement is used to control statistical batching for single replication simulations. This method creates and attaches a StatisticalBatchingElement to the model. For convenience, it also returns the created element
        Returns:
        the StatisticalBatchingElement

      • getStatisticalBatchingElement

        public final java.util.Optional<StatisticalBatchingElement> getStatisticalBatchingElement()
        Returns:
        an optional of the StatisticalBatchingElement because it may or may not be attached

      • deleteObservers

        public final void deleteObservers()
        Description copied from interface: ObservableIfc
        Deletes all the observers from the observable
        Specified by:
        deleteObservers in interface ObservableIfc

      • deleteObserver

        public final void deleteObserver​(ObserverIfc observer)
        Description copied from interface: ObservableIfc
        Allows the deletion (removing) of an observer from the observable
        Specified by:
        deleteObserver in interface ObservableIfc
        Parameters:
        observer - the observer to delete

      • countObservers

        public final int countObservers()
        Description copied from interface: ObservableIfc
        Returns how many observers are currently observing the observable
        Specified by:
        countObservers in interface ObservableIfc
        Returns:
        number of observers

      • addObserver

        public final void addObserver​(ObserverIfc observer)
        Allows an observer to be added to the simulation. The observer observes an IterativeProcess that manages the execution of the replications. Each step in the IterativeProcess represents an entire replication.
        Specified by:
        addObserver in interface ObservableIfc
        Parameters:
        observer - the observer

      • contains

        public boolean contains​(ObserverIfc observer)
        Description copied from interface: ObservableIfc
        Returns true if the observer is already attached
        Specified by:
        contains in interface ObservableIfc
        Parameters:
        observer - the observer to check
        Returns:
        true if attached

      • hasNextReplication

        public final boolean hasNextReplication()
        Returns true if additional replications need to be run
        Returns:
        true if additional replications need to be run

      • initialize

        public final void initialize()
        Initializes the simulation in preparation for running
        Specified by:
        initialize in interface IterativeProcessIfc

      • runNext

        public final void runNext()
        Runs the next replication if there is one
        Specified by:
        runNext in interface IterativeProcessIfc

      • run

        public final void run​(int numReps,
                      double runLength)
        A convenience method for running a simulation
        Parameters:
        numReps - the number of replications
        runLength - the length of the simulation replication

      • run

        public final void run​(java.lang.String expName,
                      int numReps,
                      double runLength)
        A convenience method for running a simulation
        Parameters:
        expName - the name of the experiment
        numReps - the number of replications
        runLength - the length of the simulation replication

      • run

        public final void run​(java.lang.String expName,
                      int numReps,
                      double runLength,
                      double warmUp)
        A convenience method for running a simulation
        Parameters:
        expName - the name of the experiment
        numReps - the number of replications
        runLength - the length of the simulation replication
        warmUp - the length of the warm up period

      • run

        public final void run()
        Runs all remaining replications based on the current settings
        Specified by:
        run in interface IterativeProcessIfc

      • end

        public final void end​(java.lang.String msg)
        Causes the simulation to end after the current replication is completed
        Specified by:
        end in interface IterativeProcessIfc
        Parameters:
        msg - A message to indicate why the simulation was stopped

      • end

        public final void end()
        Causes the simulation to end after the current replication is completed
        Specified by:
        end in interface IterativeProcessIfc

      • isUnfinished

        public final boolean isUnfinished()
        Checks if the replications were finished
        Specified by:
        isUnfinished in interface IterativeProcessIfc
        Returns:
        true if unfinished

      • executionTimeExceeded

        public final boolean executionTimeExceeded()
        Checks if the simulation stopped because of real clock time
        Specified by:
        executionTimeExceeded in interface IterativeProcessIfc
        Returns:
        true if exceeded

      • isStepCompleted

        public final boolean isStepCompleted()
        Part of the IterativeProcessIfc. Checks if a step in the process is completed. A step is a replication Checks if the state of the simulation is that it just completed a replication
        Specified by:
        isStepCompleted in interface IterativeProcessIfc
        Returns:
        true if completed

      • isRunning

        public final boolean isRunning()
        Checks if the simulation is running. Running means that it is executing replications
        Specified by:
        isRunning in interface IterativeProcessIfc
        Returns:
        true means it is running

      • isInitialized

        public final boolean isInitialized()
        Checks if the simulation has been initialized. If it is initialized, then it is ready to run replications
        Specified by:
        isInitialized in interface IterativeProcessIfc
        Returns:
        true if initialized

      • isEnded

        public final boolean isEnded()
        Checks to see if the simulation is in the ended state If it is ended, it may be for a number of reasons
        Specified by:
        isEnded in interface IterativeProcessIfc
        Returns:
        true if end

      • isCreated

        public final boolean isCreated()
        Description copied from interface: IterativeProcessIfc
        Checks if the iterative process is in the created state. If the iterative process is in the created state this method will return true
        Specified by:
        isCreated in interface IterativeProcessIfc
        Returns:
        true if in the created state

      • stoppedByCondition

        public final boolean stoppedByCondition()
        Checks if the simulation has ended because it was stopped
        Specified by:
        stoppedByCondition in interface IterativeProcessIfc
        Returns:
        true if stopped by condition

      • isDone

        public final boolean isDone()
        Checks if the simulation is done processing replications
        Specified by:
        isDone in interface IterativeProcessIfc
        Returns:
        true if done

      • allStepsCompleted

        public final boolean allStepsCompleted()
        Checks if the simulation completed all of its replications
        Specified by:
        allStepsCompleted in interface IterativeProcessIfc
        Returns:
        true if all

      • setMaximumExecutionTime

        public final void setMaximumExecutionTime​(long milliseconds)
        Sets a real clock time for how long the entire simulation can last
        Specified by:
        setMaximumExecutionTime in interface IterativeProcessIfc
        Parameters:
        milliseconds - the max allowed

      • getMaximumAllowedExecutionTime

        public final long getMaximumAllowedExecutionTime()
        Returns the real clock time in milliseconds for how long the simulation is allowed to run
        Specified by:
        getMaximumAllowedExecutionTime in interface IterativeProcessIfc
        Returns:
        the max allowed

      • getEndExecutionTime

        public final long getEndExecutionTime()
        The absolute time in milliseconds that the simulation ended
        Specified by:
        getEndExecutionTime in interface IterativeProcessIfc
        Returns:
        the end time (in real clock time)

      • getElapsedExecutionTime

        public final long getElapsedExecutionTime()
        The time in milliseconds between when the simulation was started and the simulation ended
        Specified by:
        getElapsedExecutionTime in interface IterativeProcessIfc
        Returns:
        the elapsed time (in real clock time)

      • getBeginExecutionTime

        public final long getBeginExecutionTime()
        The absolute time in milliseconds that the simulation was started
        Specified by:
        getBeginExecutionTime in interface IterativeProcessIfc
        Returns:
        the begin time (in real clock time)

      • getStoppingMessage

        public final java.lang.String getStoppingMessage()
        The message supplied with stop()
        Specified by:
        getStoppingMessage in interface IterativeProcessIfc
        Returns:
        the stopping message

      • turnOnTimer

        public final void turnOnTimer​(long milliseconds)
        Turns on a default timer and task to report on simulation progress
        Specified by:
        turnOnTimer in interface IterativeProcessIfc
        Parameters:
        milliseconds - time for timer task

      • turnOnLogReport

        public final void turnOnLogReport()

      • turnOnLogReport

        public final void turnOnLogReport​(java.lang.String reportFileName)
        Parameters:
        reportFileName - the name of the report

      • turnOnLogReport

        public final void turnOnLogReport​(java.nio.file.Path pathToFile)
        Turns on a default logging report with the provided name
        Specified by:
        turnOnLogReport in interface IterativeProcessIfc
        Parameters:
        pathToFile - the path to the file

      • getNumberStepsCompleted

        public final long getNumberStepsCompleted()
        For the IterativeProcessIfc. Returns the number of steps (replications) completed
        Specified by:
        getNumberStepsCompleted in interface IterativeProcessIfc
        Returns:
        number of steps completed

      • getCurrentReplicationNumber

        public final int getCurrentReplicationNumber()
        Returns the current number of replications completed
        Specified by:
        getCurrentReplicationNumber in interface ExperimentGetIfc
        Returns:
        the number as a double

      • hasMoreReplications

        public final boolean hasMoreReplications()
        Description copied from interface: ExperimentGetIfc
        Checks if the current number of replications that have been executed is less than the number of replications specified.
        Specified by:
        hasMoreReplications in interface ExperimentGetIfc
        Returns:
        true if more

      • getNumberOfReplications

        public final int getNumberOfReplications()
        Returns the number of replications for the experiment
        Specified by:
        getNumberOfReplications in interface ExperimentGetIfc
        Returns:
        the number of replications

      • getNumberOfStreamAdvancesPriorToRunning

        public final int getNumberOfStreamAdvancesPriorToRunning()
        Description copied from interface: ExperimentGetIfc
        Returns the number of times that the streams should be advanced prior to running the experiment
        Specified by:
        getNumberOfStreamAdvancesPriorToRunning in interface ExperimentGetIfc
        Returns:
        number of streams to advance

      • setResetStartStreamOption

        public final void setResetStartStreamOption​(boolean b)
        If set to true then the streams will be reset to the start of the stream prior to running the experiments. True facilitates the use of common random numbers.
        Parameters:
        b - true means option is on

      • setAdvanceNextSubStreamOption

        public final void setAdvanceNextSubStreamOption​(boolean b)
        Sets the option to have the streams advance to the beginning of the next substream after each replication
        Parameters:
        b - true means option is on

      • setReplicationInitializationOption

        public final void setReplicationInitializationOption​(boolean repInitOption)
        Sets whether or not the replication should be initialized before each replication
        Parameters:
        repInitOption - true for initialize

      • setNumberOfReplications

        public final void setNumberOfReplications​(int numReps,
                                          boolean antitheticOption)
        Sets the number of replications to be executed and whether or not the antithetic option is on. If the antithetic option is on then the number of replications should be divisible by 2 so that antithetic pairs can be formed.
        Parameters:
        numReps - number of replications
        antitheticOption - true means option is on

      • setNumberOfReplications

        public final void setNumberOfReplications​(int numReps)
        Sets the number of replications to be executed. The antithetic option is off
        Parameters:
        numReps - number of replications

      • setMaximumExecutionTimePerReplication

        public final void setMaximumExecutionTimePerReplication​(long milliseconds)
        Sets in real clock time (milliseconds) the amount of time available for each replication within the simulation. If the replication lasts longer than the supplied time it will be stopped
        Parameters:
        milliseconds - clock time for a replication

      • setLengthOfWarmUp

        public final void setLengthOfWarmUp​(double lengthOfWarmUp)
        Allows the length of the warm up period for each replication to be set
        Parameters:
        lengthOfWarmUp - in simulation time

      • setLengthOfReplication

        public final void setLengthOfReplication​(double lengthOfReplication)
        Sets the length of the replications in simulation time.
        Parameters:
        lengthOfReplication - the length of the replication

      • getResetStartStreamOption

        public final boolean getResetStartStreamOption()
        Returns whether or not the start stream will be reset prior to executing the simulation
        Specified by:
        getResetStartStreamOption in interface ExperimentGetIfc
        Returns:
        true if option is on

      • getAdvanceNextSubStreamOption

        public final boolean getAdvanceNextSubStreamOption()
        Returns how many times the random number streams will be advanced before the simulation starts.
        Specified by:
        getAdvanceNextSubStreamOption in interface ExperimentGetIfc
        Returns:
        true if option is on

      • getReplicationInitializationOption

        public final boolean getReplicationInitializationOption()
        Returns whether or not replications will be initialized prior to running each replication
        Specified by:
        getReplicationInitializationOption in interface ExperimentGetIfc
        Returns:
        true if replications will be initialized

      • getMaximumAllowedExecutionTimePerReplication

        public final long getMaximumAllowedExecutionTimePerReplication()
        Gets in real clock time (milliseconds) the amount of time available for each replication within the simulation. If the replication lasts longer than the supplied time it will be stopped
        Specified by:
        getMaximumAllowedExecutionTimePerReplication in interface ExperimentGetIfc
        Returns:
        the clock time allowed

      • getLengthOfWarmUp

        public final double getLengthOfWarmUp()
        Provides the length of the warm up period for each replication
        Specified by:
        getLengthOfWarmUp in interface ExperimentGetIfc
        Returns:
        the length of the warm up period

      • getLengthOfReplication

        public final double getLengthOfReplication()
        Provides the length of each replication
        Specified by:
        getLengthOfReplication in interface ExperimentGetIfc
        Returns:
        the length of the replication

      • getAntitheticOption

        public final boolean getAntitheticOption()
        Indicates whether or not the antithetic streams have been turn on or off
        Specified by:
        getAntitheticOption in interface ExperimentGetIfc
        Returns:
        true means option is on

      • setGarbageCollectAfterReplicationFlag

        public final void setGarbageCollectAfterReplicationFlag​(boolean flag)
        Determines whether or not System.gc() is called after each replication
        Parameters:
        flag - true means yes

      • getGarbageCollectAfterReplicationFlag

        public final boolean getGarbageCollectAfterReplicationFlag()
        Returns whether or not System.gc() is called after each replication
        Specified by:
        getGarbageCollectAfterReplicationFlag in interface ExperimentGetIfc
        Returns:
        true means yes

      • setAdvanceStreamNumber

        public final void setAdvanceStreamNumber​(int n)
        Sets the number of streams to advance prior to running an experiment
        Parameters:
        n - the number to advance

      • getRepLengthWarningMessageOption

        public final boolean getRepLengthWarningMessageOption()
        Returns:
        true if the flag permits the message to be printed

      • setRepLengthWarningMessageOption

        public final void setRepLengthWarningMessageOption​(boolean flag)
        False turns off the message
        Parameters:
        flag - false turns of the message

      • setExperimentName

        public final void setExperimentName​(java.lang.String name)
        Sets the name of the underlying experiment
        Parameters:
        name - the name to set

      • setExperiment

        protected final void setExperiment​(Experiment e)
        Set the simulation experiment to the same attribute values as the supplied experiment
        Parameters:
        e - the experiment

      • turnOnDefaultEventTraceReport

        public final void turnOnDefaultEventTraceReport​(java.lang.String name)
        Turns on a default tracing report for the Executive to trace event execution to a file
        Parameters:
        name - the name of the file

      • turnOnDefaultEventTraceReport

        public final void turnOnDefaultEventTraceReport()
        Turns on a default tracing report for the Executive to trace event execution to a file

      • turnOffDefaultEventTraceReport

        public final void turnOffDefaultEventTraceReport()
        Turns off a default tracing report for the Executive to trace event execution to a file

      • getDefaultExecutiveTraceReport

        public final java.util.Optional<ExecutiveTraceReport> getDefaultExecutiveTraceReport()
        Gets a reference to the default event tracing report. May be null if not turned on.
        Returns:
        the ExecutiveTraceReport

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getHalfWidthSummaryReport

        public java.lang.StringBuilder getHalfWidthSummaryReport()
        Returns:
        a StringBuilder with the Half-Width Summary Report and 95 percent confidence

      • getHalfWidthSummaryReport

        public java.lang.StringBuilder getHalfWidthSummaryReport​(double confLevel)
        Parameters:
        confLevel - the confidence level of the report
        Returns:
        a StringBuilder with the Half-Width Summary Report

      • getHalfWidthSummaryReport

        public java.lang.StringBuilder getHalfWidthSummaryReport​(java.lang.String title,
                                                         double confLevel)
        Parameters:
        title - the title
        confLevel - the confidence level
        Returns:
        a StringBuilder representation of the half-width summary report

      • printHalfWidthSummaryReport

        public void printHalfWidthSummaryReport()
        Prints the default half-width summary report to the console

      • printHalfWidthSummaryReport

        public void printHalfWidthSummaryReport​(double confLevel)
        Parameters:
        confLevel - the confidence level of the report

      • printHalfWidthSummaryReport

        public void printHalfWidthSummaryReport​(java.lang.String title,
                                        double confLevel)
        Parameters:
        title - the title of the report
        confLevel - the confidence level of the report

      • writeHalfWidthSummaryReport

        public void writeHalfWidthSummaryReport​(java.io.PrintWriter out)
        Parameters:
        out - the place to write to

      • writeHalfWidthSummaryReport

        public void writeHalfWidthSummaryReport​(java.io.PrintWriter out,
                                        double confLevel)
        Parameters:
        out - the place to write to
        confLevel - the confidence level of the report

      • writeHalfWidthSummaryReport

        public void writeHalfWidthSummaryReport​(java.io.PrintWriter out,
                                        java.lang.String title,
                                        double confLevel)
        Parameters:
        out - the place to write to
        title - the title of the report
        confLevel - the confidence level of the report

      • makeSimulationReporter

        public SimulationReporter makeSimulationReporter()
        Constructs a SimulationReporter instance that uses this Simulation instance
        Returns:
        the SimulationReporter

      • beforeExperiment

        protected void beforeExperiment()
        This method is automatically called at the start of the experiment Sub-classes can inject behavior within here

      • afterExperiment

        protected void afterExperiment()
        This method is automatically called at the end of the experiment Sub-classes can inject behavior within here

      • beforeReplication

        protected void beforeReplication()
        This method is automatically called before each replication Sub-classes can inject behavior within here

      • afterReplication

        protected void afterReplication()
        This method is automatically called after each replication Sub-classes can inject behavior within here

      • isExecutionTimeExceeded

        public final boolean isExecutionTimeExceeded()
        Description copied from interface: IterativeProcessIfc
        Returns if the elapsed execution time exceeds the maximum time allowed. Only true if the maximum was set and elapsed time is greater than or equal to getMaximumAllowedExecutionTime()
        Specified by:
        isExecutionTimeExceeded in interface IterativeProcessIfc
        Returns:
        true if the execution time exceeds getMaximumAllowedExecutionTime()

      • getStoppingFlag

        public final boolean getStoppingFlag()
        Description copied from interface: IterativeProcessIfc
        Returns the stopping flag
        Specified by:
        getStoppingFlag in interface IterativeProcessIfc
        Returns:
        true if the process has been told to stop via stop()

      • stop

        public final void stop()
        Description copied from interface: IterativeProcessIfc
        This sets a flag to indicate to the process that is should stop after the next step is completed. This is different than end(). Calling end() immediately places the process in the End state. The process needs to be in a valid state before end() can be used. Calling stop tells the process to eventually get into the end state. stop() can be used to arbitrarily stop the process based on some user defined condition.
        Specified by:
        stop in interface IterativeProcessIfc

      • stop

        public final void stop​(java.lang.String msg)
        Description copied from interface: IterativeProcessIfc
        This sets a flag to indicate to the process that is should stop after the next step is completed. This is different than end(). Calling end() immediately places the process in the End state. The process needs to be in a valid state before end() can be used. Calling stop tells the process to eventually get into the end state. stop() can be used to arbitrarily stop the process based on some user defined condition.
        Specified by:
        stop in interface IterativeProcessIfc
        Parameters:
        msg - A string to represent the reason for the stopping

      • isRunningStep

        public final boolean isRunningStep()
        Description copied from interface: IterativeProcessIfc
        Indicates that the iterative process is currently running an individual step
        Specified by:
        isRunningStep in interface IterativeProcessIfc
        Returns:
        true if the step is in progress

      • noStepsExecuted

        public final boolean noStepsExecuted()
        Description copied from interface: IterativeProcessIfc
        Indicates that the iterative process ended because of no steps
        Specified by:
        noStepsExecuted in interface IterativeProcessIfc
        Returns:
        True if no steps are executed