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 on the "FIXER" directory 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 "FIXER" 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 editing programs of the FIXER 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 FIXER directory contains an interactive program for editing the node locations and other variable fields which are contained in the packed-number "reports" that LARAMY reads in for initial conditions and writes out periodically during simulations. The two primary uses of FIXER are (1) to adjust the initial conditions file before a run is begun, and (2) to hand-edit portions of the grid which become "folded" due to excess strain, thus permitting a simulation to be resumed rather than abandoned. However, it should be understood that FIXER cannot change the topology of the finite-element grids, and thus is NOT a grid generating program. (Note: If you look elsewhere, in the DRAWGRID directory of this archive, you will find my program DrawGrid, which operates on PCs with DOS or Windows to create grids of 6-node finite elements. You can use this if you eschew fault elements, keep the grid topologically rectangular as required by LARAMY, and if you are prepared to massage the grid file formats a bit.) 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 software needed to run the FIXER program includes a FORTRAN- 77 compiler (vectorizing, if possible), a linear-equation solver (I used one from IBM's ESSL), 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 interactive graphics package, such as DISSPLA. You should be aware of useful programs in related 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 under 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 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 metabolism. 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 requires IBM's Graphical Data Display Manager. 3. VERSATEC is comparable to GRAFIC, but 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 (this directory) 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. You need to have/get/emulate 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. You also need IBM's Graphical Data Display Manager. The hitch with accessory programs #1-#4 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 maps of output (and you don't have GDDM or a Versatec), then use Laramy2AI. If you need to run FIXER (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). However, if you already 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 "FIXER" DIRECTORY FIXRCOMP = Fortran77 source code for the program FIX, plus IBM Job Control Language statements needed to compile it into a load module. 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 FIX (see above) is run to edit finite-element "report" files 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. ----------------------------------------------------- FIXRCOMP This file has teo logical parts: the "outer wrapper" of IBM Job Control Language statements, and the program FIX. 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 program, link it with the necessary graphics and matrix-algebra packages, and store it as a load module 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.FIXERMOD,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 FIXRCOMP, these two lines: //CLEAR EXEC PGM=IEFBR14 //DD1 DD DSN=xxxxxxx.FIXERMOD,DISP=(OLD,DELETE) should be omitted, because FIXERMOD 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 FIX 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. -At the end of the file, there is some further JCL (where you might miss it). This defines the LKED (link-edit) step, where the compiled program FIX is linked with necessary support routines to create load module FIXERMOD(FIX). 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 FIX, 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 library. 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 FIX 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! Program FIX. ============= Program FIX resembles a stripped-down version of LARAMY, with the following main differences. While it also reads packed-numbers files on device 8 like LARAMY, and writes new ones on device 9, there is no physics in it; the changes between input and output are all provided one-node-at-a-time by the user. Also, 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. When FIX begins to run, it first displays a menu of commands, most of which are single letters (or combinations, or single letters followed by numbers). If you have print-screen capability, use it at this point. Otherwise, you can call up the menu anytime by entering "m" (or "M") in the DISPLAY:________ command field. Notice that some letters are used twice, but have different meanings in the DISPLAY command field versus the EDIT command field! (If you have already used program VIEW in my GRAFIC directory, you will already know the DISPLAY commands.) The syntax for entering commands is simple: Use either upper- or lower-case as you wish. Pack as many commands as you like onto the two lines (up to 15 characters each). (Do not leave any spaces, or the command interpreter will stop interpreting.) Generally, they will all execute, in the order typed, with DISPLAY commands executed (internally) before EDIT commands. (However, there are cases where I felt multiple commands could be too confusing, so some commands automatically truncate the string.) When you are a new user, you will tend to give one command at a time. However, the screen must be redrawn after every command, which takes time. Thus, an experienced user will tend to enter strings like: DISPLAY: M3VVIWWXXXXXX EDIT: IH101 which means "turn off the Menu, go to timestep 3 of the input dataset, move down a Variable in the list available for editing (twice), turn off the Inventory display, move the Window west (twice), eXpand the image (6 times), turn on the display of nodes positions and numbers (I), and Highlight node number 101." Generally, the new user's first command will be just "M" in the DISPLAY: field to clear the Menu. They will then be facing the Inventory screen (which is cleared or brought back by I in the DISPLAY command field). This screen shows which timesteps and variables are available for editing, and which one you are working on now. The display is a table, with variables as rows and times as columns. Red squares are not available to edit. Green squares are available. The yellow dot shows which variable and time will appear when the inventory screen is cleared. You can move the dot down with "V" (for next Variable) or Up with "U". If there is more than one report or timestep in the input dataset, you can move horizontally with "F" for Forward or "B" for Back, or just enter the (integer) number of the timestep you wish to jump to. Of course, if this is an initial- conditions file, there will be only one report/timestep. If you are editing output from a long run, you are limited to 24 reports in the input dataset (which makes a VERY BIG dataset!). If necessary, split up your input file before editing. If the variable you choose is one of the two finite element grids (crust or mantle layers), then the next screen (after command "I") will show the grid. Nodes are represented by asterisks (*). There will be a number next to each node, which may have one of two meanings. It is either the index number of the node (which helps you to get the highlight where you want it), or else it is the number of kilometers between the node and the trench edge of the crustal finite element grid (sometimes useful for aligning initial conditions). You can switch the type of number displayed with "I" in the EDIT command field. Each triangular finite element has 7 "integration points" within it, and these are represented by round dots. You cannot edit the dots, but you need to know something about them. The color of the dot is determined by the value of the determinant of the Jacobian matrix of the function which maps from internal element coordinates (S1,S2,S3) to external (x,y) coordinates. Program LARAMY cannot proceed unless these values are all positive! (If one is negative, it means that the element is "folded over" and doubled back on itself, so that there is no unique functional relationship between (x,y) and (S1,S2,S3). When the sides of the triangular elements are all straight, these values are 1.0. If the value is less than 0.5, a yellow dot is displayed. If it is less than 0., a red dot is displayed. YOU SHOULD EDIT UNTIL YOU HAVE CLEARED ALL THE RED DOTS; it is also advisable to clear the yellow ones. You change the dot colors by moving nodes. If you just want to straighten an element side, Highlight the node at the midpoint of that side, and then enter "Z". If you want to move a corner node, you must first highlight it and then use the "V" (Vector command). For example, to move node 317 west 1 inch and south 0.2 inches, you enter: EDIT: H317VW1.VS.2 (Notice that the "V" is repeated before each component. I should also explain that the meaning of "North", "East", etc. is not precise except near the origin of your coordinate system. In other places, "East" really means +x, or right.) When you have all the nodes placed properly, you need to F(ix) the changes you have made to this variable. Otherwise, they will dissapear if you switch to a different variable or time! This is to prevent you from losing a whole session due to a foul-up, but it means that you can lose part of a session if you forget to F(ix)! A related caution is that the F(ix) command only applies to the computer's memory; to write a modified output file you must enter the command (W)rite command toward the end of your session! If you enter W(rite) more than once, multiple edited reports will be stacked in your output dataset, which quickly grows rather large! If the variable you have selected is not a finite-element grid, you will see a colored contour map. For scalar values, this is all. However, vector variables (velocity) will be colored according to the magnitude of the vector, and a selection of point vectors will be plotted to show direction. Obviously, you modify scalar values with the S(calar) command, and vector values with the V(ector) command, followed by a direction and a floating-point number. (For some odd reason, there will be an error message if you leave out the decimal point.) For your convenience, the units of the editing changes are NOT the original units of the variables. Instead, the unit for Vector changes is inches-on-the-display (as above), while the unit for Scalar changes is a number of contour intervals. A useful option is command "I" in the EDIT field, which will bring up (or suppress) the node locations and their index numbers. This makes it easier to move the highlight mark to the node you wish to modify. When you have all the nodes placed properly, you need to F(ix) the changes you have made to this variable. Otherwise, they will dissapear if you switch to a different variable or time! This is to prevent you from losing a whole session due to a foul-up, but it means that you can lose part of a session if you forget to F(ix)! A related caution is that the F(ix) command only applies to the computer's memory; to write a modified output file you must enter the command (W)rite command toward the end of your session! If you enter W(rite) more than once, multiple edited reports will be stacked in your output dataset, which quickly grows rather large! ----------------------------------------------------- FIXCLIST 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 FIX (see file FIXRCOMP above) is to be run. In this environment, you may attach ("allocate") read 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 FIXCLIST (provided) are the suggested contents of such a CLIST member, which you might wish to name FIX. 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. FIXCLIST 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 FIXCLIST. (Its only argument is the name of the partitioned dataset and member containing the compiled program FIX that was produced by FIXRCOMP.) Before starting GDDM, however, we need to identify the specific names of some generic datasets, FT04F001, FT08F001, FT09F001, FT11F001, SYSCP, and ADMSYMBL. FT04F001 is the input file to be read from Fortran device 4, and it should be IN9828 (from the LARAMY directory), or a parameter file of similar format. Note that the plot-control parameters at the end of this file will not be used. The most important information that FIX will get out of the file is the number of rows and columns in the finite element grid, the location of the (x,y) origin, and the radius of the Earth. FT08F001 is the packed-numbers file read/written by LARAMY which you wish to edit. You can use file CORD11N from the LARAMY directory to try out FIX the first time. This file is NOT overwritten by edits, instead a new file is created. FT09F001 is the output file, modified from FT08F001. Notice that naming an output file is optional (you can just hit Enter instead), but that you can't change your mind later in the session and save your work! Therefore, I always designate one, even when I don't expect to use it. The name should be a new one; if the file exists, a fatal error results. FT11F001 is the file of state lines used as a basemap. Use BASEMAP (provided). Designating this file is not optional, but once inside FIX you can choose not the display its contents. This file cannot be edited. SYSCP is the logical name under which Graphical Data Display Manager expects to find its partitioned dataset of load modules. Find out from your local consultants where they are stored, and substitute the name in FIXCLIST where I currently specify APP1.GDDM4.LOAD. ADMSYMBL is the logical name under which Graphical Data Display Manager expects to find its dataset of color shading patterns. Find out from your local consultants where they are stored, and substitute the name in FIXCLIST where I currently specify APP1.GDDM4.SYMBOL. -IRAAGPB and EFF9GPB are two of my account numbers. Change them to yours everywhere(!) they occur. -VIEWCLST also includes two "fire exit" questions before it loads and runs the main program. This is useful if, for example, you mistyped the name of a dataset and got an error message. ----------------------------------------------------- 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 (provided) 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 !!!!!!!!