24 June 1998 TO: Fellow Earth Scientists and Hackers FROM: Peter Bird Department of Earth and Space Sciences University of California Los Angeles, CA 90045 (310) 825-1126 pbird@ess.ucla.edu RE: Introduction to software in the "GRAFIC" subdirectory THIS FILE CONTAINS A GENERAL INTRODUCTION TO THE SOFTWARE I AM OFFERING, WITH INSTRUCTIONS ON HOW TO OBTAIN RELATED PROGRAMS. THIS IS FOLLOWED BY DETAILED NOTES ON THE INDIVIDUAL FILES OF THE "GRAFIC" SUBDIRECTORY. I ASSUME THAT YOU ALREADY HAVE "LARAMY". I currently offer four thin-plate finite-element programs: LARAMY finite-strain no faults flat-Earth crust/mantle FAULTS neotectonics with faults flat-Earth crust only PLATES neotectonics with faults flat-Earth crust/mantle SHELLS neotectonics with faults round-Earth crust/mantle The finite element program LARAMY and the associated graphics programs in the GRAFIC directory may be copied and used without charge or restriction, except that (1) any user who obtains publishable results is expected to acknowledge the source of the program, and (2) no charge may be made for copies of the software which are passed on to third parties. It was developed with support from the National Science Foundation and the University of California, which places it in the public domain. Also, I would be very pleased to see my 6 years of programming effort bring some benefit to others besides myself. Finally, I have no desire to be personally responsible for running simulations of every interesting problem for the rest of my career! The LARAMY program was created to permit simulations of continental deformation in which a crust of either one or two rheological layers (either one of which may enclose the brittle- ductile transition) overlies a mantle lithosphere and/or fluid asthenosphere and/or subducting slabs. While it has been customized for simulations of the Tertiary history of North America, the problem- specific data are mostly enclosed in DATA statements in two BLOCK DATA subprograms which can be replaced with relative ease. Its only fundamental limitations are that it is (1) a continuum program, with no fault discontinuities, but only an equivalent frictional plasticity; (2) rigorously isostatic, and neglects all bending stresses; and (3) written for a flat Earth. The GRAFIC directory contains programs needed to post-process the results of LARAMY runs to produce colored contour maps of the variables on a graphics terminal connected to a system which has IBM's Graphical Data Display Manager. (If you prefer to work on a PC or Mac, see subdirectory Laramy2AI, instead!) Before attempting to work with Laramy, it is essential to gain an overview of the program's structure, abilities, and limitations. Readers are STRONGLY ADVISED to skim the following two articles before proceeding further: Bird, P. (1988) Formation of the Rocky Mountains, western United States: a continuum computer model, Science, v. 239, p. 1501-1507. Bird, P. (1989) New finite element techniques for modeling deformation histories of continents with stratified temperature-dependent rheologies, J. Geophys. Res., v. 94, p. 3967- 3990. The first of these references contains figures which give some idea of the capabilities of the GRAFIC post-processing programs. The software needed to run the GRAFIC programs includes a FORTRAN-77 compiler (vectorizing, if possible) and an IBM graphics package called Graphical Data Display Manager. However, with a little time and ingenuity, the program can be adapted to work with any low- level graphics package, such as DISPLA. About the compiler; it shouldn't matter which one you use, but I have had mysterious bugs under some versions of IBM VS FORTRAN prior to 2.4.0 (for the 3090/VF); version 2.4.0 seem to be OK. You should be aware of useful programs in other subdirectories. Here is an overview. (Note: Numbers 0 - 5 tie to the Read_me.n files.) 0. Laramy2AI (added 1997) is a graphics program that takes output from LARAMY and produces single or multiple maps of various scalar, vector, or tensor variables-- as .AI files readable by Adobe Illustrator for Windows. This allows the maps to be previewed and edited(!) before printing, and also allows the printing to take place on a wide variety of hardware (including hardware run by service bureaus)! The .AI files produced can be read by Adobe Illustrator 4 for Windows 3.1, and by Adobe Illustrator 7 for Windows 95 or Windows NT. They probably can be read by Adobe Illustrator on Macs, too. The processing program Laramy2AI.exe runs on Windows 95 or Windows NT on Intel (or compatible) processors. Source code is also provided in Fortran 90 so that you can move this utility to Mac, Unix, or other systems. 2.GRAFIC (this directory) is a two-part graphics package that post- processes finite element results to produce colored contour maps of all variables, with overlays to show vector and tensor directions and/or state lines, etc. The number-crunching part is run as a batch job, and produces graphics metafiles. The second part is run interactively from a graphics terminal to view the images at various scales, with or without the overlays, etc. These images can be photographed from the screen to make slides. This (older) graphics package requires a package called Graphical Data Display Manager. (To my knowledge, this is only for mainframes, not PCs.) Its capabilities are roughly the same as Laramy2AI, but it is designed for a mainframe environment where you might keep libraries of 20-100 plots (10-50 Mb) per model run. 3. VERSATEC is comparable to Laramy2AI and GRAFIC, but it produces either B/W or color output on a Versatec electrostatic plotter (for publications). It runs as a single batch job and is not interactive at all. 4. FIXER is a fully interactive package for correcting small parts of a finite element grid which become excessively strained, so that a run can continue. It can also be used to fine-tune the files representing initial conditions. (However, it is not a bells-and-whistles grid-generator like some expensive engineering programs offer; just an editor. You must have already created and input a grid with the same topology as the final product you want.) A color graphics monitor attached to your mainframe is required, but not a mouse. This requires IBM's Graphical Data Display Manager. 5. MAPPER is a fully interactive package for making plate reconstructions of oceanic plates which are no longer on the Earth's surface (based on marine magnetic anomaly data and finite rotations) and saving the results in the form of DATA statements that can then be compiled into LARAMY in order to represent complex boundary conditions on the bottom of continents. This program also interactively displays the boundary conditions as they would be applied to a representative finite-element grid, so that unexpected or erroneous BC's can be corrected. A color graphics monitor attached to your mainframe is required, but not a mouse. This also required IBM's Graphical Data Display Manager. The hitch with accessory programs #2-#5 is that, while they have been written in pure FORTRAN77, they make thousands of calls to proprietary graphics packages which may not be available to you. My packages GRAFIC, FIXER, and MAPPER make calls to subroutines of the IBM Graphical Data Display Manager software (sometimes known as "that G*D-D*M* software"); my VERSATEC program calls the proprietary package that is supplied with that brand of plotter. My advice to you is that if you only want to plot output (and you don't have GDDM) you should use Laramy2AI (in a different subdirectory). If you need to use FIXER or MAPPER (and you don't have GDDM) it will probably be easiest and cheapest to hire a programmer to provide dummy interface subroutines that accept these calls and translate them into further calls to your local graphics software (rather than programming these tools from scratch). Or, if you have finite-element post-processors that you are satisfied with, another simple alternative is to write an "output translator" which reads the packed-numbers (device-9) output from LARAMY and puts it into the format required by your existing package. Please understand that I will expect you to communicate with me if you find significant bugs or opportunities for program improvement, and that if you use these programs to obtain publishable results I will expect the source of the program to be acknowledged in your manuscript. I also hope that you will remember me when you have reprints to distribute. =========================================================== NOTES ON THE FILES OF THE "GRAFIC" DIRECTORY GDDMCOMP = Fortran77 source code for the two programs DRAW (creates graphics metafiles) and VIEW (displays graphics metafiles), plus IBM Job Control Language statements needed to compile them into load modules. PAINT = IBM Job Control Language used to run the precompiled program DRAW (see above) as a batch job and store graphics metafiles on disk. VIEWCLST = a short program in the C-List command language of IBM's interactive Time Sharing Option (TSO) environment, used to set up files for an interactive session in which precompiled program VIEW (see above) is run to display graphics metafiles on a terminal. BASEMAP = a file of digitized state lines in North America, useful as a geographic reference to overlay on displays; also a model for similar files that could be created for other regions. ----------------------------------------------------- GDDMCOMP This file has three logical parts: the "outer wrapper" of IBM Job Control Language statements, the program DRAW, and the program VIEW. JCL Statements. =============== The JCL statements all begin with '//'. If you wish to use these programs on a non-IBM system, you will begin by stripping these out and replacing them by commands to your own operating system. Their function is to compile the two programs, link them with the necessary graphics and matrix-algebra packages, and store them as load modules on disk. -IRAAGPB and EFF9GPB are two of my account numbers. Change them to yours everywhere(!) they occur. -I begin with a dummy job step, running a dummy program //CLEAR EXEC PGM=IEFBR14 //DD1 DD DSN=xxxxxxx.GDDMMOD,DISP=(OLD,DELETE) The point of this odd procedure is actually in the following line, which instructs the system to scratch any existing load modules (from a previous compilation). Due to a bug in IBM operating systems, multiple uncatalogued datasets may be created unless you begin with this step. However, on the VERY FIRST run of GDDMCOMP, these two lines: //CLEAR EXEC PGM=IEFBR14 //DD1 DD DSN=xxxxxxx.GDDMMOD,DISP=(OLD,DELETE) should be omitted, because GDDMMOD does not yet exist. -Check with your local consultants for the local name of the Fortran compiler. At UCLA this program FORTVS resides in a dataset called APP1.FORTVS.COMPILER, which has the logical name STEPLIB. However, the name of the dataset may be different at your institution. (I recommend version 2.4.0 or later if you use the IBM VS Fortran compiler; earlier versions have bugs which cause mysterious errors.) At the end of the compilation, the compiled program DRAW is saved in a temporary disk dataset (//SYSLIN DD DSN=&&LOADSET...). It is not yet ready to run because it lacks Fortran, algebraic, and graphical support routines. -In the middle of the file, between programs DRAW and VIEW, there is some further JCL (where you might miss it). This defines the LKED1 (link-edit) step, where the compiled program DRAW is linked with necessary support routines to create load module GDDMMOD(DRAW). Necessary Fortran77 routines are supplied under the name APP1.FORTVS.LIBRARY at UCLA; see your local consultants for the equivalent dataset name at your institution. -A second source of code needed during link-editing is IBM's Engineering & Scientific Subroutine Library, or some equivalent source of a linear-system solver. As described in the first page of DRAW, routines DGBF and DGBS are used to factor and solve real, asymmetric banded linear systems. If you have ESSL at your institution (either the scalar or the vector version is OK), then identify the dataset containing its load modules in the place where I have "APP1.ESSLV". If you don't have ESSL, your work will be a little harder. Substitute appropriate calls to some local libraries. If your computer has 4- byte precision as the default, then use double-precision routines as I have. If your computer (a Cray?) has 8-byte numbers as the default, double precision is not needed and will be very costly. Unfortunately, different solvers assume different storage schemes for the banded coefficient matrix! To preserve portability, I have always referred to the coefficient matrix as a "vector" array, with a single subscript. The index to this vector (i.e., position in memory) is computed from the two logical (row, column) indeces by a statement function INDEXK which appears in many subroutines. Thus, if you change the banded-equation solver called by SOLVER, then you should also write a new statement function INDEXK and copy it into each subprogram that currently has such a statement (the name is always the same). [Incidentally, the incorrect compilation of DRAW by some earlier version of VS Fortran seemed to be connected with improper vectorization of loops which invoked this statement function for indirect addressing. ] -Link-editing also involves some routines from something called "APP1.GDDM4.LOAD". This is our local name for load modules of the IBM Graphical Data Display Manager package. If you have this at your institution, substitute the local name of this partitioned dataset of load modules. If you don't have it, and your system is non-IBM, or you can't convince your institution to get it, then the best alternative is to get only the GDDM manual from IBM, and then to write substitute Fortran subroutines that simulate GDDM functions by using some other graphics package you do have. The best manual to get is "Graphical Data Display Manager Application Programming Guide", catalog number SC33-0148-2, available from Central Library, IBM Corp., P.O. Box 60737, Los Angeles, CA 90060, (213) 621-6479. (If you are adding Fortran routines to translate to another graphics package, this DD statement is the place to identify the location of that other dataset of load modules to the link-editor.) -The link-editor requires its own tiny dataset of control statements, which appears as: //SYSIN DD * ENTRY MAIN INCLUDE SYSLIB(FSINN) INCLUDE SYSLIB(ADMLSYS1) /* The INCLUDE statements tell the link-editor to grab two routines from the GDDM library that will be needed when the program starts to run. I don't know why the link-editor cannot figure this out for itself, but it can't! -The compilation of program VIEW proceeds in the same way, except that the ESSL linear-system routines are not needed. These two compilations could be run separately, if you wish. Program DRAW. ============= Program DRAW resembles a stripped-down version of LARAMY, with the following main differences. While it reads the same parameter- input file as LARAMY, it reads further down into the file to find the plot-control parameters which specify which variables are to be plotted and how. It reads packed-numbers files on device 8 like LARAMY, but it does not produce any new ones. It has no subroutines to calculate the velocities of the nodes or to advance the variables through time, since LARAMY has already done this and stored the arrays in the dataset which will be connected to device 8. And, it has extra graphical subroutines called from the report-writing subroutine REPORT. The most important are PAINT (which does colored contour maps) and ETCH (which draws the finite element grids). The logical heart of the program is subroutine CONTEL which contours the variables within each finite element and then colors in the spaces between the contours. Program DRAW needs to know what kind of output device the metafiles will be displayed on. (Yes, I know that's illogical, but it's true in the world of GDDM!) I designed the program with an IBM 3179-G color graphics terminal in mind, but it will work with others. You must consult with GDDM gurus to determine the "secret code" word that identifies your intended output device, and supply this code word as text in the Fortran statement DATA ASTER /'xxxx'/ near the beginning of DRAW. If you wish to change the color pallette used for contouring, this can be done by adjusting the DATA statements in subroutine PAINT. However, I don't recommend this. Something that the user does not really need to know about (but a programmer might) is that in GDDM one cannot successfully overlay graphical items unless they are in different "graphics segments". For this reason, subroutines PAINT and ETCH will divide each image into a number of segments. Think of them as overlays made of ink on transparent plastic, with the lowest-numbered segment at the bottom, sitting on a black background. In order to make it possible to omit some layers during the display (i.e., state lines, or titles), every image (consisting of the map of a single variable at a single time) is stored as a set of 5 graphics metafiles rather than one. (Confusingly, a graphics metafile may contain more than one segment.) If you must get involved in this, it is useful to know the name convention. The names of these many graphics metafiles are automatically generated, and are all like "V09T05S3" which means "variable #9, timestep #5, and graphics-segment-group #3". The graphics segment numbers are defined in practice by the code in subroutines PAINT and ETCH which create and store them. The timestep numbers refer to the different consecutive "reports" obtained from LARAMY through the input dataset read from device 8 by subroutine GOON. The numbering of the variables that may be displayed is rather arbitrary, but is defined by a menu screen which you will see when you run program VIEW. Program VIEW. ============= This program will be used to view the graphics metafiles interactively from an IBM 3179-G color graphics terminal, or something similar. It is much simpler, as it only takes the graphics metafiles from disk, and turns them into pixel patterns. Its only inputs are the metafiles and some simple commands entered from the terminal. Its only capabilities are to change variable, change timestep, change scale, move the window, and add or delete titles, color bars, and state lines. Note that this program does not specify an output device to GDDM. This is because GDDM has a default that the output device is the terminal in use. However, I would not expect the program to work very well if the terminal is radically different from the one specified in the DATA ASTER /'xxxx'/ statement in program DRAW. The basic plan of VIEW is to: (1) suppress all error messages from GDDM; (2) attempt to load the graphics metafiles containing the titles (only) for every possible variable/timestep combination; (3) create a table of variable/timestep combinations actually available in the dataset (according to the error codes returned); and (4) to enter a loop in which it draws a picture, and then allows you to enter commands which will control the next picture displayed. The commands are all single-letter, and are explained in a menu which automatically pops up when VIEW executes. The most important to remember are M (Menu) to pop-up/suppress the command menu, I (Inventory) to pop-up/suppress the screen listing available images, and Q (Quit) to get out of the loop and stop the program. Commands are enetered only in a 5-character space at the lower right (so as not to obscure the image). They may be upper- or lower-case, and may be combined (up to 5 of them) if you don't leave any spaces between. ----------------------------------------------------- PAINT This is a short file of IBM Job Control Language statements used to run the pre-compiled program DRAW and create graphics metafiles stored on disk. If you are on an IBM MVS system, you can run this with only minor changes; if your system is another type, you may wish to ignore this file completely and start from scratch. However, you should still read the comments below about how the operation of DRAW is controlled by the input file (//SYSIN DD DSN=xxxxxxx.IN9828). -IRAAGPB and EFF9GPB are two of my account numbers. Change them to yours everywhere(!) they occur. -ADMSYMBL and ADMGDF are the logical names of two datasets that the GDDM software expects to find when it runs. The first contains the definitions of the pixel patterns which create the colors used the shade the contour maps (and color bars). The calls to GSPAT in subroutines PAINT and CONTEL will not work unless this dataset is defined; see your consultant for the local name. (If you are converting to another graphics package, then you don't need this line, but you may need something similar.) ADMGDF is the logical name of a partitioned dataset (library) in which the many graphics metafiles are to be stored. My approach is to pre-allocate this before running PAINT. That way, PAINT just adds to the dataset, and I can run it several times for a single finite-element model if I decide to plot a few more variables or a few more timesteps. -The SYSIN dataset is actually file IN9828, which is available in the LARAMY directory. This single unified parameter file combines physical and graphics-control parameters. The graphics commands begin at about line 80, and are all fixed-format (so don't enter them in any other columns than they appear in presently). The first plot parameter is an integer which specifies which timestep is to be plotted (or, you can choose to plot all of them by entering 0). Following that are a list of 24 variables which you may choose to plot. For each variable: Use "T" (True) to plot it or "F" (False) to skip it. The next number following on the line is the desired contour interval (always positive). Do not choose a tiny interval or the program will run out of workspace and "give up on" many of the finite elements, leaving them blank (it will also get very expensive). If you leave this blank, the program will assign a contour interval based on the number of contours you typically prefer. (This is set in an input line further down in the file; try 10.) The third entry on the line, also optional, is a "normal" value of the variable which, if specified, will be "pinned" at a mid-range color (yellow or yellow-green) in all plots. (This is to prevent one undesirable result of auto-scaling, in which the predominant color of a plot changes from one timestep to the next even though the modal value of the variable has not changed.) Finally, there is an integer switch, which is given a value of +1 or -1. This determines which end of the color scale is associated with high values of the variable. A setting of +1 means that red and white shades are high, a setting of - 1 means that blue and black shades are high. Following the list of variables are a number of plot parameters which are used only by the VERSATEC program group in the directory of that name. Specifying plot scales, pen weights, or color vs. B/W will have no effect on the operation of DRAW, which autoscales, uses fixed pen weights, and is always in color. The only parameters in this last group which do affect the plot are: -the number of contours to be used when a contour interval is not given (try 10); the RMS (root-mean- square) size of vector and scalar overlays, in inches (try 0.5); and an option to plot a basemap of state lines. If you do choose to plot state lines, then you will have to connect a dataset such as BASEMAP (provided here) to Fortran device 11 with a DD statement, as I have done in this JCL file PAINT. An interesting option in this program is that the statelines may be retro-deformed to their previous positions if you desire. The way that this is done is the final (present-day) positions of the nodes of the finite-element grid is read from Fortran device 12. Then, the difference in the positions at any timestep currently being plotted is the paleo-displacement. This is interpolated to move all features of the basemap back to their paleo-positions. The result is very elegant; as one flips through a series of plots from past to present, the basemap slowly unflexes from a distorted to a familiar geometry. This option is useful because most geologists think in a reference frame that follows the outcrop, not an abstract one fixed to some distant rigid part of the plate. However, if a computation is not finished, the final node locations may not yet be available! Therefore, there is a logical switch "T" or "F" in the input file just after the switch which selects for inclusion of a basemap, and you can turn off the retrodeformation feature. If you are not using a basemap, then Fortran devices 11 and 12 do not need to be defined in PAINT. If you are not retro-deforming, Fortran device 11 needs to be connected, but not device 12. My preference is to leave the lines in PAINT as a reminder, but to "DUMMY" out the datasets I'm not using. Look at the current contents of PAINT to see an example of this. ----------------------------------------------------- VIEWCLST On the UCLA system, the only interactive environment supporting graphics is IBM's venerable Time Sharing Option (TSO). This is the environment under which the load module produced from program VIEW (see file GDDMCOMP above) is to be run. In this environment, you may attach ("allocate") real datasets (with your choice of name) to logical datasets (with set names) by hand. However, the process is cumbersome, and TSO is very unforgiving about small errors. Therefore, most people automate the process by creating files of commands with a single memnonic name. These files are stored as members in a special partitioned dataset called CLIST, and are invoked by typing their individual names at the TSO prompt. Usually, the institution provides a few default CLIST members, whose format can be followed. IBM also publishes manuals on the special CLIST command language. The contents of file VIEWCLST are the suggested contents of such a CLIST member, which you might wish to name VIEW. They will need at least minor modifications. If you do not have TSO, then perhaps you will wish to follow the spirit rather than the letter of this file. VIEWCLST is really quite simple because our consultants have already created another CLIST for running graphics programs using GDDM; they called it RUNGDDM, and it appears as the last command of VIEWCLST. (Its only argument is the name of the partitioned dataset and member containing the compiled program VIEW that was produced by GDDMCOMP.) Before starting GDDM, however, we need to identify the specific names of two generic datasets, ADMSYMBL and ADMGDF. The first contains the definitions of the pixel patterns which create the colors used the shade the contour maps (and color bars). The calls to GSPAT in subroutines PAINT and CONTEL will not work unless this dataset is defined; see your consultant for the local name, and substitute it into VIEWCLST where I presently have APP5.GDDM4.SYMBOL. (If you are converting to another graphics package, then you don't need this line, but you may need something similar.) ADMGDF is the logical name of a partitioned dataset (library) in which the many graphics metafiles were stored by PAINT (see above). VIEWCLST will prompt you for the name of this partitioned dataset. -IRAAGPB and EFF9GPB are two of my account numbers. Change them to yours everywhere(!) they occur. -VIEWCLST also includes a "fire exit" question just before it loads and runs the main program. This is useful if, for example, you mistyped the name of the dataset of graphics metafiles and got an error message. -VIEWCLST also reminds the user about how to photograph the screen. Note down the information if you need it, because you can't go back to see it again during a session! ----------------------------------------------------- BASEMAP This is a very simple file containing digitised statelines in the 48 conterminous United States, plus the northern 2/3 of Mexico, plus the southern 2/3 of Canada. If you choose (by setting parameters in the Fortran device-5 input file IN9828) to have state lines included in plots, then this dataset is required when you use PAINT to run the compiled version of program DRAW (see GDDMCOMP above). The state lines are then converted to graphics metafiles which can be called up (or not, as you choose) to the screen by program VIEW (see GDDMCOMP above). The state lines are expressed as a sequence of straight-line segments connecting points. The file consists of a string of point positions, and for each a logical indicator (T/F). If the indicator is T, then the "pen is down" when moving to the point, and a segment is drawn. If the indicator is F, then the "pen is up" and we are beginning a new line by moving to its initial point. You can easily write a little program to take digitizer output and put it into this format, for any other region where you need a basemap. The points are expressed as (latitude, longitude) coordinate pairs. The units are degrees. Latitude is positive in the Northern hemisphere. Longitude is positive East of Greenwich, England (the prime meridian). It is not important whether a point is indentified with a positive or a negative longitude (i.e., 245.007 = -114.993). ----------------------------------------------------- GOOD LUCK !!!!!!!!