The Application Program Interface

The implementation of the filter routines has been discussed in chapter 7. The names of user supplied subroutines are handled in the framework as subroutine argu-ments in the filter routines and have thus to be specified in the API. This allows the user to choose the subroutine names flexibly.

8.3 Framework for Joint Process Sets for Model

Subroutine Filter Init(type ass,subtype ass,param int,dim pint, param real, dim preal,COM M M ODEL, COM M F ILT ER, COM M COU P LE, modeltask,n modeltasks,f ilterpe,Init Ensemble,verbose,status)

int type ass {Type a filter algorithm, input} int subtype ass {Sub-type of filter, input}

int param int(dim pint) {Array of integer parameters, input} int dim pint {Size of param int, input}

real param real(dim preal) {Array of floating point parameters, input} int dim preal {Size of param real, input}

int COM M M ODEL {Model communicator, input} int COM M F ILT ER {Filter communicator, input} int COM M COU P LE {Coupling communicator, input} int modeltask {Model task the process belongs to, input} int n modeltasks {Number of parallel model tasks, input}

int f ilterpe {Whether the process belongs to the filter processes, input} external Init Ensemble {Subroutine for ensemble initialization, input} int verbose {Whether to print screen information, input}

int status {Output status flag of filter, output}

Algorithm 8.1: Interface to the subroutine Filter Init in the case of joint process sets for model and filter.

are be required for some of the filters. For SEIK and EnKFparam real has a size of 1 and contains only the value of the forgetting factor ρ. For SEEK it is dim preal= 2.

While the first entry of param real specifies the forgetting factor ρ, the second entry sets the value of ² for the gradient approximation of the forecast. The flexible sizes of param int and param real allow for future extensions of the functionality. Next to these variables, the three communicators are handed over to the filter initialization rou-tine. Further, the index modeltask of the model task of the process callingFilter Init and the total number n modeltasks of parallel model tasks is passed to the filter ini-tialization routine. The argument f ilterpe specifies whether a process belongs to the filter processes. The name of the subroutine performing the ensemble generation is the next argument. The interface is completed by an argument which defines whether the filter routines will print out screen information and a final argument which serves as a status flag. It will have a non-zero value if a problem occurred during the initialization.

The subroutineGet State is called in the model source code before the time stepping loop is entered. Get State initializes the state fields of the model and provides the infor-mation on the current model time and the number of time steps to be computed, The interface to this routine is shown as algorithm 8.2. All parameters which are required by the filters have already been specified in the filter initialization. Accordingly, the interface of Get State contains only names of subroutines and output variables which are initialized for the model time stepper. The variables nsteps and time, as well as the status flag status are outputs of the routine. In addition, the names of three sub-routines are specified. The sub-routinesNext Observation and User Analysis have already

Subroutine Get State(nsteps,time,Next Observation,Distribute State, User Analysis,status)

int nsteps {Number of time steps to be performed, output} real time {Model time at begin of evolution, output} external Next Observation

{Subroutine to get number of time steps and current time, input} external Distribute State

{Subroutine to distribute state in COMM MODEL, input} external User Analysis {Subroutine for user analysis, input} int status {Output status flag of filter, output}

Algorithm 8.2: Interface to the subroutine Get State in the case of joint process sets for model and filter.

been described in section 3.3.1. The routineDistribute State transfers a state vector to model fields and distributes these within the model task defined by COMM MODEL.

In the variant with mode-decomposition, the framework itself only initializes a state vector on a single process in each model task. The model-dependent operations are then performed by the routine Distribute State which is described in section 8.5.

Having computed the evolution of a model state, this forecast is stored back in the ensemble or mode matrix of the filter algorithm. This is performed in the rou-tine Put State. If Put State is called after the filter forecast phase has been com-pleted, the analysis and resampling phases are executed by this routine. In its in-terface, the names of several subroutines which are called by the filter analysis and resampling algorithms have to be specified. The observation-related routines Mea-surement Operator, Measurement, RinvA, RplusA, and Get Dim Obs have already Subroutine Put State(Collect State,Get Dim Obs,Measurement Operator,

Measurement,Measurement Ensemble,User Analysis,RinvA,RplusA,status) external Collect State

{Subroutine to collect state vector in COMM MODEL, input} external Get Dim Obs

{Subroutine to provide dimension of observation vector, input} external Measurement Operator

{Subroutine with implementation of measurement operator, input} external Measurement {Subroutine to initialize observation vector, input} external Measurement Ensemble

{Subroutine to initialize ensemble of observation vectors, input} external User Analysis {Subroutine for user analysis, input}

external RinvA {Subroutine for product of R⁻¹ with some matrix, input} external RplusA {Subroutine to add R to some matrix, input}

int status {output status flag of filter, output}

Algorithm 8.3: Interface to the subroutine Put State in the case of joint process sets for model and filter.

been discussed in section 3.3.2. The routine Measurement Ensemble is required in the EnKF. It provides the observation ensemble according to the observation error co-variance matrixR. Collect State performs the operation inverse to that of the routine Distribute State. That is, the ensemble fields in a model task are gathered in a state vector. For mode-decomposed ensemble matrices, the state vector is gathered by a single process of this task. Next to the names of subroutines, the interface ofPut State contains again the status flag status as an output variable.

The routine Put State is generic for all three filter algorithms. Due to this, the interface requires the specification of all possible subroutine names, even if they are not required for all filters. For example, SEEK and SEIK only require the routine RinvA but notRplusA. The latter routine is required by the EnKF analysis while the former one is not used by this filter. To generate an executable program all three routines must be present (possibly as an empty routine, if it is not called by the chosen filter), since they are required for the linker step. To facilitate the implementation if only one filter type is used, we have implemented specific routines likePut State SEEK for the SEEK filter. The interface of the specific put-routines contains only the names of the subroutines relevant for the chosen filter.

It would be possible to avoid the names of subroutines in the calling interfaces to Filter Init, Get State, and Put State. This would simplify the API considerable.

On the other hand this would disable the possibility to use arbitrary names for the subroutines. We prefer this flexibility, since the user is not urged to use specific names for his subroutines.