= PDAF_sampleens = 

This page documents the routine `PDAF_sampleens` of PDAF, which was introduced with PDAF V1.12.

This routine generates an ensemble of model states from a provided central state and EOF modes (singular vectors of a perturbation matrix) and singular values (EOF coefficients). The resulting ensemble is the 2nd order-exact sample covariance matrix and mean state. 

The ensemble state vectors are computed as
{{{ ens_i = state + sqrt(dim_ens-1) modes (Omega C)^T }}}
where '''C''' holds in its diagonal the singular values ('''svals''') and '''Omega''' is an orthogonal transformation matrix that preserves the mean state.
The generated ensemble fulfills the condition for the state error covariance matrix, i.e. the sample covariance matrix of the ensemble is the prescriped covariance matrix given by the EOF modes and coefficients.

The routine is typically called in the call-back routine that performs the ensemble initialization ([wiki:init_ens_pdaf init_ens_pdaf]) in the case that one does a start from the covariance matrix. 

The interface is the following:
{{{
SUBROUTINE PDAF_SampleEns(dim, dim_ens, modes, svals, state, &
     ens, flag)
}}}
with the following arguments:
 * `dim` : `integer, intent(in)`[[BR]] Dimension of state vector
 * `dim_ens` : `integer, intent(in)`[[BR]]  Size of ensemble
 * `modes` : `real, intent(inout), dimension(dim, dim_ens-1)`[[BR]] Array of EOF modes (singular vectors)
 * `svals` : `real, intent(in), dimension(dim_ens-1)`[[BR]] Vector of EOF coefficients (singular values)
 * `state` : `real, intent(inout), dimension(dim)`[[BR]] Central state of the ensemble 
 * `ens` : `real, intent(out), dimension(dim, dim_ens)`[[BR]] Created state ensemble
 * `flag` : `integer, intent(out)`[[BR]] Status flag

To use the routine, one has to provide the central state (`state`) as well as the EOF modes (`modes`) and EOF coefficients (`svals`). The routine applies the 2nd order exact sampling and returns the ensemble array `ens` with the prescribed central state as its mean and the covariance matrix according to the EOFs. 

The routine can be conveniently used in combination with the routine [wiki:PDAF_eofcovar PDAF_eofcovar]. This routine computes the EOF modes and coefficients from a model trajectory. It is usually used in a separate program to preprate the EOF information. The EOFs are then stored in a file and read by the ensemble initialization routine ([wiki:init_ens_pdaf init_ens_pdaf]). 

The use of this ensemble generation is demonstrated in the Lorenz-96 model example (see testsuite/src/lorenz96/init_ens_eof.F90). It is also used in the simple 1D test case (see testsuite/src/dummymodel_1D/init_seik_pdaf.F90).