/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright (C) 1998-2004 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 & ---------------------------------------------------------------------------------