--- manual/s_phys_pkgs/text/exf.tex 2005/07/15 20:08:42 1.3 +++ manual/s_phys_pkgs/text/exf.tex 2008/01/15 23:58:53 1.11 @@ -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,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,21 +32,38 @@ %---------------------------------------------------------------------- -\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{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|} @@ -68,10 +86,6 @@ \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} & @@ -93,18 +107,26 @@ \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 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 2 categories: -(i) general flags and parameters, and -(ii) attributes for each forcing and climatological field. +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{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}. +\paragraph{General flags and parameters} +~ \\ +% \begin{table}[h!] +\centering \label{tab:pkg:exf:runtime_flags} {\footnotesize \begin{tabular}{|l|c|l|} @@ -126,6 +148,73 @@ 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'} & @@ -137,7 +226,8 @@ \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. @@ -156,6 +246,7 @@ % \begin{table}[h!] +\centering \label{tab:pkg:exf:runtime_attributes} {\footnotesize \begin{tabular}{|l|c|l|} @@ -231,7 +322,14 @@ %---------------------------------------------------------------------- -\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}. @@ -241,7 +339,7 @@ \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---------------------------------------------------------------------- @@ -263,6 +361,12 @@ 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 @@ -299,6 +403,11 @@ 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 @@ -328,6 +437,11 @@ 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 < ???? @@ -360,12 +474,12 @@ %---------------------------------------------------------------------- -\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: @@ -373,8 +487,6 @@ 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 @@ -385,77 +497,70 @@ 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 | | * ctrl_getatemp -c | | * ctrl_getaqh -c | | * ctrl_getuwind -c | | * ctrl_getvwind +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_check_range -c | | 1. Check whether read fields are within assumed range -c | | (may capture mismatches in units) +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 | | 1. Compute net or downwelling radiative fluxes via -c | | Stefan-Boltzmann law in case only one is known. -c | | 2. Compute air-sea momentum and buoyancy fluxes from -c | | atmospheric state following Large and Pond, JPO, 1981/82 +c | | Compute air-sea 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 | | 1. If forcing and control are fluxes, then -c | | controls are added here. +c |-- exf_check_range +c | | Check whether read fields are within assumed range +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. +c | | Forcing fields from exf package are mapped onto +c | | mitgcm forcing arrays. +c | | Mapping enables a runtime rescaling of fields c | o -c | -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 - +C o \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} -\subsubsection{Generic I/O routine: \texttt{exf\_set\_gen.F}} +Bulk formula: \texttt{exf\_bulkformulae.F} -\subsubsection{Interpolation routine: \texttt{exf\_interp.F}} +Generic I/O: \texttt{exf\_set\_gen.F} -\subsubsection{Header routines} +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 @@ -464,12 +569,17 @@ 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 @@ -477,10 +587,12 @@ 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} @@ -490,12 +602,14 @@ %---------------------------------------------------------------------- -\subsection{Reference experiments} - -\subsubsection{global\_with\_exf} +\subsubsection{Experiments and tutorials that use exf} +\label{sec:pkg:exf:experiments} -\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}