\svnidlong
{$HeadURL: https://repos.deltares.nl/repos/openda/public/trunk/core/doc/native_model_builders/m06005.tex $}
{$LastChangedDate: 2014-03-05 12:03:01 +0100 (Wed, 05 Mar 2014) $}
{$LastChangedRevision: 4363 $}
{$LastChangedBy: vrielin $}

% Horizontale lijn over de complete breedte van het vel
\newcommand{\horzline}{
\noindent
\begin{picture}(100,1)(1,1)
\put(1,1){\line(1,0){162}}
\end{picture}
}

% Tabbing definities voor functie omscrijvingen
\newcommand{\functab}{==\=====\==========\=====\kill}
\newcommand{\funcdef}[1]{\tt #1\\}
\newcommand{\funcline}[3]{\> {\tt #1} \> {\tt #2} \> #3}

% Tabbing definities voor parameter lijsten
\newcommand{\partab}{=================\========\kill}
\newcommand{\parheader}[1]{{\tt #1}: \\ {\tt Name} \> Description \\}
\newcommand{\parline}[2]{{\tt #1} \>  {#2}} 

%===============================================================================

\odachapter{Using the modelbuilders in COSTA}

{\bf{Remark:}}
COSTA is incorporated in \oda, {\tt /public/core/native/src/cta}.\\

\begin{tabular}{p{4cm}l}
\textbf{Contributed by:} & Nils van Velzen, CTA memo200605\\
\textbf{Last update:}    & \svnfilemonth-\svnfileyear\\
\end{tabular}

\section{Introduction}
The COSTA environment makes a number of building blocks available for
creating data assimilation and calibration systems. Combining and building
new building blocks should be possible with a minimum of effort.

COSTA contains tools for rapidly creating a COSTA model component. These
tools are called modelbuilders. The various modelbuilders are described in
this document.

\section{General description of a model}

COSTA deals with assimilation methods for simulation models. Simulation models
can compute the model state at different time instances. 
\begin{eqnarray}\label{Eq:GeneralModel}
\phi \left( t_0 \right) &=& \phi_0, \nonumber \\
\phi\left( t_{i+1} \right) &=& 
 A \left[ \phi \left(t_i\right), u \left( t_i \right), g\right]
\end{eqnarray}
with
\begin{itemize}
\item $\phi_0$ the initial model state,
\item $\phi\left(t\right)$ the model state at time $t$,
\item $A$ the operator that computes one time-step of the numerical
      simulation model,
\item $u\left(t\right)$ the time dependent forcings at
      time $t$,
\item $g$ the time independent model parameters
\end{itemize}

The model as stated in Equation \ref{Eq:GeneralModel} is a general form.
This means that it is not mandatory that all arguments exist in the model.
An extreme example is the model, as specified by Equation
\ref{Eq:Calibration} that can be used in a calibration context where an
optimal value for $g$ is determined using observed data.
\begin{equation}\label{Eq:Calibration}
\phi = A \left[g\right]
\end{equation}

\section{SP Model builder}
The SP modelbuilder (Single processor) can be used to create
sequential (non-parallel) model components. The SP modelbuilder handles the
storage and administration of the model-instance specific data. By using
this modelbuilder it is possible to create a full working COSTA model
component by only implementing a very small number of routines.

The routines that are supported in the current version of the SP Model
builder are:
\begin{itemize}
\item cta\_model\_create
\item cta\_model\_free (not yet supported)
\item cta\_model\_compute
\item cta\_model\_setstate
\item cta\_model\_getstate
\item cta\_model\_axpymodel
\item cta\_model\_axpystate
\item cta\_model\_setforc   (not yet supported)
\item cta\_model\_getforc   (not yet supported)
\item cta\_model\_axpyforc
\item cta\_model\_setparam  (not yet supported)
\item cta\_model\_getparam  (not yet supported)
\item cta\_model\_axpyparam (not yet supported)
\item cta\_model\_getnoisecount
\item cta\_model\_getnoisecovar
\item cta\_model\_getobsvalues
\item cta\_model\_getobsselect
\item cta\_model\_addnoise 
\end{itemize}

Not all methods are supported in the current release of the modelbuilder.
The modelbuilder will support in the near future however.

Using the modelbuilder the model programmer only needs to implement a small
number of subroutines. The modelbuilder will use these subroutines for
implementing all methods. The subroutines that must be provided by the
model programmer and their interface are given in the following sections.

\subsection{Create a new model instance}
This routine creates and initialises a new model instance.

\horzline
\begin{tabbing}
\functab
\funcdef{USR\_CREATE(hinput, state, sbound, sparam, nnoise, \\
\hspace{2.2cm}       time0, snamnoise, husrdata, ierr)}
\funcline{IN} {hinput}    {Model configuration CTA\_Tree of CTA\_String}\\
\funcline{OUT}{state}     {Model state (initialized to initial value}\\
\funcline{}   {}          {Note this statevector must be created}\\
\funcline{OUT}{sbound}    {State-vector for the offset on the forcings.}\\
\funcline{}   {}          {CTA\_NULL if not used}\\
\funcline{}   {}          {Note this statevector must be created}\\
\funcline{OUT}{nnoise}    {The number of noise parameters in model state}\\
\funcline{}   {}          {is 0 in case of a deterministic model}\\
\funcline{OUT}{time0}     {Time instance of the initial state state}\\
\funcline{}   {}          {The time object is already allocated}\\
\funcline{OUT}{snamnoise} {Name of the substate containing the noise parameters}\\
\funcline{}   {}          {The string object is already allocated}\\
\funcline{OUT}{husrdata}  {Handle that can be used for storing instance specific data}\\
\funcline{OUT}{ierr}      {Return flag CTA\_OK if successful}\\


\end{tabbing}
\horzline

\begin{verbatim}
   void usr_create(CTA_Handle *hinput,  CTA_State *state, CTA_State sbound, 
                    CTA_State *sparam, int *nnoise, CTA_Time time0, 
                    CTA_String *snamnoise, CTA_Handle *husrdata, int *ierr)
\end{verbatim}

\begin{verbatim}
   USR_CREATE(hinput, state, sbound, sparam, nnoise, time0, 
               snamnoise, husrdata, ierr)
   integer hinput, state, sbound, sparam, nnoise, time0 
   integer snamnoise, husrdata, ierr
\end{verbatim}

\subsection{Compute}
This routine is computes several timesteps over a giving timespan.

\horzline
\begin{tabbing}
\functab
\funcdef{USR\_COMPUTE(timespan,state, saxpyforc, baddnoise, sparam, husrdata, ierr)}
\funcline{IN}     {timespan}  {Timespan to simulate}\\
\funcline{IN/OUT} {state}     {State vector}\\
\funcline{IN}     {saxpyforc} {Offset on models forcings}\\
\funcline{IN}     {baddnoise} {flag (CTA\_TRUE/CTA\_FALSE) whether to add noise}\\
\funcline{IN}     {sparam}    {Model parameters}\\
\funcline{IN/OUT} {husrdata}  {Instance specific data}\\
\funcline{OUT}    {ierr}      {Return flag CTA\_OK if successful}\\
\end{tabbing}
\horzline

\begin{verbatim}
   void USR_COMPUTE(CTA_Time *timespan, CTA_State *state, CTA_State *saxpyforc,
                     int *baddnoise, CTA_State *sparam, CTA_HAndle *husrdata,
                     int *ierr)
\end{verbatim}

\begin{verbatim}
   USR_COMPUTE(timespan,state, saxpyforc, baddnoise, sparam, husrdata, ierr)
   integer timespan,state, saxpyforc, baddnoise, sparam, husrdata, ierr
\end{verbatim}

\subsection{Covariance matrix of the noise parameters}
This routine is responsible for returning the covariance matrix of the noise parameters.

\horzline
\begin{tabbing}
\functab
\funcdef{USR\_COVAR(colsvar,nnoise, husrdata, ierr)}
\funcline{OUT} {colsvar(nnoise)}   {covariance of noise parameters array of noise}\\
\funcline{}    {}                  {Note the substates are already allocated}\\
\funcline{IN}     {nnoise}    {Number of noise parameters}\\
\funcline{IN/OUT} {husrdata}  {Instance specific data}\\
\funcline{OUT}    {ierr}      {Return flag CTA\_OK if successful}\\
\end{tabbing}
\horzline

\begin{verbatim}
   void usr_covar(CTA_State *colsvar, int *nnoise, CTA_Handle *husrdata, int *ierr)
\end{verbatim}

\begin{verbatim}
   USR_COVAR(colsvar, nnoise, husrdata, ierr)
   integer nnoise, husrdata, ierr
   integer colsvar(nnoise)
\end{verbatim}

\subsection{Model state to observations}
This routine is responsible for the transformation of the state-vector to the observations. 

\horzline
\begin{tabbing}
\functab
\funcdef{USR\_OBS(state, hdescr, vval, husrdata, ierr)}
\funcline{IN}  {state}        {state vector}\\
\funcline{IN}  {hdescr}       {Observation description of observations}\\
\funcline{OUT} {vval}         {Model (state) values corresponding to observations in hdescr}\\
\funcline{IN/OUT} {husrdata}  {Instance specific data}\\
\funcline{OUT}    {ierr}      {Return flag CTA\_OK if successful}\\
\end{tabbing}
\horzline

\begin{verbatim}
   void usr_obs(CTA_State *state, CTA_ObsDescr *hdescr, CTA_Vector *vval,
                CTA_Handle *husrdata, int *ierr)
\end{verbatim}

\begin{verbatim}
   USR_OBS(state, hdescr, vval, husrdata, ierr)
   integer state, hdescr, vval, husrdata, ierr
\end{verbatim}

\subsection{Observation selection}
This routine is responsible for producing a selection criterion that will filter out all invalid observations.
Invalid observations are observations for which the model cannot produce a corresponding value. For example
observations that are outside the computational domain.

\horzline
\begin{tabbing}
\functab
\funcdef{USR\_OBSSEL(state, ttime, hdescr, sselect, husrdata, ierr)}
\funcline{IN} {state}  {state vector} \\
\funcline{IN} {ttime}  {timespan for selection} \\
\funcline{IN} {hdescr} {observation description of all available observations}  \\
\funcline{OUT} {sselect} {The select criterion to filter out all invalid observations}\\
\funcline{IN/OUT} {husrdata}  {Instance specific data}\\
\funcline{OUT}    {ierr}      {Return flag CTA\_OK if successful}\\
\end{tabbing}
\horzline

\begin{verbatim}
   void usr_obssel(CTA_State *state, CTA_Time *ttime, CTA_ObsDescr *hdescr,
           CTA_String *sselect, CTA_Handle *husrdata, int* ierr)
\end{verbatim}

\begin{verbatim}
   USR_OBSSEL(state, ttime, hdescr, sselect, husrdata, ierr)
   integer state, ttime, hdescr, sselect, husrdata, ierr
\end{verbatim}

\subsection{xml-configuration}
The modelbuilder need to be configured in order to create a new model. This
configuration specifies which functions
are provided to implement the model.

The configuration has the following form (in xml)
\begin{verbatim}
<modelbuild_sp> 
<functions>
   <!-- The functions that implement the model -->
   <create>my_create</create>
   <covariance>my_covar</covariance>
   <getobsvals>my_obs</getobsvals>
   <compute>my_compute</compute>
   <getobssel>my_getobssel</getobssel>
   <model>
   <!-- Everything overhere is passed through to the model (input argument hinput of the create routine) -->
   </model>
</functions>
</modelbuild_sp> 

\end{verbatim}
This configuration file is read into a COSTA-tree and is used as input
argument for each instance that is created.

The names of the functions eg. my\_compute, correspond to the name specified when administrating the function in
COSTA using the {\tt cta\_func\_create}. 

Future versions of the modelbuilder will support dynamic linking to the user functions. When this is supported it
will be possible to directly link the routines from the dynamic link library. 

\subsection{Examples}
The modelbuilder is used for the models lorenz96, lorenz, and oscill in the COSTA model-directory. These models are
a source of information concerning the use of this modelbuilder.


