= Implementation of Observation Generation with PDAF =

[[PageOutline(2-3,Contents of this page)]]


== Overview ==

Twin data assimilation experiments are a common approach to assess data assimilation methods. In twin experiments one uses the model to generate a ''true'' model state. Further one generates synthetic observations by adding random perturbations to the true state. The, in the actual twin experiment one starts the data assimilation with a state estimate that is different from the true state and assimilates the synthetic observations. One can analyze the assimilation result by comparing the state estimate from the twin experiment with the previously generated true state.

Starting with version 1.14, PDAF provides functionality to generate synthetic observations. The functionality bases on the normal implementation of the assimilation used with PDAF. However, one can run the observation generation with an ensemble of just one member, which should be initialized with the initial true state. PDAF provides the routines `PDAF_generate_obs` and `PDAF_put_state_generate_obs` to perform the observation generation. These routines use the observation operator routines which the user implements e.g. for assimilating real observations. 

Here we describes the steps need to generate synthetic obsrvations. 

== Initialization ==

The implementation of the initialization of PDAF is explained on the [wikiInitPdaf page on `init_pdaf` and `PDAF_init`].

For the observation generation one just has to set `filtertype = 11`. 

There are no particular options for the observation generation functionality. So for `filter_param_i` one just has to specify the mandatory values of the state dimension and the ensemble size. For `filter_param_r` one has to specify the mandatory values of the forgetting factor (even though, this value is ignored for the observation generation)

== Observation Generation Step ==

This step replaces the analysis step. However, the implementation is analogous to implementing the analysis step as described on the [wiki:ImplementationofAnalysisStep page on implementing the analysis step].

== `PDAF_generate_obs` ==

This routine is used in the same way as the filter specific routines `PDAF_assimilate_*`. Thus the general aspect have been described on the page [ModifyModelforEnsembleIntegration Modification of the model code for the ensemble integration] and its sub-page on [InsertAnalysisStep inserting the analysis step]. The routine `PDAF_generate_obs` is used in the fully-parallel implementation variant of the data assimilation system. When the 'flexible' implementation variant is used, the routines `PDAF_put_state_generate_obs' is used as described further below. Here, we list once more the full interface. Subsequently, the full set of user-supplied routines specified in the call to `PDAF_generate_obs` is explained.

{{{
  SUBROUTINE PDAF_generate_obs(U_collect_state, U_distribute_state, &
                                  U_init_dim_obs_f, U_obs_op_f, U_get_obs_f, U_init_obserr_f, &
                                  U_prepoststep, U_next_observation, status_pdaf)
}}}
with the following arguments:
 * `U_collect_state`: The name of the user-supplied routine that initializes a state vector from the array holding the ensemble of model states from the model fields. This is basically the inverse operation to `U_distribute_state` used in [ModifyModelforEnsembleIntegration#PDAF_get_state PDAF_get_state]
 * `U_distribute_state`:  The name of a user supplied routine that initializes the model fields from the array holding the ensemble of model state vectors.
 * `U_init_dim_obs_f`: The name of the user-supplied routine that provides the size of the full observation vector
 * `U_obs_op_f`: The name of the user-supplied routine that acts as the full observation operator on some state vector
 * `U_get_obs_f`: The name of the user-supplied routine that receives the full vector of generated synthetic observations from PDAF
 * `U_init_obserr_f`: The name of the user-supplied routine that initializes the vector of observations error standard deviations for for full observation vector
 * `U_prepoststep`: The name of the pre/poststep routine as in `PDAF_get_state`
 * `U_next_observation`: The name of a user supplied routine that initializes the variables `nsteps`, `timenow`, and `doexit`. The same routine is also used in `PDAF_get_state`.
 * `status_pdaf`: The integer status flag. It is zero, if `PDAF_assimilate_lestkf` is exited without errors.


== `PDAF_put_state_generate_obs` ==

When the 'flexible' implementation variant is chosen for the assimilation system, the routine `PDAF_put_state_generate_obs` has to be used instead of `PDAF_generate_obs`. The general aspects of the filter specific routines `PDAF_put_state_*` have been described on the page [ModifyModelforEnsembleIntegration Modification of the model code for the ensemble integration]. The interface of the routine is identical with that of `PDAF_generate_obs` with the exception the specification of the user-supplied routines `U_distribute_state` and `U_next_observation` are missing. 

The interface is the following:
{{{
  SUBROUTINE PDAF_put_state_generate_obs(U_collect_state, U_init_dim_obs_f, U_obs_op_f, U_get_obs_f, &
                                  U_init_obserr_f, U_prepoststep, status_pdaf)
}}}