/[MITgcm]/manual/s_phys_pkgs/text/exf.tex

Diff of /manual/s_phys_pkgs/text/exf.tex

Parent Directory | Revision Log | View Revision Graph Revision Graph | View Patch Patch

-revision 1.3 by heimbach,
Fri Jul 15 20:08:42 2005 UTC
+revision 1.14 by dimitri,
Tue Jun 21 19:07:20 2011 UTC
 Line 1
- \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
-Line 21 
 forcing fields an arbitrary grid onto th
+Line 22 
 forcing fields an arbitrary grid onto th
  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}.
  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}.
+ output is listed in Section \ref{sec:pkg:exf:diagnostics}.
  %----------------------------------------------------------------------
- \subsection{EXF configuration, compiling \& running}
+ \subsubsection{EXF configuration, compiling \& running}
- \subsubsection{Compile-time options
+ \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{sec: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!]
-   \label{tab:pkg:exf:cpp}
+   \centering
    {\footnotesize
      \begin{tabular}{|l|l|}
        \hline
-Line 68 
 Table \ref{tab:pkg:exf:cpp} summarizes t
+Line 85 
 Table \ref{tab:pkg:exf:cpp} summarizes t
        \hline
           \multicolumn{2}{|c|}{\textit{used in conjunction with relaxation to prescribed (climatological) fields}} \\
           \hline
-         \texttt{ALLOW\_CLIMTEMP\_RELAXATION} &
-           relaxation to 3-D temperature climatology \\
-         \texttt{ALLOW\_CLIMSALT\_RELAXATION} &
-           relaxation to 3-D salinity climatology \\
          \texttt{ALLOW\_CLIMSST\_RELAXATION} &
            relaxation to 2-D SST climatology \\
          \texttt{ALLOW\_CLIMSSS\_RELAXATION} &
-Line 85 
 Table \ref{tab:pkg:exf:cpp} summarizes t
+Line 98 
 Table \ref{tab:pkg:exf:cpp} summarizes t
      \end{tabular}
    }
    \caption{~}
+   \label{tab:pkg:exf:cpp}
  \end{table}
-Line 93 
 Table \ref{tab:pkg:exf:cpp} summarizes t
+Line 107 
 Table \ref{tab:pkg:exf:cpp} summarizes t
  \subsubsection{Run-time parameters
  \label{sec:pkg:exf:runtime}}
- Run-time parameters are set in files \texttt{data.pkg},
+ Run-time parameters are set in files
- and \texttt{data.pkg\_clim} (for relaxation/climatological fields)
+ \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 2 categories:
+ Run-time parameters may be broken into 3 categories:
- (i) general flags and parameters, and
+ (i) switching on/off the package at runtime,
- (ii) attributes for each forcing and climatological field.
+ (ii) general flags and parameters, and
+ (iii) attributes for each forcing and climatological field.
- \paragraph{General flags and parameters}
- ~
+ \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}.
- \begin{table}[h!]
+ \paragraph{General flags and parameters}
-   \label{tab:pkg:exf:runtime_flags}
+ ~ \\
+ %
+ \begin{table}[!ht]
+   \centering
    {\footnotesize
      \begin{tabular}{|l|c|l|}
        \hline
-Line 126 
 Run-time parameters may be broken into 2
+Line 147 
 Run-time parameters may be broken into 2
             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'} &
-Line 134 
 Run-time parameters may be broken into 2
+Line 222 
 Run-time parameters may be broken into 2
      \end{tabular}
    }
    \caption{~}
+   \label{tab:pkg:exf:runtime_flags}
  \end{table}
- \paragraph{Field attributes} ~ \\
+ \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.
-Line 155 
 prepend the field name to the listed att
+Line 245 
 prepend the field name to the listed att
  \end{eqnarray*}
  %
- \begin{table}[h!]
+ \begin{table}[!ht]
-   \label{tab:pkg:exf:runtime_attributes}
+   \centering
    {\footnotesize
      \begin{tabular}{|l|c|l|}
        \hline
-Line 182 
 prepend the field name to the listed att
+Line 272 
 prepend the field name to the listed att
           \multicolumn{3}{|c|}{\textit{used in conjunction with}
                                \texttt{EXF\_USE\_INTERPOLATION}} \\
           \hline
-          \textit{field}\texttt{\_lon0} & $thetaMin+delX/2$  &
+          \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} &  $phiMin+delY/2$ &
+          \textit{field}\texttt{\_lat0} &  $ygOrigin+delY/2$ &
             starting latitude of input \\
           \textit{field}\texttt{\_lat\_inc} & $delY$ &
             increment in latitude of input \\
-Line 197 
 prepend the field name to the listed att
+Line 287 
 prepend the field name to the listed att
        \hline
      \end{tabular}
     }
-    \caption{\newline
+   \caption{\newline
-             Note one exception for the default of
+            Note one exception for the default of
-             \texttt{atempconst} = celsius2K = 273.16}
+            \texttt{atempconst} = celsius2K = 273.16}
+   \label{tab:pkg:exf:runtime_attributes}
  \end{table}
  \paragraph{Example configuration} ~ \\
-Line 222 
 It defines attributes for the heat flux
+Line 313 
 It defines attributes for the heat flux
  \end{verbatim}
  EXF will read a file of name 'ncep\_qnet.bin'.
- Its first record represents January 1st, 1991 at 00:00 UTC.
+ Its first record represents January 1st, 1992 at 00:00 UTC.
  Next record is 2592000 seconds (or 30 days) later.
+ Note that the first record read and used by the EXF package corresponds to the
+ value 'startDate1' set in data.cal.  Therefore if you want to start the EXF
+ forcing from later in the 'ncep_qnet.bin' file, it suffices to specify
+ startDate1 in data.cal as a date later than 19920101 (for example, startDate1
+ = 19940101, for starting January 1st, 1994).  For this to work,
+ 'ncep_qnet.bin' must have at least 2 years of data because in this
+ configuration EXF will read 2 years into the file to find the 1994 starting
+ value.
  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
-Line 231 
 supplied as well.
+Line 330 
 supplied as well.
  %----------------------------------------------------------------------
- \subsection{EXF input 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}.
-Line 241 
 Output fields which EXF provides to the
+Line 347 
 Output fields which EXF provides to the
  \textbf{fu}, \textbf{fv}, \textbf{Qnet}, \textbf{Qsw}, \textbf{EmPmR},
  and \textbf{pload}. They are defined in \texttt{FFIELDS.h}.
- {\scriptsize
+ {\footnotesize
  \begin{verbatim}
  c----------------------------------------------------------------------
-Line 263 
 c               |  Typical range: -0.5 <
+Line 369 
 c               |  Typical range: -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
-Line 299 
 c               |  Typical range: -10 <
+Line 411 
 c               |  Typical range: -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
-Line 328 
 c               |  Typical range: 0 < pr
+Line 445 
 c               |  Typical range: 0 < pr
  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 < ????
-Line 360 
 c---------------------------------------
+Line 482 
 c---------------------------------------
  %----------------------------------------------------------------------
- \subsection{Key subroutines
+ \subsubsection{Key subroutines
  \label{sec:pkg:exf:subroutines}}
- \subsubsection{Top-level routine: \texttt{exf\_getforcing.F}}
+ Top-level routine: \texttt{exf\_getforcing.F}
- {\scriptsize
+ {\footnotesize
  \begin{verbatim}
  C     !CALLING SEQUENCE:
-Line 373 
 c ...
+Line 495 
 c ...
  c  exf_getforcing (TOP LEVEL ROUTINE)
  c  |
  c  |-- exf_getclim (get climatological fields used e.g. for relax.)
- c  |   |--- exf_set_climtemp (relax. to 3-D temperature field)
- c  |   |--- exf_set_climsalt (relax. to 3-D salinity field)
  c  |   |--- exf_set_climsst  (relax. to 2-D SST field)
  c  |   |--- exf_set_climsss  (relax. to 2-D SSS field)
  c  |   o
-Line 385 
 c  |   |      depending on CPP options (
+Line 505 
 c  |   |      depending on CPP options (
  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
+ c  |   |      then the control variable anomalies are read here via ctrl_get_gen
- c  |   |          * ctrl_getatemp
+ c  |   |      (atemp, aqh, precip, swflux, swdown, uwind, vwind).
- c  |   |          * ctrl_getaqh
- c  |   |          * ctrl_getuwind
- c  |   |          * ctrl_getvwind
  c  |   |      If forcing and control are fluxes, then
  c  |   |      controls are added later.
  c  |   o
  c  |
- c  |-- exf_check_range
+ c  |-- exf_radiation
- c  |   |   1. Check whether read fields are within assumed range
+ c  |   |    Compute net or downwelling radiative fluxes via
- c  |   |      (may capture mismatches in units)
+ 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  |   |   1. Compute net or downwelling radiative fluxes via
+ c  |   |   Compute air-sea buoyancy fluxes from
- c  |   |      Stefan-Boltzmann law in case only one is known.
+ c  |   |   atmospheric state following Large and Pond, JPO, 1981/82
- c  |   |   2. Compute air-sea momentum and buoyancy fluxes from
- c  |   |      atmospheric state following Large and Pond, JPO, 1981/82
  c  |   o
  c  |
- c  |-- < add time-mean river runoff here, if available >
+ 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_getsurfacefluxes
+ c  |-- exf_check_range
- c  |   |   1. If forcing and control are fluxes, then
+ c  |   |   Check whether read fields are within assumed range
- c  |   |      controls are added here.
+ c  |   |   (may capture mismatches in units)
  c  |   o
  c  |
- c  |-- < treatment of hflux w.r.t. swflux >
+ c  |-- < add shortwave to hflux for diagnostics >
  c  |
  c  |-- exf_diagnostics_fill
- c  |   |   1. Do EXF-related diagnostics output here.
+ c  |   |   Do EXF-related diagnostics output here.
  c  |   o
  c  |
  c  |-- exf_mapfields
- c  |   |   1. Map the EXF variables onto the core MITgcm
+ c  |   |   Forcing fields from exf package are mapped onto
- c  |   |      forcing fields.
+ c  |   |   mitgcm forcing arrays.
+ c  |   |   Mapping enables a runtime rescaling of fields
  c  |   o
- c  |
+ C  o
- c  |-- exf_bulkformulae
- c  |   If ALLOW_BULKFORMULAE, compute fluxes via bulkformulae
- c  |
- c  |-- exf_getsurfacefluxes
- c  |   If forcing and control is flux, then the
- c  |   control vector anomalies are read here
- c  |      * ctrl_getheatflux
- c  |      * ctrl_getsaltflux
- c  |      * ctrl_getzonstress
- c  |      * call ctrl_getmerstress
- 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
  \end{verbatim}
  }
- \subsubsection{Bulk formula routine: \texttt{exf\_bulkformulae.F}}
+ Radiation calculation: \texttt{exf\_radiation.F}
+ Wind speed and stress calculation: \texttt{exf\_wind.F}
+ Bulk formula: \texttt{exf\_bulkformulae.F}
- \subsubsection{Generic I/O routine: \texttt{exf\_set\_gen.F}}
+ Generic I/O: \texttt{exf\_set\_gen.F}
- \subsubsection{Interpolation routine: \texttt{exf\_interp.F}}
+ Interpolation: \texttt{exf\_interp.F}
- \subsubsection{Header routines}
+ Header routines
  %----------------------------------------------------------------------
- \subsection{EXF diagnostics
+ \subsubsection{EXF diagnostics
  \label{sec:pkg:exf:diagnostics}}
  Diagnostics output is available via the diagnostics package
-Line 463 
 Diagnostics output is available via the
+Line 576 
 Diagnostics output is available via the
  Available output fields are summarized in
  Table \ref{tab:pkg:exf:diagnostics}.
- \begin{table}[h!]
+ \begin{table}[!ht]
- \label{tab:pkg:exf:diagnostics}
+ \centering
  {\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
-Line 477 
 Table \ref{tab:pkg:exf:diagnostics}.
+Line 594 
 Table \ref{tab:pkg:exf:diagnostics}.
   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{~}
+ \label{tab:pkg:exf:diagnostics}
  \end{table}
  %----------------------------------------------------------------------
- \subsection{Reference experiments}
+ \subsubsection{Experiments and tutorials that use exf}
+ \label{sec:pkg:exf:experiments}
- \subsubsection{global\_with\_exf}
- \subsubsection{lab\_sea}
+ \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}

 Legend:



Removed from v.1.3
 


changed lines


 
Added in v.1.14
 Legend:



Removed from v.1.3
 


changed lines


 
Added in v.1.14
-Removed from v.1.3
+Added in v.1.14

	ViewVC Help
Powered by ViewVC 1.1.22