Gmodel

Interactive 2-D gravity modelling — User Manual

Overview

Gmodel is a desktop application for two-dimensional gravity modelling. It lets you extract a gravity profile from a survey dataset, define a geological model made up of standard geometrical bodies, compute the predicted gravity response using the Talwani (1959) polygon method, and compare it with observed data — all within a single interactive window.

The main operations are:

• Load a gridded or scattered gravity survey file and cut a profile through it by clicking on a map.
• Build a model by adding cylindrical, dike, sill, and polygon bodies with density contrasts, then display the predicted anomaly alongside the observed profile.
• Load physical-feature outlines (faults, coastlines, geological contacts) as map overlays.
• Export the finished plot to a PNG or JPEG file at a chosen resolution.

Interface layout

The window is divided into three zones:

Sidebar buttons that require data to be present (e.g. profile location, edit model, and inversion) are greyed out until the corresponding data or model is loaded into memory.

Toolbar

Physical features

Physical-feature files contain polyline outlines — faults, coastlines, geological contacts — that are overlaid on the data maps in the create profile and profile location panels. They play no role in the gravity calculation.

Loading files

1. Click physical features in the sidebar.
2. Click Add file… and select one or more outline files (.dat, .txt, .xyz, .csv accepted).
3. Repeat to add further files; each appears in the list on the left.
4. To remove a file, select it and click Remove selected.
5. Click Load to parse all listed files and display a preview on the right-hand map. The outlines are immediately available to all map panels.

File format

See Physical features file.

Create profile

This panel lets you extract a gravity profile from a 6-column survey dataset by drawing a line across an interactive map.

Panel layout

The panel is split 60 / 40. The left side contains all the controls; the right side shows the data map (top) and the resulting profile (bottom).

Step 1 — Load the survey file

1. Type a file path in Input 6-column file or click Browse….
2. Accepted formats: .dat, .txt, .xyz, .asc, .csv. Lines beginning with # are treated as comments.
3. The map on the right fills with a colour-coded scatter plot of the station locations.

Step 2 — Choose the gravity column

Select which column of the survey file to use for the profile:

• Bouguer value (default) — column 6 of the file.
• Free Air — column 5.

Step 3 — Define the profile line

1. The radio button defaults to Profile start. Click anywhere on the data map to place the start point (shown as a green circle). The X and Y coordinates are displayed below.
2. The radio button automatically advances to Profile end. Click the map again to place the end point (red square).
3. To reposition either endpoint, select the appropriate radio button and click again on the map.

Step 4 — Calculate the profile

Click Calculate. The profile plot (lower right) shows gravity versus distance. Elevation along the profile is obtained from the same nearest-neighbour interpolation.

Step 5 — Save the profile

Click Save profile data to write a 3-column text file. The file is immediately usable by Read Profile. See Profile data file format.

Profile location

Opens an enlarged version of the data map showing the current profile line and all loaded data. This panel is only available when a profile is in memory.

If no 6-column file is in memory the map is scaled to the profile start / end coordinates. Loading a 6-column file via the Input 6-column file field at the top of the panel rescales the map to the data extent.

The map displays, if available:

• Scatter plot of survey stations coloured by Bouguer anomaly (red–blue colour scale).
• Profile line (black) with green start marker and red end marker.
• Physical-feature outlines (black lines).

Create model

Build a new gravity model by adding geological bodies one at a time. The model is saved in Magra-compatible JSON format.

Panel layout

The panel is split 55 / 45. The left side contains the input form; the right side shows the model summary list.

Background gravity

Enter the regional background level in the Gravity background (mGal) field (default: 0). This constant is added to the computed response of every body in the model.

Adding a body

1. Select the body type using the radio buttons: C Cylinder, D Dike, P Polygon, or S Sill.
2. Fill in the parameter fields (see Body types).
3. Click Add Body. The body appears in the Model summary list on the right and the model is immediately pushed to memory for use in the View panel.

Removing a body

Select a row in the Model summary list and click Remove selected body.

Saving the model

Click Save Model to write the model to a JSON file. See Model JSON file.

Body types

C Cylinder

An infinitely long horizontal cylinder (Bouguer rod).

D Dike

A tabular body of finite width and depth extent, optionally dipping.

P Polygon

An arbitrary closed polygon — the most general body type. The polygon is automatically closed by repeating the first vertex at the end before computing the gravity response.

S Sill

A horizontal sheet of finite thickness that extends to infinity in one direction from a given edge position.

Edit model

Modify an existing model that is already in memory. This panel is only available after a model has been created or loaded.

Workflow

1. Click edit model in the sidebar. The panel opens with the current model pre-loaded. The Model summary list shows all bodies; the first body is selected by default.
2. Click any body in the list. Its type and parameters immediately populate the input fields on the left.
3. Modify any field.
4. Click Update selected body to save the changes. The list entry and the in-memory model update instantly.
5. To add a new body, choose a type, fill in the fields, and click Add body.
6. To remove a body, select it and click Remove selected body.
7. Click Save Model to write the updated model to a JSON file.

Inversion

The inversion panel adjusts body parameters automatically so that the calculated gravity response best matches the observed profile. It is only available when a model is in memory; observed profile data must also be loaded for the inversion to run.

Bodies — parameters to invert

Each non-Background body in the current model is listed as a row with three checkboxes:

Any combination of checkboxes can be selected independently for each body. Bodies whose checkboxes are all unchecked are treated as fixed and their contribution is subtracted from the data before solving.

Regularisation controls

Running the inversion

1. Open inversion in the sidebar. The panel is populated with the current model bodies.
2. Check or uncheck the Density, H-shift, and V-shift boxes for each body as required.
3. Adjust Damping λ and (if using position parameters) Max iterations.
4. Click Run Inversion. The calculation runs immediately and the Results section appears below.
5. Inspect the RMS misfit before and after, and the table of inverted values.
6. If the result is acceptable, click Apply to Model to write the inverted parameters back into the in-memory model. The edit model panel is refreshed automatically.
7. Click View to confirm the improved fit visually.
8. Save the updated model with Save Model in the edit model or create model panel.

Results display

Algorithm

Two code paths are used depending on which parameters are selected:

Density only (linear)

When only density checkboxes are ticked the problem is linear: the gravity response scales exactly with density contrast. The sensitivity matrix G is assembled column by column — each column is the gravity at all stations when the corresponding body has density = 1 g/cm³ — and the system is solved directly:

(GᵀG + λI) ρ = Gᵀ r

where r is the residual (observed minus background minus contributions from fixed bodies). This is equivalent to one Gauss-Newton step and converges exactly in a single pass.

Density and/or position (nonlinear — Gauss-Newton)

When H-shift or V-shift parameters are included the problem is nonlinear because the gravity response is not a linear function of position. The Gauss-Newton iterative method is used:

1. Compute the residual r = observed − calculated for the current parameter values.
2. Build the Jacobian J by central finite differences (step 0.01 km for positions, 0.001 g/cm³ for densities).
3. Solve the damped normal equations for the parameter update Δp:
   (JᵀJ + λI) Δp = Jᵀ r
4. Update parameters: p ← p + Δp.
5. Repeat until convergence (‖Δp‖ < 10⁻⁶) or the maximum number of iterations is reached.

Position parameters represent cumulative shifts from the body's original position in the current model. Density parameters represent absolute values. All body types (Cylinder, Dike, Polygon, Sill) are shifted correctly according to their internal coordinate representation.

View panel

Click View in the toolbar to display the two-subplot figure. At least one of a profile or a model must be in memory.

Upper subplot — Gravity profile

• Observed data (blue circles / line): plotted when a profile file has been loaded.
• Calculated response (red line): plotted when a model is in memory. If no observed data is present, 200 equally spaced stations are used along the profile range.
• Grid lines are drawn at low opacity for readability.
• A legend is shown when both curves are present.

Lower subplot — Model cross-section

Each body in the model is drawn as a filled shape:

• Cylinder — filled circle at the body's centre depth.
• Dike — filled parallelogram respecting thickness and dip.
• Polygon — filled polygon as defined.
• Sill — filled rectangle; the infinite wing is clipped to the plot extent.

The depth axis starts at 0 at the top and increases downward. Tick labels are in kilometres.

Elevation scaling

The Elevation scaling spinbox at the bottom of the View panel (range 0–999, default 0) controls an optional elevation profile overlaid on the gravity graph.

The elevation fill starts at 0 (sea level) regardless of the actual elevation range of the data. The elevation axis label reads Elevation (m).

True scale in model

The True scale in model checkbox (default: unchecked) enforces an equal data scale in the cross-section plot — one kilometre of depth spans the same number of screen pixels as one kilometre of horizontal distance.

Because the plot frame does not change, bodies that extend below the scale-corrected depth range are simply clipped and not shown. The top of the depth axis is always anchored to 0.

The checkbox triggers an immediate re-render.

Save Plot

The Save Plot toolbar button is enabled only while the View panel is on screen. Clicking it opens the Save Plot dialog.

Dialog options

Profile data file format

A plain-text file with three whitespace-separated columns. Lines beginning with # are optional comments.

# ProfileStart: 412.5 6830.2
# ProfileEnd:   487.1 6854.9
# Distance  Elevation  Bouguer
0.00     312.4    -28.4
1.20     298.1    -27.9
2.40     281.6    -27.1
...

The optional header lines (ProfileStart / ProfileEnd) record the map coordinates of the profile endpoints and are written automatically by the Save profile data button in create profile.

Model JSON file format

A JSON array of body objects. The first entry must always be the Background body.

[
  {"shape": "Background", "gra_back": -25.0},
  {"shape": "Cylinder",   "x": 10.0, "y": -3.0,
                         "radius": 1.5, "density": 0.3},
  {"shape": "Dike",       "x_top": 20.0, "y_top": -0.5,
                         "thickness": 0.8, "bottom": -8.0,
                         "dip": 15.0, "density": -0.15},
  {"shape": "Polygon",    "corners": [[5,-1],[8,-1],[8,-4],[5,-4]],
                         "density": 0.2},
  {"shape": "Sill",       "hor_pos": 30.0, "depth": -2.0,
                         "height": 0.4, "right": true,
                         "density": 0.25}
]

Physical features file format

A two-column text file of X / Y map coordinates. Separate polyline segments are delimited by a sentinel line containing 9999.0 9999.0.

# Geological contact
410.2   6820.5
415.8   6828.1
422.0   6835.4
9999.0  9999.0
# Fault zone
430.0   6810.0
435.0   6840.0

Coordinates should be in the same projection and unit (km) as the gravity survey data.

Workflow A — Create a profile and model from scratch

1. Open physical features (optional) and load any outline files you want displayed on the map.
2. Open create profile, load your 6-column survey file, select the gravity column, and click the map to define the profile start and end points.
3. Adjust the How many points and Nearest neighbours values if needed, then click Calculate.
4. Click Save profile data. The saved file can also be reloaded at any time with Read Profile.
5. Open create model and set the background gravity value.
6. Choose a body type, fill in the parameters, and click Add Body. Repeat for each body.
7. Click View in the toolbar to compare the observed and calculated profiles, and inspect the cross-section.
8. Return to create model or use edit model to adjust body parameters.
9. When satisfied, click Save Model in the model panel, then click View and Save Plot to export the figure.

Workflow B — Load and refine an existing model

1. Click Read Profile in the toolbar and open a 3-column profile file.
2. Click Read Model and open a JSON model file.
3. Click View to inspect the initial fit.
4. Click edit model in the sidebar.
5. Select a body in the Model summary list, edit its parameters, and click Update selected body.
6. Click View again to see the updated fit.
7. Repeat steps 4–6 until the fit is acceptable, then save the model and export the plot.

Workflow C — Display a model response without observed data

1. Open create model (or use Read Model) to load or build a model.
2. Click View. Because no profile data is in memory Gmodel uses 200 equally-spaced stations across the model's horizontal extent to compute and display the predicted response.
3. Use the elevation overlay and true-scale controls at the bottom of the View panel if required.
4. Export with Save Plot.

Workflow D — Refine a model using inversion

1. Click Read Profile and load a 3-column profile file.
2. Click Read Model and load a JSON model file, or build a starting model with create model. The starting model should already approximate the observed anomaly — the inversion refines it, it does not construct one from scratch.
3. Click View to assess the initial fit between observed and calculated gravity.
4. Click inversion in the sidebar.
5. For a quick first pass, leave all Density boxes checked and all position boxes unchecked. Use the default λ = 1.
6. Click Run Inversion. Inspect the RMS misfit before and after, and the table of inverted densities.
7. If the fit is acceptable, click Apply to Model. If not, adjust λ and re-run, or enable H-shift or V-shift for bodies whose position may be uncertain.
8. Click View to confirm the improved fit visually.
9. If further refinement is needed, open edit model to make manual adjustments, then return to inversion and run again.
10. When satisfied, save the model and export the plot.

Gravity calculation method

Gmodel uses the Talwani (1959) algorithm for two-dimensional bodies of arbitrary polygonal cross-section. Each body is decomposed into edges, and the gravity contribution of each edge at the observation point is summed. Cylinders and dikes are converted to equivalent polygons before the calculation; sills are treated as rectangles of very large horizontal extent.

The gravitational constant used is:

_GAMMA = 6.67   # for km coordinates, g/cm³ density, mGal output

This value is 6.67 × 10⁻³ SI scaled appropriately for kilometre coordinates so that the output is in milligals.

All stations and body vertices must share the same horizontal coordinate frame, with distances in kilometres and depths in kilometres (positive downwards in the model; converted internally as needed).

Units summary

Troubleshooting

The View button is greyed out

Neither a profile file nor a model is in memory. Load one or the other using the toolbar buttons, or create a profile or model via the sidebar panels.

The profile location and edit model sidebar items are greyed out

Profile location requires a profile in memory (load one with Read Profile or calculate one in create profile). Edit model requires a model in memory.

The calculated gravity response is zero or flat

Check that all body density contrasts are non-zero. A body with density contrast 0 g/cm³ produces no gravity anomaly.

The elevation overlay is not visible

Set Elevation scaling to a value greater than 0 in the View panel controls. A value of 1 is true scale; increase the value for a more pronounced elevation profile.

The map rescales unexpectedly when physical features are loaded

The data map in create profile is always scaled to the extent of the 6-column survey data, not to the outlines. If the outlines extend far outside the data area they will be clipped at the map edge.

The cross-section shows negative depths (above the surface)

This can occur if True scale in model is checked and the profile is very long relative to the maximum body depth. The true scale enlarges the apparent depth range so that the centre of the cross-section stays at mid-depth; the top of the axis is always forced to 0. If bodies appear missing, uncheck True scale in model.

The polygon body produces an unexpected gravity signature

Make sure the vertices are listed in a consistent winding order (all clockwise or all anticlockwise). Mixing orders can cause the Talwani algorithm to produce incorrect results. Do not repeat the first vertex — Gmodel closes the polygon automatically.

The inversion sidebar item is greyed out

A model must be in memory before inversion is available. Load one with Read Model or create one in the create model panel.

The Run Inversion button is disabled

Observed profile data must be loaded (via Read Profile or create profile) before the inversion can run. The panel displays a warning message when data is missing.

The RMS misfit does not improve after inversion

Try reducing the damping parameter λ. With a large λ the regularisation dominates and the inversion makes only small changes to the parameters. Also check that the Density checkbox is ticked for at least one body, and that the starting model is not already a near-perfect fit.

Inverted densities are very large or of unexpected sign

Increase λ. Very small λ (close to 0) can allow unconstrained solutions, especially when two bodies have similar positions and their gravity signatures are nearly identical (correlated columns in the sensitivity matrix). Alternatively, uncheck the Density box for bodies whose density is well-constrained and should not be changed.

Inversion with H-shift or V-shift does not converge

Increase Max iterations. If the solution still oscillates, increase λ to dampen the position updates. Very large shifts (bodies moving by several kilometres per iteration) usually indicate that λ is too small or that the starting model is far from the solution — in that case, adjust the model manually in edit model first.

A body disappears from the cross-section after Apply to Model

A large V-shift may have moved the body above the surface (Δz large and positive) or far below the plotted range. Open edit model, select the affected body, and check its depth parameters. Use True scale in model unchecked to see bodies at any depth.