File contents

                ZEUS-3D FREQUENTLY ASKED QUESTIONS

                by Robert Fiedler, LCA,  8/18/95


1)  OUTPUT FROM zeus34.s IS TOO VERBOSE 
2)  NAMELIST IN xzeus34 KEEPS GIVING ERRORS 
3)  EDITOR KEEPS GIVING PRECOMPILE ERRORS
4)  UNSATISFIED EXTERNALS ismax, ismin, sasum, isamax, idmax, idmin, ...
5)  USING CHANGE DECKS, MACRO DEFINITION FILES, zeus34.s
6)  ERROR FROM THE mv COMMAND
7)  PIXEL DUMPS DO NOT WORK ON SGI FOR RTP IN THE "3" DIRECTION
8)  HOW TO SPECIFY LOCATION OF A POINT MASS
9)  SELF-GRAVITY MODULE DOES NOT WORK
10) HOT ZONES AND VISCOSITY
11) FLOATING POINT, UNDER/OVERFLOW ERRORS, NaNs, AND
    RUNNING IN DOUBLE PRECISION
12) NUMERICAL MHD INSTABILITIES -- HSMoC
13) RUNNING IN PARALLEL ON SHARED-MEMORY MULTIPROCESSORS
14) ZEUS-3D ENVIRONMENT VARIABLES
15) TURNING OFF INTERACTIVE EDITING
16) MISSING LIBRARIES


1) OUTPUT FROM zeus34.s IS TOO VERBOSE 

Q: I downloaded the script zeus34.s and ran it using the command line:

     csh -v zeus34.s

   as stated in the ZEUS-3D User Manual.

   There is an incredible amount of output written to the screen and I
   cannot tell if there were any error messages.

A: Do not run zeus34.s using csh -v.  Use "chmod u+x zeus34.s" to give 
   yourself execute permission, and then simply type "zeus34.s" to run 
   it.  The instruction to use "csh -v" was removed in the latest 
   version (3.2.1) of the ZEUS-3D User Manual.


2) NAMELIST IN xzeus34 KEEPS GIVING ERRORS 

Q: I'm trying to modify the input file "inzeus" to change some 
   parameters.  Right after I issue "xzeus34", I get error messages 
   about the first character in the line being reserved -- but it looks 
   like a space to me.

A: There is probably a tab character in the offending line.  Substitute
   all tab characters with 8 spaces in any files to be read by ZEUS-3D
   or EDITOR.  Also, with some text editors it is possible to accidently
   delete the last newline (\n) character in a file.


3) EDITOR KEEPS GIVING PRECOMPILE ERRORS

Q: I'm trying to modify chgzeus to change array sizes, but now EDITOR
   complains about the edited lines.  They look perfectly OK to me.

A: EDITOR wants NO TABS and NOTHING BEYOND 72 CHARACTERS.  Replace all
   tabs with 8 spaces, and shorten or break lines longer than 72 
   characters.  Some text editors, such as EMACS, allow you to delete
   the last newline (\n) character in a file (by accident).  This will 
   also cause problems for EDITOR.


4)  UNSATISFIED EXTERNALS ismax, ismin, sasum

Q: I'm trying to compile and load ZEUS-3D on my workstation.  The loader
   warns that it can't find routines ISMAX, ISMIN, SASUM, or ISAMAX.

A: You can use the simplified, unoptimized versions of these routines 
   coded in Fortran.  There of them are contained in the zeus34.s 
   script itself.  Most systems have the ISAMAX routine, which is part
   of the standard BLAS library.  If you do not have it, just take the
   source for ismax and modify it to find the element with the largest
   ABSOLUTE VALUE instead if just the largest value.  

   These routines are in the Cray SCILIB (loaded by default) library, 
   the Convex veclib library, and are supposed to be in SGI 
   complib.sgimath library.  This can be tricky on the Convex, since
   the double precision versions are in veclib8.


5) USING CHANGE DECKS, MACRO DEFINITION FILES, zeus34.s

Q: I'm confused about how to modify ZEUS-3D for the problem I want to 
   solve -- how do I use a change deck?

A: The easiest way is to download the "setup block" for the blast test
   problem for the coordinate system you want to use.  The XYZ 
   version is in .../lca/codes/zeus3d/tests/blast/XYZ, while the ZRP 
   and RTP versions are in the ZRP and RTP subdirectories of .../blast,
   respectively.  These setup blocks produce the macro, chgzeus and 
   input files needed to run the problem -- all you need to do is run 
   the zeus34.s script and edit the files it creates when it gives
   you the opportunity.

   Be sure to change any tab characters to 8 spaces in the 
   files you modify, and limit line lengths to 72 characters or less.  
   If you have a problem generator module whose name is not "blast", 
   be sure to set the PROBLEM alias in zeus34.mac to the correct name.

   As described in the ZEUS-3D User Manual, the file "chgzeus" can 
   contain lines such as "*read chgz34", which tells EDITOR to include 
   the contents of the file chgz34 as it processes the source code.  
   There is nothing special about the name "chgz34" -- the chgzeus file 
   can also have lines such as "*read changes", which will cause 
   EDITOR to use the directives in the file "changes" to edit the 
   ZEUS-3D source.

   Note that even if you put "dthdf=0.2", for example, in 
   the hdfcon block in inzeus, you will not get HDF dumps unless the 
   HDF macro is defined in zeus34.mac.  This applies to the other 
   output options as well.


6) ERROR FROM THE mv COMMAND

Q: I'm running xzeus34 and I get the message, "mv: cannot find gmeta".
   (On some machines, it's GMETA).

A: ZEUS-3D is attempting to rename an NCAR Graphics output file, but it
   does not have the expected name -- gmeta (or GMETA).  To fix this, 
   type "setenv NCARG_GKS_OUTPUT gmeta" (or "setenv NCARG_GKS_OUTPUT 
   GMETA") and rerun xzeus34.  You can put this setenv command in your 
   .login file so that it will be executed for you whenever you log in.


7) PIXEL DUMPS DO NOT WORK ON SGI FOR RTP IN THE "3" DIRECTION

Q: On the SGI Power Challenge at NCSA, certain pixel dumps cause
   ZEUS-3D to quit with a bus error or segmentation violation.

A: This is a known bug.  It happens only in RTP when the normal is in
   the "3" direction.  Changing optimization levels does not seem to
   help.  I think it is a problem with the compiler.


8) HOW TO SPECIFY LOCATION OF A POINT MASS

Q: I want to put a point mass outside my computational grid or at a 
   point away from the origin.  The User Manual mentions izero, jzero,
   kzero, but the code does not seem to know about them.

A: Locating point masses is easy with version 3.4.  You just specify
   the coordinates of the point mass with x1ptm, x2ptm, x3ptm.


9) SELF-GRAVITY MODULE DOES NOT WORK

Q: I would like to use self-gravity in all three coordinate systems on a
   machine without the CRAY Calmath library.  It does not seem to work.

A: We are working on a new one which will be portable, run in parallel,
   be efficient, and work for many geometries and boundary conditions.
   I'll let you know when it is ready...


10) HOT ZONES

Q: I get warnings about HOT ZONES and the computation goes nowhere.

A: A HOT ZONE is a zone in which the Courant condition on the explicit
   time step requires that it must be less than some dtmin.  There are
   several possible ways around this problem.

   The simplest solution is to decrease dtmin by changing the value of
   the parameter "dtrat" in the hycon namelist.  This rarely works.

   Recall that the time step goes as (zone size)/(propagation velocity)
   for non-diffusive flows.  It could be that the grid you are using has
   tiny zones in a region where you are not really interested in the 
   solution.  In a numerically stable scheme, truncation errors tend to
   introduce numerical diffusion which smooths the solution, and thereby
   reduces truncation errors.  Larger zones may damp out some numerical 
   noise in the solution which may have been leading to a HOT ZONE.

   On the other hand, insufficient spatial resolution can lead to 
   unphysical features in the soltion which may cause HOT ZONES.  If
   decreased resolution does not help, try increasing it.

   Artificial viscosity can be used to spread sharp gradients which can
   lead to unphysically large velocities.  If you have shocks in your
   problem, you will probably need the von Neumann artificial viscosity.
   Be aware that this viscosity is not a tensor, so it is not 
   rotationally invariant.  That means it tends to distort the shapes of
   spherical fronts -- they move faster along each coordinate 
   direction than they do in other directions.  Try to use the 
   smallest value of qcon that allows you to get a solution.

   Perhaps you would like to damp everything out, just to see the bulk
   physics.  You can try the artificial viscosity routine called
   VISCSUB in place of VISCOUS.  VISCSUB takes viscosity (both linear
   and quadratic) out of the physical time step calculation and
   performs subcycles including just the viscous terms until it reaches
   the physical time step.  This procedure seems to enhance the effect
   of viscosity, and there are instances where it can distort the shapes
   of shock fronts more than VISCOUS does.

   Consider changing input parameters.  It is difficult to get a 
   solution to problems in which a rapidly moving flow crashes into a 
   boundary because the accuracy of spatial differencing is often lowest
   there.  Do the easiest cases first, and then try to tweak the grid or
   viscosity to get a solution for the stubborn ones.
   
   Think hard about your boundary conditions.  It is very easy to
   specify a problem that makes little physical sense.  HOT ZONES are
   one of ZEUS-3D's ways of telling you that your problem may be 
   ill-posed.
   
   If your boundary conditions impose values on physical quantities
   which are in conflict with the basic equations or your initial 
   conditions, you will notice that the solution looks very different 
   near the boundaries (boundary layer).  This can lead to HOT ZONES.   


11) FLOATING POINT/UNDER/OVERFLOW ERRORS, NaNs, DOUBLE PRECISION

Q: I get floating point, underflow, or overflow errors when I run 
   ZEUS-3D on my 32-bit (4 byte) word machine.  I may need to run in 
double precision.  How can I do this?


A: ZEUS-3D v.3.4, double precision is the default on machines other 
   than Crays.  The precision is controlled by the macro "REAL", which
   is normally aliased to "real*8" in zeus34.mac.  You should not use
   compiler options to promote floating point quantities to 8 bytes.

   The downside of double precision is that such a calculation typically 
   runs somewhat more slowly than it does in single precison -- from 10%
   to 100% depending on the machine arcitechture.

   If you want to run in single precision, alias REAL to "real", copy
   the single-precision namelist library "edit22_nl.a" to namelist.a,
   and recompile the source code.

   Users of machines that the zeus34.s script recognizes (and therefore 
   automatically downloads compiled libraries from NCSA's AFS file
   server) can get edit22_nl.a from space.ncsa.uiuc.edu (141.142.4.10) in
   /afs/ncsa/projects/lca/codes/zeus3d/editor/xeq/<your_machine>.
   Users of other machines can use the edit22_nl.a created in building
   the xedit22 executable.
   
   Some Sun workstations report "inexact" and "underflow" errors after
   the blast test problem terminates.  They get the correct solution,
   however.

12) NUMERICAL MHD INSTABILITIES -- HSMoC

Q: I'm seeing MHD instablilies that should not be there, even in the 
   blast test problem after significant time evolution.  I believe they 
   are numerical.  They greatly amplify the magnetic field.

A: The latest and greatest algorithm for evolving magnetic fields in 
   ZEUS-3D is called HSMoC.  This fix was suggested by John Hawley and 
   Jim Stone.  To use it, define BOTH MOC and HSMOC in zeus3d.mac.
   When these macros are defined, you will see a message from 
   "GREETING" indicating that the HSMOC algorithm has been selected
   when you start running xzeus34.


13) RUNNING IN PARALLEL ON SHARED-MEMORY MULTIPROCESSORS

Q: I would like to run ZEUS-3D across many processors on an SGI
   Challenge/Power Challenge or Convex Exemplar.

A: For SGIs, define the operating system as "IRIX, SGIMP" and set
   IUTASK (either the environment variable or the parameter in
   the inedit file created by zeus34.s) to 1.  This tells EDITOR
   to put parallelization directives in the code.  You will need
   to link the -lm library, and you might want to use -lfastm and
   -lcomplib.sgimath_mp.  For the Exemplar, just set IUTASK=1.
   All of this is done automatically in zeus34.s for machines
   whose names it recognizes.

   Our experience is that the parallel speedup levels off (adding
   more processors does not decrease the run time) at about 8
   processors on the Power Challenge and 10(?) on the Challenge
   for a problem with a 64-cubed mesh.  Unless you are running a
   much larger problem, I would recommend using 4 processors or 
   fewer on either machine for best speedup.  See our WWW page,
   URL http://zeus.ncsa.uiuc.edu:8080/lca_banchmarks.html
   for performance data on many platforms.

14) ZEUS-3D ENVIRONMENT VARIABLES

Q: What evironment variables can I set to make it easier to compile 
   and customize ZEUS-3D for my application?

A: Below is the list from zeus34.s.  The variables marked by a "*"
   are needed to identify your machine if its name is not recognized
   by the script.  If these are not set, you will be prompted for
   values.  Once they are set, the script will pick reasonable
   default values for compilers, flags, and options.  The variables
   marked by a "+" are used in the setup block to customize the
   code and the input file.

#
#   HOST_NAME    Name of your machine (before the first ".")
# * OP_SYS       Operating system name
#   SERVER       Machine to retrieve files from (space.ncsa.uiuc.edu)
#                                               (141.142.4.10)
#   User         Your signon on SERVER (normally zeus3d)
# * ACCESS       Type of file transfer (AFS or ftp)
#   F_COMP       FORTRAN compiler name
#   F_COMP_OPTS  FORTRAN compiler options
#   F_C_OPTS     FORTRAN compiler options for compiling EDITOR
#   REAL         set to "real" for single precision, "real*8" for
#                double precisioa.  Always "real" for UNICOS.
#   IUTASK       EDITOR flag to insert parallelization directives
#                Default value is 0 except for SGI and EXEMPLAR multi-
#                processors
#   C_COMP       C compiler name
#   C_COMP_OPTS  C compiler options
#   LDR          Loader name (./ncargf77 with NCAR 3.1.2 or 3.2.1)
#   LDR_OPTS     Loader options
#   LD           Loader for loading EDITOR, including options
# * HDF          Set to "-ldf" with NCSA HDF library, "" without
# * NCAR_LIB     Set to "ncar" with NCAR v3.x.x, "ncard" without
#   LIBS         Libraries to load including HDF and NCAR
# + NZX1         Number of zones in the "1" direction
# + NZX2         Number of zones in the "2" direction
# + NZX3         Number of zones in the "3" direction
# + NXPX         Number of x-pixels in pixel dumps
# + NYPX         Number of y-pixels in pixel dumps
#   ENVIRONMENT  Set to "BATCH" for no interactive editing of input
#                files (default: INTERACTIVE)
#   PAGER        Utility to display text on the terminal (default: more)
#   EDITOR       Text editor to use on input files (default: vi)  Please
#                do not confuse this with the EDITOR preprocessor!

15) TURNING OFF INTERACTIVE EDITING

Q: I want to run the zeus34.s script without any interactive prompting
   (batch job or do not want option to edit files)

A: Turn off this feature by typing "setenv ENIRONMENT BATCH"
   (or put this command in your batch job script).

16) MISSING LIBRARIES

Q: I am trying to link the libraries to create the executable, but I
   get messages like "UNSATISFIED EXTERNALS: dss..., dsp....

   Or, on one of NCSA's SGI Power Challenge systems, I get the message:
   Library directory </afs/ncsa/packages/ncar/IRIX_6.0/lib> does not exist.

A: The dss... and dsp... routines are in NCSA's HDF library.  HDF is
   available at no charge for many platforms vi anonymous ftp to
   ftp.ncsa.uiuc.edu.  Your system may already have it.  The loader
   command line should have "-ldf", which will cause the loader to
   search your library path (default is /lib and /usr/lib) The default
   library search path can be changed either by setting the LIBPATH
   environment variable or by including "-L<path to libdf.a>" on the
   loader command line.  On NCSA's SGI Power Challenge systems, 
   <path to libdf.a> would be: 

     /afs/ncsa/packages/hdf/IRIX_6.0/lib64.

   At NCSA, the NCAR Graphics libraries are also on AFS.  You should
   put the following line in your .login file:

     setenv NCARG_ROOT /afs/ncsa/packages/ncar/IRIX_6.0

   At NCSA, even if you are not using NCAR, YOU MUST ISSUE A "klog" COMMAND
   TO CONNECT TO AFS BEFORE RUNNING THE zeus34.s SCRIPT OR 
   ATTEMPTING TO LINK THE EXECUTABLE WITH "smake -f makezeus"