4.2.4. MAGINV3D

This program actually performs the 3D inversion of magnetic data. Command line usage is:

maginv3d maginv3d.inp [nThreads]

For a sample input file type:

maginv3d -inp

The argument specifying the number of CPU threads used in the OpenMP format is optional. If this argument is not given to the program, chooses to use all of the CPU threads on the machine. This argument allows the user to specify half, for example, of the threads so that the program does not take all available RAM. Note that this option is not available in the MPI-based code used for clusters.

4.2.4.1. 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 (including the filename). Files that may be used by the inversion are:

  1. obs.mag: Mandatory observations file.
  2. maginv3d.mtx: Mandatory sensitivity matrix from MAGSEN3D
  3. initial.sus: Optional initial model file. This can be substituted by a value within the input file (see below).
  4. ref.sus: Optional reference model file. This can be substituted by a value within the input file (see below).
  5. active.txt: Optional ref:active model file <activeFile>
  6. upperBound.sus: Optional upper bounds model file. A value can be used to set a global bound (see below).
  7. lowerBound.sus: Optional lower bounds model file. A value can be used to set a global bound (see below).
  8. weights.wt: Optional weighting file.
  9. maginv3d.inp: The control file containing the options. Does not need to be specifically called “maginv3d.inp”.

Format of the control file has been changed since previous version. Any numeric entries beyond the trade-off parameter, and tolerance should be preceded by VALUE. The input files has been modified as follows:

../../_images/maginv3d.png

The parameters within the control file are:

  • mode: An integer specifying one of two choices for determining the trade-off parameter.

    1. mode=1: the program chooses the trade off parameter by carrying out a line search so that the target value of data misfit is achieved (e.g., \(\phi_d^*=N\)).
    2. mode=2: the user inputs the trade off parameter.

  • par, tolc Two real numbers that are depe.sust upon the value of mode.

    1. mode=1: the target misfit value is given by the product of par and the number of data \(N\) , i.e., par=1 is equivalent to \(\phi_d^*=N\) and par=0.5 is equivalent to \(\phi_d^*=N/2\) . The second parameter, tolc, is the misfit tolerance in fractional percentage. The target misfit is considered to be achieved when the relative difference between the true and target misfits is less than tolc. Normally, par=1 is ideal if the true standard deviation of error is assigned to each datum. When tolc=0, the program assumes a default value of tolc=0.02 since this number must be positive.
    2. mode=2: par is the user-input value of trade off parameter. In this case, tolc is not used by the program.
    NOTE: When both par and tolc are used. When only par is used. When mode=3, neither nor tolc are used. However, the third line should always have two values.

  • obs: Input data file. The file must specify the standard deviations of the error. By definition these values are greater than zero.

  • matrixFile: The binary file of sensitivities created by MAGSEN3D.

  • initial: The initial susceptibility model (SI) can be defined as a value for uniform models (e.g. VALUE 0.001), or by a filename. The initial model must be within the upper and lower bounds.

  • ref: The reference susceptibility model (SI) can be defined as a value for uniform models (e.g. VALUE 0), or by a filename (for non-uniform reference models).

  • active: The active model file defining which cells in the model are allowed to be solved.

  • lowerBound: The lower bounds model (SI) can be defined as a value for uniform models (e.g., VALUE -1) or by a filename.

  • upperBound: The upper bounds model (SI) can be defined as a value for uniform models (e.g., VALUE 1) or by a filename.

  • \(\alpha_s, \alpha_x, \alpha_y, \alpha_z\): Coefficients for the each model component. \(\alpha_s\) is the smallest model component. Coefficient for the derivative in the easting direction. \(\alpha_y\) is the coefficient for the derivative in the northing direction. The coefficient \(\alpha_z\) is for the derivative in the vertical direction.

    If null is entered on this line, then the above four parameters take the following default values: \(\alpha_s = 0.0001, \alpha_x = \alpha_y = \alpha_z = 1\). All alphas must be positive and they cannot be all equal to zero at the same time.

    NOTE: The four coefficients in line 9 of the control file may be substituted for three corresponding length scales \(L_x, L_y\) and \(L_z\) and are in units of metres. To understand the meaning of the length scales, consider the ratios \(\alpha_x/\alpha_s\), \(\alpha_y/\alpha_s\) and \(\alpha_z/\alpha_s\). They generally define smoothness of the recovered model in each direction. Larger ratios result in smoother models, smaller ratios result in blockier models. The conversion from \(\alpha\)’s to length scales can be done by:

    \[L_x = \sqrt{\frac{\alpha_x}{\alpha_s}} ; ~L_y = \sqrt{\frac{\alpha_y}{\alpha_s}} ; ~L_z = \sqrt{\frac{\alpha_z}{\alpha_s}}\]

    When user-defined, it is preferable to have length scales exceed the corresponding cell dimensions. Typically having length scales of four cell widths are a good starting point.

  • SMOOTH_MOD: This option was not available in previous versions of the code and can be used to define the reference model in and out of the derivative terms. The options are: SMOOTH_MOD_DIF (reference model is defined in the derivative terms) and SMOOTH_MOD (reference model is defined in only the smallest term). See equation details on the model objective function section for details.

  • weights: Name of the weights file containing weighting matrices. If null is entered, default values of unity are used (no extra weighting).

4.2.4.1.1. Example of control file

Below is an example of a control file with comments:

../../_images/maginv3dEx.png

4.2.4.2. Output files

Five general output files are created by the inversion. They are:

  1. maginv3d.log: The log file containing the minimum information for each iteration and summary of the inversion.
  2. maginv3d.out: The “developers” log file containing the details of each iteration including the model objective function values for each component, number of conjugate gradient iterations, etc.
  3. maginv3d_xxx.sus: Susceptibility (SI) model files output after each “xxx” iteration (i.e., maginv3d_012.sus)
  4. maginv3d_xxx.pre: Predicted data files (without uncertainties) output after each “xxx” iteration.