Seismic model specification subroutine package MODEL
(general description)
                                                                 
Version 5.10
Date: 1997, October 25

Authors:
    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
    Vlastislav Cerveny
            Department of Geophysics, Charles University Prague
            Ke Karlovu 3
            121 16  Praha 2,  Czech Republic
            E-mail: vcerveny@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

This is just a general overview, the detailed description of input
data, procedures, and other important topics is included within the
individual FORTRAN77 source code files.

References:
    Cerveny V., Klimes L. and Psencik I. (1988):  Complete seismic-ray
            tracing in three-dimensional structures. In: Seismological
            Algorithms, ed. Doornbos D.J., Academic Press, New York.
    The above paper contains detailed description of the model
    construction and is frequently referred throughout the FORTRAN77
    code of model specification routines.  The references like
    (C.R.T.5.4) or (5.4) are related to the paper.  The detailed
    description of the input data, subroutine and function parameters,
    and other specifications not contained in the paper, is included
    within the individual source code files.

    Cline, A.K. (1974):  Scalar- and planar-valued curve fitting using
            splines under tension.  Commun. ACM, 17, 218-220.
    Cline, A.K. (1974):  Algorithm 476 -- Six subprograms for curve
            fitting using splines under tension.  Commun. ACM, 17,
            220-223.
    Cline, A.K. (1981):  FITPACK -- software package for curve and
            surface fitting employing splines under tension.  Dept. of
            Comp. Sci., Univ. of Texas, Austin.
    These references are related to the interpolation subroutines
    located in file 'fit.for'.

Model specification:
    The way of building the model is concisely described in the above
    paper on C.R.T.  The model building technique is independent of
    the coordinate system, independent of the method used to specify
    and interpolate the surfaces covering structural interfaces, and
    independent of the functions describing the distribution of
    material properties within the individual complex geological
    blocks.
    The basic subroutines to deal with general blocky geological
    structures are located within the source code file 'model.for'.
    Among them, the most important subroutine is BLOCK determining
    the relation of a given point with respect to geological blocks.
    The data describing the model topology are described within the
    source code file 'model.for'.
    To specify a particular model, the following routines should be
    available:
    METR1 (file 'metric.for')... Memorizes the type of the model
            coordinate system.
    KOOR (file 'metric.for')... Recalls the type of the model
            coordinate system (zero for Cartesian coordinates).
    METRIC (file 'metric.for')... Evaluates the metric tensor and
            Christoffel symbols at a given point.
    CARTES (file 'metric.for')... Transforms the model coordinates to
            Cartesian coordinates.  Not employed within the complete
            ray tracing, used rather for model imaging.
    SRFC1 (file 'srfc.for')... Reads the input data for smooth
            surfaces.
    SRFC2 (file 'srfc.for')... Evaluates functions describing the
            smooth surfaces.
    PARM1 (file 'parm.for')... Reads the input data for the material
            parameters of the model.
    PARM2 (file 'parm.for')... Evaluates the material parameters of a
            given complex geological block at a given point.
    To deal with the first order model variations for the purposes of
    inverse problems, the routines VAR1 to VAR5 should be called
    properly during the evaluation of functions describing surfaces or
    material properties in order to memorize the variations.  The
    invocations of VAR1 to VAR5 are irrelevant for forward modelling.
    These invocations are denoted by '*V' in the first two columns of
    source code (files 'model.for', 'parm.for', 'val.for', and
    'fit.for').  The source code lines with '*V' should be modified or
    removed by means of the program 'clean.for' or a text editor.
    When submitting different subroutines SRFC2 and PARM2 while
    dealing with inverse problems, the user is responsible for proper
    invocation of routines VAR1 to VAR5.

......................................................................

The model specification subroutine package MODEL consists of the
following FORTRAN77 source code and demo files:

(A) Documentation:
    'modeldoc.htm'... This file containing a brief overview of the
            MODEL package.  The detailed description of input data,
            procedures, and other important topics is included within
            the individual FORTRAN77 source code files.

(B) General subroutines dealing with blocky geological structures:
    'model.for'... Subroutines reading input data to specify a blocky
            seismic model for complete ray tracing (see C.R.T.3.2.1),
            routines to determine the position of a given point with
            respect to geological blocks and structural interfaces,
            and other auxiliary subroutines related to the model (see
            C.R.T.3.3).  These routines assume a general form of
            user-defined subroutines METR1 (file 'metric.for') to
            define the coordinate system.
    'modelv.for'... Version of 'model.for' for inverse problems.
    'model.inc'... Include file with COMMON blocks for 'model.for'.

(C) Sample user-defined model specification routines required for
            forward modelling:
    'metric.for'... Subroutine evaluating the metric tensor and
            Christoffel symbols at a given point (see C.R.T.2), and
            the related subroutines and external functions.
            Any user-defined coordinate system may simply be
            introduced by modification of these subroutines.
    'metric.inc'... Include file with COMMON block for 'metric.for'.
    'srfc.for'... Subroutines for specification and interpolation, in
            rectangular grids, of the functions describing smooth
            surfaces in the model (see C.R.T.3.2.2).
            Any user-defined surfaces may simply be included within
            the whole system by modification of these subroutines.
    'parm.for'... Subroutines for specification and interpolation, in
            rectangular grids, of the material parameters within
            individual complex blocks in the model (see C.R.T.3.2.3).
            Any user-defined spatial distribution of material
            properties may simply be included within the whole system
            by modification of these subroutines.
    'parmv.for'... Version of 'parm.for' for inverse problems.
    'val.for'... Subroutines controlling function specification and
            interpolation.  Designed to perform the interpolation
            of a set of functions in a rectangular grid, employing
            splines under tension.  These subroutines are referred
            by the subroutines of files 'srfc', 'parm', and sample
            complete ray tracing source code file 'init'.
    'valv.for'... Version of 'val.for' for inverse problems.
    'val.inc'... Include file with COMMON block for 'val.for'.
    'fit.for'... Some routines taken from Cline's software package
            'FITPACK', called by the subroutines of the package 'val'
            to perform the spline-under-tension interpolation.
            Note that not all of the subroutines of the software
            package 'fit' are used at the same time.
    'fitv.for'... Version of 'fit.for' for inverse problems.
    'auxmod.inc'... Include file with COMMON block containing
            auxiliary storage locations for local model parameters
            required to call subroutines METRIC, SRFC2, PARM2 and
            VELOC.

(D) Additional model specification routines related to inverse
            modelling:
    'var.for'... Subroutine VAR1 and its entries VAR2, VAR3, VAR4 and
            VAR5 are called from the model-treating subroutine
            packages in order to keep in the memory variations of the
            functions describing the model, with respect to their
            coefficients. The variations are required for the
            travel-time inversion of the model and are recalled from
            the memory by calling the entry VAR6.
    'varnul.for'... Empty versions of the subroutine VAR1 and its
            entries VAR2 to VAR6 called from the model-treating
            subroutine files in order to keep in the memory
            variations of the functions describing the model, with
            respect to their coefficients.
            The variations are required for the travel-time inversion
            of the model, see also the subroutine file 'var.for'.  In
            the case of forward modelling, the variations are useless.
    'spsp.for'... Subroutines evaluating the Sobolev scalar products
            of variations of the functions describing the model, with
            respect to their coefficients.  This raw low-level version
            is related rather to the low-level 'fit.for' subroutines
            than to 'srfc.for' and 'parm.for' model specification
            subroutines.

(E) Service routines useful to handle the model and to perform some
            calculations:
    'means.for'... Service subroutines facilitating the work with the
            model.  E.g., subroutine CROSS determining the point of
            intersection of a given curve with a given surface
            described by a general subroutine SRFC2 of 'srfc.for',
            subroutine CDE searching for the point of intersection of
            the given curve with the boundaries of the complex block
            based on the subroutine BLOCK of 'model.dat', or
            subroutine SMVPRD mutually transforming covariant and
            contravariant coordinates of a vector.
            These routines are employed by complete ray tracing and by
            model imaging routines 'modsec.for'.
    'hpcg.for'... Subroutine of the IBM Scientific Subroutine Package
            solving a system of general first order ordinary
            differential equations with given initial values.  It is
            called, e.g., by the subroutine RAYCB of the complete ray
            tracing source code file 'raycb.for'.
    'rkgs.for'... Subroutine of the IBM Scientific Subroutine Package
            solving a system of general first order ordinary
            differential equations with given initial values.  It is
            called, e.g., by the subroutines of the file 'modsec.for'.

(F) Sample application programs and routines working with the model:
    'modchk.for'... Program checking the model consistency.
    'grid.for'... Program generating velocities in a rectangular grid
            required for full wave finite differences, shortest path
            calculation of seismic rays, eikonal equation 'finite
            differences', raster imaging of the model, or debugging
            purposes.
    'sec.for'... Program to determine interfaces and velocity
            isolines in 2-D sections of a 3-D seismic model.  May be
            used to generate a wireframe representing some model
            properties to be displayed, or to approximate interfaces
    'sec.inc'... Include file with COMMON blocks for 'sec.for'.
            by small tetragonal facets for display purposes.
    'intf.for'... Program to check the positions of given points with
            respect to interfaces in the model.
    'inv3.for'... Program designed to update the input data for a
            function describing the model according to the results of
            a tomographic inversion.  The tomographic inversion proper
            is not included.
    'inv4.for'... A simple program designed to subtract two sets of
            grid values of a function describing the model:
            GRID1-GRID2=GRID3.

(G) Source code editing program:
    'clean.for'... Program to modify the lines with a given letter in
            the first column.
    'mod.bat'... Sample MS-DOS batch file demonstrating how to convert
            model specification routines 'model.for', 'parm.for',
            'val.for' and 'fit.for' for forward modelling programs
            into the model specification routines 'modelv.for',
            'parmv.for', 'valv.for' and 'fitv.for', for inverse
            modelling programs.

(H) Demo files:
    'model.dat'... Sample input data for the model specification
            routines.  The 3-D model consists of two layers and of the
            lenticular inclusion with edges, situated in the upper
            layer, see the schematic Figure 5 in the paper on C.R.T.
            mentioned above.  The data are read by the subroutine
            MODEL1 of 'model.for' with the help from the subroutines
            of files 'srfc.for', 'parm.for', 'val.for', and 'fit.for'.
    'modchk.dat'... Sample additional input data for the 'modchk.for'
            program, supplementing data 'model.dat' with the
            specification of the free-space simple block.
    'grid.dat'... Sample main input data for the 'grid.for' program.
    'gridnet.dat'... Additional input data file for the 'grid.for'
            program, referred in 'grid.dat'.
    'sec.dat'... Sample input data for the 'sec.for' program to
            generate the file with isolines.
    'sec-pts.dat'... Sample input data for the 'sec.for' program to
            generate the file with points at structural interfaces.
    'inv3.dat'... Sample additional input data file for the INV3
            program, containing the specification of the rectangular
            grid for the discretization of the P-wave velocity in the
            1-st complex block.
    'len-grd.bat'... MS-DOS batch file to display 2-D velocity sections
            across the demo model 'model.dat'.
    'fmod.bat'... MS-DOS batch file for Lahey Fortran 77 compiler
            driven by means of predefined batch file L.BAT.
    'fmod'..Unix script to compile the MODEL package by means of
            predefined script 'f'.

(I) Subdirectories with data files related to particular models:
    'sd'... Salt dome model and dislocated salt dome model.
    'slit'..Slit model.
    'wb'... Western Bohemia a priori model.
    'l7'... Model L7.
    'mar'...INRIA bench-mark versions of the 2-D Marmousi model.

......................................................................

Compilation and linking:

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 (since version
5.00) which should be more convenient than uppercase on Unix systems.

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.

Notes on linking:
    Model specification routines (B) and (C) for forward modelling are
            likely to be required by all applications.
            Example: 'grid.for' program linked with all files of (B)
              and (C).
    In addition, some of service routines (E) are required by some
            applications.
            Example 1: 'sec.for' program linked with the files
              'modsec.for', 'means.for', 'rkgs.for', and all files of
              (B) and (C).
            Example 2: complete ray tracing program and routines
              linked with 'means.for', 'hpcg.for', and all files of
              (B) and (C).
    Inverse modelling programs are likely to require model
            specification routines (B) and (C) for forward modelling
            together with the model specification routines (D) for
            inverse modelling.  Do not forget to use the versions with
            '*V' in the first two columns of source code replaced by a
            pair of spaces.

......................................................................

Running the executable programs:

Within the FORTRAN77 source code submitted with this package, all
programs read main input data from the * interactive unit.

MS-DOS example:
Executable program named, e.g., PROG.EXE may be run with single-line
main input data
            'DATA' 1 2 3 'END' /
in at least three different ways:
(a) Running the program by entering
            PROG
    from the MS-DOS command line, then entering data
            'DATA' 1 2 3 'END' /
(b) Redirection: storing
            'DATA' 1 2 3 'END' /
    into a file named, e.g., prog.tmp (e.g., by entering
            ECHO 'DATA' 1 2 3 'END' / >prog.tmp
    ), then entering
            PROG