--- manual/s_phys_pkgs/text/exf.tex 2005/07/14 22:04:52 1.2 +++ manual/s_phys_pkgs/text/exf.tex 2016/12/09 21:41:30 1.16 @@ -1,11 +1,12 @@ -\section{EXF: The external forcing package +\subsection{EXF: The external forcing package \label{sec:pkg:exf}} \begin{rawhtml} \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,289 +22,600 @@ 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 + \hline \textbf{CPP option} & \textbf{Description} \\ \hline \hline - \texttt{EXF\_VERBOSE} & + \texttt{EXF\_VERBOSE} & verbose mode (recommended only for testing) \\ - \texttt{ALLOW\_ATM\_TEMP} & + \texttt{ALLOW\_ATM\_TEMP} & compute heat/freshwater fluxes from atmos. state input \\ - \texttt{ALLOW\_ATM\_WIND} & + \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 \\ + \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 - \texttt{ALLOW\_CLIMTEMP\_RELAXATION} & - relaxation to 3-D potential temperature climatology \\ - \texttt{ALLOW\_CLIMSALT\_RELAXATION} & - relaxation to 3-D salinity climatology \\ + \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 - \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} } \caption{~} + \label{tab:pkg:exf:cpp} \end{table} - %---------------------------------------------------------------------- \subsubsection{Run-time parameters \label{sec:pkg:exf:runtime}} -Run-time parameters are set in files \texttt{data.pkg}, -and \texttt{data.pkg\_clim} (for relaxation/climatological fields). -Run-time parameters may be broken into 2 categories: -(i) general flags and parameters, and -(ii) attributes for each forcing and climatological field. +Run-time parameters are set in files +\texttt{data.pkg} and \texttt{data.exf} +%\texttt{data.exf\_clim} (for relaxation/climatological fields) +which is 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!] - \label{tab:pkg:exf:runtime_flags} +~ \\ +% +\begin{table}[!ht] + \centering {\footnotesize - \begin{tabular}{|l|cl|} - \hline + \begin{tabular}{|l|c|l|} + \hline \textbf{Flag/parameter} & \textbf{default} & \textbf{Description} \\ \hline \hline - useExfCheckRange & \texttt{.TRUE.} & ~ \\ - useExfYearlyFields & \texttt{.FALSE.} & ~ \\ - twoDigitYear & \texttt{.FALSE.} & ~ \\ - repeatPeriod & \texttt{0.0} & ~ \\ - windstressmax & \texttt{2.0} & ~ \\ - exf\_albedo & \texttt{0.1} & ~ \\ - exf\_iprec & \texttt{32} & ~ \\ - exf\_yftype & \texttt{'RL'} & ~ \\ + 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{~} + \label{tab:pkg:exf:runtime_flags} \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}[!ht] + \centering + {\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} + \label{tab:pkg:exf:runtime_attributes} +\end{table} + +\paragraph{Example configuration} ~ \\ +% +The following block is taken from the \texttt{data.exf} file +of the verification 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, 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 +supplied as well. + +%---------------------------------------------------------------------- +\subsubsection{EXF bulk formulae +\label{sec:pkg:exf:bulk_formulae}} +T.B.D. (cross-ref. to parameter list table) %---------------------------------------------------------------------- -\subsection{EXF fields and units +\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}. +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 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 | > 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 | (including shortwave) +c | hflux = latent + sensible + lwflux + swflux +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 (see Section \ref{sec:pkg:diagnostics}). -Available output fields are summarized in +Available output fields are summarized in Table \ref{tab:pkg:exf:diagnostics}. -\begin{table} -\label{tab:pkg:exf:diagnostics} -\caption{~} +\begin{table}[!ht] +\centering {\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{~} +\label{tab:pkg:exf:diagnostics} \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}