VPutility UserGuide v1.2

VPutility 1.
2 - User guide
© 2019 Mira Geoscience Limited. All rights reserved.
The information in this document is subject to change without notice and should not be construed as a commitment
by Mira Geoscience Limited. No responsibility will be taken for any errors that may appear in this document. Mira
Geoscience Limited owns the rights to all intellectual property, copyrights and proprietary information with respect to
this product. This includes, but is not limited to, what you view, read, download, or access, including files, images,
and other materials. You are not allowed, by any means, to copy, modify, repost, reproduce, or distribute content
from this document.
Contains information licensed under the Open Government Licence – Canada.
Contact Information
CANADA
Westmount, Quebec Vancouver, British Columbia
#309 – 310 Victoria Avenue #512B - 409 Granville Street
+1 514 489-1890 +1 778 329-0430
Sudbury, Ontario
1039 Regional Rd 24
+1 705 479-0114
AUSTRALIA
Brisbane, QLD Perth, WA
Level 1, 39 Sherwood Rd, Toowong 45 Ventnor Avenue, West Perth
+ 61 7 3720 8321 + 61 8 9429 8838
General information: info@mirageoscience.com

Licence installation issues: licensing@mirageoscience.com
Technical issues: support@mirageoscience.com
CHAPTER 1 Introduction 1
CONTENTS Overview
Scope
Updates from previous version
How to use this guide
2
4
4
5
Getting started 6
CHAPTER 2 Modes 7
Common control file parameters 8
dataType flag 8
Model header 9
Mode 1: Create a layered model 10
Mode 2: Export a model to Geoscience ANALYST 13
Mode 3: Add geometry constraints 15
Mode 4: Constrain geometry of an entire layer 17
Mode 5: Add a layer 18
Mode 6: Create heterogeneous cells 23
Mode 7: Compute weights for heterogeneous cells 26
Mode 8: Rotate an existing model 28
Mode 9: Transfer geometry 30
Mode 10: Remove constraints 32
Information mode 33
CSV export mode 35
CHAPTER 3 File formats 37

Data and Layer 38
VP model file 39
Description of model sections 42
Parameter 42
Geometry 44
Basement 44
Heterogeneous unit block(s) 45
Response 45
CHAPTER 1 Introduction
This chapter provides an introduction and overview of VPutility and
helps you to get started with a project.
Overview 2
Scope 4
Updates from previous version 4

How to use this guide 5
Getting started 6
Overview
VPutility is software to help you to create and modify VP models. The VP model directly links the rock
properties and geologic units to the geophysics. The earth is laterally divided equally into vertical prisms
(VP), which are then sub-divided further to conform with undulating topographic and geologic layers.
VPutility is part of VP Suite—a collection of geophysical modelling and inversion products. The
discretization of the earth (required for all programs in the genre) sets the VP Suite apart from other
available programs. The VP model directly links the rock properties and geologic units to the geophysics.
The earth is laterally divided equally into vertical prisms (VP), which are then sub-divided in depth to
conform with undulating topographic and geologic layers.
Each VP model classifies geology units based on its average physical property, which we call
homogeneous units. These units can be further divided into smaller cells to create heterogeneities within
the unit. Heterogeneous cells may vary yet stay within the user-specified bounds of its geological unit.
This unique structure allows you to explore the geologic possibilities that reproduce the geophysical
data, by performing actions such as:
l Adjusting homogeneous units

l Moving geologic horizons (geometry inversion)
l Solving for heterogeneities (heterogeneous inversion) within a unit or units
l Finding a variable basement under the units of interest
Introduction
|
VPutility 1.2 - User guide 2
The illustration below depicts a simple schematic of VP model prisms as an example with two
homogeneous geologic units:
Every VP model has a VP basement. It is important to note that this may be the interpreted geologic
"basement". This bottom unit is important because it will continue to the absolute bottom of the model
(usually -25 km in elevation). The VP basement stems from the idea that the VP Suite modelling space is
implicitly within the earth (see illustration below). This methodology allows you, for example, to recover
density instead of density contrast.
Illustration of the location of a VP model.
VPutility is run through the command prompt as a standalone executable. Using VPutility requires a
control file.
Introduction
|
Scope
This guide will help you to become proficient in implementing VPutility to maximize the use of the VP Suite
products that model and invert geophysical data.
Updates from previous version

We have added more features to help create and work with VP models in VPutility 1.2. Below is a list of
new features:
l Output model cell-centre locations to a CSV file.

l Trim padding/area of interest option to output to Geoscience ANALYST.
l Added masking distance to "information" mode.
l Minor bug fixes
Introduction
|
How to use this guide
It will be useful for you to be familiar with the following conventions used throughout this guide:
l Italic denotes parameters and variables.

l Monospace font denotes file names and folders.
l Bold and monospace font denotes command line.
l Brackets [•] denote optional parameters (do not include brackets when using the parameter).
Introduction
|
Getting started
VPutility is run through the command prompt as a stand-alone executable.
To run VPutility:
1. In the Start menu, open the command prompt found under Mira Geoscience VP Suite.
2. Run VPutility 1.2 Command Prompt.
3. Change to your working directory and type VPutility followed by the input control file.
Alternatively, if you selected Path Environment Variables during installation, you can:
1. Go to the working directory.
2. Open a PowerShell window:
a. Use the shortcut: Shift+F10.
b. Select Open PowerShell window here in the menu.
3. Type VPutility followed by the input file.
Tip: For an example input file use --help as the input file followed by the mode number (e.g.,
VPutility --help 1). If just --help is given as the input file, the output will remind you of the
available modes.
Note: VPutility does not perform inversion or forward modelling.
Note: .geoh5 files are only compatible with Geoscience ANALYST version 2.60 and later.
|
CHAPTER 2 Modes
This chapter describes elements of VPutility such as control file
parameters and formats, creating models, as well as several example
files.
Common control file parameters 8

dataType flag 8
Model header 9
Mode 1: Create a layered model 10
Mode 2: Export a model to Geoscience ANALYST 13
Mode 3: Add geometry constraints 15
Mode 4: Constrain geometry of an entire layer 17
Mode 5: Add a layer 18
Mode 6: Create heterogeneous cells 23
Mode 7: Compute weights for heterogeneous cells 26
Mode 8: Rotate an existing model 28
Mode 9: Transfer geometry 30
Mode 10: Remove constraints 32

Information mode 33
CSV export mode 35
This section describes the twelve modes available in VPutility. Each mode requires a control file, except
for mode 2: exporting a model to Geoscience ANALYST format (.geoh5), mode 8: rotating an existing
model, the "info" mode, and exporting to a .csv file. The control file format is mode dependent, however,
the first line is the same for all modes (mode and data type flags). Refer to the VP model file format
section when dealing with modes that create and require VP model files.
Common control file parameters

The majority of the control-file based uses of VPutility will require two parameters. For brevity, we define
those inputs here. These two common control-file parameters are:
l dataType flag
l Model header
dataType flag
Every mode's control file contains the dataType flag describing the type of data that are given. You may
use the data type that will be used in the VP Suite forward modelling and inversion products. However,
the output of VPutility is a VP model file for a specific property and therefore changing the data type flag
that is associated with the same physical property will not change the output of the model. The table
below lists the available dataType flags:
Modes
|
This table summarizes the output model type from VPutility given the input data type. Therefore,
changing data types that share a common output model type will not change the output.
Model header
When creating models, a VP model header is sometimes required that will be transferred to the new VP
model ASCII file. Therefore, this header is the same format found in the Parameter Block of the VP model
file. It is described here for clarity due to its use in VPutility control files. The model header for the n th layer
is defined as:
dlayn The physical property of the nth unit.

dminn Lower limit of physical property of the nth unit.
dmaxn Upper limit of physical property of the nth unit.
[Qn, decn, incn] Koenigsberger ratio (positive) or remanent portion in susceptibility
(negative), remanent declination, and remanent inclination for the nth
susceptibility unit. Only present when dataType = -6, -3, -4, -2, 0, 2. Purely
induced susceptibility layers will have Q=0, dec=0, and inc=0.
labeln Label describing nth unit. Use quotes for multiple words (e.g. “My favourite
rock”).
Modes
|
Mode 1: Create a layered model
Mode 1 will create a layered model. A few points about the layers:
l The top of each layer can be defined in a data file or in elevation (m), in the case of a flat layer.
l Layers are interpreted in the order they are presented in the control file. Deeper layers will have
precedence allowing you to create intrusions.
l There is no maximum number of layers that can be used to create a model.
Control file format

Below is the control file for creating a layered model. If a data file is given, #dataflag# must precede it. The
line column (#line# col) is only valid when the data file is given. This option will use the lines to determine
prism widths. Each layer will only be added to a prism once. The layer file and elevation options can be
interchangeable from layer to layer. Layer files denoted by #layerfileprop# must have properties in the
fourth column and will create latereral heterogeneities throughout the model. Each cell will be the
thickness of the unit and contain the interpolated property from the file (not specifically sub-celled in
depth). Give the angle (degrees positive clockwise from North) to create a rotated model.
1 dataType [zero_thick] [angle]

outputFile
#datafile# inputFile OR emin, emax, nmin, nmax
#line# col_num OR de, dn
nlayer
#layerfile# fileName OR #layerfileprop# fileName OR elev AND model_header
[ehsfix [elevback densback]]
dataType Defines the data type that determines the output physical property (see Mode section
introduction).
zero_thick Optional flag to keep any zero-thickness layers or discard them:
zero_thick = 0: Removes any zero thickness layers from the model.
zero_thick = 1: Keeps all zero-thickness layers.
angle Optional angle in degrees clockwise from North. The angle must be preceded by the
zero_thick flag. The VP model will be rotated when created at the angle using this
option.
outputFile File name of the VP model that the program will create.
Modes
|
inputFile Data file that must be preceded by #datafile#. VPutility will find the aerial extremes in
this file and use it to create the model boundaries. If a density or susceptibility model is
being created, it will add a buffer of 4 prisms. See the Data and Layer section for
details.
emin Minimum easting of rectangular model area. It is the coordinate of the external wall of
the most “westerly” boundary prism. It is xcell/2 less than the most “westerly” prism
centre.
emax Maximum easting of rectangular model area. It is the coordinate of the external wall of
the most “easterly” boundary prism. It is xcell/2 greater than the most “easterly” prism
centre.
nmin Minimum northing of rectangular model area. It is the coordinate of the external wall of
the most “southerly” boundary prism. It is ycell/2 less than the most “southerly” prism
centre.
nmax Maximum northing of rectangular model area.It is the coordinate of the external wall of
the most “northerly” boundary prism. It is ycell/2 greater than the most “northerly” prism
centre.
de East-West width of model prisms (m). May be given with a data file. Must be given with
the model region values.
dn North-South width of model prisms (m). May be given with a data file. Must be given
with the model region values.
col_num The column number specifying the lines in the data file inputFile. The lines may be
numeric or contain letters although they should not contain spaces. The lines are used
to compute the prism widths in the easting and northing directions attempting to put
data at the centres of prisms. This option cannot used when emin, emax,
nmin,andnmax are given.
nlayer Number of layers in the model. Must be an integer from 1 to 99. The last layer (nlayer)
is the VP basement (with its base defined at -25km); nlayer = 1 is equivalent to creating
a terrain model or an apparent susceptibility or density model.
fileName Data file containing layer top coordinates preceded by #layerfile# or
#layerfileprop#. The latter will read the fourth column of the file and create lateral
variations in the unit. The file is the data file format and is not required to be on a grid.
The coordinates should be consistent with the model file region.
Elev Elevation (m) top of the flat contact.
model_header Defines the physical property, its bounds (and remanent parameters), and label (see
introduction of Modes section)
ehsfix Optional flag for the enclosing half-space property for inversion (when applicable).
Must be present when defining the enclosing half-space top and property.
ehsfix = 1: enclosing half-space property fixed during inversion.
ehsfix = 0: enclosing half-space property variable (optimized) during inversion.
Modes
|
elevback Optional background elevation (m) for top of uniform half-space enclosing model.
VPutility will use the average of the top of the VP model if not specified. Must be
following ehsfix and preceding densback.
densback Optional Background physical property for uniform half-space enclosing model.
VPutility will use the average of the physical properties within the VP model if not
specified. Must follow the ehsfix and densback parameters.
Example files
The first example is specifically for VPem1D. It takes in a data set in a file along with the line column
number (4) and creates a simple three- layered model file with the layer top defined at the topography.
VPutility computes the VP model region and the widths of the prisms. The enclosing half-space value is
unnecessary for VPem1D, so it is omitted.
The second example file is a susceptibility model file (with TMI data). The enclosing half-space is fixed,
but VPutility will compute its property and top. A data file is given to determine the model region, but the
prism widths are set to 50 m x 50 m. The model will have two layers, both purely induced. The first layer
could be broken up into heterogeneous cells by calling VPutility again and on the output file model (two_
layer.sus) and using mode 6.
Modes
|
Mode 2: Export a model to Geoscience ANALYST
The second mode will output a Geoscience ANALYST project file (.geoh5) from a VP model ASCII file.
This can be done in two ways: via the command line or with a control file format.
The first way is to type on the command line: VPutility inputFile [outputFile] [--trim],
where inputFile is the name of the VP model file. The outputFile is optional and may or may not have the
.geoh5 extension given. The extension will be added regardless. If outputFile is omitted, the file
InputFile.geoh5 is created and any extension of the VP model is removed and replaced. The trim
option: --trim will remove the padding prisms used by VPmg either from the area of interest or the
standard four prisms on the outside of the model. The trim option is not selected by default.
Control file format

The second method is through a control file. Below is its format:
2 dataType [itrim]
inputModel
[outputFile]
dataType Defines the data type that determines the output physical property (see Modes section
introduction).
itrim Optional integer to define whether VPutility should trim the model when writing to the
Geoscience ANALYST project file. Use itrim = 2 to trim and itrim = 1 (or do not include it) to
not trim.
inputModel The VP model to convert to a Geoscience ANALYST project file.
outputFile Optional name of the output file. It may or may not have the .geoh5 extension given. The
extension will be added regardless.
Project file contents

VPutility will create the following items in the project file. They will be found under a Geoscience ANALYST
container with the input file name followed by VP model:
l blockMesh: The VP model is created as a block mesh to view in the 3D Viewport. All nodes are
created to be able to view a true representation of the model. If the model consists of more than 15
million cells, then VPutility groups vertical nodes within one metre and tries again. If the model still
consists of more than 15 million cells, it will not write out a block mesh. The properties written out
are:
Modes
|
o Geologic unit: classification data labelled based on the model header
o Conductivity / Susceptibility / Density: VP model physical property values
o Lower bound: lower limit(s) of the physical properties
o Upper bound: upper limit(s) of the physical properties
o [Heterogeneous weights]: Weights used for heterogeneous inversion (if existing)
l Surfaces: Surfaces are always exported regardless of the size of model. The nodes that define
the surfaces are the centres of the prisms. The surfaces that are exported are:
o [Label] top: The highest top of each unit in each prism labelled with its name from the model
header followed by top.
The top of the VP basement is the label appended with VP basement.
o Topography: The top of the VP model.
o Base of Model: The complete base of the VP model (elmin, usually -25km).
l Data: Output if the data block is present in the VP model file. If the data block includes a LINE
column at the end, the data will be output as a curve. Otherwise, the data is output as points.
o Each channel is output as a property of the data.
o EM data are set to multi-component data based on the time channels and transmitters.
o The line column can be alphanumeric.
l Geologic constraints: Any geologic constraints in the VP model are written as points. The flag
that controls the inversion based on those constraints is output as a property.
l
Note: These points are located at the centre of the prisms that they affect, so when comparing
them to drillhole data they will not necessarily line up horizontally.
Example files
Below are two example control files of exporting starting_model.sus to the Geoscience ANALYST
project start.geoh5. Both files will create the same output file.
Tip: You can achieve the same output file though the command prompt by typing
VPutility starting_model.sus start, which does not require a control file.
Modes
|
Mode 3: Add geometry constraints
Mode 3 adds pierce-point constraints to an already created model. The locations of these constraints
are given in the data file format. A few important notes:
l Constraints flagged as observed contacts (iFlag = 1) are snapped to the VP model. VPutility finds
the closest layer to the given location.
l User-specified constraints (iFlag = 2) will be snapped to the closest layer if one is given within one
metre of the location. VPutility will insert a layer (of the same unit) if the location is further away than
one metre to the closest layer.
The latter point is important as it allows you to add flags within layers that constrain them from moving
higher (or lower) than that layer. Effectively, it allows you to set bounds for geometry inversion. Exercise
caution with complex models to ensure constraint flags are not added in the wrong unit. (You can view
these in Geoscience ANALYST.)
Tip: You will need to create your own locations file if you are using drillhole data with classifications.
Use the pierce-point locations of the top of the modelled units.
Control file format

Below is the control file format to add geometric constraints to your VP model:
introduction).
inputModel VP model to add the constraints to.
inputConstraints 3D locations to constrain the geometry given in the data file format.
outputModel VP model that has the constraints added to inputModel.
iFlag Flag for the inversion interaction:
iFlag = 1: VP Suite products will set the layer fixed and radially influence the surrounding
contacts.
iFlag = 2: VP Suite products will set the layer fixed without influencing surrounding
contacts.
Modes
|
Example file
Below is an example of adding pierce-point constraints based on drillhole data to a gravity gradiometry
problem (density VP model). The constraints will influence the inversion results. Their locations are in
constraints.csv.
Modes
|
Mode 4: Constrain geometry of an entire layer
This option is useful when you want to fix an entire layer during inversion. The output file will add a flag = 2
everywhere the layer is present (so it does not influence the inversion). The mode offers the layer to be
constrained either throughout the model or in a specified rectangular area.
Control file format

Below is the control file format to add user constraint flags (iflag=2) to a layer:
introduction).
outputModel VP model that will be written.
unitIdentifier Either an integer representing the unit number (i.e., 2 for the second unit, top down), or the
name (label) of the unit (i.e., Unit_2)
[regionBounds] Optional rectangular region of interest (model coordinates) consisting of four numbers in
order:
emin: minimum easting (west)
emax: maximum easting (east)
nmin: minimum northing (south)
nmax: maximum northing (north)
Example files
Below are two example files. The left constrains the third layer of the input model everywhere. The right
example constrains a layer named Shale in a rectangular region of interest (model coordinates).
Modes
|
Mode 5: Add a layer
Mode 5 allows you to add a geologic unit to your model. There are a few caveats when adding a layer:
l It will be associated with an existing layer.

l It can be added at the top or in the middle of the existing layer. An overburden mode is also
available.
l The layer will only be added once per prism at the first instance of the existing layer.
l A desired thickness (m) is given in the control file.
l The layer can be added throughout the model or in a specified rectangular area.
l It will be homogeneous (the heterogeneous mode can be subsequently used).
The thickness of the layer is affected by whether or not you want to add the layer to the bottom or in the
middle. A third mode is available to add overburden. The bottom and overburden cases will keep the
thickness the minimum of what was specified or the reference unit thickness. The middle layer case will
set the thickness to the desired thickness or a third of the thickness of the reference unit - whichever is
smaller. This allows you to take care of wedges.
Control file format
introduction).
unitIdentifier Identifier of the reference layer. Either an integer representing the unit number (i.e., 2 for the
second unit, top down), or the name (label) of the unit (i.e., Unit_2).
model_header Defines the physical property, its bounds (and remanent parameters), and label of the
inserted layer (see Modes section introduction).
thickness The thickness (m) of the inserted layer.
Modes
|
mode Integer of how VPutility will insert the layer:
mode = 1: layer is inserted at the top of the reference layer, pushing reference layer down
by the thickness.
mode = 2: layer is inserted in the middle of the reference unit. The reference unit will be split
in two layers, but the model header will be the same.
mode = 3: An overburden layer is added. The reference unit identifier must still be present
(and valid), but it will be ignored. We suggest using 1 for the identifier.
[regionBounds] Optional rectangular region of interest (model coordinates) consisting of four numbers in
order:
emin: minimum easting (west)
emax: maximum easting (east)
nmin: minimum northing (south)
nmax: maximum northing (north)
Example files
Below are three example files: one for each mode. With each, we include
2D cross-sections of the starting and ending model along with the example control file. The starting
model is the same for all examples.
The first example is for the first mode using a density model. The new unit is added on top of the third unit.
The control file will look like this:
Below is the result of this control file. At left is the starting model; at right the resulting model, both coloured
by unit number. The new layer is added prior to the VP basement unit (which is always the last unit in a VP
model file), so in this case the new unit layer becomes 6 and the basement becomes unit 7.
Modes
|
The starting model consists of dipping layers (left).
The inserted dipping layer (red) at the top of unit 3 (green) using the first mode (right).
The second example will insert a layer into the middle of the deepest non-basement layer (orange): unit
5. The thickness will be changed to 45 m. The mode is set to 2.
Below is the result of this control file. The layer is 45 m thick until it is more than one third the thickness of
unit 5 (orange) near the end of the wedge with the VP basement. The layer thickness is set to one-third
the unit thickness until it disappears at the junction of the VP basement and unit 5.
Modes
|
The inserted dipping layer (red) in the middle of unit 5 (orange) using the second mode (right).
The third example adds a single layer of 100 m thick overburden to the model. Although the reference
layer is set to unit 1, VPutility inserts the overburden at the top of the VP model. This is mode 3. The
control file is displayed below. It is important to note that the overburden is from the top of the model, so it
will mimic the topography of the model. In this example, the topography is flat and therefore it is also a flat
layer.
The resulting model (below, right) shows the overburden layer added to the model.
Modes
|
The inserted overburden layer (red) on the top of the VP model using the third mode (right).
Modes
|
Mode 6: Create heterogeneous cells
Layers created with VPutility are homogeneous. However, with mode=6, you can convert those layers to
heterogeneous units through sub-celling. Modes 6 and 7 are closely tied together. It is important to know
that you do not have to call mode 7 if you create heterogeneous cells with mode 6 (it is built in the control
file for you). When you create heterogeneous cells, the following is considered:
l The cells can either be of constant height or expand in depth (VPutility optimizes the latter so
“slivers” of small cells are not created at the end of the unit).
l More than one unit can be designated to be sub-celled including its expansion or height.
l Every instance of the unit(s) will be sub-celled.
l For units that have a thickness of less than 1.5x the desired height, the entire thickness will be
converted to a single cell.
l Weighting is automatically assigned to the cells after creation. The same weighting style will be
assigned to all units being sub-celled.
l A data file is always necessary and used in distance weighting but ignored for depth weighting.
Control file format

The control file format for creating heterogeneous cells is displayed below. See Mode 7: Compute
weights for heterogeneous cells for details on how the weights are computed.
introduction).
dataFile A data file (in data file format) that contains the locations of the data to compute full and
approximate distance weighting. This line is ignored (but must be present) when using depth
weighting.
nUnit Number of homogeneous units to be sub-celled into heterogeneous units.
Modes
|
mode Integer flag to describe the type of weighting computed for the cells.
mode = 1: Depth weighting from top of prism.
mode = 2: Approximate distance weighting.
mode = 3: Full distance weighting.
unitIdentifier Identifier of the homogeneous layer to sub-cell. Either an integer representing the unit number
(i.e., 2 for the second unit, top down), or the name (label) of the unit
(i.e., Unit_2).
dz Nominal height of the ith unit’s cells.
exp_percent Optional expansion percentage of ith unit’s cells. This value can be given or omitted for any unit.
This value is given as a fractional percentage, e.g., 5% expansion = 0.05.
Example file
We use the dipping layer starting model from Mode 5: Add a layer as the starting model. Unit 2 (cyan) will
be sub-celled into approximate 5 m heights (it's possible to set the expansion to 0.0). Unit 5 (orange) will
be sub-celled into 10 m heights and expand at a rate of 3% (at least attempt to be based on the unit
thickness). Depth weighting is computed and set in the output VP model file. The data file will be ignored
in this case yet must be there. We have denoted this by writing “ignored” on the line. The control file will
look like this:
Below are the results of the sub-celling. The initial model is on the right. The final model is on the left with
the sub-cells randomly coloured to make the heterogeneous cells visible. The weighting functions are
displayed in the next section.
Modes
|
Model coloured by geologic unit (left).
Outline of heterogeneous cell created for the green and red units (right).
Modes
|
Mode 7: Compute weights for heterogeneous cells
Weights are important in heterogeneous inversion because they help offset the geometry of the problem
(they are ignored in VPem1D). They attempt to give equal probability to the perturbation of the physical
property in any prism or cell, regardless of its distance from data. If you use VPutility to create the
heterogeneous cells, the weights are computed along with the cell creation; it is not necessary to call
VPutility more than once.
VPutility offers three different types of weights to compute for heterogeneous cells: depth, approximate
distance, and full distance. Weights range from 0.9999 (practically giving the derivatives no affect) to
0.0001 (giving the derivative the most affect). Each weighting computation uses the data type to specify
the power law governing the field decay
(e.g., gravity = 2, magnetics = 3).
Depth weighting computes the weight based on the thickness of the cell compared to the thickness of
the prism and its distance from the top of the prism. It is the simplest and fastest computation and does
not require a data locations file. Depth weighting is sufficient in situations with little topographic relief and
similar vertical cell thicknesses.
Approximate distance weighting computes the distance of the closest data location to the centre of
the cell. The weighting is computed using the data type power and normalized with all other cells. A data
locations file is necessary to find the closest data location.
Full distance weighting computes an approximate sensitivity of the cell to all data locations. The result
is normalized with the other heterogeneous cells to obtain a weight from 0.0001 to 0.90. Due to the
calculation of the sensitivity for all cells and all data locations, this method requires the most time.
However, it may perform best in large topographic relief or scattered data locations. A data locations file
is necessary for this method.
Control file format
Modes
|
introduction).
inputModel VP model to which to compute and add the heterogeneous weights.
dataFile A data file (in data file format) that contains the locations of the data to compute full and
approximate distance weighting. This line is ignored (but must be present) when using depth
weighting.
nUnit Number of heterogeneous units to have weights computed and added.
mode Integer flag to describe the type of weighting computed for the cells.
mode = 1: Depth weighting from top of prism.
mode = 2: Approximate distance weighting.
mode = 3: Full distance weighting.
unitIdentifier Identifier of the heterogeneous unit to compute weights. Either an integer representing the unit
number (i.e., 2 for the second unit, top down), or the name (label) of the unit (i.e., Unit_2).
dz Nominal height of the ith unit’s cells.
Example files
The example file comes from the previous example of heterogeneous cell creation. In this case, the file is
used multiple times, except with a changing of the mode. The main example file for depth weighting is:
The images below show the output of all the weights given a line of data, represented by black dots. It is
important to remember that the top layer and bottom layer may differ due to each unit’s nominal
thickness.
Modes
|
The locations of the heterogeneous cells for reference (top left). Data locations are shown as black dots.
Depth weighting values (top right). Approximate distance weighting (bottom left). Full distance weighting (bottom right).
Mode 8: Rotate an existing model

This mode does not use a control file and is done via command line. The inputs are the model file, the
declination in degrees clockwise from North, and an optional output file name. The file is rotated with
respect to (emin, nmin) of the model (remember, VP uses an ENU coordinate system). Use this feature
on the command line by typing:
VPutility --rotate inputModel dec [outputModel]
inputModel Input VP model to rotate

dec Rotation declination in degrees from north, positive clockwise.
outputModel Optional name of VP model that will be written. If not given, VPutility will name the output
the input model name with _rotated prior to its suffix.
Modes
|
Example
Here, we show the result of rotating an existing VP model 65 degrees. To create the model, VPutility is
called:
VPutility --rotate gravityModel.den 65

The utility creates the file gravityModel_rotated.den.
Plan-view of the input model (green) and the rotated output model (blue). The model was rotated by 65°.
Modes
|
Mode 9: Transfer geometry
This mode allows you to transfer the existing geometries of a model and define a new physical property
type. Any heterogeneous cells will not be kept, however geometric constraints may be included in the
new model. The enclosing half-space may be given as input, or the property will be computed as an
average of the given new properties. This mode can be helpful in the cooperative inversion of multiple
data types by solving for physical properties and geometries of one and then switching to another.
Control file format

9 new_dataType [keep_constraints] inputModel outputModel model_header1 ... model_headernprop
[denback [elevback]]
new_dataType Defines the data type that determines the output physical property (see Mode section
introduction). keep_constraints Optional flag to keep any geometric-constraints or to discard (default)
them when writing to the new model file:
keep_constraints = 0: Removes all constraints found in inputModel

keep_constraints = 1: Keeps all constraints found in inputModel inputModel The VP model to convert to a
new VP model with a new data type. outputFile Name of the new output VP model file. model_headeri
Defines the physical property header for the ith property in the inputModel parameter section. Its bounds
(and remanent parameters, if applicable) and label (see introduction of Modes section) should be
included. The given model headers must also be the same order as in the inputModel file. densback
Optional background physical property for uniform half-space enclosing model. VPutility will use the
average of the physical properties within the VP model if not specified. elevback Optional background
elevation (in metres) for top of uniform half-space enclosing model. VPutility will use the elevation from
the input model if not specified. Must be following densback.
Example file
The example file will come from the output of the Mode 1 layered model created original for VPem1D. A
susceptibility model will be created with susceptible material in the middle layer. The background
susceptibility for the enclosing half-space will be set to zero and the top of the half-space will be the same
as the input model. Although the labels could change, they are kept consistent. The control file will look
like this:
900
vpem1d_sm.con
vpmg_sm.sus
0 0 5 0 0 0 "top layer"
5 0 1000 0 0 0 middle_layer
Modes
|
0 0 1000 0 0 0 basement
0
The model vpmg_sm.sus is then output. The parameter block of the new model contains the same
geometry as the conductivity model, but now has a middle layer with 5 milliSI susceptibility. All other parts
of the model are set to zero susceptibility.
Modes
|
Mode 10: Remove constraints
This mode can remove constraints from the input file writes the output to a new file. The types of
constraints that are removed is dependent upon a flag given in the input control file.
Control file format

10 inputModel outputModel FLAG
inputModel The input VP model file outputFile Name of the new output VP model file FLAG A 3 character
flag describing the type of constraints to remove: GEO: Pierce-point (geometric) HET: Heterogeneous
USR: User-denoted ALL: All constraints
Example file
Below is an example that removes all pierce-point constraints from a VP model. These constraints affect
geometry inversion and are also affected by the radius of influence. The output is written to the new file
model_no_constraints.den.
10
model.den
model_no_constraints.den
GEO
Modes
|
Information mode
The information or "info" mode does not use a control file and is performed through the command line. It
outputs to screen and to the a log file with the input file name and the suffix .info. An optional data file
can be added to the line, which triggers the computation of derivative matrix sizes for inversion. The
matrix sizes will also be computed if there are data at the end of the file. Note that the matrix size is "per
component" so when figuring out multi-component data (i.e. gravity gradiometry), multiply the final
number by the number of components to invert. Memory requirements of less than 0.005 GB will show
up as 0.00 GB. If inversions cannot be performed (i.e. there are no heterogeneous cells), the size of the
matrix output is set to N/A. Any data file will take precedence over the data in the VP model file. Use this
feature on the command line by typing:
VPutility --info inputModel [dataFile]
inputModel Input VP model to retrieve informations

dataFile Optional data file to input (only uses the x, y, z locations). The mode will compute derivative
sizes for a single component given the locations in the data file.
Example
The example will use the example from Mode 6 that creates heterogeneous cells. VPutility is run on
hetDippingLayers.den first without a data file (there is no data in the newly created model). If the
data file is given, it would have the number of locations found in the file, and the approximate required
memory for basement, geometry (not available with the specific model), and heterogeneous inversions.
To get the information of the model, type in the command prompt:
VPutility --info hetDippingLayers.den

The log file hetDippingLayers.info is created. The screen output mimicking the log file is shown
below.
Modes
|
Information for a VP model written to screen using the information mode.
The same information is also written to a log file. No data was given in this example.
Modes
|
CSV export mode
This mode creates a comma delimited file containing the cell centres of each prism. There is no control
file for this mode; it is via the command line only. The command is:
VPutility --csv inputModel [csv_file]
The output file is optional and may or may not have the .csv extension given. The extension will be added
regardless. If csv_file is omitted, the file inputModel.csv is created and any extension of the VP model is
removed and replaced. The output contains the headers: XC, YC, ZC, DZ, model_unit, ID, ID_NAME
where:
XC easting prism centre (m)

YC northing prism centre (m)
ZC cell midpoint elevation (m)
DZ cell thickness (m)
model_unit the units of the model being exported (i.e. g/cc)
ID the numeric ID of the cell's unit
ID_NAME the ID name cell's unit (i.e., Basement)
It should be noted that true cell extents (top/bottom) can be computed by ZC +/- (DZ/2). Zero-thickness
cells are not output.
Example
The example will be the model from Mode 6 (heterogeneous cell creation) and the information mode. To
export the cell centres to a .csv file, type in the command prompt:
VPutility --csv hetDippingLayers.den

The .csv file hetDippingLayers.csv is created. The picture below shows the first few lines of the file.
Modes
|
A screenshot from the first few lines of .csv export showing the locations of the VPmodel cells.
Modes
|
CHAPTER 3 File formats
This chapter provides a comprehensive list of file formats you will be
using when working with VPem1D.
Data and Layer 38

VP model file 39
Description of model sections 42

Parameter 42
Geometry 44
Basement 44
Heterogeneous unit block(s) 45
Response 45
Data and Layer
The Cartesian coordinate system for VPutility is right-handed following an ENU system in metres. All
vertical data is in elevation. The layer and data files follow the same format (and do not need to be evenly
gridded). These files are more comprehensive than they are in other VP Suite programs. Observe the
following:
l Easting, Northing, Elevation must be the first three numbers.

l No need for delimiter to signal comment lines.
l At least three points must be given.
l Data locations to create an areal region (mode=1) do not need an elevation.
l Elevations are required for layer files and data used in distance weighting computations.
The general format is:
Example files
Below are two example files. Each one consists of four locations:
File formats
|
VP model file
The VP model file is the ASCII representation of the VP model. There is no limit (other than computing
resources) to the number of prisms, the number of heterogeneous cells per prism, and the maximum
number of geologic units.
Physical property units are in milliSI (i.e. 10 -3 SI) for susceptibility and g/cc for density. The data units
follow the data file assumptions. The locations are in an ENU Cartesian coordinate system: Easting,
Northing, Elevation in metres.
If only one model file is denoted it is considered active. If a local model is being incised into a regional
model, the local model is considered active.
Rotated VP model files only slightly differ in the header and region lines (xmin, xmax, ymin, ymax). The
cell centres in UTM are still given in the geometry section.
Note: For VPem1D models, rotation is not applied and background data are zero.
The model file is broken up into five sections:
Parameter
Geometry
Basement
Heterogeneous unit block(s)
Response
The heterogeneous unit section has its own blocks corresponding to each heterogeneous unit. If a VP
model only has VP basement prisms (e.g., apparent density or terrain model) specifically, the VP model
breaks down into this general format:
File formats
|
Parameter modelHeader
modelTitle
xmin xmax ymin max OR [x0 xlength y0 ylength angle]
[#polyfile# file]
xcell ycell
nlay [het {uindex(j),dzsc(j),j=1,nhet}]
dlay1 dmin1 dmax1 label1
dlay1 dmin1 dmax1 label1
...
dlaynlay dminnlay dmaxlay labellay
elevback densback ehsfix
ibackg minel imask dismask [elmin]
Geometry east1 north1 elev1 nlay1 elev(1)1 flag(1)1 ....elev(nlay1 -1)1 flag(nlay1 -1)1
east2 north2 elev2 nlay2 elev(1)2 flag(1)2 ....elev(nlay2 -1)2 flag(nlay1 -1)1
...
eastn northn elevn nlayn elev(1)n flag(1)n ....elev(nlayn -1)n flag(nlayn -1)n
Basement Basement title

east1 north1 elev1 propertyb1
east2 north2 elev2 propertyb2
...
eastn northn elevn propertybn
Heterogeneou Heterogn nhetu nhetc ihu1

s unit block(s)
east1 north1 ni1 {ihu(j) 1 zt(j) 1 zb(j) 1 nsc(j) 1 j=1,nheti1}{[phet(k) 1 pflag(k) 1 k=1,nsc(j) 1],j=1,ni1}
...
eastn northn nin {ihu(j) n zt(j) n zb(j) n nsc(j) n j=1,nhetin}{[phet(k) n pflag(k) n k=1,nsc(j) n],j=1,nin}
Heterogn nhetu nhetc ihunhet
...
eastn northn nin {ihu(j) n zt(j) n zb(j) n nsc(j) n j=1,nhetin}{[phet(k) n pflag(k) n k=1,nsc(j) n],j=1,nin}
File formats
|
Response ResponseTitle
eastd1 northd1 elevd1 obs1 1-nch pre1 1-nch [Bx1 ,By1 ,Bz1 ] back1 1-nch [line1 ]
eastd2 northd2 elevd2 obs2 1-nch pre2 1-nch [Bx2 ,By2 ,Bz2 ] back2 1-nch [line2 ]
...
eastdn northdn elevdn obsn 1-nch pren 1-nch [Bxn ,Byn ,Bzn ] backn 1-nch [linen ]
[DC_SHIFT dc]
File formats
|
Description of model sections
Parameter
modelHeader Identifier of VP model. Acceptable identifiers for VPmg are: #MOD_3D#, #VPMG3D#, and
#VPMG3DROT# or #MOD_3DROT#. Use #VPMG3DROT# or #MOD_3DROT# for rotated models.
Acceptable identifiers for VPem1D are: #VPEM1D# or #MOD_3D#.
modelTitle Title of file contents
xmin Minimum easting of rectangular model area. It is the coordinate of the external wall of the
most “westerly” boundary prism. It is xcell/2 less than the most “westerly” prism centre.
xmax Maximum easting of rectangular model area. It is the coordinate of the external wall of the
most “easterly” boundary prism. It is xcell/2 greater than the most “easterly” prism centre.
ymin Minimum northing of rectangular model area. It is the coordinate of the external wall of the
most “southerly” boundary prism. It is ycell/2 less than the most “southerly” prism centre.
ymax Maximum northing of rectangular model area.It is the coordinate of the external wall of the
most “northerly” boundary prism. It is ycell/2 greater than the most “northerly” prism centre.
x0 Origin of x (or easting in UTM) of rotation
y0 Origin of y (or northing in UTM) of rotation
xlength Length (positive number in metres) of the "x" (east/west for 0 degree rotation) side of the
VP model.
ylength Length (positive number in metres) of the "y" (south/north for 0 degree rotation) side of the
VP model.
angle Rotation angle in degrees. Positive clockwise from North. Non-rotated models can be
considered rotated at 0 degrees.
#polyfile# file An optional flag and file defining the region of interest or holes for active prisms in the
model. The flag may be #POLYFILE# or #polyfile#.
xcell Width of model prisms in x (E-W for non-rotated model) direction (m).
ycell Width of model prisms in y (N-S for non-rotated model) direction (m).
nlay Total number of geological units, including VP basement, in model. nlay=1 for basement-
only models, e.g., terrain models (next section would be the basement section). If nlay < 0,
some of the geological units are heterogeneous.
nhet Number of heterogeneous units; required only when nlay < 0.
uindex(j) Unit index for the jth heterogeneous unit; required only when nlay < 0.
dzsc(j) Notional sub-cell dimension (m) for the jth heterogeneous unit.
dlayn Physical property of nth unit. The property must be within the given bounds unless it is
considered fixed for inversion.
File formats
|
dminn Lower limit of physical property in inversion nth unit. If dminn=dmaxn, the property of the nth
layer is fixed: it plays no part in inversion.
dmaxn Upper limit of physical property in inversion for nth unit. If dminn=dmaxn, the property of the
nth layer is fixed: it plays no part in inversion.
Qn Koenigsberger Ratio for nth unit (if positive or 0) or effective susceptibility (10-3 SI) if
negative. Omit value for density models.
decn Declination of magnetic remanence (clockwise angle from grid north) of unit n (degrees).
Omit value for density models.
dincn Inclination of magnetic remanence (negative angle in southern hemisphere) of unit n
(degrees). Omit value for density models.
labeln Description of geological nth unit. Must be in quotes if more than one word with spaces.
elevback Background elevation (m) for top of uniform half-space enclosing model. Read from
regional VP model file when incising a local model.
densback Background physical property for uniform half-space enclosing model. Read from regional
VP model file when incising a local model.
ehsfix ehsfix = 1: enclosing half-space property fixed during inversion.
ehsfix = 0: enclosing half-space property variable (optimized) during inversion. Read from
regional VP model file when incising a local model.
ibackg Background response calculation flag. Read from regional VP model file when incising a
local model. Simple checks are done to ensure that the data are at the same locations and
the model has not changed (due to surface data locations). If those checks are violated, the
ibackg is over-written to 0 and the responses are computed during the first iteration.
ibackg = 0: background model responses (regional and enclosing half space) must be
(re)calculated during the first iteration.
ibackg = 1: background responses read from the data section of the active model file. The
active model file in this case would normally be an output file generated during an earlier
run of VPmg.
ibackg = 2: active model responses (for the starting model) as well as the fixed background
responses are read from the data section of the active model file. This is the default ibackg
for VPmg after a run.
minel Controls the base elevation of the model, below which a uniform half space is assumed.
Read from regional VP model file when incising a local model.
minel = 0: Set to -25000 m
minel = 1: Set to 0 m
minel = -1: Set to elmin (see below; end of line)
File formats
|
imask Flag controlling the radius of influence (i.e. footprint) of derivative. Prisms within a
horizontal radius of a datum are active in the inversion. Read from the active model.
imask = 0: Default footprint value. This value is translated to metres and output in the log
file.
imask = 1: Same as imask=0 (backwards compatibility from previous versions) imask = 2:
Footprint size (m) defined in distmask
distmask Radius of influence (m) for derivative calculations. Ignored if imask is not 2. Read from
active model.
elmin Defines the basal elevation (m) of model prisms, below which a uniform half space is
assumed. elmin is read from the active model only when minel = -1.
Geometry
eastn Easting coordinate of centre of nth prism.
northn Northing coordinate of centre of nth prism.
elevn Surface elevation of top of nth prism.
nlayn Number of cells or interfaces in nth prism.
elev(j)n Elevation of interface at base of cell j within vertical prism n.
flag(j)n Flag controlling whether the interface at elev(j)n is fixed or free during inversion and defines the
geological unit immediately above. Interfacial flags are floating point numbers (not integers) for
the model. The flag takes the form (assuming < 100 layers):
Where: IFLAG(j,n) denotes the integer interfacial flag, and where INDD(j-1,n) is the index for the
geological unit assigned to the cell immediately above the interface. (Note that interface j is at the
base of the (j-1)th cell.) Only one fixed interface flag affects inversion parameter weighting. In
practice, VPmg only checks if flag = 0, 1, or other. The remaining flags are for the user’s benefit.
iflag(j)n = 0 : free interface

iflag(j)n = 1 : fixed interface that affects parameter weighting during geometry inversion
iflag(j)n = 2 : fixed interface given by user
iflag(j)n = -1 : fixed “artificial” interface. Imposed owing to a near-miss by drillhole(s)
iflag(j)n = -2 : fixed “artificial” interface. Imposed by user
iflag(j)n = -3 : fixed “artificial” interface between sub-cells in a heterogeneous unit
Basement
Basement Basement density/susc section title. Must begin with the word Basement, starting in first column.
title If the remaining part of the section is not present, a uniform basement is set based on the
parameter section (typically set to “Basement property uniform”).
File formats
|
eastbn Easting coordinate of centre of nth prism.
northbn Northing coordinate of centre of nth prism.
elevbn Elevation of top of basement of nth prism.
propertybn Physical property of nth prism’s basement.
Heterogeneous unit block(s)

Heterogn Title for Heterogeneous Unit block. Must begin with the word Heterogn, starting in first column.
nhetu Number of heterogeneous units defined in this block; always set to 1: nhetu=1.
nhetc Number of sub-cells in the heterogeneous unit block #ihu.
ihu Geologic unit number (positive) for the heterogeneous unit defined in this block.
eastbn Easting coordinate of centre of nth prism. Only prisms which contain cells belonging to one or
more heterogeneous units are listed in this section of the model file.
northn Northing coordinate of centre of nth prism. Only prisms which contain cells belonging to one or
more heterogeneous units are listed in this section of the model file.
nhetin Number of intervals of heterogeneous units within nth prism. Note: There can be more than one
interval of a particular heterogeneous unit.
ihu(j)n Unit index identifying the jth interval of a heterogeneous unit within nth prism; j increases
downwards.
zt(j)n Elevation of top of the jth interval of a heterogeneous unit in the nth prism.
zb(j)n Elevation of bottom of the jth interval of a heterogeneous unit in the nth prism.
nsc(j)n Number of cells which comprise the jth interval of a heterogeneous unit in the nth prism. Each cell
has vertical dimension [zt(j)n - zb(j)n] / n.
phet(k)j Physical property of the kth cell within the jth interval of a heterogeneous unit in the nth prism.
Index k ranges from 1 to nsc(j)n.
pflag(k)j Inversion flag of the kth cell within the jth interval of a heterogeneous unit [index ihu(j)] in nth
prism. pflag is of the form ipf.nnnn, where ipf is an integer flag and where nnnn is a weight,
defined to 4 decimal places.
ipf = 0: the cell property is free to change during heterogeneous property inversion (when ILD = -
1)
ipf = non-zero: the cell property is fixed.
The decimal part nnnn of pflag is a weight that offsets the decay of the derivatives. The weight
ranges from 0.0000 to 0.9999. The weight is inversely proportional to the derivative influence.
Weights of 0.9999 will virtually zero the derivative. Maximum values around 0.9000 are ideal.
Response
responseTitle Title for Responses block. Must begin with the word EAST.
File formats
|
eastdn Easting of nth measurement location.
northdn Northing of nth measurement location.
elevdn Elevation of nth measurement location.
obsn[1-nch] Observed data channel at nth measurement location. Multi-channel data (i.e. gravity
gradiometry) are written in order
calcn[1-nch] Calculated data channel at nth measurement location. Ultimately, it is the combination of model
response, background contribution, and DC shift.
Bxn,Byn,Bzn Calculated magnetic components at nth measurement location. Used for subsequent runs of
VPmg if preloading checks are successful (i.e., iback=2). Only present in susceptibility models.
backn Background response for the nth measurement location.
linen Optional alphanumeric line number, if XYZ observed data given (with "Line" or "Tie") or a line
column was denoted in the parameter file.
DC_SHIFTdc The DC shift is optional but must follow the header DC_SHIFT when given. The value dc is the
DC shift added to the combination of background and computed model responses. This flag and
value can be included in the model file even if the response block is not given.
File formats
|

VPutility UserGuide v1.2

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

VPutility UserGuide v1.2

Uploaded by

Copyright:

Available Formats

VPutility 1.

General information: info@mirageoscience.com

CHAPTER 3 File formats 37

Updates from previous version 4

l Adjusting homogeneous units

Illustration of the location of a VP model.

Updates from previous version

l Output model cell-centre locations to a CSV file.

l Italic denotes parameters and variables.

Note: VPutility does not perform inversion or forward modelling.

Common control file parameters 8

Mode 10: Remove constraints 32

Common control file parameters

dlayn The physical property of the nth unit.

Control file format

1 dataType [zero_thick] [angle]

Control file format

Project file contents

Control file format

Control file format

l It will be associated with an existing layer.

Control file format

Control file format

Control file format

Mode 8: Rotate an existing model

VPutility --rotate inputModel dec [outputModel]

inputModel Input VP model to rotate

VPutility --rotate gravityModel.den 65

Control file format

keep_constraints = 0: Removes all constraints found in inputModel

Control file format

VPutility --info inputModel [dataFile]

inputModel Input VP model to retrieve informations

VPutility --info hetDippingLayers.den

VPutility --csv inputModel [csv_file]

XC easting prism centre (m)

VPutility --csv hetDippingLayers.den

Data and Layer 38

Description of model sections 42

l Easting, Northing, Elevation must be the first three numbers.

The general format is:

The model file is broken up into five sections:

xmin xmax ymin max OR [x0 xlength y0 ylength angle]

nlay [het {uindex(j),dzsc(j),j=1,nhet}]

dlay1 dmin1 dmax1 label1

dlay1 dmin1 dmax1 label1

dlaynlay dminnlay dmaxlay labellay

elevback densback ehsfix

ibackg minel imask dismask [elmin]

Basement Basement title

Heterogeneou Heterogn nhetu nhetc ihu1

Heterogn nhetu nhetc ihunhet

iflag(j)n = 0 : free interface

Heterogeneous unit block(s)

You might also like