Complete ray tracing subroutine package CRT
(general description)
                                                                 
Version 5.20
Date: 1998, September 20

Authors:
    Vaclav Bucha
            Department of Geophysics, Charles University Prague
            Ke Karlovu 3
            121 16  Praha 2,  Czech Republic
            E-mail: bucha@seis.karlov.mff.cuni.cz
    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.

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

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             < crt.con
  DEL               crt.con
from the MS-DOS command line.  The 3 consecutive blank lines in
'crt.con' represent pressing enter required by 'scropc.for' when
finishing one elementary wave in order to clear the screen and
continue the computation.  Running other programs from the MS-DOS
command line:
  ECHO 'r01.out' 'r01i.out' 'rays1.out' /     |CRTRAY
  ECHO 'r02.out' 'r02i.out' 'rays2.out' /     |CRTRAY
  ECHO 'r03.out' 'r03i.out' 'rays3.out' /     |CRTRAY

Analogously under the UNIX operating systems.

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

Data sets:
    The complete ray tracing program reads or may write the following
    data sets:
(1) CRT...  Main data set with the names of the files containing the
            data sets (2) to (8).  It is read in by the subroutine
            CRTIN of the package 'crtin.for', called by the main
            program CRT.  The data are described in the package
            'crtin.for'.
(2) MODEL...Input data for the model.
            The data are read by the subroutine MODEL1 and are
            described in the subroutine file 'model.for'.
(3) DCRT... Input data for the complete ray tracing.
            The data are read by the subroutine RAY1 and are
            described in the subroutine file 'ray.for'.
(4) INIT... Input data specifying the initial conditions for rays.
            The data are read by the subroutine INIT1 and are
            described in the subroutine file 'init.for'.
(5) CODE... Input data specifying the codes of elementary waves.
            The data are read by the subroutine CODE1 and are
            described in the subroutine file 'code.for'.
(6) RPAR... Input data specifying the take-off parameters of the
            computed rays.  The data are read by the subroutine
            RPAR1 and are described in the subroutine file
            'rpar.for'.
(7) WRIT... Names of the files containing the data sets (9) to (11).
            This data set is read by the subroutine WRIT1 and is
            described in the subroutine file 'writ.for'.
(8) LOG...  Log output.
            The data are written by the subroutines WRIT1, WRIT2,
            WRIT4 and WRIT5 and are described in the subroutine
            package 'writ.for'.
(9) (WRIT31(I),I=1,KWAVE)... Output data sets with the computed
            quantities along the rays (see C.R.T.5.5.3).  KWAVE is the
            number of the computed elementary waves, or KWAVE=1 if the
            quantities corresponding to all waves are stored into a
            single file.  The data are written especially by the
            subroutine WRIT31 and are described in the subroutine
            package 'writ.for'.  The data sets may also be, in part,
            written by the subroutines WRIT1, WRIT2, WRIT4 or WRIT5.
            Unformatted.
(10) (WRIT32(I),I=1,NSTOR)... Output data sets with the computed
            quantities at the specified surfaces (see C.R.T.5.5.2).
            NSTOR is the number of surfaces at which the quantities
            are to be stored.  The data are written especially by the
            subroutine WRIT32 and are described in the subroutine
            package 'writ.for'.  The data sets may also be, in part,
            written by the subroutines WRIT1, WRIT2, WRIT4 or WRIT5.
            Unformatted.
(11) ((WRIT33(I,J),I=1,NELEM(J)),J=1,NWAVE)... Output data sets with
            the computed quantities at the endpoints of the elements
            of rays of individual elementary waves (see C.R.T.5.5.3).
            NWAVE is the number of the computed elementary waves.
            NELEM(J) is the number of elements of rays of J-th
            elementary wave which do not coincide with the elementary
            waves which have been computed.  The data are written
            especially by the subroutine WRIT33 and are described in
            the subroutine file 'writ.for'.  The data sets may also
            be, in part, written by subroutines WRIT1, WRIT2, WRIT4
            or WRIT5.  These files are auxiliary disk storage
            locations to the program CRT and are not intended to be
            the output of the complete ray tracing used by the user
            application programs.  Unformatted.
(12) File with the quantities at the initial points of rays (see
            C.R.T.6.1) corresponding to each of the files (9), (10)
            and (11).  Unformatted.
    Several data sets may be read from or written to a single file.
    The data sets are read in the following order:
            Successively reading data (1), (2), (3), (4) and the
            introduction part of (7).
            Writing the introduction parts of (8) and, perhaps, of (9)
            and (10).
            For each elementary wave IWAVE: successively reading the
            parts of data (5), (6), (7) corresponding to this
            elementary wave, then simultaneously writing the parts of
            (8), (9), (10), (11) corresponding to this elementary
            wave.
            Writing the end parts of (8) and, perhaps, of (9) and
            (10).

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

Output statements:
    Outputs written into disk files:
            Are concentrated in the subroutine file 'writ.for'.
    Screen output:
            Is concentrated in generic subroutine file 'scro.for', in
            subroutines SCRO1, SCRO2, SCRO3, SCRO4 and SCRO5.
            For the description of the screen output, both textual
            and graphical, refer to the version of 'scro.for' screen
            output software used (e.g. to 'scropc.for').  Users are
            encouraged to customize screen output by means of
            preparing their own versions of 'scro.for'.

Reasons of the termination of the computation of a ray
    are specified by the output parameter IEND of the subroutines
    INIT2 and RAY2 and are listed in the subroutine files 'ray.for'
    (reasons 10 to 61) and 'init.for' (reasons 71, 72, 73, and 74).

List of the computed quantities is given in the package 'ray.for'.

Graphics:
    All graphic outputs are concentrated in the subroutine file
    'scropc.for', in subroutines SCRO1, SCRO2, SCRO3, SCRO4 and SCRO5.
    CalComp subroutines
            PLOTS(0,0,0)
            PLOT(XPAGE,YPAGE,IPEN)
            NEWPEN(INP)
    are called.  The subroutine SYMBOL cannot be used because its
    CalComp specification is not conformal with the FORTRAN77
    standard.  The subroutine NUMBER is not employed.  If the
    subroutines PLOTS, PLOT and NEWPEN are not present in the
    computer, they must be substituted by user-defined or void
    subroutines.  The specification of their parameters can be found
    in the subroutine file 'scropc.for'.

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

Acknowledgements:
    The development of the complete ray tracing algorithm and the
    related Fortran 77 packages has been partially supported by:
    Faculty of Mathematics and Physics, Charles University, Prague.
    Energy, Mines and Resources Canada, Ottawa, Ontario.
    Institute of Geotechnics, Czechoslovak Academy of Sciences,
            Prague.
    Geophysical Institute, Academy of Sciences of the Czech Republic.
    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 3-D Structures'.

======================================================================