
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *                                                                 *
 * Copyright (C) 1998-1999 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:                          *
 *   $EPIC_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., 59 Temple Place - Suite 330,         *
 * Boston, MA  02111-1307, USA.                                    *
 *                                                                 *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

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

  Required: 
    Unix operating system

  Optional: 
    MPI - message passing interface software (free)
    AVS - visualization software (commercial)

 Topics covered:
   A. INSTALLING
   B. TROUBLESHOOTING
   C. INITIALIZING
   D. CHANGING
   E. RUNNING
    
====================================================================
====================================================================

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.
  License.txt   Software license.
  README.txt    This file.
  avs/          AVS misc files.
  bin/          Executable files.
  data/         Data for the planets.
  help/         Help files for executables.
  idl/          IDL plotting .pro files.
  include/      Header (.h) files.
  netcdf/       Source code for Network Common Data Format.
  notes/        Remarks on version history, etc.
  src/
    mpg/        Grid decomposition MPI functions.
    mpi/        MPI (parallel-processor) specific code.
    shared/     Platform independent code.
    single/     Single-processor specific code.
    view/       Visualization, control, and diagnostic code.
  tmp/          A location for temporary files.
  util/         Utility programs, like shell scripts.

  2. To archive and compress the model:

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

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

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


  3. In your .cshrc file, or relevant dot-file, add the
     following lines, and then edit them for your environment:

setenv EPIC_MPI_HOST    matins.spd.louisville.edu
setenv EPIC_SINGLE_HOST flolab.spd.louisville.edu
setenv EPIC_VIEW_HOST   flolab.spd.louisville.edu
setenv EPIC_PATH        /fvl/dowling2/epic
setenv MPI_PATH         none
setenv AVS_PATH         /fvl/avs/avs
setenv MACHINE_TYPE `$EPIC_PATH/util/get_machine_type.sh`
setenv MACHINE_NAME `$EPIC_PATH/util/get_machine_name.sh`
setenv EPIC_CC cc
setenv EPIC_FC f77
setenv EPIC_CFLAG -O

      EPIC_MPI_HOST is the full internet name of the front-end 
           to a parallel computer running MPI (Message Passing Interface).
           If none exists, write "setenv EPIC_MPI_HOST none".

      EPIC_SINGLE_HOST is the full internet name of the unix computer 
           running the single-processor version of the model.

      EPIC_VIEW_HOST is the full internet name of the graphics workstation
           running AVS to view and control the model.
           If none exists, write "setenv EPIC_VIEW_HOST none".

      EPIC_PATH is the unix path where the EPIC model is kept.

      MPI_PATH is the unix path where MPI is kept. If not available,
           write "setenv MPI_PATH none".

      AVS_PATH is the unix path where AVS is kept. If not available,
           write "setenv AVS_PATH none".

      MACHINE_TYPE is set by the shell script get_machine_type.sh.

      MACHINE_NAME is set by the shell script get_machine_name.sh. This
           may need to be edited to work properly on your computer.

      EPIC_CC is the name of the C compiler to be used. Most of the model
           is written in C.

      EPIC_FC is the name of the Fortran compiler to be used. Parts
           of the model are written in Fortran.  Additions can be made
           in either C or Fortran.

      EPIC_CFLAG is set to the mneumonic "-O" for optimization or
           "-g" for debugging.  In practice, this environment variable often
           needs to be changed before recompiling.

    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 $EPIC_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 
         $EPIC_PATH/include/epic.h, one should use make clear.

      c) Dependencies may be determined by typing
           make depend
         This step is optional.

      d) Compile the model by typing
           make install 

      If the compilation is successful, the executables will be  
      automatically placed in $EPIC_PATH/bin.

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

B. TROUBLESHOOTING

 1. Makefile library flags

   The most common problem encountered when compiling the EPIC model 
   in a new environment is related to library flags in the makefiles, 
   usually nonstandard libraries that hold Fortran math functions not 
   found in libm.a. 
   At present, we are handling these on a platform-by-platform basis. 
   The makefile library flags that may need to be edited are preceded 
   by the comment:
#
# These library flags may need tuning for other platforms.
#
   The makefile statements that use these flags have the form 
   "if [ $(MACHINE_TYPE) = ... ]".
   Use the command "ar -t libname.a", where libname is a particular library,
   to search and locate those function calls that the linker (ld) reports 
   it cannot find, and add links to the appropriate libraries.

  2. $EPIC_PATH/util/get_machine_name.sh

    Another common problem is the shell script "get_machine_name.sh" in
    $EPIC_PATH/util.  The user may need to edit this so that it properly returns
    the full internet name of the host computer. Sometimes, the problem is
    simply that the shell scripts in this directory do not have executable
    permission, in which case chmod will fix the problem.

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

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 may want to customize the prompts in 
  $EPIC_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

  1. With AVS

    The most convenient way to control and visualize the EPIC model is 
    through a graphical user interface (GUI).  Included with the model
    is an AVS graphical user interface (AVS is commercial software).
   
    --Details on using AVS go here--

  2. Without a Graphical User Interface

    The EPIC model may be run without a graphical user interface.
    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.LINUX -h

    to get a list of command-line flags and their meanings.
      
------------------------------ Example 3 ----------------------------------------  

   To integrate the file epic.nc forward 10000 timesteps as a batch job,
   saving twice and backing up every 1000, for code compiled and running
   on an HP, with error messages to be written to the file ``log'', type:

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


---------------------------------------------------------------------------------  


    
