Fortran 77 package FORMS version 6.20

Vaclav Bucha: Department of Geophysics, Charles University Prague, Ke Karlovu 3, 121 16 Praha 2, Czech Republic; E-mail: bucha@seis.karlov.mff.cuni.cz
Petr Bulant: Department of Geophysics, Charles University Prague, Ke Karlovu 3, 121 16 Praha 2, Czech Republic; E-mail: bulant@seis.karlov.mff.cuni.cz
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

Package FORMS is designed to facilitate the data exchange between individual programs and to simplify writing, reading, comparing and plotting various kinds of data. Package FORMS contains specifications of data forms, subroutines to write and read them, programs to perform simple operations with the data, programs to generate the data of given properties, simple graphics subroutines and programs, etc.

General description of package FORMS

Programming language, error messages, screen output, etc.

Unified memory management.

History files.

Alphabetical list of input parameters of all programs.

Unified error management. The error and warning messages are written to the output error file of fixed name 'error.out'. File 'error.out' is deleted by Perl script 'go.pl' before executing the history file. When an error or warning message is issued, the message is appended to the error file, starting with string '##Error' or '##Warning', respectively. Error file 'error.out' is checked for string '##Error' before running the next program of the history file.

New in version 6.20

General description of data forms

SEP (parameter files):

SEP (Stanford Exploration Project) parameter files are convenient for the specification of input parameters of programs, and especially for the description of grid dimensions for the gridded data (data forms GRD and MGRD).
Subroutines to read and write the SEP data are collected in file sep.for.

GSE (seismograms):

GSE waveform data exchange files are one of many seismological standards used to store and exchange seismograms, and are very simple and readable ASCII files.
Subroutines to read and write the GSE files are collected in file gse.for.

GRD (GRiDded data):

Singlevalued data on regular rectangular grids are written gridpoint-by-gridpoint into formatted files. N1*N2*N3 grid values are stored in the Fortran manner, i.e. with the inner loop corresponding to N1 and outer loop corresponding to N3. The gridded data are sometimes repeated for N4 time snaphots. In such a case, each new snapshot (N1*N2*N3 grid) should begin on a new line.
The files are designed to be read by the list-directed input (free format). The null values are generated in place of undefined values (e.g., travel times in a free space). The null values are treated as default values when read by list-directed input (free format). Example: 124 null values are written as ' 124* '.
The grid dimensions are usually assumed to be specified by parameters N1, N2, N3, sometimes N4 (numbers of gridpoints), D1, D2, D3, sometimes D4 (grid intervals), O1, O2, O3, sometimes O4 (coordinates of the grid origin, i.e., of the first gridpoint).
Subroutines WARRAY and WARAY to write real-valued gridded data, WARRAI and WARAI to write integer gridded data, RARRAY and RARAY to read real-valued gridded data, and RARRAI and RARAI to read integer gridded data, are collected in file forms.for. Subroutines with double R work with a single N1*N2*N3 spatial grid, subroutines with single R work with a space-time grid (N4 spatial grids).

MGRD (Multivalued GRiDded data):

Multivalued data on regular rectangular grids are given by a couple of files:
(a) Integer gridded data file (form GRD) containing for each gridpoint the number of data values.
(b) Formatted file containing all data values at the first, second, ..., last gridpoints.
The subroutines to write and read singlevalued gridded data GRD may be used to write and read these files.

Matrices and vectors:

General matrices (GM), symmetric matrices (SM), skew matrices and diagonal matrices (DM) are distinguished. Vectors are general matrices with a single row or a single column, and are not distinguished from general matrices.
Each matrix is stored in two files:

The matrix header file is a formatted SEP-like file which contains the parameters describing the matrix. The parameters are as follows:
- IN='string' ... Name of the matrix data file.
- M1=integer ... Number of rows of the matrix.
- M2=integer ... Number of columns of the matrix.
- SPARSE='string' ... Identifies whether the matrix is written as sparse matrix or not. SPARSE=' ' means dense, not sparse matrix. SPARSE='CSC' means that the matrix is written as sparse matrix in the Compressed Sparse Column format.
- NELEM=integer ... Number of nonzero elements of the matrix. Used only for sparse matrices (SPARSE differs from ' ').
- SYMMETRY='string' ... Identifies the symmetry of the matrix. Possible values are 'diag' for diagonal matrix, 'sym' for symmetric matrix, 'skew' for skew matrix, and ' ' for general matrix.
- FORM='string' ... Identifies the format of the matrix data file. Possible values are 'formatted' and 'unformatted'.
The matrix data file is a formatted or unformatted file with the values of matrix elements.
For a symmetric matrix, just components from the first row to the diagonal are stored for each column, i.e., M1*(M1+1)/2 matrix components are stored for symmetric M1*M1 matrix.
For a skew matrix, just components above the diagonal are stored, M1*(M1-1)/2 matrix components are stored for skew M1*M1 matrix.
For a diagonal M1*M1 matrix, just M1 diagonal components are stored.
The matrix data files differ for sparse and for dense (not sparse) matrices:
- For dense, not sparse matrices, (SPARSE=' ') the values of all matrix elements are stored component by component. Components of the matrices are stored columnwise.
- For sparse matrices, Compressed Sparse Column (CSC) format is used. In this format, the nonzero elements of the matrix are stored columnwise, together with the integer values of their row indices, and with the "pointers" dividing the stored matrix elements into individual columns.
  - The M2 integer pointers, corresponding to the matrix columns, are stored first. The value of each pointer equals the number of stored nonzero matrix elements from the beginning of the matrix to the end of the corresponding column.
  - Then NELEM pairs of integers equal to the row indices of nonzero matrix elements and reals equal to the values of the nonzero matrix elements are stored. For formatted files, the pairs start on a new line of the file after the pointers, and each line contains NUMLINM pairs.
  Example of the pointers: Assume a matrix with 2 nonzero elements in the first column, and 3 nonzero elements in the second column. Than the first pointer is 2, the second pointer is 5, and so on. The last pointer is NELEM.
The matrices may be stored either in the formatted files, or in the unformatted files, depending on the value of input SEP parameter FORMM of the programs dealing with the matrices. Reading and writing of the unformatted files is usually much faster.
The formatted files are designed to be read by a single list-directed input (free format). The number of components per line is given by input SEP parameter NUMLINM, default for matrix data files is NUMLINM=5. The different matrix components may correspond to different quantities. The matrix components are thus written using the 'E' Fortran format in order to preserve the relative accuracy of all matrix components.

LIN (LINes):

Subroutine FORM2 of file forms.for may be useful when writing these data.

PTS (PoinTS):

Subroutine FORM2 of file forms.for may be useful when writing these data.

FTT (Travel Times):

Subroutine FORM2 of file forms.for may be useful when writing these data.

Compiling and linking programs of package FORMS

All Fortran 77 source code and include files are assumed to be located in a single directory 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.

Compilation and linking:

Copy all files (or at least all *.for and *.inc files) of package FORMS into your working directory. All the files may also be extracted using pkunzip -d forms.zip or tar -xvf forms.tar.
If you wish to compile following programs you need also few subroutines (mentioned in parentheses) of the Numerical Recipes and the corresponding licence.
grdfft.for (fourn.for),
grdran2d.for (fourn.for, ran2.for, ran3.for),
grdran.for (ran3.for),
grdckn.for (gammln.for, bessik.for, beschb.for, chebev.for),
smpower.for (indexi.for, indexx.for, tred2.for, tqli.for, pythag.for),
smeigen.for (indexi.for, indexx.for, tred2.for, tqli.for, pythag.for).
Necessary subroutine files are included at the end of above listed files containing main programs.
On a computer with a very small memory (less than 16 MB), you may need to decrease array dimension MRAM in the include file ram.inc. You may also wish to increase array dimension MRAM in the include file ram.inc if 16 MB are not sufficient for your calculations.
Edit Perl script f.pl designed to compile and link a single file according to your Fortran compiler and linker.
Test Perl script f.pl by entering command
perl f.pl do-test
to compile program do-test.for, which may be executed on most systems by entering command
do-test
If you have no Perl interpreter, it should be available at www.perl.org. You may ask your system manager to install the Perl interpreter.
Run Perl script fforms.pl by entering command
perl fforms.pl
to compile and link the programs of package FORMS. For the list of files to compile and link, refer to Perl script fforms.pl, which employs Perl script f.pl to compile each program. All necessary subroutine files and include files are included by the Fortran 90 INCLUDE command. Fortran 77 subroutine files are included at the end of above listed files containing main programs.

Running programs of package FORMS

All Fortran 77 source code and include files together with all the Perl scripts and data files of package FORMS are assumed to be located in the same single working directory in which the programs will be run.

It is recommended to run the programs from the history files. The history files may contain the information how to execute the programs, the data read from standard input (Fortran) or from the command line (Perl) and the data read from the SEP parameter files.

Data from standard input *:
Main input data of each program are read from the standard input, and mostly consist of a single line containing filenames and at most few numerical parameters. For the description of input data of individual programs refer to the list of files below.

Path to the root directory of the SW3D software:
There is a possibility to edit file go.pl and set path to the root directory of the SW3D software in global variable $SW3D to enable full functionality of the Perl script chk.pl. Some history files will then be able to copy their input data from the SW3D-CD disk to the working directory automatically.

List of error messages

File list of package FORMS

(A) Documentation:

forms.htm: This file (main HTML file containing basic description of this package).
formsver.htm: List of released versions.
formserr.htm: List of error messages with links to their descriptions.
formsdat.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.
sep.htm: Description of history files.
fortran.htm: Notes on programming language, coding, error messages, screen output, etc.

(B) Unified memory management and error handling:

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.
error.for: Subroutines to handle error and warning messages.

(C) Subroutines and programs dealing with data forms:

sep.for: Subroutines to read data in the form of the SEP history 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: Subroutines to convert a string into lowercase and to determine the length of a string without trailing blanks.
gse2segy.for: Program GSE2SEGY to convert seismograms stored in the GSE data exchange format to SEGY format.; Description of input data.

(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.
gksps.for: GKS to PostScript interface containing just several GKS plotting subroutines required by program 'pictures.for'.

(E) Colour interpolation subroutines, WRL subroutines, and other subroutines:

colors.for: Subroutines to linearly interpolate discrete colour maps in the RGB space.
hsv.dat: Data for 'colors.for' specifying the HSV (HSB) colour scale for interpolation in the RGB colour space.
wrl.for: Subroutines to facilitate writing VRML, GOCAD and POV files.
hg.for: Subroutines to calculate some hypergeometric functions.

(F) General and graphical application programs:

iniwrl.for: Program INIWRL to initialize a VRML or GOCAD file.; Description of input data.
ptswrl.for: Program PTSWRL to convert points into VRML or GOCAD representation.; Description of input data.
linwrl.for: Program LINWRL to convert lines into VRML or GOCAD representation.; Description of input data.
srfwrl.for: Program SRFWRL to convert triangulated surfaces into VRML or GOCAD representation.; Description of input data.
grdwrl.for: Program GRDWRL to convert gridded data into the GOCAD representation.; Description of input data.
plgn.for: Program PLGN to convert polygons described by names of the vertices into the same polygons described by indices of the vertices.; Description of input data.
trgl.for: Program TRGL to divide polygons on a curved surface into triangles, right-handed with respect to the surface normals.; Description of input data.
trglsort.for: Program TRGLSORT to sort triangles according to the values at their vertices.; Description of input data.
trglnorm.for: Program TRGLNORM to compute normals to given triangles.; Description of input data.
trglps.for: Program TRGLPS to display triangulated 2-D velocity and other sections in PostScript.; Description of input data.
tsurf.for: Program TSURF to convert GOCAD triangulated surfaces into a file with points and a file with triangles.; Description of input data.
pictures.for: Program PICTURES to draw lines and points.; Description of input data.
pallet.for: Program PALLET to interpolate the RGB colour pallet linearly in the HSB colour space.; Description of input data.
ss.for: Program SS (Synthetic Seismograms) to read or generate and filter the source time function. It may store the filtered source time function and its Hilbert transform in the GSE data exchange format, or read the frequency-domain response function and generate synthetic seismograms in the GSE data exchange format.; Description of input data.
sp.for: Program SP (Seismogram Plotting) to plot seismograms previously stored in the GSE data exchange format.; Description of input data.
srp.for: Program SRP to translate the system of points (e.g., sources or receivers) to a new position determined by the given configuration parameters. Program generates 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.; Description of input data.
linden.for: Program LINDEN to make LINes more DENsely sampled. May be used, e.g., to calculate functional values in more densely sampled points along a given line.; Description of input data.
sgfhom.for: Program SGFHOM to generate the structural Gabor functions which shape is optimized for a zero-offset surface seismic reflection survey in a homogeneous 2-D velocity model.; Description of input data.
sgfmat.for: Program SGFMAT to generate the system of linear equations for the complex-valued coefficients of the structural Gabor functions in decomposing a given gridded real-valued quantity.; Description of input data.
sgfgrd.for: Program SGFGRD to calculate the grid values of a real-valued quantity decomposed into the structural Gabor functions.; Description of input data.

(G) Programs for calculations with gridded data (data cubes):

mgrd.for: Program MGRD to convert a multivalued grid into several singlevalued grids.; Description of input data.
grdpts.for: Program GRDPTS to generate the file of form PTS, containing the coordinates of all gridpoints of the given grid.; Description of input data.
grdtrans.for: Program GRDTRANS to transpose the coordinate axes of the gridded data.; Description of input data.
grdnew.for: Program GRDNEW to trilinearly interpolate grid values into a new grid of different dimensions or density.; Description of input data.
grdmerge.for: Program GRDMERGE to merge two nonoverlapping sets of values given on the same grid into a single set, especially in order to display the data together.; Description of input data.
grdcal.for: Program GRDCAL to perform vectorial calculations with real-valued arrays (data cubes) stored in disk files (i.e., with singlevalued gridded data).; Description of input data.
copy.cal
abs.cal
neg.cal
inv.cal
sqrt.cal
eq.cal
add.cal
sub.cal
mul.cal
div.cal
invsub.cal
absdif.cal
reldif.cal
reldev.cal
relerr.cal
atan2.cal
norm2.cal
addsob.cal
subsob.cal: Sample command files '*.cal' for program 'grdcal.for' describing simple operations with gridded data.
loc0.cal
loc1.cal
loc2.cal: Command files for program 'grdcal.for' to perform nonlinear kinematic location of seismic hypocentre.
grdnorm.for: Program GRDNORM to calculate the spatial density of the Lebesgue norm L_n of gridded values.; Description of input data.
grdfft.for: Program GRDFFT to compute the 1-D, 2-D or 3-D Fourier transform of a real or complex function defined on 1-D, 2-D or 3-D grid of points.; Description of input data.
grdfd.for: Program GRDFD to calculate gradient of the grid values by means of the second-order finite differences.; Description of input data.
grd2d3d.for: Program GRD2D3D to extend 2-D grid into 3-D grid; Description of input data.
grdiso.for: Program GRDISO for identification of points at isosurfaces of 3-D gridded values.; Description of input data.
grdiso.inc: Include file with COMMON block for 'grdiso.for'.
grdgse.for: Program GRDGSE to convert gridded data into the GSE format.; Description of input data.
grdran2d.for: Program GRDRAN2D to generate a 2-D rectangular grid of random real numbers having a desired spatial correlation function, specified variance and mean.; Description of input data.
grdran.for: Program GRDRAN to compute the pseudorandom numbers on a given grid, distributed uniformly between -0.5 and 0.5.; Description of input data.
grdcor.for: Program GRDCOR to compute the values of the spectral filters corresponding the typical correlation functions of random media on a given grid.; Description of input data.
grdstat.for: Program GRDSTAT to rescale gridded data to given statistical properties.; Description of input data.
grdckn.for: Program GRDCKN to compute the values of the Von Karman correlation functions.; Description of input data.
grdcros.for: Program GRDCROS to calculate autocorrelations and crosscorrelations of given grid values.; Description of input data.
grdte.for: Program GRDTE to compute the values of a real or complex function, described in terms of the Taylor expansions of its amplitude and phase, on a given grid.; Description of input data.
binasc.for: Program BINASC to convert gridded data (data cubes) from binary files to formatted ascii files.; Description of input data.
ascbin.for: Program ASCBIN to convert gridded data (data cubes) from formatted ascii files to direct-access binary files.; Description of input data.
swap.for: Program SWAP to convert binary gridded data between little-endian (PC's) and big-endian (VAX, Alpha, RISC workstations) hardware.; Description of input data.
ptsgrd.for: Program PTSGRD to generate grid file containing undefined values at gridpoints closest to the given points, and zeros elsewhere. Used to display the points with the gridded values by program 'grdps.for'.; Description of input data.
grdmigr.for: Program GRDMIGR to perform common-source Kirchhoff migration using gridded travel times and amplitudes.; Description of input data.
grdps.for: Program GRDPS to Display GRiD values in PostScript.; Description of input data.

(H) Programs for matrix calculations:

Programs to perform operations with general matrices (gm), symmetric matrices (sm) and diagonal matrices (dm).

mat.for: Subroutines for reading and writing matrices and for other operations with matrices.
matmul.for: Program MATMUL for multiplication of two matrices.; Description of input data.
matlin.for: Program MATLIN to compute linear combination of two matrices.; Description of input data.
matfun.for: Program MATFUN to compute a function of a matrix.; Description of input data.
matinv.for: Program MATINV to compute symmetric matrix SM2=SM1^-1 inverse to symmetric matrix SM1.; Description of input data.
sinv.for
mfsd.for: Subroutines of the IBM Scientific Subroutine Package employed by program 'matinv.for'.
gels.for: Subroutine of the IBM Scientific Subroutine Package to solve a system of simultaneous linear equations with symmetric coefficient matrix. Not used in this version of package FORMS.
smpower.for: Program SMPOWER to compute matrix SM2=SM1^POWER, which is POWER-th power of given symmetric matrix SM1.; Description of input data.
smeigen.for: Program SMEIGEN to read a symmetric matrix SM1 and to compute general matrix GM1 of its eigenvectors and diagonal matrix DM1 of its eigenvalues.; Description of input data.
eigen.for: Subroutine EIGEN of the IBM Scientific Subroutine Package.
eigennr.for: Subroutine to compute eigenvalues and eigenvectors of a real symmetric matrix, using subroutines of Numerical Recipes. Form of the subroutine is identical to subroutine EIGEN of the IBM Scientific Subroutine Package.
trsmsm.for: Program TRSMSM to calculate the trace of the product of two symmetric matrices.; Description of input data.

(I) Programs for calculation of R/T coefficients:

rtcoef.for: Program RTCOEF to control the computation of R/T coefficients using the subroutine COEF52.; Description of input data.
coef52.for: Subroutine COEF52 for the computation of the displacement reflection/transmission coefficients (R/T coefficients) of inhomogeneous P, SV and SH plane waves at a stack of homogeneous isotropic dissipative layers between two homogeneous isotropic dissipative halfspaces.

(J) Auxiliary programs:

cremove.for: Program CREMOVE to split a Fortran code into executable lines and comment lines.; Description of input data.
do-test.for: Program DO-TEST to test compilation of DO loops.; Program 'do-test.for' has no input data.

(K) Perl scripts:

sep.pl: Perl counterpart of 'sep.for'.
forms.pl: Perl counterpart of 'forms.for'.
go.pl: Perl script 'go.pl' to run programs according to a history file and to assist other Perl scripts in running programs and handling the data.
echo.pl: Perl script doing what Unix or MS-DOS 'echo' command does.
append.pl: Perl script to append the content of a file to another file.
copy.pl: Perl script to copy files.
chk.pl: Perl script to check input data files required by history files or various scripts.
compdel.pl: Perl script to compare the files in two directories and delete the files which are the same.
del.pl: Perl script to delete files.
f.pl: Perl script to compile and link a single Fortran 77 source code file with extension '.for'.
fforms.pl: Perl script to compile the FORMS package by means of predefined script 'f.pl' compiling and linking a single Fortran 77 source code file.

(L) Demo data:

grd.h: Example of the SEP parameter file describing the grid dimensions.

Acknowledgements

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, 38/94, 237/2001, 229/2002 and 375/2004.
Grant Agency of the Czech Republic under Contracts 205/95/1465, 205/01/0927, 205/01/D097, 205/04/1104 and 205/07/0032.
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".