 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *                                                                 *
 * Copyright (C) 1998-2009 Timothy E. Dowling                      *
 *                                                                 *
 * This program is free software; you can redistribute it and/or   *
 * modify it under the terms of the GNU General Public License     *
 * as published by the Free Software Foundation; either version 2  *
 * of the License, or (at your option) any later version.          *
 * A copy of this License is in the file:                          *
 *   $EPIC4_PATH/License.txt                                       *
 *                                                                 *
 * This program is distributed in the hope that it will be useful, *
 * but WITHOUT ANY WARRANTY; without even the implied warranty of  *
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.            *
 *                                                                 *
 * You should have received a copy of the GNU General Public       *
 * License along with this program; if not, write to the Free      *
 * Software Foundation, Inc., 51 Franklin Street, Fifth Floor,     *
 * Boston, MA 02110-1301, USA.                                     *
 *                                                                 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

=====================================================================
The Explicit Planetary Isentropic Coordinate (EPIC) Atmospheric Model
                        Version History
=====================================================================

===========
Version 4.3
===========

T. Dowling (04/2009):

 1) Horizontal velocities, U and V, have been moved from the layers to the layer interfaces,
    as has the turbulence variable NU_TURB. Already on the interfaces were THETA and
    the mixing rations Qsp (s is species index, p is phase index). The goal is a 
    reduction of computational modes caused by vertical averaging. The hybrid density, H, 
    remains the only prognostic variable carried in the layers.

 2) Hydrostatic integration has been improved. The model now defaults to the finite-volume   
    formulation for horizontal pressure gradient force.  These changes reduce the
    spurious-wind problem in steep terrain.

 3) For arrays, the model is now writing and reading from epic.nc layers K = 0 to grid.nk
    (instead of 1 to grid.nk), which includes the top and bottom interfaces of the model.
    The epic.nc file format now includes P3, full pressure on the interfaces, instead of
    HDRY, the dry hybrid densith in the layers, since pressure is more intuitive and
    the density does not contain information about the pressure at the top of the model.

 4) Time is now computed as UTC calendar time, instead of arbitrary time, 
    to facilitate models with seasonal forcing. The model's starting time is user specified.
    The macro TIME behaves as before, giving the elapsed time since this start in seconds
    as a floating point number.

 5) Keplerian orbital elements are now included for calculation of orbit position, plus
    season with respect to time, for Epoch J2000.

 6) Gravity has been upgraded from a constant to a function of latitude, based on
    the planet's Omega, J2 and GM. Saturn in particular has a large variation in g with latitude.

 7) We are now distinguishing between the sidereal and synodic angular velocities for
    planetary rotation (planet->omega_sidereal and planet->omega_synodic).

 8) The model's path environment variable has been changed from "EPIC_PATH" to "EPIC4_PATH".
    The version without the "4" now refers to the older EPIC Version 3 (the pure-isentropic
    coordinate model). Making this distinction facilitates compiling different versions
    of the model on the same computer.

 9) The executable epic (and mpi_epic) now gets its t_vs_p and t_cool_vs_p profiles from
    the input epic.nc file, rather than reading them in at runtime from epic/data.  The 
    executable initial now looks for these profiles, as well as u_vs_lat, in the local 
    directory first, and then in epic/data.

10) Fixed known bugs.

===========
Version 4.2
===========

T. Dowling (10/2007):

 1) Advection of theta in the sigma region improved from the 1st-order
    upwind scheme, which is highly dissipative and therefore undesirable,
    to the Hsu predictor corrector or Akima monotonized, centered scheme.
    The Hsu scheme is the default and is recommended.

 2) Improved hyperviscosity operators.  The meridional hyperviscosity
    now uses finite-difference weights generated by fitting the first
    three Legendre polynomials to the 3-pt stencil. This greatly improves
    the model's behavior at the poles. It alse runs faster than the previous
    algorithm.  The zonal hyperviscosity is now based on the Crank-Nicolson
    scheme, which provides both stability and accuracy.

 3) Added the Earth case. This is being developed primarily at New Mexico Tech, 
    by Dave Raymond's group. Their integrated "toy physics" cumulus 
    parameterization, precipitation and radiation package is called nmt_physics.

 4) Added the option of Fred Fritsch's PCHIP 
    monotonic spline.  The issue is that a regular cubic spline is smooth 
    but not monotonic, whereas the PCHIP (piecewise cubic
    Hermite interpolating polynomial) spline is both smooth and monotonic.

 5) Added the Akima advection scheme as an option.  As with other centered,
    fourth-order schemes, this one is noisy and typically requires biharmonic
    hyperviscosity (nu4) to keep under control.  However, it provides a
    useful alternative to the Hsu predictor corrector.

 6) Upgraded the netcdf output files (epic.nc, extract.nc) to meet the 
    Climate and Forecast (CF) and Common Data Model (CDM) metadata conventions.
    This means that plotting packages like Panoply and IDV will automatically
    recognize the variables, units, and axes in EPIC output files.

 7) Fixed known bugs.


===========
Version 4.1
===========

T. Dowling (09/2006):

 1) Included Jupiter cloud microphysics model. (Csaba Palotai)
 2) Now maintaining bottom pressure as constant for the gas-giant case.
    This fixes a bug that was causing vortices to not hold together, which
    stemmed from the calculation of the bottom geopotential via gradient
    balance; we were using the constant-pressure formulation but allowing
    the bottom pressure to evolve.  Now, 'sigma' is
    a pressure coordinate for the gas-giant case.  The terrestrial
    case is unaffected by this change. (Tim Dowling)
 3) Added new initialization scheme based on inversion of an elliptic problem
    (Aaron Herrnstein).  This yields improved initial balance between
    the mass and momentum fields.
 4) Latest Matlab tools. (Aaron Herrnstein)
 9) Fixed known bugs.

===========
Version 4.0
===========

T. Dowling (8/2005):

  1) Converted to hybrid isentropic-sigma vertical coordinate.
  2) Added terrestrial planets.
  3) Added phase changes and latent heating of multiple condensables.
  4) Converted remaining Fortran subroutines into C.
  5) Fixed known bugs.

===========
Version 3.9
===========

T. Dowling (12/2002):

This version number was reserved for Adam Showman for some independent
development.

===========
Version 3.8
===========

T. Dowling (7/1998):

  1) Incorporated P. Gierasch's saturation vapor-pressure fortran 
     functions.
  2) Switched to the NetCDF standard (Network Common Data Format). 
  3) Added chemical_elements.h, which contains the atomic numbers,
     names, symbols, molar masses (atomic weights), and solar 
     abundances of the elements.
  4) Added specific humidities (water, ammonia, methane, etc.)
     as optional prognostic variables.
  5) Fixed known bugs.
 

===========
Version 3.7
===========

T. Dowling (4/1998):

  1) Added virial equation of state. The choices are now "ideal" and
     "virial."
  2) 1st and 2nd time steps now use 1st and 2nd order Adams-Bashforth
     steps, instead of a cold start (zero tendencies) for the model's 
     3rd order Adams-Bashforth time step.
  3) Switched from rsh to ssh (secure remote shell) for EPIC_Receive
     AVS module.
  4) Voyager velocity data files for Jupiter's Great Red Spot and White 
     Oval BC now included in $EPIC4_PATH/data/jupiter.
  5) Fixed known bugs.

===========
Version 3.6
===========

T. Dowling (4/1998):

First version posted on the NASA Planetary Data System (PDS)
Atmospheres Node.

The EPIC Model is described in Dowling et al (1998, Icarus 132, 221-238) 
"The Explicit Planetary Isentropic Coordinate (EPIC) Atmospheric Model."

C. Santori (5/30/1997):

 1) u_vs_lat.saturn: u at 89S latitude changed from 16.20 to 16.30.
 2) mqspec structure added to epic.h.
 3) Definitions of initialization types (search for SORPTOP) added to epic.h.
 4) Function prototypes for mont_from_q and low_mode added to epic.h.
 5) epic_init_funcs.c replaced entirely.
 6) Section inside "else if (grid.init_type == USE_Q_VS_M) {" replaced.
 7) epic_init_eigen.c added to epic/src/shared.
 8) Makefile.epic: epic_init_eigen.c added, mimicking epic_init_funcs.c.
 9) Spinup questions removed for case Q(M).
10) New defaults added.


