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