Fortran 77 package FORMS version 7.10

Prague, June 2014
Vaclav Bucha
Department of Geophysics, Charles University Prague, Ke Karlovu 3, 121 16 Praha 2, Czech Republic
Petr Bulant
Department of Geophysics, Charles University Prague, Ke Karlovu 3, 121 16 Praha 2, Czech Republic
Ludek Klimes
Department of Geophysics, Charles University Prague, Ke Karlovu 3, 121 16 Praha 2, Czech Republic
Ivan Psencik
Institute of Geophysics, Acad. Sci. Czech Rep., Bocni II 1401, 141 31 Praha 4, Czech Republic
Libor Sachl
Department of Geophysics, Charles University Prague, Ke Karlovu 3, 121 16 Praha 2, Czech Republic
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.

Copyright note

This software package is property of its authors, is distributed in source form, and may be used free of charge. If any result obtained with help of any part of this package is published, we appreciate citation of all papers related to the used part of this package. Refer to the references related to this package.

General remarks on the SW3D software

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 7.10

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:
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:

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.
Note: Possible conflict with Linux system program ss (utility to investigate sockets).
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.
gsecal.for
Program GSECAL to calculate a linear combination of seismograms 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.
indexi.for
Modification of subroutine 'indexx.for' from Numerical Recipes. Used in programs 'grdcal.for', 'smpower.for' and 'smeigen.for' of package FORMS, and in programs 'mtt.for' and 'wfsrf.for' of package CRT.
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.
anirot.for
Program ANIROT to rotate the tensor of elastic moduli of an anisotropic elastic medium.
anisrf.for
Program ANISRF to triangularize the phase-slowness surface or the ray-velocity surface.
For the example of triangularizing the phase-slowness surface and the ray-velocity surface in model SC1_II using program ANISRF refer to package DATA, history file sc2-srf.h.
(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 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.
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.
grdborn.for
Program GRDBORN to calculate the Born approximation of the wavefield at specified receivers.
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=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.
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 or to print the content of a file on the screen.
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:

References