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 "Laramy2AI" 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 "Laramy2AI" DIRECTORY. 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 of the Laramy2AI 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 Laramy2AI directory contains programs needed to post-process the initial conditions and/or results of LARAMY runs to produce either black & white or colored contour maps of the variables. The output format is a PostScript metafile, which can be read by Adobe Illustrator 4 for Windows 3.1, and by Adobe Illustrator 7 for Windows 95 or Windows NT. (It may also be readable by Adobe Illustrator for Macintosh; I haven't tried.) Once you are viewing the maps in Adobe Illustrator, you can edit then, modify them, and print them on a wide variety of output devices (including those owned by service bureaus)! 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 Laramy2AI post-processing programs. (Actually, these images where created with the GRAFIC package and photographed off of a terminal; the Laramy2AI package has the same capabilities, except that the backgrounds will be usually be white.) Laramy2AI is provided in two forms: Laramy2AI.exe is an executable for 32-bit Windows (Windows 95 or Windows NT) running on Intel (or compatible) chips. It uses a simple text-mode interface, but requires the large amounts of memory available in 32-bit systems. If you insist on running Laramy2AI on another system (Mac, Unix, ...) OR if you need to increase the sizes of the arrays, you will need to recompile. For this purpose I provide source code Laramy2AI.F90, which is Fortran 90. (When you look into it, it will look like Fortran 77, because the code is fixed-format, and all-capitals, with short variable names. However, in a few ways (modules, PAD option in OPEN, ...) it actually requires Fortran 90 to compile. Another thing you need to compile is one routine (LSLPB) from IMSL (International Mathematics Subroutine Library), or a substitute. IMSL is available in the Professional Editions of both the Microsoft Fortran Power Station compiler (buggy, not reccommended) and the newer DIGITAL Visual Fortran (Prof. Ed.). The routine is needed to factor and solve positive-definate symmetric linear systems with real coefficients in banded symmetric storage form. You can probably find a substitute in other linear-system software packages besides IMSL. However, beware: this may mean changing the storage scheme for the compressed banded coefficient matrix! If you don't have access to 32-bit Windows OR to IMSL and you just want to get started, you can insert a dummy substitute for LSLPB. You will still be able to plot the finite element grid and the values of scalar data defined at nodes, such as crustal thickness, heat flow, and elevation. However, you will not be able to plot variables which are defined at integration points of elements (strain-rate, stress, and things derived from these) because in order to plot these they must be made continuous, which means extrapolating values to nodes, which means solving a linear system, which requires LSLPB or a substitute. You should be aware of useful programs in other related subdiretories. Here is an overview. (Note: Numbers 0 - 5 tie to Read_me.n files.) 0. Laramy2AI (this package) 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 package requires IBM's Graphical Data Display Manager. 3. VERSATEC is comparable to Laramy2AI, 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 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 also need 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 #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 maps of output (and you don't have a Versatec or IBM's Graphical Data Display Manager), then you should use Laramy2AI (in a different subdirectory) instead. If you need to run 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 "Laramy2AI" SUBDIRECTORY Old_Laramy2AI.exe = executable for 32-bit Windows (Windows 95 or Windows NT) on Intel or compatible processors. Old_Laramy2AI.F90 = Fortran 90 source code, for running on other systems (or if arrays must be enlarged). LanModel.AI = a "blank-canvas" file in the Adobe Illustrator dialect of the PostScript graphics metafile language, containing headers and footers needed in an .AI file. Laramy2AI will copy these lines into each of your new .AI files, filling in your actual map with additional lines added in the middle. IN9828 = a sample parameter-input and plot-control file for a typical run of LARAMY. Needed to run Laramy2AI as well; this is where you set type of plot, scale, colors, etc. CORD11N = a sample initial-conditions file in LARAMY format, just so that you have something to try plotting. 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. ----------------------------------------------------- Laramy2AI.exe (or) Old_Laramy2AI.exe Before running this program, use any text editor to edit the bottom half of the physical-parameter and plot-control file (like IN9828, provided), in order to specify which plots will be made, whether color will be used, where the map should be centered, etc. (Do not change the physical parameters in the first half of the file if LARAMY has already been run, or the plotted values could be incorrect and misleading. In fact, I suggest keeping one file like IN9828 for EACH AND EVERY model experiment you run with LARAMY. Then, you will never forget what physical parameters and/or switches you used in a particular run.) Laramy2AI runs in text-only mode (a "DOS box") under 32-bit Windows (Win 95 or Win NT). It prompts you for the names of all necessary files, and for the desired name(s) of your output graphics (*.AI) files. By default, these are located in the current directory. If not, give complete paths with the filenames. You will need: -a physical-parameter and plot-control file, like in9828, provided. -a basemap file of state lines and/or coastlines, like BASEMAP, provided. -a model .AI file, like LanModel.AI, provided. -a file of initial conditions or time-integrated values of physical variables (either for or form LARAMY, respectively) in the same format as cord11n, provided. -For plots of timesteps in a long history, Laramy2AI will also need to read a file with the final (present-day) positions of all the nodes in the grid. This information is used to retrodeform the basemap to earlier epochs. The simplest way to get such a file is just to make an extra copy of the last "report" written by LARAMY when it reaches t = 0 at the end of its run. [There is a switch near the end of the plot-control file (e.g., IN9828) which allows the basemap to be switched off. In that case, this last file, and the basemap file, will not be needed.] When Laramy2AI finishes it will exit. Start up Adobe Illustrator, read in your new .AI file(s), view, edit, and print! Laramy2AI 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. (Because the logic in CONTEL is very complex and was previously buggy, I have left in some debugging WRITE statements which are surrounded by comment lines ("C$$$$$$$$$$$$$$$$$$$$"). These WRITE statements are currently inactive (because DUMPIT=.FALSE.) but you can make use of them if you encounter any problems in the future.) ----------------------------------------------------- Laramy2AI.F90 (or) Old_Laramy2AI.F90 Fortran 90 source code for Laramy2AI. Provided in case: (1) You do not have access to 32-bit Windows, or (2) You need to recompile with larger arrays. Array sizes can be increased by simply changing the values of the parameters (N50,N121,NSTATE) at the top of Program Laramy2AI. When you recompile, you will need to supply one routine (LSLPB) from IMSL, or a substitute. (This was discussed above.) Frankly, this is ***UGLY*** code, because of its history: a. Graphics code was written using IBM's Graphical Data Display Manager. b. Code was modified for DISSPLA graphics package. c. Code was modified to produce PostScript output. Because of this, I do NOT ADVISE that you try to understand or modify it! (I have a completely new package under development, FiniteMap, that will use only Fortran 90, and will be ready about 2000.) ----------------------------------------------------- LanModel.AI A "blank-canvas" or "wrapper" file of PostScript statements defining (1) the Adobe Illustrator dialect of macros (from Adobe), and (2) the custom colors and shading patterns which I use. WARNING: In theory, you can open this with Adobe Illustrator, view it (it is not very exciting!), and save it, and it will still work. However, a bug in Adobe Illustrator sometimes causes a few lines to be terminated with only the CR byte (where we should have both CR and LF bytes on PC-type systems). This can cause Laramy2AI to produce .AI files which crash when opened in Adobe Illustrator. Thus, I strongly recommend that you do NOT modify LanModel.AI in any way, and if you open it with Adobe Illustrator, that you NOT save it under the same name! ----------------------------------------------------- IN9828 A sample physical-parameter and plot-control file. There will be one for each model experiment you run with LARAMY. (This particular one was from by model #28 of 1998.) The top half of the file is read by both LARAMY and Laramy2AI, and it defines the physical parameters of the model Earth. The bottom half of the file is read ONLY by Laramy2AI, and it defines which timestep in the history you want to plot, which variables you want to plot, whether the plot should be in color, what the scale of the map should be, where the center of the map window should be (in the Cartesian x/y system of the flat-Earth model plane), etc. See other notes in the LARAMY subdirectory. To turn on a particular plot, change F to T in that line. (You can do more than one plot type per run.) The next number (if present) is the desired contour interval (which does not apply to some plots, like the element grid). The 2nd number (if present) is a variable value that will be plotted with a color (or shading pattern) from the middle of the color spectrum. Notice that Adobe Illustrator custom colors can be changed (for the whole plot) from within Adobe Illustrator, AFTER the .AI file has been created by Laramy2AI. Also, graphics groups of simple black lines can be selected, and their widths can be changed very easily. The line widths in file IN9003 are in units of points. (72 points = 1 inch). ----------------------------------------------------- CORD11N Sample output file from LARAMY, just so you have something to try plotting. Since it is an an initial-condition file from the beginning of a run, it is not very exciting. When LARAMY has been allowed to run through many timesteps, it will produce other files of the same format (but much longer!) which you should substitute. See additional comments in the LARAMY subdirectory Read_me.1 file. ----------------------------------------------------- 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 IN9003) to have state lines included in plots, then this dataset is required when you use PLOT (provided) to run the compiled version of program DRAW (see VERSCOMP 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 = -115). ----------------------------------------------------- GOOD LUCK !!!!!!!!