Package FORMS (general description)

Version 5.10 Date: 1997, October 27 Authors: Ludek Klimes Department of Geophysics, Charles University Prague Ke Karlovu 3 121 16 Praha 2, Czech Republic E-mail: klimes@seis.karlov.mff.cuni.cz Ivan Psencik Geophysical Institute, Acad. Sci. Czech Rep. Bocni II, 1401 141 31 Praha 4, Czech Republic E-mail: ip@ig.cas.cz Paul Spudich U.S. Geological Survey 345 Middlefield Road Menlo Park, CA 94025, U.S.A. E-mail: spudich@samoa.wr.usgs.gov ...................................................................... Subroutine package FORMS consists of the following FORTRAN77 source code and demo files: (A) Documentation: 'forms.htm'... Main HTML file containing basic description and links the files of this package. 'formsdoc.htm'... General description of files containing Lines (lines at interfaces, velocity isolines, rays, etc.) or Points (gridded interfaces, sources, receivers, ray endpoints, etc.). The files are introduced especially to simplify data transfer and plotting. 'formserr.htm'... HTML file containing links to error descriptions. (B) Unified memory management: 'ram.inc'... Include file with COMMON block /RAMC/ designed to be included in all programs demanding huge amounts of memory, e.g., in programs dealing with dense rectangular grids of points. Assuming no other considerable memory requirements of the respective programs, this include file enables to approximately adjust the memory requirements of all programs for a particular computer at one go. (C) Subroutines dealing with data forms: 'sep.for'... Subroutines to read data in the form of the SEP header or parameter files. 'sep.inc'... Include file with COMMON block for 'sep.for'. 'gse.for'... Subroutines to write and read seismograms in the GSE data exchange format. 'forms.for'... Subroutines to write real arrays into disk files and to read them, or to determine the best output format for reals. 'length.for'... Subroutine to determine the length of a string without trailing blanks. (D) Calcomp plotting subroutines: 'calcomp.for'... Interface subroutines from the 'CalComp' to 'GKS' (Graphic Kernel System) Level 0b subroutines. It contains subroutines PLOTS, PLOT, NEWPEN, SYMBOL, and NUMBER. 'calcomp.inc'... Include file with COMMON block for 'calcomp.for'. 'calcops.for'... CalComp to PostScript interface containing the CalComp plotting routines PLOTS, PLOT, NEWPEN, SYMBOL and NUMBER. 'calcops.inc'... Include file with COMMON block for 'calcops.for'. 'calcops.rgb'... Colour table to be used with 'calcops.for' by Petr Bulant. (F) Sample application programs: 'pallet.for'... Program to interpolate the RGB colour pallet linearly in the HSB colour space. 'srp.for'... Program to generate files containing source and receiver points corresponding to given configuration parameter(s). The dependence of the source and receiver coordinates on the configuration parameters is assumed to be linear. 'grdpts.for'... Program to generate the file containing the coordinates of all gridpoints of the given grid. 'mgrd.for'... Program to convert multivalued grid into several singlevalued grids. 'grdnew.for'... Program to trilinearly interpolate grid values into a new grid of different dimensions or density. 'grdcal.for'... Program to perform vectorial calculations with real-valued arrays stored in disk files. 'copy.cal','abs.cal','add.cal','sub.cal','mul.cal','div.cal' 'absdif.cal','reldif.cal','relerr.cal','atan2.cal','norm2.cal'... Sample command files for 'grdcal.for' describing simple operations with gridded data. 'grdran2d.for'... Program to generate a 2-D rectangular grid of random real numbers having a desired spatial correlation function, specified variance and mean. 'grdmerge.for'... Program to merge two nonoverlapping sets of values given on the same grid into a single set. 'grdps.for'... Program to Display GRiD values in PostScript. (G) Auxiliary programs: 'cremove.for'... Program to split a Fortran code into executable lines and comment lines. (H) Demo data: 'grd.h'... Example of the SEP parameter file describing the grid dimensions. 'grdran2d.dat'... Example of input data for 'grdran2d.for' supplemented with some comments. 'grdps.dat'... Example of input data for 'grdps.for' supplemented with some comments. (I) Batch files and scripts: 'corfun.bat'... Sample MS-DOS batch file to generate PostScript figures of random functions with different correlation functions. 'run.bat'... MS-DOS batch file to run a program with a line of given input data, redirected to the standard input. 'f.bat'... Sample MS-DOS batch file to compile and link a single Fortran 77 source code file using the Lahey F77L3 compiler. 'f'... HP-Unix script to compile and link a single Fortran 77 source code file with extension '.for'. 'fforms.bat'... 'fforms'... 'fforms.bat'... MS-DOS batch file for Lahey Fortran 77 compiler driven by means of predefined batch file 'f.bat'. 'fforms'..Unix script to compile the FORMS package by means of predefined script 'f' compiling and linking a single Fortran 77 source code file. ...................................................................... Compilation and linking: All Fortran 77 source code and include files of the FORMS package are assumed to be located in a single directory together with all source code and include files of the MODEL package when being compiled and linked. The files with main programs contain, at their ends, Fortran 90 INCLUDE command for all subroutine files required. In this way, each program may simply be compiled and linked as a single file. All filenames are assumed to be expressed in lowercase. Fortran 77 source code files have extension '.for'. The corresponding files with specifications of the COMMON blocks have extension '.inc' and are included in the Fortran 77 source code by means of Fortran 90 INCLUDE command. ...................................................................... Released versions: 5.10 (1997, September): 'formsdoc.htm','gse.for','forms.for','length.for', 'srp.for', 'calcomp.for','calcomp.inc','calcops.for', 'calcops.inc', 'pallet.for': Moved from package MODEL. 'calcomp.for','calcops.for': BLOCK DATA subprograms canceled. All error descriptions moved towards the corresponding reporting statements. 'gse.for': *** Considerably revised version. *** *** new *** All Fortran files supplemented with HTML references. 'grdpts.for' 'mgrd.for' 'grdnew.for' 'grdcal.for' 'grdran2d.for' 'grdmerge.for' 'grdps.for' 'cremove.for' ====================================================================== General forms of data files with Lines and Points, related to 3-D seismic modelling. By Ludek Klimes, Ivan Psencik The data files are designed to simplify the data exchange between various programs, especially for the purposes of plotting. The data files are assumed to be formatted, sequential files, readable by list-directed input (free format). Thus the items like numbers or strings should be separated by the separators like spaces or commas, and all strings should be enclosed in apostrophes. Null values may be used in place of default values where the default values are defined. In the descriptions of input data below, each low-level numbered paragraph indicates the beginning of a new input operation (new read statement). 'ITEMS' in the list of input variables enclosed in apostrophes represent CHARACTER strings enclosed in apostrophes. Otherwise, if the first letter of the symbolic name in the list of input variables is I-N, the corresponding value in input data is INTEGER, otherwise, the input parameter is of the type REAL. / in the list of input variables indicates an obligatory slash. The slash may also be used instead of default values. The slash at the end the last line of each input is obligatory because is intended for the compatibility with various extensions of the file forms. ...................................................................... File form LINES (or briefly LIN): The file structure is designed to store the lines situated in 3-D (and also 2-D) space. These lines may represent the intersections of interfaces with given 2-D sections, velocity isolines, rays, rivers, contours of lands, lakes, or cities, coordinate lines and grids, diagrams of functions of one variable (e.g. travel-time curves), isolines of functions of two variables, axes, scales and other parts of figures, etc. Each line starts with a string that may contain the name or description of the line. The string may be supplemented with the coordinates of the reference point which may, e.g., control the eventual plotting of some part of the string. Then the points of the line follow. Since the lines of zero length are allowed, this data structure may also be used to store the discrete points, but each point should be followed by the row containing slash. That is why also the special file form 'Points' has also been proposed, see the next file form below. File structure: The file consists of its header (1), lines (2), and the end-of-data identification (3). (1) Texts - one to several lines read by a single read statement: None to several strings terminated by / (a slash). It is not recommended to write too many strings (e.g. more than 20) into this file section. On the other hand, the program reading the file should read at least 20 strings, by the single read statement. A blank string followed by a non-blank one is allowed but not recommended. The strings may be used as the notes about the data or file origin, nature, version, etc., and need not be taken into account by the reading program. On the other hand, if the reading program is able to identify within the strings some kind of information written according rules specific to the program, the strings may be used to transfer various kinds of information between the specific pairs of applications. Default for all strings: ' ' (a blank string). First example: 'String1' . . . 'StringM' / Second example: / Third example: 'String1' 'String2' 'String4' 'String5' / Fourth example: 'String1' 'String2' / (2) For each line the triplet of subsections (2.1), (2.2) and (2.3): General example (one line): (2.1) 'Text' X1 X2 X3 / (2.2) X1(1) X2(1) X3(1) / X1(2) X2(2) X3(2) / . . X1(N) X2(N) X3(N) / (2.3) / (2.1) Reference text and optional reference point (single READ statement) - one of the following possibilities (a) and (b): (a) 'TEXT',X1,X2,X3,/ (b) 'TEXT',/ 'TEXT'... Arbitrary text related to the line. The string may contain the name or description of the line. It may be used as the notes about the line, but often contains some information transferred between the specific pairs of programs, encodded according to the rules specific to the programs. Especially, the string is assumed to be used at selecting only some lines for plotting according to the given selection keywords or textual masks, or to enable plotting the lines with different attributes (colour, line width, line type, etc.) according to fitting the text by the given selection masks. A selected part of the string (according to another keyword or mask) may also be drawn as the text describing the line. Also the numerical information concerning the line (e.g. the isovalue of the isoline) may be contained within the string and identified by a keyword. The string may be blank but the default must not be used, because the default identifies the end of data. The default value in the reading program should be selected in such a way that it should not match any string describing a line. For instance, the string composed of several '$' characters may be a reasonable default (e.g. '$$$$'). Thus it is not recommended to use the '$' character within the strings identifying lines. Examples of strings generated by some programs: (since:) 'SECT 12, SURF 2' (sec, v.4.10) 'SECT 12, BLOC 3, ISOL 8, VP = 5.000' (sec, v.4.10) 'SECT 12, BLOC 3, ISOL 4, VS = 3.000' (sec, v.4.10) 'REC 13' (crtray, v.4.17) 'RecNam' (crtray, v.4.17) 'SrcNam TO RecNam' (crtray, v.4.17) 'RAY 112' (crtray, v.4.17) 'RAY 112, REC 13' (crtray, v.4.17) 'RAY 112 TO RecNam' (crtray, v.4.17) 'RAY 112 FROM SrcNam' (crtray, v.4.17) 'RAY 112 FROM SrcNam TO RecNam' (crtray, v.4.17) 'WAVE 1, RAY 112' (crtray, v.4.10) 'WAVE 1, RAY 112, REC 13' (crtray, v.4.17) 'WAVE 1, RAY 112 TO RecNam' (crtray, v.4.17) 'WAVE 1, RAY 112 FROM SrcNam' (crtray, v.4.17) 'WAVE 1, RAY 112 FROM SrcNam TO RecNam'(crtray, v.4.17) 'RAY 112' (net, v.2.00) 'RAY 112 TO RecNam' (net, v.2.00) 'RAY 112 FROM SrcNam' (net, v.2.00) 'RAY 112 FROM SrcNam TO RecNam' (net, v.2.00) Here 'SrcNam' is the name of the source point at which the ray starts and 'RecNam' is the name of the receiver at which the ray terminates (names up to 6 characters long are preferable). X1,X2,X3... Coordinates of the reference point where the text can be drawn. In 2-D, the third coordinate X3 need not be specified, and its default value should always be 0. The reference point need not be specified. A missing reference point may be identified by the reading program according to the default of X1 unlike to appear within the the input data, e.g. -999999. Missing coordinates of the reference point may also be used to switch between drawing and dropping the texts describing the lines. A program may draw all texts, draw only texts with the reference point given, or draw no texts. (2.2) Points of the line - for each point of the line (2.2.1): Any number of points may be specified, including none. (2.2.1) Coordinates of the I-th point of the line: X1(I),X2(I),X3(I),/ X1(I),X2(I),X3(I)... Coordinates of the I-th point of the line. In 2-D, the third coordinate X3(I) need not be specified, and its default value should always be 0. The end of the line is identified by the reading program according to the default of X1(I) unlike to appear within the input data, e.g. -999999. Thus, such a value should be avoided in the data. Possible extensions: In place of the terminating slash, several additional numbers terminated by a slash may be written. The meaning of this numbers is specific to the applications. Example: Possible extensions (a) or (b) for rays: (a) X1(I),X2(I),X3(I),TT(I)/ (b) X1(I),X2(I),X3(I),TT(I),P1(I),P2(I),P3(I),/ TT(I)... Travel time at the point. P1(I),P2(I),P3(I)... Slowness vector components at the point. (2.3) / (a slash). (3) / (a slash) or end of file. Example file diagram: (1) 'TEXT1' 'TEXT2' 'TEXT3' / (2) 'LINE 1' 0.000 0.000 0.000 / 0.000 0.000 0.000 / 1.000 1.000 1.000 / 2.000 2.000 2.000 / / 'LINE 1' / 2.000 2.000 2.000 / 3.000 3.000 3.000 / / 'LINE 2' 0.000 1.500 0.000 / 0.000 1.500 0.000 / 3.000 1.500 0.000 / / (3) / or: (1) 'TEXT1' 'TEXT2' 'TEXT3' / (2) 'LINE 1' 0.000 0.000 0.000 / 0.000 0.000 0.000 / 1.000 1.000 1.000 / 2.000 2.000 2.000 / / 'LINE 1' / 2.000 2.000 2.000 / 3.000 3.000 3.000 / / 'LINE 2' 0.000 1.500 0.000 / 0.000 1.500 0.000 / 3.000 1.500 0.000 / / (3) / ...................................................................... File form POINTS (or briefly PTS): The file structure is designed to store the points situated in 3-D (and also 2-D) space. These points may represent seismic sources, receivers, endpoints of calculated rays, gridded earth surface or structural interfaces, map points like mountains, the dependence of measured data on one or two variables, take-off parameters of rays, descriptions of figures and objects displayed, descriptions of coordinate axes, etc. Each point has its name (generally the string that may contain the name or description of the point), and three coordinates. The file form is derived from file form 'Lines', described above, identifying points with lines of zero lengths (having no points except the reference one) and dropping the rows with the line-terminal slashes. File structure: The file consists of its header (1), points (2), and the end-of-data identification (3). (1) Texts - one to several lines read by a single read statement: None to several strings terminated by / (a slash). It is not recommended to write too many strings (e.g. more than 20) into this file section. On the other hand, the program reading the file should read at least 20 strings, by the single read statement. A blank string followed by a non-blank one is allowed but not recommended. The strings may be used as the notes about the data or file origin, nature, version, etc., and need not be taken into account by the reading program. On the other hand, if the reading program is able to identify within the strings some kind of information written according rules specific to the program, the strings may be used to transfer various kinds of information between the specific pairs of applications. Default for all strings: ' ' (a blank string). First example: 'String1' . . . 'StringM' / Second example: / Third example: 'String1' 'String2' 'String4' 'String5' / Fourth example: 'String1' 'String2' / (2) For each point (2.1): (2.1) 'TEXT',X1,X2,X3,/ 'TEXT'... Arbitrary text related to the point. The string is usually considered to be the name of the point. It may be used as the notes about the point, but often contains some information transferred between the specific pairs of programs, encodded according to rules specific to the programs. Especially, the string is assumed to be used at selecting only some points for plotting according to the given selection keywords or textual masks, or to enable plotting the points with different attributes (colour, marker type, etc.) according to fitting the text by the given selection masks. A selected part of the string (according to another keyword or mask) may also be drawn as the text describing the point. The string may be blank but the default must not be used, because the default identifies the end of data. The default value in the reading program should be selected in such a way that it should not match any string describing a point. For instance, the string composed of several '$' characters may be a reasonable default (e.g. '$$$$'). Thus it is not recommended to use the '$' character within the strings identifying the points. Examples of strings generated by some programs: (since:) 'RecNam' (net, v.2.00) 'REC 13' (crtpts, v.4.17) 'RecNam' (crtpts, v.4.17) 'RAY 112' (crtpts, v.4.17) 'RAY 112, REC 13' (crtpts, v.4.17) 'RAY 112 TO RecNam' (crtpts, v.4.17) 'RAY 112 FROM SrcNam' (crtpts, v.4.17) 'RAY 112 FROM SrcNam TO RecNam' (crtpts, v.4.17) 'WAVE 1, RAY 112' (crtpts, v.4.17) 'WAVE 1, RAY 112, REC 13' (crtpts, v.4.17) 'WAVE 1, RAY 112 TO RecNam' (crtpts, v.4.17) 'WAVE 1, RAY 112 FROM SrcNam' (crtpts, v.4.17) 'WAVE 1, RAY 112 FROM SrcNam TO RecNam'(crtpts, v.4.17) Here 'SrcNam' is the name of the source point at which the ray starts and 'RecNam' is the name of the receiver at which the ray terminates (names up to 6 characters long are preferable). X1,X2,X3... Coordinates of the point. In 2-D, the third coordinate X3 need not be specified, and its default value should always be 0. Possible extensions: in place of the point-terminating slash, several additional numbers terminated by a slash may be written. The meaning of these numbers is specific to the applications. Example: possible extensions (a) or (b) for source or receiver points: (a) 'TEXT',X1,X2,X3,TT,/ (b) 'TEXT',X1,X2,X3,TT,TTERR,/ TT... Travel time at the point. TTERR...Travel time error at the point. (3) / (a slash) or end of file. Example file diagram: (1) 'VERTICES OF A UNIT CUBE' / (2) 'POINT0' 0.000 0.000 0.000 / 'POINT1' 1.000 0.000 0.000 / 'POINT2' 0.000 1.000 0.000 / 'POINT3' 0.000 0.000 1.000 / 'POINT12' 1.000 1.000 0.000 / 'POINT13' 1.000 0.000 1.000 / 'POINT23' 0.000 1.000 1.000 / 'POINT123' 1.000 1.000 1.000 / (3) / ...................................................................... File form 'Travel Times': The file structure is designed to store field travel times (FTT) or synthetic travel times (STT). Each travel time is denoted by the couple of strings identifying the source and the receiver points. File structure: The file consists of its header (1), travel times (2), and the end-of-data identification (3). (1) Texts - one to several lines read by a single READ statement: None to several strings terminated by / (a slash). It is not recommended to write too many strings (e.g. more than 20) into this file section. On the other hand, the program reading the file should read at least 20 strings, by the single read statement. A blank string followed by a non-blank one is allowed but not recommended. The strings may be used as the notes about the data or file origin, nature, version, etc., and need not be taken into account by the reading program. On the other hand, if the reading program is able to identify within the strings some kind of information written according rules specific to the program, the strings may be used to transfer various kinds of information between the specific pairs of applications. Default for all strings: ' ' (a blank string). First example: 'String1' . . . 'StringM' / Second example: / Third example: 'String1' 'String2' 'String4' 'String5' / Fourth example: 'String1' 'String2' / (2) For each travel time (2.1): (2.1) 'SRC','REC',TT,TTERR,/ 'SRC'...String identifying the source point by its name. The coordinates of the point should be listed in a file of the 'Points' format. 'REC'...String identifying the receiver point by its name. Since travel times are reciprocal, the source and receiver names may eventually be interchanged. TT... Travel time. TTERR...Error (e.g. standard deviation) of the travel time. It may be left out if it is considered negligible (e.g. for very accurate synthetic travel times compared with field travel times). (3) / (a slash) or end of file. Example file diagram: (1) 'FIELD TRAVEL TIMES' / (2) 'SRC-01' 'REC-01' 2.132 0.008 / 'SRC-01' 'REC-02' 2.483 0.004 / 'SRC-02' 'REC-01' 4.246 0.016 / 'SRC-02' 'REC-03' 3.879 0.008 / 'SRC-02' 'REC-04' 4.412 0.024 / 'SRC-03' 'REC-02' 5.060 0.016 / 'SRC-03' 'REC-03' 5.132 0.160 / (3) / ...................................................................... Multi-data file form: The file consists of any number of data sections, identified by an identifier: General data section structure: (1) '$ identifier' - string describing the data structure, beginning with the '$' sign. (2) Data section - data formatted in a form indicated by the section identifier. Specific data section structures: The following couples of string (1) and data (2) may form a section: (1) '$ FILE FORM LINES' (2) Data formatted exactly according to file form 'Lines'. (1) '$ FILE FORM POINTS' (2) Data formatted exactly according to file form 'Points'. (1) '$ DATA FORM TEXTS' (2) Data formatted exactly according to section (1) of file form 'Lines' or 'Points'. (1) '$ DATA FORM LINES' (2) Data formatted exactly according to sections (2) and (3) of file form 'Lines'. (1) '$ DATA FORM POINTS' (2) Data formatted exactly according to sections (2) and (3) of file form 'Points'. End-of-all-data identifier: The data are terminated by the following string (3) or by the end of file: (3) '$ END' ...................................................................... Acknowledgements: Vaclav Bucha discovered hundreds of mistypes and bugs in this package and performed some test computations. The development of this package has been partially supported by: Faculty of Mathematics and Physics, Charles University, Prague. Grant agency of the Academy of Sciences of the Czech Republic under Contracts 31223 and 346110. Grant Agency of the Charles University under Contracts 8/94 and 38/94. Grant Agency of the Czech Republic under Contract 205/95/1465. European Commission within the framework of the JOULE II Project 'Integrated Structural Imaging of Seismic Data'. Members of consortium 'Seismic Waves in Complex 3-D Structures'. ======================================================================