\subsection{EXF: The external forcing package \label{sec:pkg:exf}} \begin{rawhtml} \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 \\ 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} & $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 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 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}