File contents

                Z E U S - 3 D   V E R S I O N   3 . 4 . 2

 INSTRUCTIONS FOR DOWNLOADING AND PREPROCESSING THE ZEUS-3D SOURCE CODE

                          REVISED 8/6/96

************************************************************************
* These instructions refer to some files on space.ncsa.uiuc.edu,     *
* not our anonymous ftp server (zeus.ncsa.uiuc.edu).                   *
* You must be a registered user to gain access to the ZEUS-3D source   *
* code.  Please fill out the Registration Form or send e-mail to       *
* lca@ncsa.uiuc.edu.  The Registration form can be obtained via the    *
* Web (URL http://zeus.ncsa.uiuc.edu:8080/lca_registration_form.html)  *
* or anonymous ftp (zeus.ncsa.uiuc.edu, cd LCA/info)                   *
************************************************************************


DOWNLOADING THE CODE

The ZEUS-3D source code "zeus34" needs to be preprocessed by a program 
called EDITOR (version 2.2) to customize it for your application before 
it can be compiled.

The script "zeus34.s" performs all the steps necessary to download, 
preprocess, and compile both ZEUS-3D and EDITOR on a number of 
systems (Cray UNICOS; Convex C Series and Exemplar; Silicon Graphics 
workstations, Challenge, Power Challenge; Sun SunOS, Solaris; HP 
PA-RISC-based workstations, IBM RS/6000 workstations, and DEC ALPHA
workstations).

Copy zeus34.s to the directory on your machine in which you wish to 
create the xzeus34 executable, make the script executable ("chmod 700 
zeus34.s"), and run it by typing "zeus34.s".  (Alternatively, you may
download the compressed tar file zeus34.tar.Z, which contains 
everyting you need to build ZEUS-3D on any system; however, this is
less efficient for machines whose names are recognized by the script,
since numerous compiled binaries are already available on-line.)

The script writes many (hopefully) informative messages to your 
terminal to indicate what tasks are being performed and to help 
diagnose any problems that may arise.  If the name of your computer is 
not one of those in the script (uxh, c3, loki, odin, zeus, mario, etc.),
you will be prompted for information about your machine,
including what operating system it runs and whether you have AFS or 
ftp access to NCSA's AFS servers.  You need to know almost nothing 
about AFS to use it within this script.  All you need is the current 
password to the NCSA AFS account "zeus3d" from the LCA to gain access 
via either AFS or ftp.  

When you run zeus34.s for the first time on a new system, the EDITOR 
preprocessor is created through a bootstrap procedure, in which a 
basic version is used to preprocess the full-featured EDITOR source 
code and FORTRAN NAMELIST-emulating library.  The EDITOR executable 
"xedit22" and NAMELIST library "namelist.a" do not need to be recreated 
each time you run zeus34.s to make a customized version of ZEUS-3D; the 
existing files are used if they are already present in the directory 
with zeus34.s when it is run.


PREPROCESSING ZEUS-3D TO SUIT YOUR APPLICATION

ZEUS-3D may be customized for your application in several ways.  As 
described in the ZEUS-3D User Manual, the input file "inzeus" contains 
namelists whose parameters control many aspects of the simulation, 
including output options, initial values, boundary conditions, etc.  
This file is read by ZEUS-3D when it starts running, and the parameters 
in inzeus can be changed without recompiling.

Many of the options in ZEUS-3D are controlled by the EDITOR preprocessor
input file "chgzeus", which is a "change deck" for the ZEUS-3D source.
The maximum sizes of arrays (and the number of zones in each direction)
are prescribed in chgzeus.  In addition, a macro definition file
"zeus34.mac" is read into chgzeus by EDITOR.  The macros in zeus34.mac
control the geometry, included physics, algorithms, subroutine names,
and other parameters.  Finally, a change deck called "chgz34" containing
new source code and modifications to routines already in zeus34 may be
read into chgzeus by EDITOR.  This file contains user-written code to
set up a problem, and possibly some routines that your system libraries
lack coded in Fortran and supplied by the script.

The three files for customizing ZEUS-3D described above can be edited
manually, or they can be combined into a "setup block".  There is
already a setup block in zeus34.s; it sets up the "blast" test problem
in XYZ coordinates using the original CT scheme to evolve magnetic
fields.  Several additional setup blocks may be found on 
space.ncsa.uiuc.edu in the

  /afs/ncsa/projects/lca/codes/zeus3d/tests/

subdirectories; the setup blocks have names like "blast_ZRP", 
"blast_RTP", and "shkset_XYZ".  

If the zeus34.s script is run with no arguments on the command line,
it looks for existing versions of inzeus, chgzeus, and zeus34.mac.  If
any of these do not exist, it creates versions of them from its own
internal setup block.  If instead you type, for example,

  zeus34.s blast_ZRP

then the script uses the inzeus, chgzeus, and zeus34.mac files
contained in the blast_ZRP setup block, OVERWRITING EXISTING VERSIONS.  
Of course, the inzeus, chgzeus, or zeus34.mac files created using a 
setup block could be modified by hand later to further customize 
ZEUS-3D for the desired application.

The setup blocks have a big advantage over manually editing the three
input files in that the setup blocks contain variables for several
parameters such as array dimensions.  The setup blocks contain default
values for these parameters which can be overridden by setting the
values of a few environment variables before running the script.  This
ensures that all the changes necessary to build ZEUS-3D for the desired
grid and create the corresponding inzeus file are carried out correctly.
For example, before running zeus34.s, you could simply type:

% setenv NZX1 64
% setenv NZX2 64
% setenv NZX3 64

to compile the code for a maximum grid size of 64 zones in each 
direction, rather than the default maximum 32 x 32 x 32 grid.  In
addition, a version of inzeus for a 64-cubed grid is created.  A
complete list of ZEUS-3D environment variables is given in zeus34.s.


BENCHMARKING

There is a ZEUS-3D setup block called blast_HY that sets up a 
hydro-only XYZ blast wave.  This has been used extensively
for benchmarking purposes.  See our benchmark database at

  http://zeus.ncsa.uiuc.edu:8080/lca_benchmarks.html

The scripts HYDRO_BM.s, HYDRO_FIXED.s, and HYDRO_SCALED.s, stored
along with blast_HY in 

  /afs/ncsa/projects/lca/codes/zeus3d/tests/blast/XYZ

perform benchmarking studies and print out nice tables of
performance data.  HYDRO_FIXED.s runs the same full problem size
on 1, 2, 4, 8, ... threads.   HYDRO_SCALED.s scales the problem
size with the number of threads.  See the writeup in the scripts for 
more information.


GRAPHICS OUTPUT

If your system does not have NCAR graphics, a set of dummy NCAR 
routines called ncard will be used instead.  These routines cannot
draw any graphs, but they satisfy calls to those routines, allowing
the executable to be created and run without errors or warnings.

If your system does not have NCSA's HDF library ("libdf.a" or "-ldf"), 
you should be able to download it from NCSA's anonymous ftp server 
(ftp.ncsa.uiuc.edu).  A growing number of graphics packages can read
HDF files and display their data.  NCSA offers a number of basic and
free graphics packages.  Full-featured packages based on the NCSA
ones can be purchased from Fortner Research.

You can also write your own output routine for ZEUS-3D (see the 
description of "userdump" in the ZEUS-3D User Manual) and copy it to
chgz34.  Before the first line, put:

*insert zeus3d.9999

so that your routine will be treated as one of the ZEUS-3D routines in
creating the makezeus file.


REMEDIES FOR ERRORS OCCURRING DURING COMPILATION OF THE ZEUS-3D SOURCE

************************************************************************
* If you edit any files to be read by EDITOR, be sure to convert       *
* (substitute) any tab characters with (usually 8) spaces, and be      *
* sure that none of your lines are more than 72 characters long.       *
************************************************************************

If you have trouble compiling or loading ZEUS-3D, you can try altering 
the makefile "makezeus" generated by EDITOR to change compiler options 
or libraries without rerunning zeus34.s.  To create the executable
after editing makezeus by hand, first remove xzeus34 if it exists. 
If all routines need to be recompiled, type "touch zeus3.4/*.f".  You
would need to do this to change compiler options, but would not need
to do it just to change libraries.  Finally, type "make -f makezeus" to
build the executable (use "smake" in place of "make" on SGI systems).

If you have unresolved symbols by the names ismax, idmax, ismin, idmin,
sasum, dasum, isamax, or idamax after loading, your system lacks some 
BLAS routines (found in scilib on Crays, veclib on Convex, and in
complib.sgimath or blas on some SGIs).  You can write or copy 
simplified Fortran versions of most of these routines from zeus34.s.  
Note that isamax is like ismax but finds the element with the largest 
absolute value instead of simply the lagest value.

Unresolved symbols with names like dspdata, dssdims, etc. indicate that
the loader did not find the HDF library "libdf.a".  Some systems have
HDF but the path to it is not in your LIBPATH (by default, LIBPATH is
usually /lib:/usr/lib, so only these two directories are searched).
You can fix this by either changing your LIBPATH environment variable
to also inculde the path to HDF, or by using a compiler command-line 
option (usually -L) to add a directory to the library search path.  
Either of these actions allow you to use "-ldf" as a valid library.
You can also simply use the name of the library itself, e.g.,
/usr/people/<your_signon>/hdf/lib/libdf.a could be used instead of -ldf,
if you have the HDF library in such a directory.


Robert Fiedler
LCA
lca@ncsa.uiuc.edu