Complete ray tracing subroutine package CRT
(general description)
                                                                 
Version 5.10
Date: 1997, October 26

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 algorithm of
    complete ray tracing and is frequently referred throughout the
    code of complete ray tracing.  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.

    Bulant, P. (1996):  Two-point ray tracing in 3-D.  PAGEOPH,
            in press.
    Bulant, P. (1996):  Two-point ray tracing and controlled
            initial-value ray tracing in 3-D heterogeneous block
            structures.  In: Seismic Waves in Complex 3-D Structures,
            Report 4, pp. 61-75, Dep. Geophys., Charles Univ., Prague.
    These references are related to the two-parametric shooting
    algorithm for 3-D two-point ray tracing coded in file 'RP3D.FOR'.

The code of the complete ray tracing subroutine package CRT is build
up on the basis of the model specification subroutine package MODEL.
Thus this general description of C.R.T. should be understood as a
continuation of the general description 'modeldoc.htm' of the seismic
model specification subroutines.

Attention: subroutine SCRO5 of 'scropc.for' interactively asks
    external unit * to continue.  This should be taken into account if
    linking 'crt.for' and wishing to redirect the * unit into a file.

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

The Complete Ray Tracing consists of package MODEL and of the
following FORTRAN77 source code and demo files:

(A) Documentation:
    'crt.htm'... Main HTML file containing basic description and links
            the files of this package.
    'crtdoc.htm'... This file containing a brief overview of the CRT
            package.  The detailed description of input data,
            procedures, and other important topics is included within
            the individual FORTRAN77 source code files.
    'crterr.htm'... HTML file containing links to error descriptions.

(B) Basic complete ray tracing program and subroutines:
            These files together with the forward modelling model
            specification routines of the files
              'model.for', 'metric.for', 'srfc.for', 'parm.for',
              'val.for', 'fit.for'
            form a consistent basic version of the complete ray
            tracing program.
    'crt.for'...  Main program.  It reads the input data and then
            controls the complete ray tracing of the specified
            elementary waves.
    'crtin.for'... Subroutines designed to open the data files for
            complete ray tracing and to read the input data sets CRT,
            MODEL, DCRT and INIT.  Called e.g. by the main program
            'crt.for'.
    'code.for'... Subroutine file devoted to the codes for
            elementary waves.  Contains the general description of the
            codes for elementary waves and subroutines designed to
            read the input data for the codes of elementary waves and
            to transform the used numerical code of the elementary
            wave under consideration into instructions specifying the
            behaviour of the wave at the initial points of rays and at
            all points of incidence of the rays at interfaces (see
            C.R.T.4).
    'code.inc'... Include file with COMMON block for 'code.for'.
    'ray.for'... Contains the subroutine designed to read the input
            data for complete ray tracing and to store them in the
            memory (see C.R.T.5.6), the list of the quantities
            computed along rays (see C.R.T.5.2), and the subroutine
            designed to continue the complete ray tracing of a ray
            from the given point (see C.R.T.5.7).
    'dcrt.inc'... Include file with COMMON block with data controlling
            ray tracing.  The data are read by 'ray.for' and are used
            by various ray tracing routines.
    'raycb.for'... Subroutines for complete ray tracing within one
            complex block (see C.R.T.5.8).
    'raycb.inc'... Include file with COMMON block for 'raycb.for'.
    'trans.for'... Subroutine transforming the computed quantities
            across a curved interface (see C.R.T.5.9), and subroutine
            replacing the amplitudes by ones involving the appropriate
            conversion coefficients (see C.R.T.5.5.4).
    'coef.for'... Subroutines computing the reflection/transmission
            coefficients (see C.R.T.5.9.7).
    'init.for'... Subroutines designed to read the input data for the
            initial surface, and to define the initial values of the
            quantities for complete tracing of a ray with given
            take-off parameters (see C.R.T.6).
    'initd.inc'... Include file with COMMON blocks for 'init.for',
            containing input data and related quantities.
    'initc.inc'... Include file with COMMON block for 'init.for'
            and other routines, containing the quantities at the
            initial point of the ray being currently traced.
    'rpar.for'... Subroutines controlling the take-off parameters of
            the rays.  A user may introduce his own procedure of
            selection of the take-off parameters and his own two-point
            ray tracing algorithm by means of a modification of this
            subroutine file, or subsequently referred files 'rp2d.for'
            and 'rp3d.for' controlling the shooting algorithms.
    'rpard.inc'... Include file with COMMON block for 'rpar.for',
            containing input data and related quantities.
    'rparc.inc'... Include file with COMMON blocks for 'rpar.for' to
            record the ray histories and other related quantities.
    'rp2d.for'... Subroutines controlling the one-parametric shooting
            algorithm determining the normalized take-off parameter
            of rays for 2-D two-point ray tracing.
    'rp2d.inc'... Include file with COMMON block for 'rp2d.for'.
    'rp3d.for'... Subroutines controlling the two-parametric shooting
            algorithm determining the normalized take-off parameters
            of rays for 3-D two-point ray tracing.
    'rp3dnul.for'... Void subroutines replacing 'rp3d.for' to save
            RAM if only 2-D ray tracing is performed.  Not very
            interesting.
    'writ.for'... Subroutines creating the output of complete ray
            tracing (see C.R.T.5.5).
    'writ.inc'... Include file with COMMON blocks for 'writ.for'.
    'scronum.for'... Basic version of the subroutine file 'scro.for',
            writing the index of ray and the index of elementary wave
            to the screen.  It uses the '+' ASA carriage control
            character in the first column to avoid line feed.

(C) The following subroutine files may be used to modify the basic
            version of the complete ray tracing program by means of
            additional screen output routines:
    'scronul.for'... Dummy version of the subroutine file 'scro.for'
            containing screen output subroutines called by the
            subroutines of the package 'writ.for'.
    'scropc.for'... Version of the subroutine file 'scro.for' for the
            IBM-compatible personal computers.  It should also work on
            the VAX computers.  The screen output consists of a simple
            graphic output (see the subroutine files 'plot*.for'
            below) and of writing the brief messages on the status of
            the currently computed ray to the console.  This output
            controls the console by means of the ANSI escape sequences
            supported by MS-DOS ANSI.SYS driver on IBM-compatible
            personal computers.  This console output is just an
            example, the subroutines SCRO1, SCRO2, SCRO3, SCRO4 and
            SCRO5 have to be modified by a user for the particular
            computer system.  If no screen output is required, the
            executable statements of the subroutines SCRO1, SCRO2,
            SCRO3, SCRO4 and SCRO5 may simply be deleted (see
            'scronul.for' above).
            Graphic output is accomplished by means of invocation of
            'CalComp' subroutines PLOTS, PLOT, and NEWPEN.  They may
            be already available on some computers for some FORTRAN77
            compilers (e.g., PLOTS, PLOT, and NEWPEN are included in
            the Lahey FORTRAN77 compilers for PC's).  Otherwise,
            'scropc.for' may be linked with 'plotnul.for' to disable
            plotting, or with user's own interface routines to his
            particular graphic system (see files 'plot*.for' and
            'calcomp.for').
    'scropc.inc'... Include file with COMMON block for 'scropc.for'.
    'plotnul.for'... Dummy version of the subroutine file 'plot*.for'
            containing the plot subroutines called by the subroutines
            of the package 'scropc.for', see also the section graphics
            of this guide.
    'calcomp.cfg'... Configuration file to the 'calcomp.for' routines,
            disabling the interactive communication and other features
            of 'calcomp.for' not required by the 'scropc.for'
            routines.  The 'calcomp.cfg' configuration file is active
            just if located in the current directory.  Otherwise, the
            'calcomp.for' routines run in an interactive way and may
            create another 'calcomp.cfg' configuration file.  Refer to
            the MODEL package.

(D) Application routines and programs facilitating the processing of
    the results of complete ray tracing:
            When using the complete ray tracing program composed of
            the subroutine files listed above, we determine and
            store various quantities along the ray and at the points
            of intersection of the ray with some selected surfaces.
            The following sets of routines may be utilized when
            processing the results of the complete ray tracing,
            including a kinematic inversion:
    'ap.for'... Applications and processing of the results of complete
            ray tracing.  Subroutines designed to read from the files
            the quantities describing the points of rays, and to
            evaluate many other quantities used in seismology and
            discussed in the chapter C.R.T.7.  These subroutines may
            be included in user's application programs following the
            complete ray tracing program.  Individual subroutines
            correspond to the individual sections of the chapter
            C.R.T.7, and may call many subroutines of the above
            files composing the complete ray tracing program.
    'apvar.for'... Subroutines designed to evaluate the variations of
            the travel time with respect to the model coefficients.
    'pointc.inc'... Include file with COMMON block /POINTC/ to store
            the quantities calculated at a point of a ray, used by
            'ap.for' and other routines processing the results of the
            'crt.for' program.
    'crtout.for'... Subroutines to facilitate conversion of the
            unformatted output of program CRT into formatted files.
    'ttsort.for'... Subroutine to sort the quantities according to the
            receivers, and at each receiver according to the
            increasing travel time.
    'rpplot.for': Plotting ray parameters.
    'crt2d3d.for'... Program to transform 2-D system of rays to 3-D
            system of rays to be processed by program MTT,
            which present version works only in 3-D.
    'mtt.for': Interpolation within ray cells.
    'mttgrd.for': Converting multivalued travel times produced
            by program MTT into several singlevalued grids
            corresponding to individual ray histories.
    'crt2p.for'... Program to single out two-point rays in the
            unformatted output program CRT.  Simple illustrative
            example how to use 'ap.for'.
    'crtpts.for'... Program converting the unformatted output of
            program CRT into formatted file with endpoints of rays.
    'crtray.for'... Program converting the unformatted output of
            program CRT into formatted files with rays suitable for
            plotting.
    'green.for'... Program to convert the unformatted output of
            program CRT into a formatted file containing the
            ray-theory elastodynamic Green function.
    'greenss.for'... Program to read a formatted file containing the
            ray-theory elastodynamic Green function and to generate
            ray-theory time-domain synthetic seismograms (without
            attenuation) or frequency-domain response functions
            (including causal Futterman's attenuation).
    'ss.for'(Synthetic Seismograms)... 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.
    'sp.for'(Seismogram Plotting)... Program to plot seismograms
            previously stored in the GSE data exchange format.
    'inv1tt.for'... Program designed to evaluate the derivatives of
            the travel time with respect to the model coefficients.

(E) Demo files:
    'guide.dat'... Some comments to the sample input data files
            '*.dat'.  'guide.dat' itself is not a data file.
    'crt.dat'... Sample main input data for the CRT program.
            This data file refers, among others, sample data file
            'model.dat' of the MODEL specification package, which has
            therefore to be located in the current directory.
    'dcrt.dat'... Additional input data file for the CRT program, with
            the numerical parameters for the complete ray tracing.
    'init.dat'... Additional input data file for the CRT program,
            specifying the initial conditions for rays (referring
            'len-src.dat').
    'len-src.dat'... Additional input data file for the CRT program,
            specifying the position of the point source.
    'code.dat'... Additional input data file for the CRT program,
            specifying the codes of elementary waves.
    'code1.dat'... Data specifying only the refracted wave.
    'rpar.dat'... Additional input data file for the CRT program,
            specifying the take-off parameters of the computed rays.
    'writ.dat'... Additional input data file for the CRT program, with
            names of the output files.  Whole two-point rays are
            stored in files corresponding to individual elementary
            waves and the points of intersection with given surfaces
            are stored in files corresponding to individual surfaces.
    'writsrf.dat'... Alternative data file specifying the names of the
            output files.  No whole rays are stored.  The points of
            intersection with given surfaces are stored in files
            corresponding to individual surfaces.
    'writall.dat'... Alternative data file specifying the names of the
            output files.  All whole rays are stored, not only two-point
            two-point rays.
    'source.dat'... Sample main input data for the GREENSS program to
            specify the point source (moment-tensor or single-force
            seismic source).
    'srpcrt.bat'... MS-DOS batch file to generate coordinates of the
            source and receiver points for given configuration
            parameters, perform two-point ray tracing, and convert
            unformatted output into a simple formatted file.
            It runs programs SRP, CRT and CRTPTS.
    'srpcrt.bat'... Unix script to generate coordinates of the
            source and receiver points for given configuration
            parameters, perform two-point ray tracing, and convert
            unformatted output into a simple formatted file.
            It runs programs 'srp', 'crt' and 'crtpts'.
    'fcrt.bat'... MS-DOS batch file for Lahey Fortran 77 compiler
            driven by means of predefined batch file 'f.bat'.
    'fcrt'..Unix script to compile the CRT package by means of
            predefined script 'f' compiling and linking a single
            Fortran 77 source code file.

(F) Subdirectories with data files related to particular models:
    'len'...Model with a lenticular inclusion.
    'prem'..PREM (Preliminary Reference Earth Model) specified in
            geographical spherical coordinates.
            Input data for the complete ray tracing in spherical
            coordinates.
    'elf1'..Homogeneous layers separated by dipping plane interfaces
            (model MI).
    'u2d'...2-D model UNCONFORMITY (Cormier and Mellen 1984).

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

Compilation and linking:

All Fortran 77 source code and include files of the CRT package are
assumed to be located in a single directory together with all source
code and include files of the MODEL package 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.

If using 'scropc.for' and linking with a compiler's calcomp library
(e.g. Lahey's F77L3 'GRAPH3.LIB' on a PC), do not forget to adjust
the CalComp plotting area in 'scropc.for'.

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

Running the executable programs:

MS-DOS example:
If the corresponding executables '*.EXE' have been prepared, CRT.EXE
program may be run with demo data, e.g., by entering commands:
  ECHO 'crt.dat' / >crt.con
  ECHO            >>crt.con
  ECHO            >>crt.con
  ECHO            >>crt.con
  CRT