MAG3D manual: 
Running the programs

3.1 Introduction

In a MS-WindowsXX operating environment codes are best run using the Graphical User Interface (GUI). See the separate GUI instructions.

However, all programs in the package also can be run by typing the program name followed by command line arguments. With such a format, they can be executed directly on the command line or in a shell script. When a program is executed without any arguments, it will print a simple message describing the usage. The command format is described below.

Command format:
PROGRAM arg_1 arg_2 arg_3 ...

PROGRAM = name of the executable program. If the program is not in the current directory, its path must be included also.
arg_n = a command line argument which is the name of a file. It is usually one of those described in the preceding section or a control file containing input parameters.

3.2 MAGFOR3D

This program performs forward modelling. Command line usage:

magfor3d mesh obs.loc model.sus [topo.dat]

Input files :
All files are in ASCII text format - they can be read with any text editor. Input files can have any name the user specifies. Details are in the "Elements" chapter.
mesh = the 3D mesh
obs.loc = the inducing field parameters, anomaly type and observation locations.
model.sus = the susceptibility model.
topo.dat = surface topography (optional). If omitted, the surface will be treated as being flat.

Output file:
This file is created by MAGFOR3D - it's name can NOT be specified. Details are in the "Elements" chapter.
magfor3d.mag = the computed magnetic anomaly data. Since the data in this file are accurate, the column of the standard deviations for the error is not included.

3.3 MAGSEN3D

This program performs the sensitivity and depth weighting function calculations. Command line usage:

magsen3d magsen3d.inp

For a sample input file type: magsen3d —inp .

Format of the control file magsen3d.inp

Input files and parameters:

mesh	|	3D mesh
obs.mag	|	data file . Contains the inducingfield parameters, anomaly type, observation locations, and the observed magnetic anomalies with estimated standard deviation.
topo.dat	|	surface topography (optional). If null is entered, the surface will be treated as being flat.
iwt	|	an integer identifying the type of generalized depth weighting to use in the inversion. =1 for depth weighting (only for surface data); =2 for distance weighting (surface and/or borehole).
beta, znot	|	parameters defining the depth weighting function. When iwt=1, beta and znot are used as and z0 to define the depth weighting according to eq.(13) (background). When iwt=2, beta and znot are used as and z0 to define the distanc e weighting according to eq.(14) (background). If null is entered on this line (line 5), then the program sets beta=3 and calculates the value of znot based upon the mesh and data location. This is true for iwt=1 or 2. For most inversions, however, setting this input line to "null" is recommended . The option for inputing beta and znot is provided for experienced users who would like to investigate the effect of the generalized depth weighting for special purposes. The value of beta should normally be close to 3.0. (Note this is different than the value used by GRAV3D) Smaller values of give rise to weaker weighting.
wvlet	|	a five-character string identifying the type of wavelet used to compress the sensitivity matrix. The types of wavelets available are Daubechies wavelet with 1 to 6 vanishing moments (daub1, daub2, and so on) and Symmlets with 4 to 6 vanishing moments (symm4, symm5, symm6). Note that daub1 is the Haar wavelet and daub2 is the Daubechies-4 wavelet. The Daubechies-4 wavelet should be used for most inversions, while the others are provided for users' experimentation. If null is entered, no compression is performed and the program generates a dense matrix in its original form.
itol, eps	|	an integer and a real number that specify how the wavelet threshold level is to be determined. itol=1: program calculates the relative threshold and eps is the relative reconstruction error of the sensitivity. A reconstruction error of 0.05 is usually adequate. itol=2: the user define the threshold level and eps is the relative threshold to be used. If null is entered on this line, a default relative reconstruction error of 0.05 is used and the relative threshold level is calculated (i.e., itol=1, eps=0.05). The detailed explanation of threshold level and reconstruction error can be found in the Background (section 1.5) of this manual.

Example of magsen3d.inp control file

Two output files:
1) maginv3d.mtx is the sensitivity matrix file to be used in the inversion. This file contains the sensitivity matrix, generalized depth weighting function, mesh, and discretized surface topography. It is produced by the program and it's name is not adjustable. It is very large and may be deleted once the work is completed.

2) A file sensitivity.txt is output after running magsen3d.exe. It contains the average sensitivity for each cell. This file can be used for depth of investigation analysis or for use in designing special model objective function weighting. (Added for mag3d version 4.0)

3.4 MAGINV3D

This program performs 3D magnetic inversion. Command line usage is:

maginv3d maginv3d.inp

For a sample input file type: maginv3d —inp. Format of the control file maginv3d.inp is as follows:

Control parameters:

irest	|	restarting flag: =0: start inversion from scratch. =1: restart inversion after it is interrupted. Restart requires two file written out by MAGINV3D before the interruption: maginv3d.aux and maginv3d.kap (see below).
mode	|	an integer specifying one of three choices for determining the tradeoff parameter (see Figure 4 of background). mode=1: the program chooses the tradeoff parameter by carrying out a line search so that the target value of data misfit is achieved. mode=2: the user inputs the tradeoff parameter. mode=3: the program calculates the tradeoff parameter by applying the GCV analysis to the inversion without positivity.
par, tolc	|	two real numbers that are used differently. Their use depends upon the value of mode. mode=1: the target misfit value is given by the product of par and the number of data N, i.e.,. The second parameter, tolc, is the misfit tolerance. The target misfit is considered to be achieved when the relative difference between the true and target misifts is less than tolc. Normally, the value of par should be 1.0 if the correct standard deviation of error is assigned to each datum. When 0.0 is entered for tolc, the program assumes a default value of tolc=0.02. mode=2: par is the user-input value of tradeoff parameter. In this case, tolc is not used by the program. mode=3: none of the two input values are used by the program. However, this line of input still needs to be there. NOTE: When mode=1 both par and tolc are used. When mode=2 only par is used. When mode=3, neither par nor tolc are used. However, the third line should always have two values.
s	|	coefficient for the smallest model component.
e	|	coefficient for the derivative in the easting direction.
n	|	coefficient for the derivative in the northing direction.
v	|	coefficient for the derivative in the vertical direction. If null is entered on the eighth line, then the above four parameters take the following default values: alphas=0.0001, alphae=alphan=alphav=1.0 . None of the alpha's can be negative and they cannot be all equal to 0 at the same time.
idisk	|	parameter which determines how the sensitivity matrix will be accessed. =0: sensitivity matrix will be stored in memory. If there is not enough memory, idisk will be set to 1 automatically. =1: sensitivity matrix will be accessed from disk when needed. UPDATES FOR Ver4.0 IN THE APPENDIX.

Input files:
Input files can be any file name. If there are spaces in the path or file name, you MUST use quotes ("") around the entire path+filename.

Output files:
Output files are created by the programs. They have fixed file names.

Example of maginv3d.inp control file:
The inversion is started from scratch with a zero reference model. The inversion will try to converge to a target misfit equal to the number of data. The sensitivity matrix will be stored in memory.

Log file explanation

(This explanation comes from the GRAV3D manual - the MAG3D log file is basically identical.) The log file maginv3d.log contains more detailed information about the convergence of the inversion. Depending on how the inversion is set up by the users, the content of the log file is slightly different. In general, there are two stages. In the first stage, the program estimates an approximate regularization parameter. In the second stage, the program performs the inversion with bound constraints using a logarithmic barrier method of minimization, which consists of outer iterations with the barrier parameter and inner iterations of conjugate gradient solution of an linear system within each barrier iteration. The log file information is organized according to these two levels of iterations.

We can refer to the flow chart Figure 3 in the Background chapter to understand the output in the log file. Below we briefly describe the content of the log file according to the parameter mode chosen for the inversion.

Mode 1:

In this mode, a user-defined target misfit is supplied by specifying chifact. The first stage of inversion performs a line search without the bound constraints to estimate an approximate value of the regularization parameter and the slope of the misfit curve. The log file identifies this segment and lists summaries of each linear solution such as the number of conjugate gradient (CG) iterations, data misfit, and model norm. The second stage of inversion carries out a number of logarithmic barrier solutions. Each solution corresponding to a single regularization parameter is obtained by a sequence of barrier iterations, and nested inside each barrier iteration is a set of CG iterations. This portion of the log file begins with the value of regularization parameter, initial values of data misfit and model norm. It is then organized in segments corresponding to barrier iterations and lists the number of CG iterations, data misfit, model norm, barrier parameter, and the value of the barrier function at the conclusion of that iteration. As barrier iterations progress, the data misfit, barrier parameter, and barrier function should decrease monotonically. The model objective function may increase or decrease depending on the nature of the initial model of the logarithmic barrier minimization. However, both data misfit and model objective function should plateau at the end.

One or more solutions may be obtained to complete the line search and to achieve the target misfit. Each solution will have a distinct portion in the log file. The trial values of the regularization are dynamically predicted during the inversion and they are not necessarily in any order. Upon completion of line search and the inversion, the log file will list a summary of the data misfit and model norm corresponding to different values of the regularization parameter sorted in increasing order.

Mode 2:

In this mode, the user specifies a value of regularization parameter and the program performs a single logarithmic barrier minimization to obtained the solution. The log file mainly consists of the information for one logarithmic solution as described in Mode 1.

Mode 3:

In this mode, the program first performs a GCV estimate of data noise to obtain an approximate value of the regularization parameter, and it then carries out a single logarithmic barrier minimization to obtain the inverse solution. During the first stage, a number of trial values of the regularization parameter is tested, and two linear systems are solved for each value. Thus the first part of the log file is organized according to the value of regularization parameter. For
each value, the numbers of CG iterations, data misfit, model norm, and GCV value are listed. At the end of GCV search, the log file lists the data misfit, model norm, GCV value according to the regularization parameter sorted in increasing order. The regularization parameter corresponding to the lowest GCV value is used to obtain the final solution in the second stage. The second part of the log file corresponds to a single logarithmic barrier minimization and it is identical to that when mode 2 is chosen.

3.5 MAGPRE3D

This utility multiplies a model by the sensitivity matrix in maginv3d.mtx to produce the predicted data. This program is included so that users who are not familiar with the wavelet transform and the structure of maginv3d.mtx can utilize the available sensitivity matrix to carry out model studies.

Command line usage:
magpre3d maginv3d.mtx obs.loc model.sus

Input files:
maginv3d.mtx = the sensitivityfile from MAGSEN3D.
obs.loc = the inducing field parameters, anomaly type and observation locations.
model.sus = the susceptibility model.

Output file:
magpre3d.mag = predicted data.