Index: trunk/DOC/NEMO_book.tex
===================================================================
--- trunk/DOC/NEMO_book.tex	(revision 1225)
+++ trunk/DOC/NEMO_book.tex	(revision 1320)
@@ -180,5 +180,5 @@
 \rule{345pt}{1.5pt} \\ 
 %{\small NEMO v2.3} \\
-{\small  -- version 3.0 --}   }
+{\small  -- version 3.1 --}   }
 %{ -- Draft --}   }
 %\date{\today}
Index: trunk/DOC/TexFiles/Chapters/Chap_SBC.tex
===================================================================
--- trunk/DOC/TexFiles/Chapters/Chap_SBC.tex	(revision 1225)
+++ trunk/DOC/TexFiles/Chapters/Chap_SBC.tex	(revision 1320)
@@ -27,11 +27,16 @@
 (\np{ln\_cpl}=true). The frequency at which the six fields have to be updated is
 the  \np{nf\_sbc} namelist parameter. 
+When the fields are supplied from data files (flux and bulk formulations), the input fields 
+need not be supplied on the model grid.  Instead a file of coordinates and weights can be supplied which
+maps the data from the supplied grid to the model points (so called "Interpolation on the Fly").
 In addition, the resulting fields can be further modified using 
-several namelist options. These options control the addition of a surface restoring 
-term to observed SST and/or SSS (\np{ln\_ssr}=true), the modification of fluxes 
+several namelist options. These options control  the rotation of vector components
+supplied relative to an east-north coordinate system onto the local grid directions in the model;
+the addition of a surface restoring 
+term to observed SST and/or SSS (\np{ln\_ssr}=true); the modification of fluxes 
 below ice-covered areas (using observed ice-cover or a sea-ice model) 
-(\np{nn\_ice}=0,1, 2 or 3), the addition of river runoffs as surface freshwater 
-fluxes (\np{ln\_rnf}=true), the addition of a freshwater flux adjustment in 
-order to avoid a mean sea-level drift (\np{nn\_fwb}= 0, 1 or 2), and the 
+(\np{nn\_ice}=0,1, 2 or 3); the addition of river runoffs as surface freshwater 
+fluxes (\np{ln\_rnf}=true); the addition of a freshwater flux adjustment in 
+order to avoid a mean sea-level drift (\np{nn\_fwb}= 0, 1 or 2); and the 
 transformation of the solar radiation (if provided as daily mean) into a diurnal 
 cycle (\np{ln\_dm2dc}=true).
@@ -39,5 +44,6 @@
 In this chapter, we first discuss where the surface boundary condition 
 appears in the model equations. Then we present the four ways of providing 
-the surface boundary condition. Finally, the different options that further modify 
+the surface boundary condition. Next the scheme for interpolation on the fly is described.
+Finally, the different options that further modify
 the fluxes applied to the ocean are discussed.
 
@@ -101,5 +107,5 @@
 For example:
 
-When rigid-lid assumption is made, the ocean volume becomes constant and 
+When the rigid-lid assumption is made, the ocean volume becomes constant and 
 thus, EMP$=$0, not EMP$_{S }$.
 
@@ -110,5 +116,5 @@
 only the volume flux. In addition, in the current version of \NEMO, the 
 sea-ice is assumed to be above the ocean. Freezing/melting does not change 
-the ocean volume (not impact on EMP) but it modifies the SSS.
+the ocean volume (no impact on EMP) but it modifies the SSS.
 %gm  \colorbox{yellow}{(see {\S} on LIM sea-ice model)}.
 
@@ -354,4 +360,107 @@
 atmospheric GCM (ARPEGE, ECHAM, ECMWF, HadAM, LMDz).
 
+% ================================================================
+% Interpolation on the Fly
+% ================================================================
+
+\section [Interpolation on the Fly] {Interpolation on the Fly}
+\label{SBC_iof}
+
+Interpolation on the Fly allows the user to supply input files required
+for the surface forcing on grids other than the model grid.
+To do this he or she must supply, in addition to the source data file,
+a file of weights to be used to interpolate from the data grid to the model
+grid.
+The original development of this code used the SCRIP package (freely available 
+under a copyright agreement from http://climate.lanl.gov/Software/SCRIP).
+In principle, any package can be used to generate the weights, but the
+variables in the input weights file must have the same names and meanings as
+assumed by the model.
+Two methods are currently available: bilinear and bicubic interpolation.
+
+\subsection{Bilinear Interpolation}
+\label{SBC_iof_bilinear}
+
+The input weights file in this case has two sets of variables: src01, src02,
+src03, src04 and wgt01, wgt02, wgt03, wgt04.
+The "src" variables correspond to the point in the input grid to which the weight
+"wgt" is to be applied. Each src value is an integer corresponding to the index of a 
+point in the input grid when written as a one dimensional array.  For example, for an input grid
+of size 5x10, point (3,2) is referenced as point 8, since (2-1)*5+3=8.
+There are four of each variable because bilinear interpolation uses the four points defining
+the grid box containing the point to be interpolated.
+All of these arrays are on the model grid, so that values src01(i,j) and
+wgt01(i,j) are used to generate a value for point (i,j) in the model.
+
+Symbolically, the algorithm used is:
+
+\begin{equation}
+f_{m}(i,j) = f_{m}(i,j) + \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))}
+\end{equation}
+where function idx() transforms a one dimensional index src(k) into a two dimensional index,
+and wgt(1) corresponds to variable "wgt01" for example.
+
+\subsection{Bicubic Interpolation}
+\label{SBC_iof_bicubic}
+
+Again there are two sets of variables: "src" and "wgt".
+But in this case there are 16 of each.
+The symbolic algorithm used to calculate values on the model grid is now:
+
+\begin{multline*}
+f_{m}(i,j) = f_{m}(i,j) + \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))}
+\\
+                        + \sum_{k=5}^{8} {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }
+\\
+                        + \sum_{k=9}^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} }
+\\
+                        + \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} }
+\end{multline*}
+The gradients here are taken with respect to the horizontal indices and not distances since the spatial dependency has been absorbed into the weights.
+
+\subsection{Implementation}
+\label{SBC_iof_imp}
+
+To activate this option, a non-empty string should be supplied in the weights filename column of the relevant namelist;
+if this is left as an empty string no action is taken.
+In the model, weights files are read in and stored in a structured type (WGT) in the fldread module, as and when they are first required.
+This initialisation procedure tries to determine whether the input data grid should be treated as cyclical or not.
+(In fact this only matters when bicubic interpolation is required.)
+To do this the model looks in the input data file (i.e. the data to which the weights are to be applied) for a variable with name "nav\_lon" or "lon".
+If found, it checks the difference between the first and last values of longitude along a single row.
+If the absolute value of this difference is close to 360 degrees or less than twice the maximum spacing from 360 degrees, the grid is assumed to be cyclical, and the difference determines whether the first column is a repeat of the last one or not.
+If neither "nav\_lon" or "lon" can be found, the model resorts to looking at the first and last columns of data.
+If the sum of the absolute values of the differences between the columns is very small, then the grid is assumed to be cyclical with coincident first and last columns.
+If both of these tests fail, the grid is assumed not to be cyclical.
+
+Next the routine reads in the weights.
+Bicubic interpolation is assumed if it finds a variable with name "src05", otherwise bilinear interpolation is used.
+The WGT structure includes dynamic arrays both for the storage of the weights (on the model grid), and when required, for reading in the variable to be interpolated (on the input data grid).
+The size of the input data array is determined by examining the values in the "src" arrays to find the minimum and maximum i and j values required.
+Since bicubic interpolation requires the calculation of gradients at each point on the grid, the corresponding arrays are dimensioned with a halo of width one grid point all the way around.
+When the array of points from the data file is adjacent to an edge of the data grid, the halo is either a copy of the row/column next to it (non-cyclical case), or is a copy of one from the first two rows/columns on the opposite side of the grid (cyclical case with coincident end rows/columns, or cyclical case with non-coincident end rows/columns).
+
+\subsection{Limitations}
+\label{SBC_iof_lim}
+
+\begin{description}
+\item
+Input data grids must be logically rectangular.
+\item
+This code is not guaranteed to produce positive definite answers from positive definite inputs.
+\item
+The cyclic condition is only applied on left and right columns, and not to top and bottom rows.
+\item
+The gradients across the ends of a cyclical grid assume that the grid spacing between the two columns involved are consistent with the weights used.
+\item
+Neither interpolation scheme is conservative.
+(There is a conservative scheme available in SCRIP, but this has not been implemented.)
+\end{description}
+
+\subsection{Utilities}
+\label{SBC_iof_util}
+
+% to be completed
+A set of utilities to create a weights file for a rectilinear input grid is available.
 
 % ================================================================
@@ -360,4 +469,23 @@
 \section{Miscellaneous options}
 \label{SBC_misc}
+
+% -------------------------------------------------------------------------------------------------------------
+%        Rotation of vector pairs onto the model grid directions
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Rotation of vector pairs onto the model grid directions}
+\label{SBC_rotation}
+
+When using a flux (\np{ln\_flx}=true) or bulk (\np{ln\_clio}=true or \np{ln\_core}=true) formulation, 
+pairs of vector components can be rotated from east-north directions onto the local grid directions.  
+This is particularly useful when interpolation on the fly is used since here any vectors are likely to be defined 
+relative to a rectilinear grid.
+To activate this option a non-empty string is supplied in the rotation pair column of the relevant namelist.
+The eastward component must start with "U" and the northward component with "V".  
+The remaining characters in the strings are used to identify which pair of components go together.
+So for example, strings "U1" and "V1" next to "utau" and "vtau" would pair the wind stress components together
+and rotate them on to the model grid directions; "U2" and "V2" could be used against a second pair of components, 
+and so on.
+The extra characters used in the strings are arbitrary.
+The rot\_rep routine from the \mdl{geo2ocean} module is used to perform the rotation.
 
 % -------------------------------------------------------------------------------------------------------------
Index: trunk/DOC/TexFiles/Namelist/namsbc_clio
===================================================================
--- trunk/DOC/TexFiles/Namelist/namsbc_clio	(revision 1225)
+++ trunk/DOC/TexFiles/Namelist/namsbc_clio	(revision 1320)
@@ -4,11 +4,12 @@
 !              !      file name     ! frequency (hours) !  variable  ! time interpol. !  clim   ! 'yearly' or !
 !              !                    !  (if <0  months)  !    name    !    (logical)   !  (T/F)  !  'monthly'  !
-   sn_utau     =    'taux_1m'       ,       -1.         , 'sozotaux' ,    .true.      , .true.  ,   'yearly'    
-   sn_vtau     =    'tauy_1m'       ,       -1.         , 'sometauy' ,    .true.      , .true.  ,   'yearly'    
-   sn_wndm     =    'flx'           ,       -1.         , 'socliowi' ,    .true.      , .true.  ,   'yearly'      
-   sn_tair     =    'flx'           ,       -1.         , 'socliot2' ,    .true.      , .true.  ,   'yearly'     
-   sn_humi     =    'flx'           ,       -1.         , 'socliohu' ,    .true.      , .true.  ,   'yearly'    
-   sn_ccov     =    'flx'           ,       -1.         , 'socliocl' ,    .false.     , .true.  ,   'yearly'      
-   sn_prec     =    'flx'           ,       -1.         , 'socliopl' ,    .false.     , .true.  ,   'yearly'       
+   sn_utau      =    'taux_1m'       ,      -12.         , 'sozotaux' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_vtau      =    'tauy_1m'       ,      -12.         , 'sometauy' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_wndm      =    'flx'           ,      -12.         , 'socliowi' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_tair      =    'flx'           ,      -12.         , 'socliot1' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_humi      =    'flx'           ,      -12.         , 'socliohu' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_ccov      =    'flx'           ,      -12.         , 'socliocl' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_prec      =    'flx'           ,      -12.         , 'socliopl' ,     .false.        ,    1   ,    0     , ''       , ''
+
 !
    cn_dir      = './'      !  root directory for the location of the bulk files are
Index: trunk/DOC/TexFiles/Namelist/namsbc_core
===================================================================
--- trunk/DOC/TexFiles/Namelist/namsbc_core	(revision 1225)
+++ trunk/DOC/TexFiles/Namelist/namsbc_core	(revision 1320)
@@ -4,12 +4,12 @@
 !              !   file name        ! frequency (hours) ! variable   ! time interpol. !  clim   ! 'yearly' or !
 !              !                    !  (if <0  months)  !   name     !    (logical)   !  (T/F)  !  'monthly'  !
-   sn_wndi     =    'u10'           ,       24.         , 'U_10_MOD' ,    .false.     , .true.  ,   'yearly'    
-   sn_wndj     =    'v10'           ,       24.         , 'V_10_MOD' ,    .false.     , .true.  ,   'yearly'    
-   sn_qsr      =    'rad'           ,       24.         , 'SWDN_MOD' ,    .false.     , .true.  ,   'yearly'      
-   sn_qlw      =    'rad'           ,       24.         , 'LWDN_MOD' ,    .false.     , .true.  ,   'yearly'      
-   sn_tair     =    't10'           ,       24.         , 'T_10_MOD' ,    .false.     , .true.  ,   'yearly'     
-   sn_humi     =    'q10'           ,       24.         , 'Q_10_MOD' ,    .false.     , .true.  ,   'yearly'    
-   sn_prec     =    'precip'        ,       -1.         , 'RAIN'     ,    .false.     , .true.  ,   'yearly'      
-   sn_snow     =    'precip'        ,       -1.         , 'SNOW'     ,    .false.     , .true.  ,   'yearly'       
+   sn_wndi      =    'u10'           ,       24.         , 'U_10_MOD' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_wndj      =    'v10'           ,       24.         , 'V_10_MOD' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_qsr       =    'rad'           ,       24.         , 'SWDN_MOD' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_qlw       =    'rad'           ,       24.         , 'LWDN_MOD' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_tair      =    't10'           ,       24.         , 'T_10_MOD' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_humi      =    'q10'           ,       24.         , 'Q_10_MOD' ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_prec      =    'precip'        ,      -12.         , 'RAIN'     ,     .false.        ,    1   ,    0     , ''       , ''
+   sn_snow      =    'precip'        ,      -12.         , 'SNOW'     ,     .false.        ,    1   ,    0     , ''       , ''
 !
    cn_dir      = './'      !  root directory for the location of the bulk files
Index: trunk/DOC/TexFiles/Namelist/namsbc_flx
===================================================================
--- trunk/DOC/TexFiles/Namelist/namsbc_flx	(revision 1225)
+++ trunk/DOC/TexFiles/Namelist/namsbc_flx	(revision 1320)
@@ -4,9 +4,9 @@
 !              !      file name     ! frequency (hours) !  variable  ! time interpol. !  clim   ! 'yearly' or !
 !              !                    !  (if <0  months)  !    name    !    (logical)   !  (T/F)  !  'monthly'  !
-   sn_utau     =      'utau'        ,        24.        ,    'utau'  ,     .false.    , .false. ,   'yearly'
-   sn_vtau     =      'vtau'        ,        24.        ,    'vtau'  ,     .false.    , .false. ,   'yearly'
-   sn_qtot     =      'qtot'        ,        24.        ,    'qtot'  ,     .false.    , .false. ,   'yearly'
-   sn_qsr      =      'qsr'         ,        24.        ,    'qsr'   ,     .false.    , .false. ,   'yearly'
-   sn_emp      =      'emp'         ,        24.        ,    'emp'   ,     .false.    , .false. ,   'yearly'
+   sn_utau      =      'utau.nc'     ,        24.        ,  'utau'  ,      .false.       ,    0   ,     0    , ''       , ''
+   sn_vtau      =      'vtau.nc'     ,        24.        ,  'vtau'  ,      .false.       ,    0   ,     0    , ''       , ''
+   sn_qtot      =      'qtot.nc'     ,        24.        ,  'qtot'  ,      .false.       ,    0   ,     0    , ''       , ''
+   sn_qsr       =      'qsr.nc'      ,        24.        ,  'qsr'   ,      .false.       ,    0   ,     0    , ''       , ''
+   sn_emp       =      'emp.nc'      ,        24.        ,  'emp'   ,      .false.       ,    0   ,     0    , ''       , ''
 !
    cn_dir      = './'      !  root directory for the location of the flux files
Index: trunk/DOC/TexFiles/Namelist/namsbc_rnf
===================================================================
--- trunk/DOC/TexFiles/Namelist/namsbc_rnf	(revision 1225)
+++ trunk/DOC/TexFiles/Namelist/namsbc_rnf	(revision 1320)
@@ -4,6 +4,6 @@
 !               !   file name        ! frequency (hours) ! variable   ! time interpolation !  clim  ! starting !
 !               !                    !   (if <0  months) !   name     !     (logical)      !  (0/1) !  record  !
-   sn_rnf       = 'runoff_1m_nomask' ,        -1.        , 'sorunoff' ,      .true.        ,    1   ,    0     
-   sn_cnf       = 'runoff_1m_nomask' ,         0.        , 'socoefr'  ,      .false.       ,    1   ,    0              
+   sn_rnf     = 'runoff_1m_nomask.nc' ,      -12.        ,  'sorunoff',      .true.        ,    1   ,    0     , ''       , ''
+   sn_cnf     = 'runoff_1m_nomask.nc' ,        0.        ,  'socoefr' ,      .false.       ,    1   ,    0     , ''       , ''
 !
    cn_dir       = './'       ! directory in which the model is executed
Index: trunk/DOC/TexFiles/Namelist/namsbc_ssr
===================================================================
--- trunk/DOC/TexFiles/Namelist/namsbc_ssr	(revision 1225)
+++ trunk/DOC/TexFiles/Namelist/namsbc_ssr	(revision 1320)
@@ -4,6 +4,6 @@
 !              !     file name      ! frequency (hours) ! variable   ! time interpol. !  clim   ! 'yearly' or !
 !              !                    !  (if <0  months)  !   name     !    (logical)   !  (T/F)  !  'monthly'  !
-   sn_sst      =    'sst_data'     ,        24.        ,  'sst'     ,     .false.    , .false. ,   'yearly'
-   sn_sss      =    'sss_data'     ,        -1.        ,  'sss'     ,     .true.     , .true.  ,   'yearly'
+   sn_sst       =  'sst_data.nc'     ,         24.       ,  'sst'     ,      .false.       ,    0   ,    0
+   sn_sss       =  'sss_data.nc'     ,        -12.       ,  'sss'     ,      .true.        ,    0   ,    0
 !   
    cn_dir      = './'      !  root directory for the location of the runoff files
@@ -12,3 +12,3 @@
    dqdt        =   -40.    !  magnitude of the retroaction on temperature   [W/m2/K]
    deds        =   -27.7   !  magnitude of the damping on salinity   [mm/day/psu]
-/      
+/
