Etree CVM database programs

Copyright (c) 2003
Tiankai Tu, Dave O'Hallaron
Carnegie Mellon University


*********
0. Files
********

README          This file

Makefile        Builds the program for generating and querying CVM etree 
definedomain.c  Interatively define the origin and size of a domain
domain.c        Support routine for domain definition and manipulation
createcvm.c     Create/generate an etree database for community velocity model
packcvm.c       Compactly store an etree database
querycvm.c      Query a point, line, cross section, or a 3D volume from CVM
                etree database


labase.layer    Sampling layers for generating CVM etree for LA Basin
labase.2        An extremely coarsen grained layer specification for LA Basin
labase.domain   The origin and size of the LA basin

Version3.0.tar.gz  SCEC Model version 3.0 (a Fortran program)

####################################
1. Generating the CVM etree database
####################################

Step 1: Set the DESTDIR variable in the Makefile to absolute pathname
of the directory where you want the CVM etree stored.

Step 2: Type "gmake cvmetree".  This will call the createcvm program,
which creates the CVM etree database in the file $(DESTDIR)/labase.e.

The origin of the LA Basin for which the CVM etree database is
generated is at: 
    Longitude (in degrees)   -118.7
    Latitude (in degrees)    33.58
    Depth (in meters)        0

The size of the Basin is:
    X - along latitude       100km
    Y - along longitude      100km
    Z - along depth          37.5km


##################################
2. Querying the CVM etree database
##################################

You can use the querycvm program to query the cvm etree created in
Part 1. The querycvm program takes the following 11 arguments, in
exactly the order specified:

1.    cvmetrree	- Pathname of the CVM etree database
2.    p1_lon	- The longitude (in degrees) of the "first end point"
3.    p1_lat	- The latitude (in degrees) of the first end point
4.    p1_dep	- The depth (in meters) of the first end point
5.    p2_lon	- The longitude (in degrees) of the "second end point"
6.    p2_lat	- The latitude (in degrees) of the second end point
7.    p2_dep	- The depth (in meters) of the second end point
8.    dim	- Dimension of the query; 0, 1, 2 or 3
9.    spacing	- Spacing between grid points (in meters)
10.   fieldname	- Name of the field to retrieve
11.   outfile	- Output file name



In the querycvm program, the sizes and locations of objects are
specified using two "end points" (arguments 2-7). For a 0-dimensional
point, the end points are identical and correspond to the location of
point. For a 1-dimensional line, the end points are the simply the end
points of the line. For a 2-dimensional cross-section and
3-dimensional volume, the end points can be any pair of corners points
connected by a diagonal. For example, the corner closest to the
original and the corner furthest from the origin are a valid pair of
end points.

Each record in the CVM etree database has three fields, named "Vs",
"Vp", and "density". In argument 10 of querycvm, you can specify one
of these fieldnames to retrieve one of these fields, or you can
specify the fielname "all" (without the quotation marks) to retrieve
all of the fields.

The format of the output from querycvm is as follows:

- For 3D volume, the first line has the pattern "l X m X n", where l
  is the number of grid points along the latitude; m is the number of
  grid points along the longitude; and and n is the number of grid points 
  along the depth. Naturally, the depth is zero at top surface and increase
  positively as going down deeper into the ground. The origin of the
  grid is the corner of the rectangular region that is closest to the
  origin of the CVM etree database.

  From the second line on, each line starts with i, j, k and then the
  value(s) for the field(s) specified. If all the fields are needed,
  Vp is stored first, followed by Vs, and finally density.
    
- For 2D cross section, the first line has the pattern "l X m", where l is
  the number of grid points along the X axis of the 2D plane, and m
  is the number of grid points along the Y axis of the 2D plane.

  If the cross section is a horizontal cut, the X axis is along the
  latitude, and Y axis is along the longitude.

  If the cross section is a vertical cut, the Y axis is along the depth,
  and the X axis is
  (1) along the longitude if the normal of the cut plane is along the
      latitude. 
  (2) along the latitude if the normal of the cut plane is along the 
      longitude. 
  (3) along the directional line on the longitude-latitude plane from
      the end point with a smaller longitude value to the other end     
      point.

  From the second line on, each line starts with i, j of the 2D grid and
  then the value(s) for the fields(s) specified. If all the fields are 
  needed, Vp is stored first, followed by Vs, and finally density. 
    
- For 1D line, the first line has the pattern "l", where l is the number
  of grid points on the line. The line is treated as directional from end
  point 1 (p1) to end point 2(p2). 

  From the second line on, each line starts with i and then the value(s) 
 for the fields(s) specified. If all the fields are needed, Vp is stored 
 first, followed by Vs, and finally density. 

- For 0D point, the only line in the output file lists the value(s) for
  the fields(s) specified. If all the fields are needed, Vp is stored 
  first, followed by Vs, and finally density.


########################################################
3. Example queries of the CVM etree database in labase.e
########################################################

(a) Querying for Vs at a point at lon=-118.5, lat=33.6, depth=0

unix> make pointquery
./querycvm labase.e -118.5 33.6 0 -118.5 33.6 0 0 0 Vs point.txt


(b) Querying for Vp on a line defined by end points (-118.5, 33.6, 0) and
    (-118.25, 33.8, 1000). The spacing between grid points is 100 meters.

unix>gmake linequery
./querycvm labase.e -118.5 33.6 0 -118.25 33.8 1000 1 100 Vp line.txt


(c) Querying all the fields of grid points on a 2D cross-section defined by
    end points (-118.5, 33.6, 0) and (-118.25, 33.8, 1000). The spacing is 
    is 100 meters.

unix>make slicequery
./querycvm labase.e -118.5 33.6 0 -118.25 33.8 1000 2 100 all slice.txt


(d) Querying density of grid points on a 3D volume defined by end
    points (-118.5, 33.6, 0) and (-118.25, 33.8, 1000). The spacing is is
    100 meters.

unix>make volumequery 
./querycvm labase.e -118.5 33.6 0  -118.25 33.8 1000 3 100 density volume.txt


Note that query (b), (c), and (d) have the same end points but differ
in the dimension of the object being queried. 














