--- manual/s_phys_pkgs/text/exf.tex	2005/07/14 21:04:52	1.1
+++ manual/s_phys_pkgs/text/exf.tex	2009/01/27 15:47:59	1.12
@@ -1,11 +1,12 @@
-\section{EXF: The external forcing package
+\subsection{EXF: The external forcing package
 \label{sec:pkg:exf}}
 \begin{rawhtml}
 <!-- CMIREDIR:sectionexf: -->
 \end{rawhtml}
 
+Authors: Patrick Heimbach and Dimitris Menemenlis
 
-\subsection{Introduction
+\subsubsection{Introduction
 \label{sec:pkg:exf:intro}}
 
 The external forcing package, in conjunction with the
@@ -21,7 +22,7 @@
 CPP options enable or disable different aspects of the package
 (Section \ref{sec:pkg:exf:config}).
 Runtime options, flags, filenames and field-related dates/times are
-set in \texttt{data.exf} and \texttt{data.exf\_clim}
+set in \texttt{data.exf}
 (Section \ref{sec:pkg:exf:runtime}).
 A description of key subroutines is given in Section
 \ref{sec:pkg:exf:subroutines}.
@@ -31,25 +32,44 @@
 
 %----------------------------------------------------------------------
 
-\subsection{EXF configuration \& compiling
+\subsubsection{EXF configuration, compiling \& running}
+
+\paragraph{Compile-time options
 \label{sec:pkg:exf:config}}
+~
 
 As with all MITgcm packages, EXF can be turned on or off at compile time
-using the \texttt{packages.conf} file or the \texttt{genmake2}
-\texttt{-enable=exf} or \texttt{-disable=exf} switches.
+%
+\begin{itemize}
+%
+\item
+using the \texttt{packages.conf} file by adding \texttt{exf} to it,
+%
+\item
+or using \texttt{genmake2} adding
+\texttt{-enable=exf} or \texttt{-disable=exf} switches
+%
+\item
+\textit{required packages and CPP options}: \\
+EXF requires the calendar package \texttt{cal} to be enabled;
+no additional CPP options are required.
+%
+\end{itemize}
+(see Section \ref{sect:buildingCode}).
 
-Parts of the exf code can be enabled or disabled at compile time
+Parts of the EXF code can be enabled or disabled at compile time
 via CPP preprocessor flags. These options are set in either
 \texttt{EXF\_OPTIONS.h} or in \texttt{ECCO\_CPPOPTIONS.h}.
 Table \ref{tab:pkg:exf:cpp} summarizes these options.
 
 \begin{table}[b!]
+\centering
   \label{tab:pkg:exf:cpp}
   {\footnotesize
     \begin{tabular}{|l|l|}
-      \hline
+      \hline 
       \textbf{CPP option}  &  \textbf{Description}  \\
-      \hline
+      \hline \hline
         \texttt{EXF\_VERBOSE} & 
           verbose mode (recommended only for testing) \\
         \texttt{ALLOW\_ATM\_TEMP} & 
@@ -57,23 +77,24 @@
         \texttt{ALLOW\_ATM\_WIND} & 
           compute wind stress from wind speed input\\
         \texttt{ALLOW\_BULKFORMULAE} & 
-          is used if either ALLOW\_ATM\_TEMP or ALLOW\_ATM\_WIND is enabled \\
+          is used if \texttt{ALLOW\_ATM\_TEMP} or 
+          \texttt{ALLOW\_ATM\_WIND} is enabled \\
         \texttt{EXF\_READ\_EVAP} & read evaporation instead of computing it \\
         \texttt{ALLOW\_RUNOFF} & read time-constant river/glacier run-off field \\
         \texttt{ALLOW\_DOWNWARD\_RADIATION} & compute net from downward or downward from net radiation \\
         \texttt{USE\_EXF\_INTERPOLATION} & enable on-the-fly bilinear or bicubic interpolation of input fields \\
       \hline
-        \texttt{ALLOW\_CLIMTEMP\_RELAXATION} & 
-          relaxation to 3-D potential temperature field \\
-        \texttt{ALLOW\_CLIMSALT\_RELAXATION} & 
-          relaxation to 3-D salinity field \\
+         \multicolumn{2}{|c|}{\textit{used in conjunction with relaxation to prescribed (climatological) fields}} \\
+         \hline
         \texttt{ALLOW\_CLIMSST\_RELAXATION} &
-          relaxation to 2-D SST relaxation \\
+          relaxation to 2-D SST climatology \\
         \texttt{ALLOW\_CLIMSSS\_RELAXATION} &
-          relaxation to 2-D SSS relaxation  \\
+          relaxation to 2-D SSS climatology  \\
       \hline
-        \texttt{SHORTWAVE\_HEATING} & in \texttt{CPP\_OPTIONS.h}: enable shortwave radiation \\
-        \texttt{ATMOSPHERIC\_LOADING} &  in \texttt{CPP\_OPTIONS.h}: enable surface pressure forcing \\
+         \multicolumn{2}{|c|}{\textit{these are set outside of EXF in} \texttt{CPP\_OPTIONS.h}} \\
+         \hline
+        \texttt{SHORTWAVE\_HEATING} & enable shortwave radiation \\
+        \texttt{ATMOSPHERIC\_LOADING} & enable surface pressure forcing \\
       \hline
     \end{tabular}
   }
@@ -83,155 +104,463 @@
 
 %----------------------------------------------------------------------
 
-\subsection{EXF runtime parameters
+\subsubsection{Run-time parameters
 \label{sec:pkg:exf:runtime}}
 
+Run-time parameters are set in files 
+\texttt{data.pkg}, \texttt{data.exf}, and 
+\texttt{data.exf\_clim} (for relaxation/climatological fields)
+which are read in \texttt{exf\_readparms.F}.
+Run-time parameters may be broken into 3 categories:
+(i) switching on/off the package at runtime,
+(ii) general flags and parameters, and
+(iii) attributes for each forcing and climatological field.
+
+\paragraph{Enabling the package}
+~ \\
+%
+A package is switched on/off at runtime by setting
+(e.g. for EXF) \texttt{useEXF = .TRUE.} in \texttt{data.pkg}.
+
+\paragraph{General flags and parameters}
+~ \\
+%
+\begin{table}[h!]
+\centering
+  \label{tab:pkg:exf:runtime_flags}
+  {\footnotesize
+    \begin{tabular}{|l|c|l|}
+      \hline 
+      \textbf{Flag/parameter} & \textbf{default} &  \textbf{Description}  \\
+      \hline \hline
+        useExfCheckRange & \texttt{.TRUE.} & 
+           check range of input fields and stop if out of range \\
+        useExfYearlyFields & \texttt{.FALSE.} & 
+           append current year postfix of form \texttt{\_YYYY} on filename \\
+        twoDigitYear & \texttt{.FALSE.} & 
+           instead of appending \texttt{\_YYYY} append  \texttt{YY} \\
+        repeatPeriod & \texttt{0.0} & $ > 0 $ : 
+           cycle through all input fields at the same period (in seconds) \\
+        ~            & ~            & $ = 0 $ :
+           use period assigned to each field \\
+        exf\_offset\_atemp & \texttt{0.0} & set to 273.16 to convert from deg. Kelvin (assumed input) to Celsius \\
+        windstressmax & \texttt{2.0} & 
+           max. allowed wind stress $N/m^2$ \\
+        exf\_albedo & \texttt{0.1} & 
+          surface albedo used to compute downward vs. net radiative fluxes \\
+        climtempfreeze & \texttt{-1.9} & 
+          ??? \\
+        ocean\_emissivity & \texttt{} & 
+          longwave ocean-surface emissivity \\
+        ice\_emissivity & \texttt{} & 
+          longwave seaice emissivity \\
+        snow\_emissivity & \texttt{} & 
+          longwave  snow  emissivity \\
+        exf\_iceCd & \texttt{1.63E-3} & 
+          drag coefficient over sea-ice \\
+        exf\_iceCe & \texttt{1.63E-3} & 
+          evaporation transfer coeff. over sea-ice \\
+        exf\_iceCh & \texttt{1.63E-3} & 
+          sensible heat transfer coeff. over sea-ice \\
+        exf\_scal\_BulkCdn & \texttt{1.} & 
+          overall scaling of neutral drag coeff. \\
+        useStabilityFct\_overIce  & \texttt{.FALSE.} & 
+          compute turbulent transfer coeff. over sea-ice \\
+        readStressOnAgrid & \texttt{.FALSE.} & 
+          read wind-streess located on model-grid, A-grid point \\
+        readStressOnCgrid & \texttt{.FALSE.} & 
+          read wind-streess located on model-grid, C-grid point \\
+        useRelativeWind & \texttt{.FALSE.} & 
+          subtract [U/V]VEL or [U/VICE from U/V]WIND before \\
+        ~ & ~ &  computing [U/V]STRESS \\
+        zref & \texttt{10.} & 
+          reference height \\
+        hu & \texttt{10.} & 
+          height of mean wind \\
+        ht & \texttt{2.} & 
+          height of mean temperature and rel. humidity \\
+        umin & \texttt{0.5} & 
+          minimum absolute wind speed for computing Cd \\
+        atmrho & \texttt{1.2} & 
+          mean atmospheric density [kg/m\^3] \\
+        atmcp & \texttt{1005.} & 
+          mean atmospheric specific heat [J/kg/K] \\
+        cdrag\_[n] & \texttt{???} & 
+          n = 1,2,3; parameters for drag coeff. function \\
+        cstanton\_[n] & \texttt{???} & 
+          n = 1,2; parameters for Stanton number function \\
+        cdalton & \texttt{???} & 
+          parameter for Dalton number function \\
+        flamb & \texttt{2500000.} & 
+          latent heat of evaporation [J/kg] \\
+        flami & \texttt{334000.} & 
+          latent heat of melting of pure ice [J/kg] \\
+        zolmin & \texttt{-100.} & 
+          minimum stability parameter \\
+        cvapor\_fac & \texttt{640380.} & 
+          ~ \\
+        cvapor\_exp & \texttt{5107.4} & 
+          ~ \\
+        cvapor\_fac\_ice & \texttt{11637800.} & 
+          ~ \\
+        cvapor\_fac\_ice & \texttt{5897.8} & 
+          ~ \\
+        humid\_fac & \texttt{0.606} & 
+          parameter for virtual temperature calculation \\
+        gamma\_blk & \texttt{0.010} & 
+          adiabatic lapse rate \\
+        saltsat & \texttt{0.980} & 
+          reduction of saturation vapor pressure over salt-water \\          
+        psim\_fac & \texttt{5.} & 
+          ~ \\          
+        exf\_monFreq & \texttt{monitorFreq} & 
+          output frequency [s] \\
+        exf\_iprec  & \texttt{32} & 
+          precision of input fields (32-bit or 64-bit) \\
+        exf\_yftype & \texttt{'RL'} & 
+          precision of arrays ('RL' vs. 'RS') \\
+      \hline
+    \end{tabular}
+  }
+  \caption{~}
+\end{table}
+
+
+\paragraph{Field attributes} 
+~ \\
+%
+All EXF fields are listed in Section \ref{sec:pkg:exf:fields_units}.
+Each field has a number of attributes which can be customized.
+They are summarized in
+Table \ref{tab:pkg:exf:runtime_attributes}.
+To obtain an attribute for a specific field, e.g. \texttt{uwind}
+prepend the field name to the listed attribute, e.g. for attribute
+\texttt{period} this yields \texttt{uwindperiod}:
+%
+\begin{eqnarray*}
+  \begin{array}{cccccc}
+    ~ & \texttt{field} & \& & \texttt{attribute} & \longrightarrow & \texttt{parameter} \\
+    \text{e.g.} & \text{uwind} & \& & \text{period} & \longrightarrow & \text{uwindperiod} \\
+  \end{array}
+\end{eqnarray*}
+%
+
+\begin{table}[h!]
+\centering
+  \label{tab:pkg:exf:runtime_attributes}
+  {\footnotesize
+    \begin{tabular}{|l|c|l|}
+      \hline 
+      \textbf{attribute} &  \textbf{Default} &  \textbf{Description}  \\
+      \hline \hline
+         \textit{field}\texttt{file} & ' ' & 
+           filename; if left empty no file will be read; \texttt{const} will be used instead \\
+         \textit{field}\texttt{const} & 0. &
+           constant that will be used if no file is read  \\
+         \textit{field}\texttt{startdate1} & 0. & 
+           format: \texttt{YYYYMMDD}; start year (YYYY), month (MM), day (YY) \\
+           ~&~& of field to determine record number \\
+         \textit{field}\texttt{startdate2} & 0. &
+           format: \texttt{HHMMSS}; start hour (HH), minute (MM), second(SS) \\
+           ~&~& of field to determine record number\\
+         \textit{field}\texttt{period} & 0. &
+           interval in seconds between two records \\
+         \texttt{exf\_inscal\_}\textit{field}& ~ & 
+           optional rescaling of input fields to comply with EXF units \\
+         \texttt{exf\_outscal\_}\textit{field}& ~ &
+           optional rescaling of EXF fields when mapped onto MITgcm fields \\
+         \hline
+         \multicolumn{3}{|c|}{\textit{used in conjunction with} 
+                              \texttt{EXF\_USE\_INTERPOLATION}} \\
+         \hline
+         \textit{field}\texttt{\_lon0} & $xgOrigin+delX/2$  & 
+           starting longitude of input \\
+         \textit{field}\texttt{\_lon\_inc} & $delX$ &
+           increment in longitude of input \\
+         \textit{field}\texttt{\_lat0} &  $ygOrigin+delY/2$ &
+           starting latitude of input \\
+         \textit{field}\texttt{\_lat\_inc} & $delY$ &
+           increment in latitude of input \\
+         \textit{field}\texttt{\_nlon} & $Nx$ &
+           number of grid points in longitude of input \\
+         \textit{field}\texttt{\_nlat} & $Ny$ &
+           number of grid points in longitude of input \\
+      \hline
+    \end{tabular}
+   }
+   \caption{\newline
+            Note one exception for the default of 
+            \texttt{atempconst} = celsius2K = 273.16}
+\end{table}
+
+\paragraph{Example configuration} ~ \\
+%
+The following block is taken from the \texttt{data.exf} file
+of the veification experiment \texttt{global\_with\_exf/}.
+It defines attributes for the heat flux variable \texttt{hflux}:
+
+\begin{verbatim}
+ hfluxfile       = 'ncep_qnet.bin',
+ hfluxstartdate1 = 19920101,
+ hfluxstartdate2 = 000000,
+ hfluxperiod     = 2592000.0,
+ hflux_lon0      = 2
+ hflux_lon_inc   = 4
+ hflux_lat0      = -78
+ hflux_lat_inc   = 39*4
+ hflux_nlon      = 90
+ hflux_nlat      = 40
+\end{verbatim}
+
+EXF will read a file of name 'ncep\_qnet.bin'.
+Its first record represents January 1st, 1991 at 00:00 UTC.
+Next record is 2592000 seconds (or 30 days) later.
+Interpolation on-the-fly is used (in the present case trivially
+on the same grid, but included nevertheless for illustration), 
+and input field grid starting coordinates and increments are 
+supplied as well.
+
 %----------------------------------------------------------------------
 
-\subsection{EXF fields and units
+\subsubsection{EXF bulk formulae
+\label{sec:pkg:exf:bulk_formulae}}
+
+T.B.D. (cross-ref. to parameter list table)
+
+%----------------------------------------------------------------------
+
+\subsubsection{EXF input fields and units
 \label{sec:pkg:exf:fields_units}}
 
 The following list is taken from the header file \texttt{exf\_fields.h}.
+It comprises all EXF input fields.
+
+Output fields which EXF provides to the MITgcm are fields
+\textbf{fu}, \textbf{fv}, \textbf{Qnet}, \textbf{Qsw}, \textbf{EmPmR},
+and \textbf{pload}. They are defined in \texttt{FFIELDS.h}.
 
 {\footnotesize
 \begin{verbatim}
 
-
-
+c----------------------------------------------------------------------
+c               |
+c     field     :: Description
+c               |
+c----------------------------------------------------------------------
 c     ustress   :: Zonal surface wind stress in N/m^2
-c                  > 0 for increase in uVel, which is west to
-c                      east for cartesian and spherical polar grids
-c                  Typical range: -0.5 < ustress < 0.5
-c                  Southwest C-grid U point
-c                  Input field
-c
+c               |  > 0 for increase in uVel, which is west to
+c               |      east for cartesian and spherical polar grids
+c               |  Typical range: -0.5 < ustress < 0.5
+c               |  Southwest C-grid U point
+c               |  Input field
+c----------------------------------------------------------------------
 c     vstress   :: Meridional surface wind stress in N/m^2
-c                  > 0 for increase in vVel, which is south to
-c                      north for cartesian and spherical polar grids
-c                  Typical range: -0.5 < vstress < 0.5
-c                  Southwest C-grid V point
-c                  Input field
-c
+c               |  > 0 for increase in vVel, which is south to
+c               |      north for cartesian and spherical polar grids
+c               |  Typical range: -0.5 < vstress < 0.5
+c               |  Southwest C-grid V point
+c               |  Input field
+c----------------------------------------------------------------------
+c     hs        :: sensible heat flux into ocean in W/m^2
+c               |  > 0 for increase in theta (ocean warming)
+c----------------------------------------------------------------------
+c     hl        :: latent   heat flux into ocean in W/m^2
+c               |  > 0 for increase in theta (ocean warming)
+c----------------------------------------------------------------------
 c     hflux     :: Net upward surface heat flux in W/m^2 
-c                  excluding shortwave (on input)
-c                  hflux = latent + sensible + lwflux
-c                  > 0 for decrease in theta (ocean cooling)
-c                  Typical range: -250 < hflux < 600
-c                  Southwest C-grid tracer point
-c                  Input field
-c
+c               |  excluding shortwave (on input)
+c               |  hflux = latent + sensible + lwflux
+c               |  > 0 for decrease in theta (ocean cooling)
+c               |  Typical range: -250 < hflux < 600
+c               |  Southwest C-grid tracer point
+c               |  Input field
+c----------------------------------------------------------------------
 c     sflux     :: Net upward freshwater flux in m/s
-c                  sflux = evap - precip - runoff
-c                  > 0 for increase in salt (ocean salinity)
-c                  Typical range: -1e-7 < sflux < 1e-7
-c                  Southwest C-grid tracer point
-c                  Input field
-c
+c               |  sflux = evap - precip - runoff
+c               |  > 0 for increase in salt (ocean salinity)
+c               |  Typical range: -1e-7 < sflux < 1e-7
+c               |  Southwest C-grid tracer point
+c               |  Input field
+c----------------------------------------------------------------------
 c     swflux    :: Net upward shortwave radiation in W/m^2
-c                  swflux = - ( swdown - ice and snow absorption - reflected )
-c                  > 0 for decrease in theta (ocean cooling)
-c                  Typical range: -350 < swflux < 0
-c                  Southwest C-grid tracer point
-c                  Input field
-c
+c               |  swflux = - ( swdown - ice and snow absorption - reflected )
+c               |  > 0 for decrease in theta (ocean cooling)
+c               |  Typical range: -350 < swflux < 0
+c               |  Southwest C-grid tracer point
+c               |  Input field
+c----------------------------------------------------------------------
 c     uwind     :: Surface (10-m) zonal wind velocity in m/s
-c                  > 0 for increase in uVel, which is west to
-c                      east for cartesian and spherical polar grids
-c                  Typical range: -10 < uwind < 10
-c                  Southwest C-grid U point
-c                  Input or input/output field
-c
+c               |  > 0 for increase in uVel, which is west to
+c               |      east for cartesian and spherical polar grids
+c               |  Typical range: -10 < uwind < 10
+c               |  Southwest C-grid U point
+c               |  Input or input/output field
+c----------------------------------------------------------------------
 c     vwind     :: Surface (10-m) meridional wind velocity in m/s
-c                  > 0 for increase in vVel, which is south to
-c                      north for cartesian and spherical polar grids
-c                  Typical range: -10 < vwind < 10
-c                  Southwest C-grid V point
-c                  Input or input/output field
-c
+c               |  > 0 for increase in vVel, which is south to
+c               |      north for cartesian and spherical polar grids
+c               |  Typical range: -10 < vwind < 10
+c               |  Southwest C-grid V point
+c               |  Input or input/output field
+c----------------------------------------------------------------------
+c     wspeed    :: Surface (10-m) wind speed in m/s
+c               |  >= 0 sqrt(u^2+v^2)
+c               |  Typical range: 0 < wspeed < 10
+c               |  Input or input/output field
+c----------------------------------------------------------------------
 c     atemp     :: Surface (2-m) air temperature in deg K
-c                  Typical range: 200 < atemp < 300
-c                  Southwest C-grid tracer point
-c                  Input or input/output field
-c
+c               |  Typical range: 200 < atemp < 300
+c               |  Southwest C-grid tracer point
+c               |  Input or input/output field
+c----------------------------------------------------------------------
 c     aqh       :: Surface (2m) specific humidity in kg/kg
-c                  Typical range: 0 < aqh < 0.02
-c                  Southwest C-grid tracer point
-c                  Input or input/output field
-c
+c               |  Typical range: 0 < aqh < 0.02
+c               |  Southwest C-grid tracer point
+c               |  Input or input/output field
+c----------------------------------------------------------------------
 c     lwflux    :: Net upward longwave radiation in W/m^2
-c                  lwflux = - ( lwdown - ice and snow absorption - emitted )
-c                  > 0 for decrease in theta (ocean cooling)
-c                  Typical range: -20 < lwflux < 170
-c                  Southwest C-grid tracer point
-c                  Input field
-c
+c               |  lwflux = - ( lwdown - ice and snow absorption - emitted )
+c               |  > 0 for decrease in theta (ocean cooling)
+c               |  Typical range: -20 < lwflux < 170
+c               |  Southwest C-grid tracer point
+c               |  Input field
+c----------------------------------------------------------------------
 c     evap      :: Evaporation in m/s
-c                  > 0 for increase in salt (ocean salinity)
-c                  Typical range: 0 < evap < 2.5e-7
-c                  Southwest C-grid tracer point
-c                  Input, input/output, or output field
-c
+c               |  > 0 for increase in salt (ocean salinity)
+c               |  Typical range: 0 < evap < 2.5e-7
+c               |  Southwest C-grid tracer point
+c               |  Input, input/output, or output field
+c----------------------------------------------------------------------
 c     precip    :: Precipitation in m/s
-c                  > 0 for decrease in salt (ocean salinity)
-c                  Typical range: 0 < precip < 5e-7
-c                  Southwest C-grid tracer point
-c                  Input or input/output field
-c
+c               |  > 0 for decrease in salt (ocean salinity)
+c               |  Typical range: 0 < precip < 5e-7
+c               |  Southwest C-grid tracer point
+c               |  Input or input/output field
+c----------------------------------------------------------------------
+c    snowprecip :: snow in m/s
+c               |  > 0 for decrease in salt (ocean salinity)
+c               |  Typical range: 0 < precip < 5e-7
+c               |  Input or input/output field
+c----------------------------------------------------------------------
 c     runoff    :: River and glacier runoff in m/s
-c                  > 0 for decrease in salt (ocean salinity)
-c                  Typical range: 0 < runoff < ????
-c                  Southwest C-grid tracer point
-c                  Input or input/output field
-c                  !!! WATCH OUT: Default exf_inscal_runoff !!!
-c                  !!! in exf_readparms.F is not 1.0        !!!
-c
+c               |  > 0 for decrease in salt (ocean salinity)
+c               |  Typical range: 0 < runoff < ????
+c               |  Southwest C-grid tracer point
+c               |  Input or input/output field
+c               |  !!! WATCH OUT: Default exf_inscal_runoff !!!
+c               |  !!! in exf_readparms.F is not 1.0        !!!
+c----------------------------------------------------------------------
 c     swdown    :: Downward shortwave radiation in W/m^2
-c                  > 0 for increase in theta (ocean warming)
-c                  Typical range: 0 < swdown < 450
-c                  Southwest C-grid tracer point
-c                  Input/output field
-c
+c               |  > 0 for increase in theta (ocean warming)
+c               |  Typical range: 0 < swdown < 450
+c               |  Southwest C-grid tracer point
+c               |  Input/output field
+c----------------------------------------------------------------------
 c     lwdown    :: Downward longwave radiation in W/m^2
-c                  > 0 for increase in theta (ocean warming)
-c                  Typical range: 50 < lwdown < 450
-c                  Southwest C-grid tracer point
-c                  Input/output field
-c
+c               |  > 0 for increase in theta (ocean warming)
+c               |  Typical range: 50 < lwdown < 450
+c               |  Southwest C-grid tracer point
+c               |  Input/output field
+c----------------------------------------------------------------------
 c     apressure :: Atmospheric pressure field in N/m^2
-c                  > 0 for ????
-c                  Typical range: ???? < apressure < ????
-c                  Southwest C-grid tracer point
-c                  Input field
-C
-C
-c     NOTES:
-c     ======
-c
-c     Input and output units and sign conventions can be customized
-c     using variables exf_inscal_* and exf_outscal_*, which are set
-c     by exf_readparms.F
-c
-c     Output fields fu, fv, Qnet, Qsw, and EmPmR are
-c     defined in FFIELDS.h
-c
-c     #ifndef SHORTWAVE_HEATING, hflux includes shortwave,
-c     that is, hflux = latent + sensible + lwflux +swflux
-c
-c     If (EXFwindOnBgrid .EQ. .TRUE.), uwind and vwind are
-c     defined on northeast B-grid U and V points, respectively.
-c
-c     Arrays *0 and *1 below are used for temporal interpolation.
+c               |  > 0 for ????
+c               |  Typical range: ???? < apressure < ????
+c               |  Southwest C-grid tracer point
+c               |  Input field
+c----------------------------------------------------------------------
+
 \end{verbatim}
 }
 
 %----------------------------------------------------------------------
 
-\subsection{Key subroutines
+\subsubsection{Key subroutines
 \label{sec:pkg:exf:subroutines}}
 
+Top-level routine: \texttt{exf\_getforcing.F}
+
+{\footnotesize
+\begin{verbatim}
+
+C     !CALLING SEQUENCE:
+c ...
+c  exf_getforcing (TOP LEVEL ROUTINE)
+c  |
+c  |-- exf_getclim (get climatological fields used e.g. for relax.)
+c  |   |--- exf_set_climsst  (relax. to 2-D SST field)
+c  |   |--- exf_set_climsss  (relax. to 2-D SSS field)
+c  |   o
+c  |
+c  |-- exf_getffields <- this one does almost everything
+c  |   |   1. reads in fields, either flux or atmos. state,
+c  |   |      depending on CPP options (for each variable two fields
+c  |   |      consecutive in time are read in and interpolated onto
+c  |   |      current time step).
+c  |   |   2. If forcing is atmos. state and control is atmos. state,
+c  |   |      then the control variable anomalies are read here via ctrl_get_gen
+c  |   |      (atemp, aqh, precip, swflux, swdown, uwind, vwind).
+c  |   |      If forcing and control are fluxes, then
+c  |   |      controls are added later.
+c  |   o
+c  |
+c  |-- exf_radiation
+c  |   |    Compute net or downwelling radiative fluxes via
+c  |   |    Stefan-Boltzmann law in case only one is known.
+c  |   o
+c  |-- exf_wind
+c  |   |   Computes wind speed and stresses, if required.
+c  |   o
+c  |
+c  |-- exf_bulkformulae
+c  |   |   Compute air-sea buoyancy fluxes from
+c  |   |   atmospheric state following Large and Pond, JPO, 1981/82
+c  |   o
+c  |
+c  |-- < hflux is sum of sensible, latent, longwave rad. >
+c  |-- < sflux is sum of evap. minus precip. minus runoff  >
+c  |
+c  |-- exf_getsurfacefluxes
+c  |   If forcing and control is flux, then the
+c  |   control vector anomalies are read here via ctrl_get_gen
+c  |   (hflux, sflux, ustress, vstress)
+c  |
+c  |-- < update tile edges here >
+c  |
+c  |-- exf_check_range
+c  |   |   Check whether read fields are within assumed range
+c  |   |   (may capture mismatches in units)
+c  |   o
+c  |
+c  |-- < add shortwave to hflux for diagnostics >
+c  |
+c  |-- exf_diagnostics_fill
+c  |   |   Do EXF-related diagnostics output here.
+c  |   o
+c  |
+c  |-- exf_mapfields
+c  |   |   Forcing fields from exf package are mapped onto
+c  |   |   mitgcm forcing arrays.
+c  |   |   Mapping enables a runtime rescaling of fields
+c  |   o
+C  o
+\end{verbatim}
+}
+
+Radiation calculation: \texttt{exf\_radiation.F}
+
+Wind speed and stress calculation: \texttt{exf\_wind.F}
+
+Bulk formula: \texttt{exf\_bulkformulae.F}
+
+Generic I/O: \texttt{exf\_set\_gen.F}
+
+Interpolation: \texttt{exf\_interp.F}
+
+Header routines
+
 %----------------------------------------------------------------------
 
-\subsection{EXF diagnostics
+\subsubsection{EXF diagnostics
 \label{sec:pkg:exf:diagnostics}}
 
 Diagnostics output is available via the diagnostics package
@@ -239,35 +568,48 @@
 Available output fields are summarized in 
 Table \ref{tab:pkg:exf:diagnostics}.
 
-\begin{table}
+\begin{table}[h!]
+\centering
 \label{tab:pkg:exf:diagnostics}
-\caption{~}
 {\footnotesize
 \begin{verbatim}
-------------------------------------------------------
+---------+----+----+----------------+-----------------
  <-Name->|Levs|grid|<--  Units   -->|<- Tile (max=80c)
-------------------------------------------------------
- EXFlwdn |  1 | SM |W/m^2           |Downward longwave radiation, >0 increases theta
- EXFswdn |  1 | SM |W/m^2           |Downward shortwave radiation, >0 increases theta
- EXFqnet |  1 | SM |W/m^2           |Net upward heat flux (turb+rad), >0 decreases theta
- EXFtaux |  1 | SU |N/m^2           |zonal surface wind stress, >0 increases uVel
- EXFtauy |  1 | SV |N/m^2           |meridional surface wind stress, >0 increases vVel
- EXFuwind|  1 | SM |m/s             |zonal 10-m wind speed, >0 increases uVel
- EXFvwind|  1 | SM |m/s             |meridional 10-m wind speed, >0 increases uVel
- EXFatemp|  1 | SM |degK            |surface (2-m) air temperature
- EXFaqh  |  1 | SM |kg/kg           |surface (2-m) specific humidity
- EXFevap |  1 | SM |m/s             |evaporation, > 0 increases salinity
- EXFpreci|  1 | SM |m/s             |evaporation, > 0 decreases salinity
- EXFempmr|  1 | SM |m/s             |net upward freshwater flux, > 0 increases salinity
- EXFpress|  1 | SM |N/m^2           |atmospheric pressure field
+---------+----+----+----------------+-----------------
+ EXFhs   |  1 | SM | W/m^2          | Sensible heat flux into ocean, >0 increases theta
+ EXFhl   |  1 | SM | W/m^2          | Latent heat flux into ocean, >0 increases theta
+ EXFlwnet|  1 | SM | W/m^2          | Net upward longwave radiation, >0 decreases theta
+ EXFswnet|  1 | SM | W/m^2          | Net upward shortwave radiation, >0 decreases theta
+ EXFlwdn |  1 | SM | W/m^2          | Downward longwave radiation, >0 increases theta
+ EXFswdn |  1 | SM | W/m^2          | Downward shortwave radiation, >0 increases theta
+ EXFqnet |  1 | SM | W/m^2          | Net upward heat flux (turb+rad), >0 decreases theta
+ EXFtaux |  1 | SU | N/m^2          | zonal surface wind stress, >0 increases uVel
+ EXFtauy |  1 | SV | N/m^2          | meridional surface wind stress, >0 increases vVel
+ EXFuwind|  1 | SM | m/s            | zonal 10-m wind speed, >0 increases uVel
+ EXFvwind|  1 | SM | m/s            | meridional 10-m wind speed, >0 increases uVel
+ EXFwspee|  1 | SM | m/s            | 10-m wind speed modulus ( >= 0 )
+ EXFatemp|  1 | SM | degK           | surface (2-m) air temperature
+ EXFaqh  |  1 | SM | kg/kg          | surface (2-m) specific humidity
+ EXFevap |  1 | SM | m/s            | evaporation, > 0 increases salinity
+ EXFpreci|  1 | SM | m/s            | evaporation, > 0 decreases salinity
+ EXFsnow |  1 | SM | m/s            | snow precipitation, > 0 decreases salinity
+ EXFempmr|  1 | SM | m/s            | net upward freshwater flux, > 0 increases salinity
+ EXFpress|  1 | SM | N/m^2          | atmospheric pressure field
 \end{verbatim}
 }
+\caption{~}
 \end{table}
 
 %----------------------------------------------------------------------
 
-\subsection{Reference experiments}
+\subsubsection{Experiments and tutorials that use exf}
+\label{sec:pkg:exf:experiments}
+
+\begin{itemize}
+\item{Global Ocean experiment, in global\_with\_exf verification directory }
+\item{Labrador Sea experiment, in lab\_sea verification directory }
+\end{itemize}
 
 %----------------------------------------------------------------------
 
-\subsection{References}
+\subsubsection{References}
