SSJ  3.3.1
Stochastic Simulation in Java
Public Member Functions | Static Public Member Functions | List of all members
ListOfTalliesWithCV< E extends Tally > Class Template Reference

Represents a list of tallies with control variables that inherits the functionalities of a list of tallies, and accepts vectors of length \(p+q\). More...

Inheritance diagram for ListOfTalliesWithCV< E extends Tally >:
[legend]
Collaboration diagram for ListOfTalliesWithCV< E extends Tally >:
[legend]

Public Member Functions

 ListOfTalliesWithCV ()
 Constructs a new empty list of tallies with no control variable. More...
 
 ListOfTalliesWithCV (String name)
 Constructs a new empty list of tallies with no control variable and name name. More...
 
void init ()
 
DoubleMatrix2D getBeta ()
 Returns the current matrix \(\boldsymbol{\beta}\). More...
 
void setBeta (DoubleMatrix2D beta)
 Sets the \(\boldsymbol{\beta}\) matrix to beta. More...
 
double getExpectedValue (int i)
 Gets the expected value of the \(i\)th control variable. More...
 
void setExpectedValue (int i, double e)
 Sets the expected value of the \(i\)th control variable to e. More...
 
double [] getExpectedValues ()
 Returns \(E[\mathbf{C}]\), the expected value of the vector of control variables. More...
 
void setExpectedValues (double[] exp)
 Sets \(E[\mathbf{C}]\) to exp. More...
 
int sizeWithoutCV ()
 Returns the size of this list excluding the control variables. More...
 
int getNumControlVariables ()
 Returns the number \(q\) of control variables. More...
 
void setNumControlVariables (int q)
 Sets the number of control variables to q. More...
 
void correlationX (DoubleMatrix2D c)
 Fills c with the sample correlation matrix of \(\mathbf{X}\). More...
 
void covarianceX (DoubleMatrix2D c)
 Fills c with the sample covariance matrix of \(\mathbf{X}\). More...
 
void correlationC (DoubleMatrix2D c)
 Fills c with the sample correlation matrix of \(\mathbf{C}\). More...
 
void covarianceC (DoubleMatrix2D c)
 Fills c with the sample covariance matrix of \(\mathbf{C}\). More...
 
void correlationCX (DoubleMatrix2D c)
 Fills c with the sample correlation matrix of \(\mathbf{C}\) and \(\mathbf{X}\). More...
 
void covarianceCX (DoubleMatrix2D c)
 Fills c with the sample covariance matrix of \(\mathbf{C}\) and \(\mathbf{X}\). More...
 
void add (double[] x, double[] c)
 Adds a new observation \((\mathbf{X}, \mathbf{C})\) to this list of tallies. More...
 
void add (double x, double[] c)
 Variant of the #add(double[],double[]) method that can be used when there is only one output variable. More...
 
void add (double x, double c)
 Variant of the #add(double[],double[]) that can be used when \(p=q=1\). More...
 
double averageWithCV (int i)
 Returns the average of the \(i\)th component of \(\mathbf{X}_{\mathrm{C}}\), denoted \({X}_{\mathrm{C},i}\). More...
 
void covarianceWithCV (DoubleMatrix2D covCV)
 Computes the sample covariance of \(\mathbf{X}_{\mathrm{C}}\) by replacing \(\boldsymbol{\Sigma}_{\mathrm{X}}\), \(\boldsymbol{\Sigma}_{\mathrm{C}}\), and \(\boldsymbol{\Sigma}_{\mathrm{CX}}\) with the corresponding matrices of empirical covariances. More...
 
double covarianceWithCV (int i, int j)
 Computes the covariance between component i and j of \(\mathbf{X}_{\mathrm{C}}\). More...
 
void averageWithCV (double[] a)
 Fills the given array with the controlled averages.
 
void averageX (double[] a)
 Fills the given array with the averages without control variables. More...
 
void averageC (double[] a)
 Fills the given array with the averages of the control variables. More...
 
void standardDeviationWithCV (double[] std)
 Fills the given array with the square root of the variance of each component of \(\mathbf{X}_{\mathrm{C}}\).
 
void varianceWithCV (double[] v)
 Fills the given array with the variance of each component of \(\mathbf{X}_{\mathrm{C}}\).
 
void confidenceIntervalStudentWithCV (int i, double level, double[] centerAndRadius)
 Computes a confidence interval for the \(i\)th component of \(\mathbf{X}_{\mathrm{C}}\). More...
 
void estimateBeta ()
 Estimates the \(\boldsymbol{\beta}^*\) matrix from the observations currently in this list of tallies. More...
 
ListOfTalliesWithCV< E > clone ()
 Fills the given list of tallies with controlled observations. More...
 
- Public Member Functions inherited from ListOfTalliesWithCovariance< E extends Tally >
 ListOfTalliesWithCovariance ()
 Creates an empty list of tallies with covariance support. More...
 
 ListOfTalliesWithCovariance (String name)
 Creates an empty list of tallies with covariance support and name name. More...
 
void init ()
 
void add (double[] x)
 Adds a new vector of observations x to this list of tallies, and updates the internal data structures computing averages, and sums of products. More...
 
void add (DoubleMatrix1D x)
 
double covariance (int i, int j)
 
ListOfTalliesWithCovariance< E > clone ()
 Clones this object. More...
 
- Public Member Functions inherited from ListOfTallies< E >
 ListOfTallies ()
 Constructs a new empty list of tallies.
 
 ListOfTallies (String name)
 Constructs a new empty list of tallies with name name. More...
 
void add (double[] x)
 Adds the observation x[i] in tally i of this list, for i = 0,…, size() - 1. More...
 
int numberObs ()
 Assuming that each tally in this list contains the same number of observations, returns the number of observations in tally 0, or 0 if this list is empty. More...
 
boolean areAllNumberObsEqual ()
 Tests that every tally in this list contains the same number of observations. More...
 
void average (double[] r)
 Computes the average for each tally in this list, and stores the averages in the array r. More...
 
void variance (double[] v)
 For each tally in this list, computes the sample variance, and stores the variances into the array v. More...
 
void standardDeviation (double[] std)
 For each tally in this list, computes the sample standard deviation, and stores the standard deviations into the array std. More...
 
double covariance (int i, int j)
 Returns the empirical covariance of the observations in tallies with indices i and j. More...
 
void covariance (DoubleMatrix2D c)
 Constructs and returns the sample covariance matrix for the tallies in this list. More...
 
double correlation (int i, int j)
 Returns the empirical correlation between the observations in tallies with indices i and j. More...
 
void correlation (DoubleMatrix2D c)
 Similar to covariance(DoubleMatrix2D) for computing the sample correlation matrix. More...
 
ListOfTallies< E > clone ()
 Clones this object. More...
 

Static Public Member Functions

static ListOfTalliesWithCV< TallycreateWithTally (int p, int q)
 This factory method constructs and returns a list of tallies with p+q new instances of umontreal.ssj.stat.Tally, q being the number of control variables. More...
 
static ListOfTalliesWithCV< TallyStorecreateWithTallyStore (int p, int q)
 This factory method constructs and returns a list of tallies with p+q new instances of umontreal.ssj.stat.TallyStore, q being the number of control variables. More...
 
- Static Public Member Functions inherited from ListOfTalliesWithCovariance< E extends Tally >
static ListOfTalliesWithCovariance< TallycreateWithTally (int size)
 This factory method constructs and returns a list of tallies with size instances of umontreal.ssj.stat.Tally. More...
 
static ListOfTalliesWithCovariance< TallyStorecreateWithTallyStore (int size)
 This factory method constructs and returns a list of tallies with size instances of umontreal.ssj.stat.TallyStore. More...
 
- Static Public Member Functions inherited from ListOfTallies< E >
static ListOfTallies< TallycreateWithTally (int size)
 This factory method constructs and returns a list of tallies with size instances of umontreal.ssj.stat.Tally. More...
 
static ListOfTallies< TallyStorecreateWithTallyStore (int size)
 This factory method constructs and returns a list of tallies with size instances of umontreal.ssj.stat.TallyStore. More...
 
static ListOfTallies< TallyStorecreateWithTallyStore (int size, int t)
 This factory method constructs and returns a list of tallies with size instances of umontreal.ssj.stat.TallyStore, each of size \(t\). More...
 

Detailed Description

Represents a list of tallies with control variables that inherits the functionalities of a list of tallies, and accepts vectors of length \(p+q\).

The first \(p\) tallies in the list correspond to \(\mathbf{X}\) while the \(q\) last tallies correspond to \(\mathbf{C}\). Methods are provided for adding observations with control variables, and estimating the \(\boldsymbol{\beta}^*\) matrix from the sample covariances. Convenience methods are also provided for the common cases where \(q=1\) and \(p=1\).

During simulation or pilot runs, one uses an add method to add observations with the associated values of the control variables. After the vectors of observations (and controls) are collected, one can obtain an estimate of \(\boldsymbol{\beta}^*\), by using estimateBeta. One can also set \(\boldsymbol{\beta}\) to an arbitrary matrix.

Before obtaining results with control variables, it is important to set the expected values of the controls, by using #setExpectedValues(double[]). After \(E[\mathbf{C}]\) is set, methods are then available to get the controlled average, and the controlled covariance matrix. One can also compute a confidence interval on a component \(X_i\) of \(\mathbf{X}\) taking the control variables into account.

The \(\boldsymbol{\beta}^*\) matrix can be estimated using pilot runs. In this context, if the list of tallies is reset, the values of \(\boldsymbol{\beta}\) and \(E[\mathbf{C}]\) are retained. Observations generated from production runs can then be added to the list of tallies, and the controlled average can be computed.

The following pseudocode illustrates how \(q\) control variables can be used with a \(p\)-dimensional vector, the value of \(E[\mathbf{C}]\) being stored in expControls.

ListOfTalliesWithCV<Tally> list = ListOfTalliesWithCV.createWithTally
(p, q);
list.setExpectedValues (expControls);
// Choose between NO PILOT RUNS or PILOT RUNS
NO PILOT RUNS {
// Make production runs and use list.add to add (X, C) vectors.
list.estimateBeta(); // Biased consistent estimator of the beta
matrix
}
PILOT RUNS {
// Make pilot runs and use list.add to add (X, C) vectors.
list.estimateBeta(); // Unbiased estimator of the beta matrix
list.init();
// Make production runs and use list.add to add (X, C) vectors.
}
// Call list.averageWithCV, list.covarianceWithCV, etc.

Constructor & Destructor Documentation

◆ ListOfTalliesWithCV() [1/2]

Constructs a new empty list of tallies with no control variable.

After calling this constructor, one must fill the list with tallies, call setNumControlVariables, and init.

◆ ListOfTalliesWithCV() [2/2]

ListOfTalliesWithCV ( String  name)

Constructs a new empty list of tallies with no control variable and name name.

After calling this constructor, one must fill the list with tallies, call setNumControlVariables, and init.

Parameters
namethe name of the list.

Member Function Documentation

◆ add() [1/3]

void add ( double []  x,
double []  c 
)

Adds a new observation \((\mathbf{X}, \mathbf{C})\) to this list of tallies.

The array x contains the value for \(\mathbf{X}\), while c contains the value of \(\mathbf{C}\).

Parameters
xthe value of \(\mathbf{X}\).
cthe value of \(\mathbf{C}\).

◆ add() [2/3]

void add ( double  x,
double []  c 
)

Variant of the #add(double[],double[]) method that can be used when there is only one output variable.

Parameters
xthe output variable.
cthe vector of control variables.

◆ add() [3/3]

void add ( double  x,
double  c 
)

Variant of the #add(double[],double[]) that can be used when \(p=q=1\).

Parameters
xthe output variable.
cthe control variable.

◆ averageC()

void averageC ( double []  a)

Fills the given array with the averages of the control variables.

Parameters
athe array to be filled with averages.

◆ averageWithCV()

double averageWithCV ( int  i)

Returns the average of the \(i\)th component of \(\mathbf{X}_{\mathrm{C}}\), denoted \({X}_{\mathrm{C},i}\).

This corresponds to

\[ {X}_{\mathrm{C},i}=X_i - (\boldsymbol{\beta}_{\cdot,i})^{\mathsf{t}}(\mathbf{C}- E[\mathbf{C}]) \]

where \(\boldsymbol{\beta}_{\cdot,i}\) is the \(i\)th column of the \(\boldsymbol{\beta}\) matrix.

Parameters
ithe index of the output variable.
Returns
the controlled average.

◆ averageX()

void averageX ( double []  a)

Fills the given array with the averages without control variables.

Parameters
athe array to be filled with averages.

◆ clone()

ListOfTalliesWithCV<E> clone ( )

Fills the given list of tallies with controlled observations.

The list must have size \(p\), and each element is

\[ \mathbf{X}_{\mathrm{C},i}=\mathbf{X}_i - \boldsymbol{\beta}^{\mathsf{t}}(\mathbf{C}_i - E[\mathbf{C}]), \]

where \(\mathbf{X}_{\mathrm{C},i}\) is the \(i\)th controlled observation, and \(\mathbf{X}_i\) is the \(i\)th observation. This method uses the matrix returned by getBeta, and the expectations returned by getExpectedValues to obtain \(\boldsymbol{\beta}\), and \(E[\mathbf{C}]\). Tallies in this list with control variables must be capable of storing the observations.

Parameters
athe list of tallies to be modified. This is a variant of #addControlledObservations(ListOfTallies) for the case where \(p=1\). Instead of adding the controlled observations in a list of tallies, the method adds them into a regular tally.
tathe tally filled with controlled observations. Clones this object. This clones the list of tallies as well as the data structures holding the sums of products, the \(\boldsymbol{\beta}\) matrix, and the \(\mathbf{C}\) vector, but this does not clone the tallies comprising the list. The created clone is modifiable, even though the original list is unmodifiable.

◆ confidenceIntervalStudentWithCV()

void confidenceIntervalStudentWithCV ( int  i,
double  level,
double []  centerAndRadius 
)

Computes a confidence interval for the \(i\)th component of \(\mathbf{X}_{\mathrm{C}}\).

This is the same as umontreal.ssj.stat.Tally.confidenceIntervalStudent(double,double[]) except that the variance with control variables, obtained by covarianceWithCV (i, i), is used instead of the ordinary variance.

Parameters
ithe index of the component.
levelthe level of confidence of the interval.
centerAndRadiusthe array that will be filled with the center and radius of the interval.

◆ correlationC()

void correlationC ( DoubleMatrix2D  c)

Fills c with the sample correlation matrix of \(\mathbf{C}\).

Parameters
cthe \(q\times q\) matrix filled with correlations.

◆ correlationCX()

void correlationCX ( DoubleMatrix2D  c)

Fills c with the sample correlation matrix of \(\mathbf{C}\) and \(\mathbf{X}\).

Parameters
cthe \(q\times p\) matrix filled with correlations.

◆ correlationX()

void correlationX ( DoubleMatrix2D  c)

Fills c with the sample correlation matrix of \(\mathbf{X}\).

Parameters
cthe \(p\times p\) matrix filled with correlations.

◆ covarianceC()

void covarianceC ( DoubleMatrix2D  c)

Fills c with the sample covariance matrix of \(\mathbf{C}\).

Parameters
cthe \(q\times q\) matrix filled with covariances.

◆ covarianceCX()

void covarianceCX ( DoubleMatrix2D  c)

Fills c with the sample covariance matrix of \(\mathbf{C}\) and \(\mathbf{X}\).

Parameters
cthe \(q\times p\) matrix filled with covariances.

◆ covarianceWithCV() [1/2]

void covarianceWithCV ( DoubleMatrix2D  covCV)

Computes the sample covariance of \(\mathbf{X}_{\mathrm{C}}\) by replacing \(\boldsymbol{\Sigma}_{\mathrm{X}}\), \(\boldsymbol{\Sigma}_{\mathrm{C}}\), and \(\boldsymbol{\Sigma}_{\mathrm{CX}}\) with the corresponding matrices of empirical covariances.

These are obtained by calling covarianceX, covarianceC, and covarianceCX, respectively. This gives an estimate of

\[ \mathrm{Cov}(\mathbf{X}_{\mathrm{C}}) = \boldsymbol{\Sigma}_{\mathrm{X}}+ \boldsymbol{\beta}^{\mathsf{t}}\boldsymbol{\Sigma}_{\mathrm{C}}\boldsymbol{\beta}- 2\boldsymbol{\beta}^{\mathsf{t}}\boldsymbol{\Sigma}_{\mathrm{CX}}. \]

Parameters
covCVthe \(p\times p\) matrix that will be filled with covariances.

◆ covarianceWithCV() [2/2]

double covarianceWithCV ( int  i,
int  j 
)

Computes the covariance between component i and j of \(\mathbf{X}_{\mathrm{C}}\).

This is given by

\[ \mathrm{Cov}({X}_{\mathrm{C},i}, {X}_{\mathrm{C},j}) =\mathrm{Cov}(X_i, X_j) + (\boldsymbol{\beta}_{\cdot, i})^{\mathsf{t}}\boldsymbol{\Sigma}_{\mathrm{C}}\boldsymbol{\beta}_{\cdot, j} - (\boldsymbol{\Sigma}_{\mathrm{CX}, \cdot, i})^{\mathsf{t}}\boldsymbol{\beta}_{\cdot, j} - (\boldsymbol{\Sigma}_{\mathrm{CX}, \cdot, j})^{\mathsf{t}}\boldsymbol{\beta}_{\cdot, i}. \]

Parameters
ithe index of the first component.
jthe index of the second component.
Returns
the covariance.

◆ covarianceX()

void covarianceX ( DoubleMatrix2D  c)

Fills c with the sample covariance matrix of \(\mathbf{X}\).

Parameters
cthe \(p\times p\) matrix filled with covariances.

◆ createWithTally()

static ListOfTalliesWithCV<Tally> createWithTally ( int  p,
int  q 
)
static

This factory method constructs and returns a list of tallies with p+q new instances of umontreal.ssj.stat.Tally, q being the number of control variables.

Parameters
pthe value of \(p\).
qthe value of \(q\).
Returns
the created list.

◆ createWithTallyStore()

static ListOfTalliesWithCV<TallyStore> createWithTallyStore ( int  p,
int  q 
)
static

This factory method constructs and returns a list of tallies with p+q new instances of umontreal.ssj.stat.TallyStore, q being the number of control variables.

Parameters
pthe value of \(p\).
qthe value of \(q\).
Returns
the created list.

◆ estimateBeta()

void estimateBeta ( )

Estimates the \(\boldsymbol{\beta}^*\) matrix from the observations currently in this list of tallies.

This uses covarianceC(DoubleMatrix2D) and covarianceCX(DoubleMatrix2D) to get estimates of \(\boldsymbol{\Sigma}_{\mathrm{C}}\), and \(\boldsymbol{\Sigma}_{\mathrm{CX}}\). The result of the estimation of

\[ \boldsymbol{\beta}^* = \boldsymbol{\Sigma}_{\mathrm{C}}^{-1}\boldsymbol{\Sigma}_{\mathrm{CX}} \]

is stored in the matrix returned by getBeta.

◆ getBeta()

DoubleMatrix2D getBeta ( )

Returns the current matrix \(\boldsymbol{\beta}\).

By default, this matrix is filled with 0’s.

Returns
the \(\boldsymbol{\beta}\) matrix.

◆ getExpectedValue()

double getExpectedValue ( int  i)

Gets the expected value of the \(i\)th control variable.

By default, this is set to 0.

Parameters
ithe index of the control variable.
Returns
the queried expectation.

◆ getExpectedValues()

double [] getExpectedValues ( )

Returns \(E[\mathbf{C}]\), the expected value of the vector of control variables.

Returns
the expected values of the control variables.

◆ getNumControlVariables()

int getNumControlVariables ( )

Returns the number \(q\) of control variables.

Returns
the number of control variables.

◆ setBeta()

void setBeta ( DoubleMatrix2D  beta)

Sets the \(\boldsymbol{\beta}\) matrix to beta.

The given matrix must be \(q\times p\), or an exception is thrown.

Parameters
betathe new \(\boldsymbol{\beta}\) matrix.

◆ setExpectedValue()

void setExpectedValue ( int  i,
double  e 
)

Sets the expected value of the \(i\)th control variable to e.

Parameters
ithe index of the control variable.
ethe new value of the expectation.

◆ setExpectedValues()

void setExpectedValues ( double []  exp)

Sets \(E[\mathbf{C}]\) to exp.

The length of the given array must be \(q\), or an exception is thrown.

Parameters
expthe new expected values for control variables.

◆ setNumControlVariables()

void setNumControlVariables ( int  q)

Sets the number of control variables to q.

The new value of q must not be negative or exceed size(). This method throws an exception if it is called after #init.

Parameters
qthe new number of control variables.

◆ sizeWithoutCV()

int sizeWithoutCV ( )

Returns the size of this list excluding the control variables.

This corresponds to the number of output variables \(p\).

Returns
the size of this list excluding control variables.

The documentation for this class was generated from the following file: