Fortran 77 package FORMS version 5.20

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 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 files are designed to be read by the list-directed input (free format). The null values are generated in place of undefined 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 (numbers of gridpoints), D1, D2, D3 (grid intervals), O1, O2, O3 (coordinates of the grid origin, i.e., of the first gridpoint).
Subroutines WARRAY to write real-valued gridded data, WARRAI to write integer gridded data, RARRAY to read real-valued gridded data, and RARRAI to read integer gridded data, are collected in file forms.for.
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.
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

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
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.
If you wish to compile program grdran2d.for, you need also subroutines fourn.for and ran2.for or ran3.for of the Numerical Recipes and the corresponding licence. Refer to package NR.
Now you may compile and link following programs of package FORMS:
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.
You may perform the above task by editing Perl script f.pl designed to compile and link a single file, and then running Perl script fforms.pl by entering command
perl fforms.pl
If you have no Perl interpreter, it should be available at www.perl.org

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.
Description of input data for PALLET: Interpolation of colour tables.
Description of input data for SRP: Translating the system of points (e.g., sources or receivers) to a new position determined by the given configuration parameters.
Description of input data for GRDPTS: Generating the file of form PTS, containing the coordinates of all gridpoints of the given grid.
Description of input data for MGRD: Converting multivalued grid data into several singlevalued grids.
Description of input data for GRDNEW: Interpolating grid values into a new grid of different dimensions or density.
Description of input data for GRDCAL: Performing vectorial calculations with real-valued arrays stored in disk files (i.e., with singlevalued gridded data).
Description of input data for GRDNORM: Calculating the spatial density of the Lebesgue norm Ln of gridded values.
Description of input data for GRDFD: Calculating gradient of the grid values by means of the second-order finite differences.
Description of input data for GRDRAN2D: Generating a 2-D rectangular grid of random real numbers having a desired spatial correlation function.
Description of input data for GRDMERGE: Merging two nonoverlapping sets of values given on the same grid into a single set, especially to display the data together.
Description of input data for GRDPS: Displaying GRiD values in Post Script.
Description of input data for CREMOVE: Splitting a Fortran code into executable statements and comment lines.
Description of input data for SS: Program 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 for SP: Program to plot seismograms previously stored in the GSE data exchange format.

List of error messages

Package FORMS

File list of package FORMS

(A) Documentation:

forms.htm: This file (main HTML file containing basic description and links the files of this package).
formsdoc.htm: General documentation to package FORMS.
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.

(F) Sample application programs:

pallet.for: Program to interpolate the RGB colour pallet linearly in the HSB colour space.
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.
sp.for: Program SP (Seismogram Plotting) to plot seismograms previously stored in the GSE data exchange format.
srp.for: Program to generate 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.
grdpts.for: Program to generate the file containing the coordinates of all gridpoints of the given grid.
mgrd.for: Program to convert a multivalued grid into several singlevalued grids.
grdnew.for: Program to trilinearly interpolate grid values into a new grid of different dimensions or density.
grdcal.for: Program to perform vectorial calculations with real-valued arrays (data cubes) stored in disk files.
copy.cal
abs.cal
add.cal
sub.cal
mul.cal
div.cal
absdif.cal
reldif.cal
relerr.cal
atan2.cal
norm2.cal: Sample command files '*.cal' for program 'grdcal.for' describing simple operations with gridded data.
grdfd.for: Program to calculate gradient of the grid values by means of the the second-order finite differences
grdnorm.for: Program to calculate the spatial density of the Lebesgue norm Ln of gridded values.
grdran2d.for: Program to generate a 2-D rectangular grid of random real numbers having a desired spatial correlation function, specified variance and mean.
grdmerge.for: Program to merge two nonoverlapping sets of values given on the same grid into a single set.
grdps.for: Program to Display GRiD values in PostScript.

(G) Other routines useful for the related software packages:

eigen.for: Subroutine EIGEN of the IBM Scientific Subroutine Package.

(H) Auxiliary programs:

cremove.for: Program to split a Fortran code into executable lines and comment lines.

(I) 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.
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.

(J) Demo data:

grd.h: Example of the SEP parameter file describing the grid dimensions.
grdran2d.dat: Example of input data for 'grdran2d.for' supplemented with some comments.
grdps.dat: Example of input data for 'grdps.for' supplemented with some comments.
corfun.h: Sample history file to generate PostScript figures of random functions with different correlation functions. It may be used to demonstrate Perl script 'go.pl'.