SSJ
V. labo.

umontreal.iro.lecuyer.simexp
Class SimExp

java.lang.Object
  extended by umontreal.iro.lecuyer.simexp.SimExp
Direct Known Subclasses:
BatchMeansSim, RepSim

public abstract class SimExp
extends Object

Represents a framework for performing experiments using simulation. This class defines an abstract simulate method that should implement the simulation logic. It also provides utility methods to estimate the required number of additional observations that would be necessary for an estimator to reach a given precision, for sequential sampling.

This class is the base class of BatchMeansSim and RepSim implementing the logic for a simulation on infinite and finite horizon, respectively.


Method Summary
static int getRequiredNewObservations(double center, double radius, int numberObs, double targetError)
          Returns the approximate number of additional observations needed for the point estimator bar(X)n = center, computed using n = numberObs observations and with a confidence interval having radius δn/(n)1/2 = radius, to have a relative error less than or equal to ε = targetError.
static int getRequiredNewObservations(Iterable<? extends StatProbe> it, double targetError, double level)
          Returns the approximate number of additional observations required to reach a relative error smaller than or equal to targetError for each tally enumerated by it when confidence intervals are computed with confidence level level.
static int getRequiredNewObservations(StatProbe[] a, double targetError, double level)
          Returns the approximate number of additional observations required to reach a relative error smaller than or equal to targetError for each tally in the array a when confidence intervals are computed with confidence level level.
static int getRequiredNewObservations(StatProbe probe, double targetError, double level)
          Calls getRequiredNewObservations with the average, confidence interval radius, and number of observations given by the statistical probe probe.
static int getRequiredNewObservationsTally(FunctionOfMultipleMeansTally fmmt, double targetError, double level)
          Calls getRequiredNewObservations with the average, confidence interval radius, and number of observations given by the function of multiple means fmmt.
static int getRequiredNewObservationsTally(Tally ta, double targetError, double level)
          Calls getRequiredNewObservations with the average, confidence interval radius, and number of observations given by the tally ta.
 boolean isSimulating()
          Determines if the simulation is in progress.
 void setSimulator(Simulator sim)
          Sets the simulator associated with this experiment to sim.
abstract  void simulate()
          Performs an experiment whose logic depends on the used subclass.
 Simulator simulator()
          Returns the simulator linked to this experiment object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

simulator

public final Simulator simulator()
Returns the simulator linked to this experiment object.

Returns:
the simulator linked to the experiment object

setSimulator

public final void setSimulator(Simulator sim)
Sets the simulator associated with this experiment to sim. This method should not be called while this object is simulating.

Parameters:
sim - the new simulator

isSimulating

public boolean isSimulating()
Determines if the simulation is in progress.

Returns:
true if and only if simulation is in progress.

simulate

public abstract void simulate()
Performs an experiment whose logic depends on the used subclass. Before starting the simulation, this method should set simulating to true, and reset it to false after the simulation is done. It is recommended to reset simulating to false inside a finally clause to prevent the indicator from remaining true in the case of error during simulation.

Throws:
IllegalStateException - if simulating is true when calling this method.

getRequiredNewObservations

public static int getRequiredNewObservations(StatProbe[] a,
                                             double targetError,
                                             double level)
Returns the approximate number of additional observations required to reach a relative error smaller than or equal to targetError for each tally in the array a when confidence intervals are computed with confidence level level. For each statistical collector in the given array, a confidence interval is computed independently of the other collectors, and an error check is performed by getRequiredNewObservations to determine the required number of additional observations. The method returns the maximal number of required observations.

Parameters:
a - the array of probes.
targetError - the target relative error.
level - the desired probability that, for a given statistical collector, the (random) confidence interval covers the true mean (a constant).
Returns:
an estimate of the required number of additional observations to reach the precision.

getRequiredNewObservations

public static int getRequiredNewObservations(Iterable<? extends StatProbe> it,
                                             double targetError,
                                             double level)
Returns the approximate number of additional observations required to reach a relative error smaller than or equal to targetError for each tally enumerated by it when confidence intervals are computed with confidence level level. For each statistical collector returned by the iterator obtained from it, a confidence interval is computed independently of the other collectors, and an error check is performed by getRequiredNewObservations to determine the required number of additional observations. The method returns the maximal number of required observations.

Parameters:
it - the iterable used to enumerate probes.
targetError - the target relative error.
level - the desired probability that, for a given statistical collector, the (random) confidence interval covers the true mean (a constant).
Returns:
an estimate of the required number of additional observations to reach the precision.

getRequiredNewObservations

public static int getRequiredNewObservations(StatProbe probe,
                                             double targetError,
                                             double level)
Calls getRequiredNewObservations with the average, confidence interval radius, and number of observations given by the statistical probe probe. This method always returns 0 if the probe is not a tally. For a Tally, the confidence interval is computed using confidenceIntervalStudent. For a FunctionOfMultipleMeansTally, it is computed using confidenceIntervalDelta.

Parameters:
probe - the statistical probe being checked.
targetError - the target relative error.
level - the desired probability that the (random) confidence interval covers the true mean (a constant).
Returns:
the number of required additional observations.

getRequiredNewObservationsTally

public static int getRequiredNewObservationsTally(Tally ta,
                                                  double targetError,
                                                  double level)
Calls getRequiredNewObservations with the average, confidence interval radius, and number of observations given by the tally ta. The confidence interval is computed using confidenceIntervalStudent.

Parameters:
ta - the tally being checked.
targetError - the target relative error.
level - the desired probability that the (random) confidence interval covers the true mean (a constant).
Returns:
the number of required additional observations.

getRequiredNewObservationsTally

public static int getRequiredNewObservationsTally(FunctionOfMultipleMeansTally fmmt,
                                                  double targetError,
                                                  double level)
Calls getRequiredNewObservations with the average, confidence interval radius, and number of observations given by the function of multiple means fmmt. The confidence interval is computed using confidenceIntervalDelta.

Parameters:
fmmt - the function of multiple means being checked.
targetError - the target relative error.
level - the desired probability that the (random) confidence interval covers the true mean (a constant).
Returns:
the number of required additional observations.

getRequiredNewObservations

public static int getRequiredNewObservations(double center,
                                             double radius,
                                             int numberObs,
                                             double targetError)
Returns the approximate number of additional observations needed for the point estimator bar(X)n = center, computed using n = numberObs observations and with a confidence interval having radius δn/(n)1/2 = radius, to have a relative error less than or equal to ε = targetError. It is assumed that bar(X)n is an estimator of a mean μ, n is the number of observations numberObs, and that δn/(n)1/2 ->  0 when n -> ∞.

If n is less than 1, this method returns 0. Otherwise, the relative error given by δn/|(n)1/2bar(X)n| should be smaller than or equal to ε. If the inequality is true, this returns 0. Otherwise, the minimal n* for which this inequality holds is approximated as follows. The target radius is given by δ* = ε| μ|, which is approximated by ε| bar(X)n| < δn/(n)1/2. The method must select n* for which δn*/(n^*)1/2 <= δ*, which will be approximately true if δn*/(n^*)1/2 <= ε| bar(X)n|. Therefore,

n* >= (δn*/(ε| bar(X)n|))2 =  (δn/(ε| bar(X)n|))2.

The method returns round((δn(n)1/2/(ε| bar(X)n|))2) - n where round(⋅) rounds its argument to the nearest integer.

Parameters:
center - the value of the point estimator.
radius - the radius of the confidence interval.
numberObs - the number of observations.
targetError - the target relative error.
Returns:
an estimate of the required number of additional observations to reach the precision.
Throws:
IllegalArgumentException - if radius or targetError are negative.

SSJ
V. labo.

To submit a bug or ask questions, send an e-mail to Pierre L'Ecuyer.