Fortran 77 package FORMS version 6.40
 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
 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 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 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.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), 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 SEPlike 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*(M11)/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
listdirected 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
(indexx.for, tred2.for, tqli.for, pythag.for),
smeigen.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 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
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 SW3DCD 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,
righthanded 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 2D 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 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.
 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 zerooffset surface seismic reflection survey
in a homogeneous 2D velocity model.

Description of input data.
 sgfmat.for

Program SGFMAT
to generate the system of linear equations for
the complexvalued coefficients of the structural Gabor functions
in decomposing a given gridded realvalued quantity.

Description of input data.
 sgfgrd.for

Program SGFGRD
to calculate the grid values of a realvalued 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
realvalued 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 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.
 grd2d3d.for

Program GRD2D3D
to extend 2D grid into 3D grid

Description of input data.
 grdiso.for

Program GRDISO
for identification of points at isosurfaces
of 3D 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 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.
 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 directaccess binary files.

Description of input data.
 swap.for

Program SWAP
to convert binary gridded data
between littleendian (PC's) and bigendian (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 commonsource 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 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.
 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.
 dotest.for

Program DOTEST
to test compilation of DO loops.

Program 'dotest.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 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.
 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, 205/07/0032
and P210/10/0736.
 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".