%=======================================================================
% SVN: $Id: ice_history.tex 5 2005-12-12 17:41:05Z mvr $
%=======================================================================
%  Model History Files

History files contain gridded data values written at specified times
during a model run.  By default, the history files will be written to
the directory {\tt history\_dir} defined in the namelist. 
The netCDF file names are prepended by the character
string given by {\tt history\_file} in the {\tt ice\_nml} namelist.
This character string has been set according to CESM Output Filename Requirements.
If {\tt history\_file} is not set in the namelist, the default character string
{\tt 'iceh'} is used. The user can specify the frequency at which the data
are written. Options are also available to record averaged or instantaneous data.
The form of the history file names are as follows: \\

\noindent Yearly averaged:  {\bf \$CASE.cice.h?.yyyy.nc} \\
Monthly averaged: {\bf \$CASE.cice.h?.yyyy-mm.nc} \\
Daily averaged: {\bf \$CASE.cice.h?.yyyy-mm-dd.nc} \\
Instantaneous ({\tt histfreq} = 'y', 'm', or 'd'): {\bf \$CASE.cice.h?.yyyy-mm-dd-sssss.nc} \\
Instantaneous (written every dt, {\tt histfreq} = 1): {\bf \$CASE.cice.h?.yyyy-mm-dd-sssss.nc} \\

{\tt \$CASE} is set in the main setup script. Note that the {\tt ?} denotes the
multiple stream option where the first stream is just {\tt .h.} and subsequent
streams are {\tt h1, h2, etc}. All history files are written
in the executable directory.  Changes to the frequency and
averaging will affect all output fields.  The best description
of the history data comes from the file itself using the netCDF command
{\tt ncdump -h filename.nc}.  Variables containing grid information are
written to every file and are listed in Table \ref{table:time_grid_hist}.
In addition to the history files, a netCDF file containing a snapshot
of the initial ice state can be created at the start of each run.  The file
name is {\bf \$CASE.cice.i.yyyy-mm-dd-sssss.nc} and is written
in the executable directory.

\subsubsection{Caveats Regarding Averaged Fields} 
\label{avg_fields}

In computing the monthly averages for output to the history files,
most arrays are zeroed out before being filled with data. These
zeros are included in the monthly averages where there is no ice.
For some fileds, this is not a problem, for example, ice thickness
and ice area.  For other fields, this will result in values that
are not representative of the field when ice is present.
Some of the fields affected are:

\begin{itemize}
\item Flat, Fsens - latent and sensible heat fluxes
\item evap - evaporative water flux
\item Fhnet - ice/ocn net heat flux
\item Fswabs - snow/ice/ocn absorbed solar flux
\item strairx, strairy - zonal and meridional atm/ice stress
\item strcorx, strcory - zonal and meridional coriolis stress
\end{itemize}

For some fields, a non-zero value is set where there is no ice.
For example, Tsfc has the freezing point averaged in, and Flwout
has $\sigma T_f^4$ averaged in.  At lower latitudes, these values
can be erroneous. 

To aid in the interpretation of the fields, a field called 
{\it ice\_present} is written to the history file.  It contains
information on the fraction of the time-averaging interval when any
ice was present in the grid cell during the time-averaging interval
in the history file.  This will give an idea of how many
zeros were included in the average.

The second caveat results from the coupler multiplying fluxes it receives
from the ice model by the ice area.  Before sending fluxes to the coupler,
they are divided by the ice area in the ice model.  These are the fluxes
that are written to the history files, they are not what affects the ice,
ocean or atmosphere, nor are they useful for calculating budgets.  The
division by the ice area also creates large values of the fluxes at the
ice edge. The affected fields are:

\begin{itemize}
\item Flat, Fsens - latent and sensible heat fluxes
\item Flwout - outgoing longwave
\item evap - evaporative water flux
\item Fresh - ice/ocn fresh water flux
\item Fhnet - ice/ocn net heat flux
\item Fswabs - snow/ice/ocn absorbed solar flux
\end{itemize}

When applicable, two of the above fields will be written to the
history file:  the value of the field that is sent to the coupler
(divided by ice area) and a value of the flux that has been multiplied by
ice area (what affects the ice). Fluxes multiplied by ice area will have
the suffix {\tt \_aice} appended to the variable names in the history files.
Fluxes sent to the coupler will have "sent to coupler" appended to the
long\_name.  Fields of rainfall and snowfall multiplied by ice area are
written to the history file, since the values are valid everywhere and
represent the precipitation rate on the ice cover.




\subsubsection{Changing Frequency and Averaging} 

The frequency at which data are written to a history file as well as the
interval over which the time average is to be performed is controlled
by the namelist variable {\tt histfreq}.  Data averaging is invoked
by the namelist variable {\tt hist\_avg}.  The averages are constructed
by accumulating the running sums of all variables in memory at each timestep.
The options for both of these variables are described in Table 
\ref{table:setup_nml}.  If {\tt hist\_avg} is true, and {\tt histfreq}
is set to monthly, for example, monthly averaged data is written out on
the last day of the month.

\subsubsection{Changing Content} 
\label{change_content}

The second namelist in the setup script controls what variables are written
to the history file. To remove a field from this list, add the name of the
character variable associated with that field to the {\tt \&icefields\_nml}
namelist in {\bf cice.buildnml.csh}
and assign it a value of {\tt 'xxxxx'}.  For example, to remove
ice thickness and snow cover from the history file, add

\begin{verbatim}
&icefields_nml
    f_hi   =  'xxxxx'
  , f_hs   =  'xxxxx'
/
\end{verbatim}
to the namelist.  

\begin{table}
  \begin{center}
  \leavevmode
  \caption{Time and Grid Information Written to History File}
   \label{table:time_grid_hist}
   \begin{tabular}{lll} \hline
Field          & Description                        & Units         \\
\hline \hline
{\tt time}      & model time                     & days            \\
{\tt time\_bounds} & boundaries for time-averaging interval  & days  \\
{\tt TLON}      & T grid center longitude        & degrees         \\
{\tt TLAT}      & T grid center latitude         & degrees         \\
{\tt ULON}      & U grid center longitude        & degrees         \\
{\tt ULAT}      & U grid center latitude         & degrees         \\
{\tt tmask}     & ocean grid mask (0=land, 1=ocean)&                 \\
{\tt tarea}     & T grid cell area               & m$^{2}$         \\
{\tt uarea}     & U grid cell area               & m$^{2}$         \\
{\tt dxt}       & T cell width through middle    & m               \\
{\tt dyt}       & T cell height through middle   & m               \\
{\tt dxu}       & U cell width through middle    & m               \\
{\tt dyu}       & U cell height through middle   & m               \\
{\tt HTN}       & T cell width North side        & m               \\
{\tt HTE}       & T cell width East side         & m               \\
{\tt ANGLET}    & angle grid makes with latitude line on T grid & radians \\
{\tt ANGLE}     & angle grid makes with latitude line on U grid & radians \\
{\tt ice\_present} & fraction of time-averaging interval that any ice is present& \\
\hline
  \end{tabular}
  \end{center}
\end{table}


  \begin{center}
  \tablecaption{Standard Fields Available for Output to History File}
   \label{table:history_fields}
   \tablefirsthead{\hline}
   \tablehead{\hline {\small\slshape continued from previous page}\\ \hline}
   \tabletail{\hline {\small\slshape continued on next page} \\ \hline}
   \tablelasttail{\hline}
   \begin{supertabular}{lll} \hline
Logical Variable          & Description                          & Units         \\
\hline \hline
\texttt{f\_hi}      & grid box mean ice thickness          & m             \\
\texttt{f\_hs}      & grid box mean snow thickness         & m             \\
\texttt{f\_fs}      & grid box mean snow fraction          & \%            \\
\texttt{f\_Tsfc}    & snow/ice surface temperature         & C             \\
\texttt{f\_aice}    & ice concentration (aggregate)        & \%            \\
\texttt{f\_aice1}   & ice concentration (category 1)       & \%            \\
\texttt{f\_aice2}   & ice concentration (category 2)       & \%            \\
\texttt{f\_aice3}   & ice concentration (category 3)       & \%            \\
\texttt{f\_aice4}   & ice concentration (category 4)       & \%            \\
\texttt{f\_aice5}   & ice concentration (category 5)       & \%            \\
\texttt{f\_aice6}   & ice concentration (category 6)       & \%            \\
\texttt{f\_aice7}   & ice concentration (category 7)       & \%            \\
\texttt{f\_aice8}   & ice concentration (category 8)       & \%            \\
\texttt{f\_aice9}   & ice concentration (category 9)       & \%            \\
\texttt{f\_aice10}  & ice concentration (category 10)      & \%            \\
\texttt{f\_vice1}   & ice volume (category 1)              & m            \\
\texttt{f\_vice2}   & ice volume (category 2)              & m            \\
\texttt{f\_vice3}   & ice volume (category 3)              & m            \\
\texttt{f\_vice4}   & ice volume (category 4)              & m            \\
\texttt{f\_vice5}   & ice volume (category 5)              & m            \\
\texttt{f\_vice6}   & ice volume (category 6)              & m            \\
\texttt{f\_vice7}   & ice volume (category 7)              & m            \\
\texttt{f\_vice8}   & ice volume (category 8)              & m            \\
\texttt{f\_vice9}   & ice volume (category 9)              & m            \\
\texttt{f\_vice10}  & ice volume (category 10)             & m            \\
\texttt{f\_uvel}    & zonal ice velocity                   & cm s$^{-1}$    \\
\texttt{f\_vvel}    & meridional ice velocity              & cm s$^{-1}$    \\
\texttt{f\_fswdn}   & downwelling solar flux               & W m$^{-2}$     \\
\texttt{f\_flwdn}   & downwelling longwave flux            & W m$^{-2}$    \\
\texttt{f\_snow}    & snow fall rate received from coupler & cm day$^{-1}$ \\
\texttt{f\_snow\_ai} & snow fall rate on ice cover       & cm day$^{-1}$ \\
\texttt{f\_rain}    & rain fall rate received from coupler & cm day$^{-1}$ \\
\texttt{f\_rain\_ai} & rain fall rate on ice cover       & cm day$^{-1}$ \\
\texttt{f\_sst}     & sea surface temperature              & C             \\
\texttt{f\_sss}     & sea surface salinity                 & g kg$^{-1}$   \\
\texttt{f\_uocn}    & zonal ocean current                  & cm s$^{-1}$   \\
\texttt{f\_vocn}    & meridional ocean current             & cm s$^{-1}$   \\
\texttt{f\_frzmlt}  & freeze/melt potential                & W m$^{-2}$   \\
\texttt{f\_fswabs}  & absorbed solar flux sent to coupler  & W m$^{-2}$     \\
\texttt{f\_fswabs\_ai} & absorbed solar flux in snow/ocn/ice & W m$^{-2}$     \\
\texttt{f\_aldvr}   & visible direct albedo                & \%             \\
\texttt{f\_aldvi}   & near-infrared direct albedo          & \%             \\
\texttt{f\_flat}    & latent heat flux sent to coupler     & W m$^{-2}$     \\
\texttt{f\_flat\_ai} & ice/atm latent heat flux          & W m$^{-2}$     \\
\texttt{f\_fsens}   & sensible heat flux sent to coupler   & W m$^{-2}$     \\
\texttt{f\_fsens\_ai}& ice/atm sensible heat flux        & W m$^{-2}$     \\
\texttt{f\_flwout}  & outgoing longwave flux sent to coupler & W m$^{-2}$     \\
\texttt{f\_flwout\_ai} & ice/atm outgoing longwave flux    & W m$^{-2}$     \\
\texttt{f\_evap}    & evaporative water flux sent to coupler & cm day$^{-1}$  \\
\texttt{f\_evap\_ai} & ice/atm evaporative water flux      & cm day$^{-1}$  \\
\texttt{f\_Tref}    & 2 m reference temperature            & C              \\
\texttt{f\_Qref}    & 2 m reference specific humidity      & g/kg              \\
\texttt{f\_congel}  & basal ice growth                     & cm day$^{-1}$  \\
\texttt{f\_frazil}  & frazil ice growth                    & cm day$^{-1}$  \\
\texttt{f\_snoice}  & snow-ice formation                   & cm day$^{-1}$  \\
\texttt{f\_meltb}   & basal ice melt                       & cm day$^{-1}$  \\
\texttt{f\_meltt}   & surface ice melt                     & cm day$^{-1}$  \\
\texttt{f\_meltl}   & lateral ice melt                     & cm day$^{-1}$  \\
\texttt{f\_fresh}   & ice/ocn fresh water flux sent to coupler & cm day$^{-1}$   \\
\texttt{f\_fresh\_ai} & ice/ocn fresh water flux         & cm day$^{-1}$   \\
\texttt{f\_fsalt}   & ice to ocn salt flux sent to coupler & kg m$^{-2}$ day$^{-1}$   \\
\texttt{f\_fsalt\_ai} & ice to ocn salt flux               & kg m$^{-2}$ day$^{-1}$   \\
\texttt{f\_fhnet}   & ice/ocn net heat flux sent to coupler& W m$^{-2}$   \\
\texttt{f\_fhnet\_ai}  & ice/ocn net heat flux            & W m$^{-2}$   \\
\texttt{f\_fswthru} & SW transmitted through ice to ocean sent to coupler & W m$^{-2}$   \\
\texttt{f\_fswthru\_ai} & SW transmitted through ice to ocean  & W m$^{-2}$   \\
\texttt{f\_strairx} & zonal atm/ice stress                 & N m$^{-2}$   \\
\texttt{f\_strairy} & meridional atm/ice stress            & N m$^{-2}$   \\
\texttt{f\_strtltx} & zonal sea surface tilt               & m m$^{-1}$   \\
\texttt{f\_strtlty} & meridional sea surface tilt          & m m$^{-1}$   \\
\texttt{f\_strcorx} & zonal coriolis stress                & N m$^{-2}$   \\
\texttt{f\_strcory} & meridional coriolis stress           & N m$^{-2}$   \\
\texttt{f\_strocnx} & zonal ocean/ice stress               & N m$^{-2}$   \\
\texttt{f\_strocny} & meridional ocean/ice stress          & N m$^{-2}$   \\
\texttt{f\_strintx} & zonal internal ice stress            & N m$^{-2}$   \\
\texttt{f\_strinty} & meridional internal ice stress       & N m$^{-2}$   \\
\texttt{f\_strength}& compressive ice strength             & N m$^{-1}$   \\
\texttt{f\_divu}    & velocity divergence                  & \% day$^{-1}$ \\
\texttt{f\_shear}   & strain rate                          & \% day$^{-1}$ \\
\texttt{f\_opening} & lead opening rate                    & \% day$^{-1}$ \\
\texttt{f\_sig1}    & normalized principal stress component &              \\
\texttt{f\_sig2}    & normalized principal stress component &              \\
\texttt{f\_daidtt}  & area tendency due to thermodynamics  & \% day$^{-1}$  \\
\texttt{f\_daidtd}  & area tendency due to dynamics        & \% day$^{-1}$  \\
\texttt{f\_dvidtt}  & ice volume tendency due to thermo.   & cm day$^{-1}$ \\
\texttt{f\_dvidtd}  & ice volume tendency due to dynamics  & cm day$^{-1}$ \\
\texttt{f\_mlt\_onset}  & melt onset date                   & \\
\texttt{f\_frz\_onset}  & freeze onset date                 & \\
\hline
  \end{supertabular}
  \end{center}
%\end{table}

