2.4.7. EXF: The external forcing package¶

Authors: Patrick Heimbach and Dimitris Menemenlis

2.4.7.1. Introduction¶

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 [sec:pkg:exf:config]). Runtime options, flags, filenames and field-related dates/times are set in data.exf (Section [sec:pkg:exf:runtime]). A description of key subroutines is given in Section [sec:pkg:exf:subroutines]. Input fields, units and sign conventions are summarized in Section [sec:pkg:exf:fields:sub:units], and available diagnostics output is listed in Section [sec:pkg:exf:diagnostics].

2.4.7.2. EXF configuration, compiling & running¶

Compile-time options¶

As with all MITgcm packages, EXF can be turned on or off at compile time

using the packages.conf file by adding exf to it,
or using genmake2 adding -enable=exf or -disable=exf switches
required packages and CPP options: EXF requires the calendar package cal to be enabled; no additional CPP options are required.

(see Section [sec:buildingCode]).

Parts of the EXF code can be enabled or disabled at compile time via CPP preprocessor flags. These options are set in either EXF_OPTIONS.h or in ECCO_CPPOPTIONS.h. Table 2.7 summarizes these options.

Table 2.7 EXF CPP options¶
CPP option	Description
`EXF_VERBOSE`	verbose mode (recommended only for testing)
`ALLOW_ATM_TEMP`	compute heat/freshwater fluxes from atmos. state input
`ALLOW_ATM_WIND`	compute wind stress from wind speed input
`ALLOW_BULKFORMULAE`	is used if `ALLOW_ATM_TEMP` or `ALLOW_ATM_WIND` is enabled
`EXF_READ_EVAP`	read evaporation instead of computing it
`ALLOW_RUNOFF`	read time-constant river/glacier run-off field
`ALLOW_DOWNWARD_RADIATION`	compute net from downward or downward from net radiation
`USE_EXF_INTERPOLATION`	enable on-the-fly bilinear or bicubic interpolation of input fields
used in conjunction with relaxation to prescribed (climatological) fields
`ALLOW_CLIMSST_RELAXATION`	relaxation to 2-D SST climatology
`ALLOW_CLIMSSS_RELAXATION`	relaxation to 2-D SSS climatology
these are set outside of EXF in `CPP_OPTIONS.h`
`SHORTWAVE_HEATING`	enable shortwave radiation
`ATMOSPHERIC_LOADING`	enable surface pressure forcing

2.4.7.3. Run-time parameters¶

Run-time parameters are set in files data.pkg and data.exf which is read in 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.

Enabling the package¶

A package is switched on/off at runtime by setting (e.g. for EXF) useEXF = .TRUE. in data.pkg.

General flags and parameters¶

Table 2.8 EXF runtime options¶
Flag/parameter	default	Description
useExfCheckRange	`.TRUE.`	check range of input fields and stop if out of range
useExfYearlyFields	`.FALSE.`	append current year postfix of form `_YYYY` on filename
twoDigitYear	`.FALSE.`	instead of appending `_YYYY` append `YY`
repeatPeriod	0.0	\(\gt\) 0: cycle through all input fields at the same period (in seconds)
repeatPeriod	0.0	= 0: use period assigned to each field
exf_offset_atemp	0.0	set to 273.16 to convert from deg. Kelvin (assumed input) to Celsius
windstressmax	2.0	max. allowed wind stress N m^–2
exf_albedo	0.1	surface albedo used to compute downward vs. net radiative fluxes
climtempfreeze	-1.9	???
ocean_emissivity		longwave ocean-surface emissivity
ice_emissivity		longwave seaice emissivity
snow_emissivity		longwave snow emissivity
exf_iceCd	1.63E-3	drag coefficient over sea-ice
exf_iceCe	1.63E-3	evaporation transfer coeff. over sea-ice
exf_iceCh	1.63E-3	sensible heat transfer coeff. over sea-ice
exf_scal_BulkCdn		overall scaling of neutral drag coeff.
useStabilityFct_overIce	`.FALSE.`	compute turbulent transfer coeff. over sea-ice
readStressOnAgrid	`.FALSE.`	read wind-streess located on model-grid, A-grid point
readStressOnCgrid	`.FALSE.`	read wind-streess located on model-grid, C-grid point
useRelativeWind	`.FALSE.`	subtract [U/V]VEL or [U/VICE from U/V]WIND before computing [U/V]STRESS
zref		reference height
hu		height of mean wind
ht		height of mean temperature and rel. humidity
umin	0.5	minimum absolute wind speed for computing Cd
atmrho	1.2	mean atmospheric density [kg/m^3]
atmcp		mean atmospheric specific heat [J/kg/K]
cdrag_[n]	???	n = 1,2,3; parameters for drag coeff. function
cstanton_[n]	???	n = 1,2; parameters for Stanton number function
cdalton	???	parameter for Dalton number function
flamb		latent heat of evaporation [J/kg]
flami		latent heat of melting of pure ice [J/kg]
zolmin	-100.	minimum stability parameter
cvapor_fac
cvapor_exp	5107.4
cvapor_fac_ice
cvapor_fac_ice	5897.8
humid_fac	0.606	parameter for virtual temperature calculation
gamma_blk	0.010	adiabatic lapse rate
saltsat	0.980	reduction of saturation vapor pressure over salt-water
psim_fac
exf_monFreq	monitorFreq	output frequency [s]
exf_iprec	32	precision of input fields (32-bit or 64-bit)
exf_yftype	‘RL’	precision of arrays (‘RL’ vs. ‘RS’)

Field attributes¶

All EXF fields are listed in Section [sec:pkg:exf:fields:sub:units]. Each field has a number of attributes which can be customized. They are summarized in Table [tab:pkg:exf:runtime:sub:attributes]. To obtain an attribute for a specific field, e.g. uwind prepend the field name to the listed attribute, e.g. for attribute period this yields uwindperiod:

(1)¶\[\begin{split}\begin{aligned} \begin{array}{cccccc} ~ & \texttt{field} & \& & \texttt{attribute} & \longrightarrow & \texttt{parameter} \\ \text{e.g.} & \text{uwind} & \& & \text{period} & \longrightarrow & \text{uwindperiod} \\ \end{array}\end{aligned}\end{split}\]

Table 2.9 EXF runtime attributes Note there is one exception for the default of `atempconst` = celsius2K = 273.16¶
attribute	Default	Description
field `file`	‘ ‘	filename; if left empty no file will be read; `const` will be used instead
field `const`		constant that will be used if no file is read
field `startdate1`		format: `YYYYMMDD`; start year (YYYY), month (MM), day (YY)
		of field to determine record number
field `startdate2`		format: `HHMMSS`; start hour (HH), minute (MM), second(SS)
		of field to determine record number
field `period`		interval in seconds between two records
`exf_inscal_`field		optional rescaling of input fields to comply with EXF units
`exf_outscal_`field		optional rescaling of EXF fields when mapped onto MITgcm fields
used in conjunction with `EXF_USE_INTERPOLATION`
field `_lon0`	`xgOrigin+delX/2`	starting longitude of input
field `_lon_inc`	`delX`	increment in longitude of input
field `_lat0`	`ygOrigin+delY/2`	starting latitude of input
field `_lat_inc`	`delY`	increment in latitude of input
field `_nlon`	`Nx`	number of grid points in longitude of input
field `_nlat`	`Ny`	number of grid points in longitude of input

Example configuration¶

The following block is taken from the data.exf file of the verification experiment global_with_exf/. It defines attributes for the heat flux variable hflux:

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

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.

2.4.7.4. EXF bulk formulae¶

T.B.D. (cross-ref. to parameter list table)

2.4.7.5. EXF input fields and units¶

The following list is taken from the header file EXF_FIELDS.h. It comprises all EXF input fields.

Output fields which EXF provides to the MITgcm are fields fu, fv, Qnet, Qsw, EmPmR, and pload. They are defined in FFIELDS.h.

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

2.4.7.6. Key subroutines¶

Top-level routine: exf_getforcing.F

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

Radiation calculation: exf_radiation.F

Wind speed and stress calculation: exf_wind.F

Bulk formula: exf_bulkformulae.F

Generic I/O: exf_set_gen.F

Interpolation: exf_interp.F

Header routines

2.4.7.7. EXF diagnostics¶

Diagnostics output is available via the diagnostics package (see Section [sec:pkg:diagnostics]). Available output fields are summarized below.

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

2.4.7.8. References¶

2.4.7.9. Experiments and tutorials that use exf¶

Global Ocean experiment, in global_with_exf verification directory
Labrador Sea experiment, in lab_sea verification directory