README FOR UTAH-G3D GRAVITY BLOCK MODELING PACKAGE
--------------------------------------------------
This package is a set of programs and C subroutines for computing the
gravity effect of a set of rectangular blocks.  The blocks can be of
varying sizes, and need not be cubical.  Virtually any density
structure can be approximated with this modelling scheme, although it
may be very ineffecient in some cases.  It is, however, very general
and robust.

REQUIREMENTS
------------
* - ANSI C++ compiler, to compile the model computation and visualization
    code.
* - Python, for the model geometry and horizontal grid generator;
    Python 1.5.2 has been tested, but anything after 1.5 should work.
* - VRML97/VRML2.0 viewer to use the visualization code
* - OpenGL library (libGL and libglut) to use OpenGL vis program
* - Some disk space; models take several hundred kB to several tens of
    MB of space.
* - CPU cycles to burn, particularly for the inversion code.

LICENSE
-------
This code is released under the GPL.  Have fun.  Please send
improvements, bug fixes/reports, etc. back to the author
(gettings@mines.utah.edu).

There is no warranty, express or implied, of any kind.

GENERAL OVERVIEW OF USAGE
-------------------------
1. Define the model geometry - this can be done in many ways, from typing
in the blocks by hand, to using advanced 3d CAD programs.  This package
includes a utility ("genModel") that will build model geometries from
several simple geometric shapes; see README.genModel for more information.

Once the geometry is generated in this step, it is assumed valid by
subsequent programs.  In particular, this means that overlapping
blocks, zero-sum block pairs, etc. will be blindly accepted by the
computation engine.  This is a feature of the simplicity of the system;
all geometry decisions, testing, and problem resolution should be done
by the geometry generator.

1A. If desired, visualize the model geometry-
  1Ai.  Use "vis" and a VRML viewer
    OR
  1Aii. Use "openglvis" to directly view the geometry using OpenGL

2. Define the "observation" points - these are the (x,y,z) points (in
the model coordinate system!) where the gravity effect of the model
should be calculated.  These can be put into a file by hand, or a
horizontal grid can be generated from generate_horiz_grid.py.

3. Run compute on the grid and model.
  OR
   Invert the grid and model for density structure using simanneal.

4. Plot the results - the output is a set of (x,y,z,g) points, one per
line, with space separated fields.  This should be easy to plot in
virtually any plotting software.

THEORY OF OPERATION
-------------------
See README.model for a discussion of the computation engine and
assumptions.


FILE LIST
---------
Makefile			Makefile for building C sources
model.c				C source for model engine, file I/O
model.h				Header file for programs using model.c
compute.c			Simple interface to model.c
vis.c				Converts model geometry file to VRML97
openglvis.cpp			Render model geometry using OpenGL
genModel.c			Generate geometry file from text
				description
genModel.h			Header file for genModel.c
blocktree.c			Routines for creating/traversing the
				oct-tree used in genModel
blocktree.h			Header file for blocktree.c
mt.c				Mersenne Twister LC random number
				generator; see file for copyright and
				author info
mt.h				Header file for mt.c
gaussrand.c			Gaussian PRNG, based on mt.c
gaussrand.h			Header file for gaussrand.c
matrix.c			Matrix utility functions; a very
				limited linear algebra base.
matrix.h			Header file for matrix.c
simanneal.cpp			3d gravity inversion using "simulated
				annealing" - essentially a Monte-Carlo
				inversion algorithm; another example
				application for model.c
newton.cpp			3d gravity inversion using Newton's
				method; quick convergence, but no
				regularization. Uses model.c and
				matrix.c
generate_horiz_grid.py		Generate a horizontal grid of points
generate_model.py		Generates geometry file from text
				description; Python variant of
				genModel.c
README				This file
README.model			README describing model.c and the
				Theory of Operation of the computation
				engine
README.vis			README for the vis program
README.openglvis		README for the openglvis program
README.compute			README for the compute program
README.simanneal		README for the simanneal program
README.genModel			README for genModel.c
README.generate_model		README for generate_model.py
README.generate_horiz_grid	README for generate_horiz_grid.py
README.speed_test		Results of speed benchmarks on the
				development machine; 2 us/element comp.

test				Subdir with some tests
test/block_test			Simple block model test
test/block_plot.m		Matlab script to contour block_output
test/cutout_test		Block w/ sphere overlap test
test/cutout.wrl			VRML97 of cutout_geom
test/cutout_plot.m		Matlab(R) script to contour
				cutout_output
test/horiz_grid			Horizontal grid of positions to compute
				gravity for tests
test/disc_test			Test of disc geometry creation
test/speed_test			Large model for speed testing
test/speed_grid			Observation grid for speed testing

example				Subdir with an example model
example/horiz_grid		Horizontal grid of gravity computation
				points
example/model			Model file for generate_model.py
example/geometry		Generated geometry file for computation
example/output			Computed gravity effect of model
example/plot_grav.m		Matlab script to plot gravity effect
example/run			Shell script to perform actions in
				correct order
