--- manual/s_phys_pkgs/text/exf.tex	2005/10/03 18:12:27	1.7
+++ manual/s_phys_pkgs/text/exf.tex	2009/01/27 15:47:59	1.12
@@ -22,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}.
@@ -86,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} &
@@ -123,9 +119,8 @@
 \paragraph{Enabling the package}
 ~ \\
 %
-A package is usually switched on/off at runtime by setting
+A package is 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}
 ~ \\
@@ -153,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'} & 
@@ -211,11 +273,11 @@
          \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 \\
@@ -260,6 +322,13 @@
 
 %----------------------------------------------------------------------
 
+\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}}
 
@@ -292,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
@@ -328,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
@@ -357,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 < ????
@@ -402,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
@@ -414,71 +497,64 @@
 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}
 }
 
-Bulk formula routine: \texttt{exf\_bulkformulae.F}
+Radiation calculation: \texttt{exf\_radiation.F}
+
+Wind speed and stress calculation: \texttt{exf\_wind.F}
 
-Generic I/O routine: \texttt{exf\_set\_gen.F}
+Bulk formula: \texttt{exf\_bulkformulae.F}
 
-Interpolation routine: \texttt{exf\_interp.F}
+Generic I/O: \texttt{exf\_set\_gen.F}
+
+Interpolation: \texttt{exf\_interp.F}
 
 Header routines
 
@@ -497,9 +573,13 @@
 \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
@@ -507,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}
@@ -520,11 +602,13 @@
 
 %----------------------------------------------------------------------
 
-\subsubsection{Reference experiments}
-
-global\_with\_exf:
+\subsubsection{Experiments and tutorials that use exf}
+\label{sec:pkg:exf:experiments}
 
-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}
 
 %----------------------------------------------------------------------
 
