Fortran 77 package FORMS version 5.40

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 the writing, reading, comparing and plotting the 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 5.40

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) 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 a single file, component by component. Components of the matrices are stored columnwise.
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 diagonal M1*M1 matrix, just M1 diagonal components are stored.
The files are designed to be read by a single list-directed input (free format). The number of components per line is arbitrary (usually 10). The different matrix components may correspond to different quantities. The matrix components are thus written using the 'G' 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 of packages NR and FORMS 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:

Running programs of package FORMS

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.

List of error messages

File list of package FORMS

(A) Documentation:
forms.htm
This file (main HTML file containing basic description and links the files 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 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.
(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 and WRL 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 and POV files.
(F) General and graphical application programs:
iniwrl.for
Program INIWRL to initialize a VRML file.
Description of input data.
ptswrl.for
Program PTSWRL to convert points into VRML.
Description of input data.
linwrl.for
Program LINWRL to convert lines into VRML.
Description of input data.
srfwrl.for
Program SRFWRL to convert triangulated surfaces into VRML.
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.
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.
trglps.for
Program TRGLPS to display triangulated 2-D velocity and other sections in PostScript.
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.
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.
(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.
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
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
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 Ln 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.
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.
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.
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.
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).
gmt.for
Program GMT to compute general transposed matrix GM2=GM1T.
Description of input data.
gmgm.for
Program GMGM to compute product GM3=GM1*GM2 of two general matrices GM1 and GM2.
Description of input data.
smgm.for
Program SMGM to compute product GM2=SM1*GM1 of symmetric matrix SM1 and general matrix GM1.
Description of input data.
dmgm.for
Program DMGM to compute product GM2=DM1*GM1 of diagonal matrix DM1 and general matrix GM1.
Description of input data.
smsm.for
Program SMSM to compute product GM1=SM1*SM2 of two symmetric matrices SM1 and SM2
Description of input data.
smsmsm.for
Program SMSMSM to compute product SM3=SM1*SM2*SM1 of symmetric matrices SM1 and SM2.
Description of input data.
gmdmgmt.for
Program GMDMGMT to compute product SM1=GM1*DM1*GM1T of general matrix GM1, diagonal matrix DM1 and transposed matrix GM1. Resulting matrix SM1 is symmetric.
Description of input data.
sminv.for
Program SMINV 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 'sminv.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=SM1POWER, 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.
(I) 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.
(J) 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.
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.
(K) Demo data:
grd.h
Example of the SEP parameter file describing the grid dimensions.
corfun.h
Sample history file to generate PostScript figures of random functions with different correlation functions using 2-D program 'grdran2d.for'. The history file may be used to demonstrate Perl script 'go.pl'.
corfft.h
Sample history file to generate and plot representations of random functions with different correlation functions. Calculates the same figures as 'corfun.h' but using 3-D programs 'grdran.for', 'grdfft.for', 'grdcor.for', 'grdcal.for' and 'grdstat.for'.
cknfft.h
Sample history file to calculate the medium correlation function by FFT (programs 'grdfft.for', 'grdcor.for', 'grdcal.for') and compare the result with analytic solution calculated by 'grdckn.for'.

Acknowledgements

The development of this package has been partially supported by: