/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *                                                                 *
 * 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.                                     *
 *                                                                 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

 Explicit Planetary Isentropic-Coordinate 
      (EPIC) Atmospheric Model
            Version 4.30

  Required: 
    Unix operating system

  Included third-party, GPL-licence open software:
    netCDF: self-describing file format

  Optional: 
    MPI (Message Passing Interface), for running EPIC on parallel
    computers. Free versions of MPI are available, including openmpi
    and mpich, and commercial versions are available.
    
    A host of software packages will input the self-describing
    netcdf files used by EPIC (epic.nc and extract.nc).  They tend
    to have an Earth-continent grid superimposed by default, but this
    can easily be turned off.
    We recommend:
      Panoply:
        free from http://www.giss.nasa.gov/tools/panoply/
      IDV (Integrated Data Viewer): 
        free from http://www.unidata.ucar.edu/software/idv/

    Sample tools for Matlab, IDL, and Mathematica are included in
    $EPIC4_PATH/tools. We welcome additions to this collection. 

 Topics covered:
   A. INSTALLING
   B. TROUBLESHOOTING
   C. INITIALIZING
   D. CHANGING
   E. RUNNING FROM COMMAND-LINE
    
=========================================================================
=========================================================================

A. INSTALLING 

  1.  To decompress and de-archive the file epic.tar.gz:

      a) If a directory named epic already exists, delete it (or move it):
           rm -r epic
      b) Type 
           gunzip epic.tar.gz 
           tar xpf epic.tar
           gzip epic.tar

      This will produce a directory tree similar to:

epic/           Top EPIC-model directory.
  bin/          Executable files.
  data/         Data for the planets.
  help/         Help files for executables.
  include/      Header (.h) files.
  License.txt   Software license.
  netcdf/       Source code for Network Common Data Format.
  notes/        Brief remarks on version history, etc.
  README.txt    This file.
  src/
    mpg/        Grid decomposition MPI functions.
    mpi/        MPI (parallel-processor) specific code.
    shared/     Platform independent code.
    single/     Single-processor specific code.
  tmp/          A location for temporary files.
  tools/        Analysis tools that work with external software.
  util/         Unix utility programs such as shell scripts.

  2. To archive and compress the model:

      a) Clear any object code by typing
           cd $EPIC4_PATH/src
           make clear

      b) Move up to the directory containing epic and type
           touch epic
           tar cf epic.tar epic
           gzip epic.tar

     Note: usage of the environment variable $EPIC4_PATH
     is enabled after completing step 3.


  3. In your shell resource file (such as .cshrc or .bashrc), add the
     following lines, and then edit them for your environment:

     For a .cshrc or .tcshrc file:

setenv EPIC4_PATH        ~/epic
setenv MPI_TYPE         openmpi
setenv MACHINE_TYPE     `$EPIC4_PATH/util/get_machine_type.sh`
setenv EPIC_CC          gcc
setenv EPIC_CFLAG       -g
setenv EPIC_PRECISION   8

      For a .bashrc file:

export EPIC4_PATH=~/epic
export MPI_TYPE=openmpi
export MACHINE_TYPE=`$EPIC4_PATH/util/get_machine_type.sh`
export EPIC_CC=gcc
export EPIC_CFLAG=-g
export EPIC_PRECISION=8

      NOTE: It is important that the quotes around
            $EPIC4_PATH/util/get_machine_type.sh 
            be backwards single quotes on both ends (`...`),
            such that the output of get_machine_type.sh gets written
            into MACHINE_TYPE.

      EPIC4_PATH is the unix path where the EPIC model is kept.
      It is distinct from "EPIC_PATH" without the "4", which should be used for
      the odler Version 3 of the model (the pure isentropic-coordinate version).
      Keeping these distinct facilitates compiling different versions of
      the EPIC model on the same computer.

      MPI_TYPE
            Assuming the syntax for .cshrc, the choices are:

            No MPI: setenv MPI_TYPE none
          Open MPI: setenv MPI_TYPE openmpi
               LAM: setenv MPI_TYPE LAM
             mpich: setenv MPI_TYPE mpich

      MACHINE_TYPE is set by the shell script get_machine_type.sh.

      EPIC_CC is the name of the C compiler to be used.

           NOTE: Use the most ANSI-compatible compiler available.
                 For example, on the SunOS use c89, not the default cc,
                 or install and use the most recent gcc from Gnu.

      EPIC_CFLAG has the following recognized cases
           "-O" for optimizing
           "-g" for debugging and extra checks of the validity of values
           "-p" for profiling
           "-pO" for profiling and optimizing
           In each case, an attempt is made in the top makefile to use
           the best flags depending on the platform. 

           Alternatively, you can elect to not set EPIC_CFLAG ("unsetenv EPIC_CFLAG"),
           or set it to an unrecognized case, and then pass your own flags via the 
           environment variables CFLAGS and LDFLAGS, 
           to the C compiler and linker, respectively. This is easy
           to do and advanced users are welcome to do it.

           NOTE: gcc version 2.96 with -O2 optimization, which is what "EPIC_CFLAG -O" sets up,
                 sometimes yields spurious nans (not-a-numbers) when running EPIC, and should 
                 therefore not be used. No such problem is known to occur with "EPIC_CFLAG -g" 
                 for gcc 2.96.
                 
      EPIC_PRECISION is set to "4" or "8" to compile the model with 
           single-precision or double-precision floating-point variables, 
           respectively. Double precision is recommended for long runs.

    In addition, for MPI you may need to add lines to your path like the following:
      /usr/local/mpi/lib/hpux/ch_shmem   (that is, ../lib/$(ARCH)/$(COMM))
      /usr/local/mpi/bin

    These changes will take effect when you next log in. 
    You can make the changes take effect now by typing:
      source ~/.cshrc

  4.  To compile the model:

      a) Change directories to the source directory by typing
           cd $EPIC4_PATH/src 

      b) If desired, clear previously compiled object code by typing
           make clear
         If only a few changes have been made to the source code, then
         skipping this step will avoid unnecessary compilations.
         To be on the safe side, after modifications to header files like 
         $EPIC4_PATH/include/epic.h, one should use make clear.

      c) Compile the model by typing
           make install 

      If the compilation is successful, the executables will be  
      found in $EPIC4_PATH/bin.

  5.  The IDL tools in $EPIC4_PATH/tools/IDL use the environoment variable
      IDL_EPIC4_PATH, which should be set to be the working directory for
      IDL plots and movies.

=========================================================================
=========================================================================

B. TROUBLESHOOTING

 1. If the netCDF make fails, look at the file 
    $EPIC4_PATH/netcdf/src/INSTALL for examples of environment variables
    that work for various platforms.  Use a working combination for your
    platform (ideally ones with "-O" flags for optimization) in your 
    ~/.cshrc file, type "source ~/.cshrc" and then recompile.

 2. A "semget" or other semaphore error can usually be cleared up by using 
    ipcs and ipcrm, or for example mpich's sbin/cleanipcs script, which 
    calls these functions.

=========================================================================
=========================================================================

C. INITIALIZING

   The information needed to start the EPIC model is contained in
   a single epic.nc file. The program "initial" generates this
   information.  

=========================================================================
=========================================================================

D. CHANGING

   If you wish to change only a few parameters in an existing
   epic.nc file, use the program "change," which reads an epic.nc file,
   prompts for changes, and then writes a new file.
   You will probably want to customize the prompts in 
   $EPIC4_PATH/src/shared/epic_change.c. 

   To learn about other uses of the change program try the 
   "-h" or "-help" command-line flag.

=========================================================================
=========================================================================

E. RUNNING FROM COMMAND-LINE

   Typing the name of the epic program with the command-line flag
   -h or -help prints the options on the screen.  For example, type:

%epic -h

   to get a list of command-line flags and their meanings.
      
   To integrate the file epic.nc forward 10000 timesteps as a batch job,
   saving twice and backing up every 1000, with error messages to be 
   written to the file ``epig.log'', type:

%epic -itrun 10000 -itsave 5000 -itback 1000 epic.nc >& epic.log &

   To write an extract.nc file every 100 steps, first choose the variables
   to extract using initial or change, and then run the model with:

%epic -itrun 10000 -itsave 5000 -itback 1000 -itextract 100 epic.nc >& epic.log &

   To append to an existing extract.nc file called extract2.nc, type

%epic -itrun 10000 -itsave 5000 -itback 1000 -itextract 100 -append extract2.nc epic.nc >& epic.log &

=========================================================================
=========================================================================