s_phys_pkgs/text/exf.tex

\subsection{EXF: The external forcing package
\label{sec:pkg:exf}}
\begin{rawhtml}
<!-- CMIREDIR:sectionexf: -->
\end{rawhtml}

Authors: Patrick Heimbach and Dimitris Menemenlis

\subsubsection{Introduction
\label{sec:pkg:exf:intro}}

The external forcing package, in conjunction with the
calendar package (cal), enables the handling of real-time
(or ``model-time'') forcing
fields of differing temporal forcing patterns.
It comprises climatological restoring and relaxation.
Bulk formulae are implemented to convert atmospheric fields
to surface fluxes.
An interpolation routine provides on-the-fly interpolation of
forcing fields an arbitrary grid onto the model grid.

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}
(Section \ref{sec:pkg:exf:runtime}).
A description of key subroutines is given in Section
\ref{sec:pkg:exf:subroutines}.
Input fields, units and sign conventions are summarized in
Section \ref{sec:pkg:exf:fields_units}, and available diagnostics
output is listed in Section \ref{sec:pkg:exf:fields_diagnostics}.

%----------------------------------------------------------------------

\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
%
\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
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 
      \textbf{CPP option}  &  \textbf{Description}  \\
      \hline \hline
        \texttt{EXF\_VERBOSE} & 
          verbose mode (recommended only for testing) \\
        \texttt{ALLOW\_ATM\_TEMP} & 
          compute heat/freshwater fluxes from atmos. state input \\
        \texttt{ALLOW\_ATM\_WIND} & 
          compute wind stress from wind speed input\\
        \texttt{ALLOW\_BULKFORMULAE} & 
          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
         \multicolumn{2}{|c|}{\textit{used in conjunction with relaxation to prescribed (climatological) fields}} \\
         \hline
        \texttt{ALLOW\_CLIMSST\_RELAXATION} &
          relaxation to 2-D SST climatology \\
        \texttt{ALLOW\_CLIMSSS\_RELAXATION} &
          relaxation to 2-D SSS climatology  \\
      \hline
         \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}
  }
  \caption{~}
\end{table}


%----------------------------------------------------------------------

\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 usually switched on/off at runtime by setting
(e.g. for EXF) \texttt{useEXF = .TRUE.} in \texttt{data.pkg}.
For EXF this flag is omitted, i.e. EXF is always ON if it is compiled.

\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 \\
        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} & $thetaMin+delX/2$  & 
           starting longitude of input \\
         \textit{field}\texttt{\_lon\_inc} & $delX$ &
           increment in longitude of input \\
         \textit{field}\texttt{\_lat0} &  $phiMin+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.

%----------------------------------------------------------------------

\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     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     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     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     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     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     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     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     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     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     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     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    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     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     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     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----------------------------------------------------------------------

\end{verbatim}
}

%----------------------------------------------------------------------

\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

%----------------------------------------------------------------------

\subsubsection{EXF diagnostics
\label{sec:pkg:exf:diagnostics}}

Diagnostics output is available via the diagnostics package
(see Section \ref{sec:pkg:diagnostics}).
Available output fields are summarized in 
Table \ref{tab:pkg:exf:diagnostics}.

\begin{table}[h!]
\centering
\label{tab:pkg:exf:diagnostics}
{\footnotesize
\begin{verbatim}
------------------------------------------------------
 <-Name->|Levs|grid|<--  Units   -->|<- Tile (max=80c)
------------------------------------------------------
 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}

%----------------------------------------------------------------------

\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}

%----------------------------------------------------------------------

\subsubsection{References}