Fortran 77 package FORMS version 5.40
 Vaclav Bucha
 Department of Geophysics, Charles University Prague,
Ke Karlovu 3, 121 16 Praha 2, Czech Republic
 Email:
bucha@seis.karlov.mff.cuni.cz
 Petr Bulant
 Department of Geophysics, Charles University Prague,
Ke Karlovu 3, 121 16 Praha 2, Czech Republic
 Email:
bulant@seis.karlov.mff.cuni.cz
 Ludek Klimes
 Department of Geophysics, Charles University Prague,
Ke Karlovu 3, 121 16 Praha 2, Czech Republic
 Email:
klimes@seis.karlov.mff.cuni.cz
 Ivan Psencik
 Geophysical Institute, Acad. Sci. Czech Rep.,
Bocni II 1401, 141 31 Praha 4, Czech Republic
 Email:
ip@ig.cas.cz
 Paul Spudich
 U.S. Geological Survey,
345 Middlefield Road, Menlo Park, CA 94025, U.S.A.
 Email:
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
gridpointbygridpoint 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 listdirected 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 listdirected 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 realvalued gridded data,
WARRAI and
WARAI to write integer gridded data,
RARRAY and
RARAY to read realvalued 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 spacetime 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 listdirected 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:
 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 programs
grdfft.for,
grdran2d.for,
grdran.for,
smpower.for or
smeigen.for,
you need also few subroutines
of the Numerical Recipes and the corresponding licence.
Necessary subroutine files are included at the end of above
listed files containing main programs.
Refer to package NR.
 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 dotest
to compile program dotest.for,
which may be executed on most systems by entering command
dotest
 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
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,
righthanded 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 2D 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 frequencydomain
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
realvalued 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
L_{n} of gridded values.

Description of input data.
 grdfft.for

Program GRDFFT
to compute the 1D, 2D or 3D Fourier
transform of a real or complex function defined on 1D,
2D or 3D grid of points.

Description of input data.
 grdfd.for

Program GRDFD
to calculate gradient of the grid values by means of
the secondorder finite differences.

Description of input data.
 grdran2d.for

Program GRDRAN2D
to generate a 2D 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 directaccess 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=GM1^{T}.

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*GM1^{T} 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=SM1^{POWER},
which is POWERth 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.
 dotest.for

Program DOTEST
to test compilation of DO loops.

Program 'dotest.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 MSDOS '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 2D 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 3D 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:
 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 3D Structures".