Xgrav Manual

XGRAV MANUAL

Version 97.0430


Table of Contents


NAME

Xgrav - interactive Gravity Modeling software

VERSION

These notes pertain to version 2.0

SYNOPSIS

Xgrav ( data_files ) [-S] [-h]

DESCRIPTION

Xgrav is a program used to interactively model gravity anomalies with 2.5 dimensional subsurface bodies. Xgrav is written in C and uses X windows.

Xgrav was developed on a SUN SPARCstation LX running Solaris 2.3, and compatibility with other environments should not be assumed. It is a fairly straightforward program, however, so modifications should not be extensive. Xgrav also requires a color monitor to work properly.

ARGUMENTS

data_files
specifies the data files to be read in for modeling.

OPTIONS

-S Sort the data into ascending x-order

-h Prints out the usage summary.

SOME BASIC USAGE NOTES

Getting Started

To start Xgrav, type "Xgrav" and return. A window will appear after a short time, composed of three main elements: a section at the top with several buttons that generate windows for user input, a section on the left side used to set options for the various files that are read in, and a "canvas" on which pictures are drawn. The data will be plotted in the upper half of the canvas, and the model in the lower half.

Generally, you will want to use Xgrav to model gravity data, or simply to investigate the types of anomalies produced by different kinds of bodies. A typical session will begin by reading in some data and/or a trial model, testing out various hypotheses, and then saving a result to an new file to be analyzed later or to a PostScript file for printing.

Reading in Data and Models

Data and model files are read in by selecting the "READ" button in the upper left corner and filing in the appropriate information in the window that appears. Fill in the name of the file and the directory (if different from the one where you started the program) and click on either "Read Model" or "Read Data" depending on which type of file it is (the format of files is discussed below ). You can also scale and offset the numbers in the file by filling in the x or y scale and offset lines. Note that x is the distance axis and y is either the gravity reading (for data) for depth (for model). The unit of distance is kilometers, and milligals for gravity. Scaling can be used if different units are used in the data files.

Drawing on the Screen

A screen plot of the model and data can be made by selecting the "DRAW" button. The data files will be shown on the upper half of the canvas, and the model files on the lower half. Prior to drawing, an input window will appear that allows you to modify the appearance of the plot. The program tries to make a reasonable decision about how the plot should look, but often it is useful to adjust these manually.

Calculating Anomalies

Once a model has been input, for example by a file being read in, an anomaly can be calculated by selecting the "CALC ANOM" button. Gravity will be calculated at all points in the data files. If no data files have been entered, you will be shown a default station spacing which you can change by editing. The anomaly will appear in the data (upper part) of the canvas.

Saving Your Work

At any time you can save models and anomalies to files for future reference using the "WRITE MODEL" and "WRITE DATA" buttons. These write out the current model or data arrays to a file that can be read in by Xgrav later.

You can also make a hard copy of what you see on the screen by selecting "PS-DUMP" which will generate a PostScript file that you can later send to the printer. If you want to modify the printed file options select "PS-PREF" prior to dumping.

Quitting

You can quit Xgrav at any time by selecting the "QUIT" button.

More Advanced Stuff You Can Do

In addition to the basic tasks outlined above, Xgrav allows you to modify the model extensively. You can change the shape of bodies, enter new bodies, move bodies, change the density contrast or halfwidth of any body, and delete bodies. You can modify the density or shape automatically to best-fit the data using a least-squares procedure. You can also continue the data upwards (or downwards, though this is not advised) any distance.

There are also many options for changing the appearance of the plot, both on the screen and on paper. You can change fonts, add labels, shade bodies or fill them with patterns. Data can be plotted with different symbols and connected with different types of lines. You can even use color shading.

All of these options are defined systematically and in detail below. First, however, we need to discuss how data files and model files are treated.

TYPES OF FILES

Xgrav manages two types of files: data sets and model descriptions.

Data Files

Data files consist of ASCII files with up to two columns of information, with each row corresponding to a given point. One column is a distance (X) and the other is a gravity value (Y). The default is that the first column is X and the second Y, but this can be reversed if the "Reverse Y and X Columns" button is selected when the file is read in.

Calculated and Continued Anomalies are also stored as data files in the program, but are distinguished from data files (as "anomaly files") for purposes of optimizing density contrasts or offsetting files.

Currently, the program will accept up to 50 data files with a total of 20000 points each (probably much more that you really need!).

The "Current File"

When you read in a data set or calculate an anomaly, the name of the data file will appear in the top panel along with it's position in the stack of files (e.g., 2/3 means the second of three files in memory). The file appearing in the panel is called the "current data set" and will have the characteristics shown in both the top and left panels. File plotting characteristics can be changed by altering the selections while the desired file is current.

A file automatically becomes current when it is created or read in. You can alter which file is current by using the "DATA++" or "DATA--" buttons to move forward or backward in the stack.

Selected Files

Selected files are those files which are plotted or used in various calculations. Those which are not selected remain in memory but are "dormant". Selecting subsets of files allows them to be more easily viewed or plotted and also allows deletion of files to be more rapid.

A file automatically is selected when it is created or read in. You can delselect or reselect a file by using the "SEL DAT" option.

Model Files

Models are ASCII files containing points that define a set of bodies. A body is defined by a density, a half width, and a set of points defining its position. The format of a model file is as follows:

The first line is in integer indicating the number of bodies are in the model.

The next line contains the number of points that describe the first body, along with it's density (in gr/cc) and halfwidth (in km).

This line is followed by (X,Y) ordered pairs giving the location (Distance, Depth) of the points of the polygon that defines the body. Note that the last point should equal the first point! Also, note that the depth cannot be negative. The program will prevent this from occuring. These lines are repeated for the total number of bodies in the model.

As an example, the following lines could be read in as a model file for two rectangular prisms:

 2
 5 0.1 10000.
 0. 0.
 0. 1.
 1. 1. 1. 0.
 0. 0.
 5 0.2 50.
 -1. 1.
 -1. 2.
 2. 2.
 2. 1.
 -1. 1.

There are 2 bodies in this model. The first has 5 points, a density of 0.1 and a halfwidth of 10000. km, while the second has 5 points, a density of 0.2 gr/cc and a halfwidth of 50 km.

The program will allow up to 50 models, each of which can have up to 20 bodies. The total number of points in the model cannot exceed 20000.

Bodies joined together as models have the following characteristics:

  1. They are read in, selected, and deleted together.

  2. Their densities are optimized together.

Bodies within a model may be modified in many ways, as discussed below.

THE BUTTONS ON THE TOP PANEL

In the upper window there are several buttons which, when selected, will pop up a window for user input.

READ
Brings up a window for inputing the names of data and model files to be read in. The file name and directory are typed in the first two input rows, and the file type and column order are selected in the buttons above. The lower four lines allow the user to offset and scale the x and y values in the dataset. Note that this scaling is irreversible so that the dataset needs to be read in again if a mistake is made.

When the information is correct select "OK", or, if you want to quit, select "CANCEL". Up to 50 data sets and 50 models can be stored. Note that once a file is read in it becomes the "Current" data set or model.

After a model or data file is read in, the extremal values of Y (depth or gravity) and X (distance) are shown in the top panel.

DRAW
Draws a picture on the screen, using the selected models and data sets. The program will determine the maximum and minimum values for the plot based on the files used, but these can be changed by typing in new ones. There are several options for setting ticks (the program tries to make an intelligent choice, but this can always be overruled). The Header and X label will be shown at the bottom of the screen, but the Y labels will not (thanks to some problem with X Windows handling vertical text).

DEL DAT
Delete some set of data sets, either only the current data set of all of the selected data sets.

SEL DAT
Select which datasets to plot on the screen (or to delete).

DATA++
Makes the next data set in the list the current data set.

DATA--
Makes the previous data set the current data set.

DEL MOD
Delete some set of models, either only the current model of all of the selected models.

SEL MOD
Select which models to plot on the screen (or to delete).

MOD++
Makes the next model in the list the current model.

MOD--
Makes the previous model the current model.

CALC ANOM
Calculate the gravity anomaly produced by the selected models. After calculation the anomaly is plotted on the screen. If a data file has been read in, the anomaly is calculated at all points at which data exists. The resulting file type is "anomaly". If no data file has been read in, the program computes an anomaly at a regular spacing which the user can modify in a pop-up window prior to the calculation. The resulting file is treated as "data".

OFFSET
Add an offset to the data files so that the means of the data and anomaly files are equal. All selected data sets are used in the calculation.

RESET
Undoes the OFFSET command, and restores the data to its original values.

OPT AMP
Attempts to optimize the density in the selected models to minimize the difference between observed and calculated gravity profiles. Densities in all bodies in the selected models are treated as variables. Currently, a variation limit of +-4 gr/cc is hardwired into the code.

PS-DUMP
Creates a PostScript file that can be sent to the printer

PS-PREF
Select various options for the PostScript file such as the file name and orientation of plot.

WRITE DATA
Output current data file to another ASCII file.

WRITE MODEL
Output current model file to another ASCII file.

NEW MIN/MAX
Resets the minimum and maximum values used in plotting by determining the miniums and maximum values in the selected data sets. This is a useful option if several model modifications have been made.

CONTINUATION
Calulates what the data in the CURRENT data set would look like if viewed at a different elevation by using up/down continuation. When selected, you are asked for an data set name to reference the anomaly, and a continuation distance. This distance is the elevation of the new data set with respect to the current data set, in the distance units of the current data set. For example, suppose the data was collected at one kilometer elevation, and you would like to see what it would look like at 3 kilometers elevation. To do this, enter "2" (i.e., 3-1) into the blank after "Continuation Distance:". Downward continuation can be tried but is not recommended because of numerical problems. This is due to the exponential nature of the continuation filter, the arguement to which depends not only on the distance of continuation but on the spacing of the dataset! Upward continuation is always stable, however.

READ PAL
Read in a pallette to be used in relating colors to shades.

QUIT
Stop the program.

PLOT MODE OPTIONS

In the window on the left side are a number of options that can be set for the overall plot. These are:

Gridding
Draws a grid on major or major and minor ticks or no grid at all. Default is no grid.

x positive right/y postive up
Use these to reverse the directions of the plot.

Show labels
if you have entered labels in the plot, you can select this option to remove them temporarily.

Equal X-Y Scaling/Full Screen
this sets the scaling for the plot. If Full Screen, the entire screen is used, and for Equal X-Y Scaling the units in x and y are scaled equally from the values in the model files.

Font (Several Choices) This is the font to use in the PostScript plot. No effect on the screen.

Annotation Fonsize
This is the size of the font for axes to use in the PostScript plot. No effect on the screen.

# decimals in x/y annotation
This is the number of decimal places in the axis labels. This will also change on the screen.

Header fontsize
This is the size of the font for the header to use in the PostScript plot. No effect on the screen.

CURRENT MODEL OPTIONS

There are several options that can be set for each model file that is read in. Note that the options that appear in this area are for the CURRENT MODEL FILE. To reset the options for any other file you need to use the MOD++ and MOD-- buttons to set the file you wish to be the current file and then change the options for it.

Symbol type
this is the type of symbol used in plotting. In addition to 5 shapes (cross, circle, square, diamond, triangle), you can choose "no symbol" to not have any point or "item number" to plot the point number of the item in the file. "Item number" is a useful option to determine if the order of the points is clockwise or counterclockwise, since this will effect the sign of the anomaly calculated. The default is "no symbol".

Symbol Size
just like it sounds. Affects size of symbol both on screen and paper plot. Default is medium (0.05) size.

Penwidth
the width of the line to draw. Default is thinest line (= 1).

Solid/Dotted/Dot-Dash/Dashed line
The type of line to use. Default is Solid line.

Shade
the shade used to fill in the bodies. Default is No Shading.

Pattern
Bodies in a model may optionally be filled with one of several patterns, but only if No Shading is used. Default is No Pattern.

CURRENT DATA OPTIONS

There are several options that can be set for each data file that is read in. Note that the options that appear in this area are for the CURRENT DATA FILE. To reset the options for any other file you need to use the DAT++ and DAT-- buttons to set the file you wish to be the current file and then change the options for it.

Symbol type
this is the type of symbol used in plotting. In addition to 5 shapes (cross, circle, square, diamond, triangle), you can choose "no symbol" to not have any point or "item number" to plot the point number of the item in the file. The default is "cross". Note that as anomalies are calculated and added to the data file list, the symbol and line style used automatically cycles for ease in identification.

Plotting ID's
This is not used at present, so ignore it.

Connect Points
Select this if you want to draw lines between points in the order they were read in. There is an option "Connect every second point" which is useful for drawing lines. The default is "Connect points".

Symbol Size
just like it sounds. Affects size of symbol both on screen and paper plot. Default is medium (0.05) size.

Penwidth
the width of the line to draw. Default is thinest line (= 1).

Shade
the shade used to fill in the symbols. Default is No Shading.

Solid/Dotted/Dot-Dash/Dashed line
The type of line to use. Default is Solid line.

File Type
Data files are considered to be either "Data" or "Anomalies" for purposes of calculating offsets, optimizing, or calculating anomalies. By default, files that are read in are considered "Data" and those that are calculated are "Anomalies", with the exception of an anomaly calculated when no data file has been read in, in which case it is assigned as "Data". The File Type switch is provided to allow the user to override these defaults.

CANVAS ACTIVITY

There are a variety of functions that can be performed on the Canvas. These are selected using the switch in the middle of the panel on the left side of the window.

Note that there are "Canvas Activity Help Windows" that can be switched on and off using the button on the top panel. These are to help the user remember how to use the different activities.

Note that there are "Canvas Activity Help Windows" that can be switched on and off. These are to help the user remember how to use the different activities.

Locate points on the screen
This allows numbers to appear on the screen showing the location of the cursor in the local coordinate frame. Pressing and holding down either right or left mouse button will cause numbers to appear on the screen below a cursor. Letting go of the button will leave the number stationary on the screen. Hitting the middle key will erase the number from the screen.

Zoom
This allows the user to zoom in on a section of the MODEL. Move cursor on screen to any corner of the desired zoom area, and then press the left mouse button. If you decide not to use this point and want to start over, press the middle mouse button. Otherwise, hold down the left mouse button and a box will appear. When the box covers the desired area, click the right mouse button and the program will zoom to that area.

Zoom-out
This will "un-zoom" to the previous zoom level. Just put the cursor on the canvas and press the left mouse button.

Enter Body
A body can be added by drawing a closed polygon on the screen. This is done as follows:

  1. Select the first point by clicking the left mouse button.

  2. Enter subsequent points by dragging with the left mouse button depressed and then clicking the right mouse button.

  3. Finsh the body by returning to the starting point.

Bodies are considered subsets of models, so upon finishing the body you will be asked if you want to add another body to the model or finish the model. You can add up to 20 bodies to the model.

Delete Body
You can delete a body by moving the cursor to any of the points of the body and clicking the left mouse button. When the body is deleted, it will disappear from the screen.

Move a Body
You can move a body by moving the cursor to any of the points of the body and clicking the left mouse button, and then dragging it to a new location with the left mouse button depressed. When you have reached the new position, click the right mouse button to complete the move. The old body will disappear when this action is completed.

Add a Point
You can add a point to an existing body by first moving the cursor to any of the points of the body and clicking the left mouse button. A new point will be added between this selected point and the next point in the sequence. Drag the left mouse button to where you want the new point located. When you have reached the desired position, click the right mouse button to enter the point. The old boundaries will disappear when this action is completed.

Delete a Point
You can delete a point from an existing body by moving the cursor to the desired point of the body and clicking the left mouse button. The body will be redrawn when this action is completed. Note that at least three points are required to define a body, so deleting a point from a triangle will delete the body.

Move a Point
You can move a point in an existing body by moving the cursor to the desired point of the body and clicking the left mouse button, and then dragging the point to a new postion with the left mouse button depressed. When you have reached the desired position, click the right mouse button to complete the move.

Auto Move Point
If you are trying to explain an observed gravity anomaly, you can get the program to try adjusting the postion of a point automatically. Click the left mouse button over the point in question, and the program will determine a new position for the point which will minimize the misfit in a least squares sense.

Reverse a Body
Anomalies are calculated by evaluating edges of the polygon in sequence. You can reverse the sequence by moving the cursor to the desired point of the body and clicking the left mouse button. If you have drawn the body with the "item number" option, you will see the order of the numbers reverse.

Edit a Body
You can edit (view and/or change) the density and halfwidth of any body by moving the cursor to the desired point of the body and clicking the left mouse button. A pop-up window will appear showing the current values. Simply type in new numbers to change these.

Enter a label
Labels may be entered on the plot by moving the cursor to the place where the label is desired and pushing the left mouse button. This point will be the beginning position of the label. If you want to start over, push the middle mouse button. Otherwise, depress the left mouse button and a rubber line will appear, which you can use to specify the angle of the label. When you are satisfied with the angle, click the right mouse button. At this point a window will appear in which you enter the label. You can also change the value of the angle and the font size if you wish. Note that the label will be written on the screen but not at the proper angle. Don't worry - it will be ok on the plot.

Delete a label
Labels can be deleted by moving the cursor to the endpoint of the label and clicking the left mouse button.

SEE ALSO

Xmag

Xprofile

AUTHOR

Steve Roecker
roecker@harold.geo.rpi.edu

ACKNOWLEDGMENTS

Thanks to the many students in the Applied Geophysics classes who have pointed out bugs and improvements over the years.

BUG REPORTS

Send bug reports to: roecker@harold.geo.rpi.edu


Go to Table of Contents