mmt_multipole_inversion

Submodules

• mmt_multipole_inversion.__about__
• mmt_multipole_inversion.magnetic_sample
• mmt_multipole_inversion.magnetic_sample_modules
• mmt_multipole_inversion.multipole_field
• mmt_multipole_inversion.multipole_inversion
• mmt_multipole_inversion.plot_tools
• mmt_multipole_inversion.susceptibility_modules

Attributes

__author__
__copyright__
__email__
__license__
__summary__
__title__
__uri__
__version__

Classes

MultipoleInversion	Class to perform multipole inversions
MagneticSample	Class for the specification of a scan grid detecting the out plane flux of

Package Contents

class mmt_multipole_inversion.MultipoleInversion(sample_config_file, sample_arrays, expansion_limit='quadrupole', sus_functions_module='spherical_harmonics_basis')

Bases: object

Class to perform multipole inversions

Class to perform multipole inversions of a magnetic scan surface into multiple magnetic sources located within a sample. Specifications of the scan grid and the magnetic particles in the sample can be generated using the MagneticSample class. The sensors of the magnetic scan surface are modelled either as point sensors or sensor with cuboid shape (volume).

Parameters:

• sample_config_file (Union[str, pathlib.Path])

• sample_arrays (Optional[Union[str, pathlib.Path]])

• expansion_limit (_ExpOptions)

• sus_functions_module (_SusOptions)

sus_mod

_expansion_limit = 'dipole'

property expansion_limit

particle_positions = None

Q

property Bz_array

generate_measurement_mesh()

Generate coordinates for the measurement mesh

The number of grid points in each direction (xy) are calculated by rounding the lateral size by the grid step size, e.g. round(Sx / Sdx)

generate_forward_matrix(optimization='numba')

Generate the forward matrix adding the field contribution from all the particles for every grid point at the scan surface. The field is computed from the scalar potential of the particles approximated with the multipole expansion up to the order specified by self.expansion_limit

Parameters:

optimization

The method to optimize the calculation of the matrix elements: numba or cuda

Parameters:

optimization (_MethodOptions)

Notes

In case of using one of the _area or _volume susceptibility modules, where the sensor is modelled in 2D or 3D, remember to specify the self.sensor_dims tuple with the dimensions of the sensor

generate_field_mask(fieldMaskTool)

Creates a mask array for the Bz field array

Parameters:

fieldMaskTool

This method accepts different ways to create a filter where no data is specified. FUNCTION: define a function that depends on r=(x,y) as argument, which returns True for sites with data and False where data is filtered. ARRAY: which has the same dimensions as the Bz scanning data array, and where True/False or 1/0 is for sites with/without data. STR or PATH: to an image file in black and white, where black pixels are specified for sensor data that is filtered/removed.

Parameters:

fieldMaskTool (Union[collections.abc.Callable[[numpy.ndarray], bool], numpy.ndarray, str, pathlib.Path])

compute_inversion(method='sp_pinv', apply_field_mask=False, sigma_field_noise=None, **method_kwargs)

Computes the multipole inversion. Results are saved in the inv_multipole_moments and inv_Bz_array variables. This method requires the generation of the Q matrix, hence the generate_forward_matrix method using numba is called if Q has not been set. To optimize the calculation of Q, call the function before this method.

Parameters:

method

The numerical method to perform the inversion. Options:

np_pinv -> Numpy’s pinv sp_pinv -> Scipy’s pinv (not recommended -> memory issues) sp_pinv2 -> Scipy’s pinv2 (this will call sp_pinv instead) direct -> direct inverse (quickest and most memory efficient)

apply_field_mask

Set True if a masking array is used for the magnetic field. The mask must be created using the generate_field_mask method, which sets the self.fieldMask array for the Bz field. Values labeled as False are ignored.

sigma_field_noise

If a float is specified, a covariance matrix is produced and stored in the covariance_matrix variable. This matrix uses the value of sigma as the standard deviation of uncorrelated noise in the magnetic flux field. Units are T m^2. In addition, the standard deviation of the magnetic moments are calculated and stored in the inv_moments_std 2D array where every row has the results per grain. For details, see [F. Out et al. Geochemistry, Geophysics, Geosystems 23(4). 2022]

**method_kwargs

Extra parameters passed to Numpy or Scipy functions. For Numpy, the tolerance can be set using rcond while for Scipy it is recommended to use atol and rtol. See their documentations for detailed information.

Parameters:

• method (_InvMethodOps)

• apply_field_mask (bool)

• sigma_field_noise (Optional[float])

save_multipole_moments(save_name='TIME_STAMP', basedir='.', save_identifier=False, save_moments_std=False)

Save the multipole values in npz files.

Values need to be computed using the compute_inversion method.

Parameters:

save_name

File name of the npz file

basedir

Base directory where results are saved. Will be created if it does not exist

save_identifier

Add a set identifier to the magnetic moments

save_moments_std

Add the standard deviation of the magnetic moments to the npz file in case the sigma_field_noise was specified in the inversion

Parameters:

• save_name (str)

• basedir (Union[pathlib.Path, str])

• save_identifier (bool)

• save_moments_std (bool)

Return type:

None

class mmt_multipole_inversion.MagneticSample(Hz, Sx, Sy, Sdx, Sdy, Lx, Ly, Lz, sensor_origin=(0.0, 0.0), bz_field_module='spherical_harmonics_basis')

Bases: object

Class for the specification of a scan grid detecting the out plane flux of the magnetic field generated by an arbitrary number of magnetic sources. The magnetic sources can be dipoles, quadrupoles or octupoles. The scan grid is defined in the XY plane, at a given height above the magnetic sample containing the point sources.

This class calculates the magnetic field from the point sources and adds them to generate the total flux at every area of the scan grid mesh.

                   Sdx
                ___/___
               /      /            Scan Grid
         _     ______________________________
  Sdy_ /     /       /      /       /       /
      /_    /_______/______/_______/_______/__      _
           /       /      /       /       /   /|     |
          / ______/______/_______/_______/   / |     |_ Lz
         /       /      /       /       /   /  |     |
     _  /_______/______/_______/_______/   /   |     |
Hx _|     /                O              /  O |    _|
    |_   /______________________________ /    /
        |                               |    /
        |            O                  |   /
        |   O                           |  /
        |    dipole               O     | /
        |_______________________________|/  Sample

Parameters:

• Hz (float)

• Sx (float)

• Sy (float)

• Sdx (float)

• Sdy (float)

• Lx (float)

• Ly (float)

• Lz (float)

• sensor_origin (tuple[float, float])

• bz_field_module (str)

Hz

Sx

Sy

Sdx

Sdy

Lx

Ly

Lz

sensor_origin_x = 0.0

sensor_origin_y = 0.0

time_stamp

_metadict

quadrupole_moments = None

octupole_moments = None

bz_field_mod

get_metadict()

Generate a dictionary with the keys defined in the _metadict variable. Values are obtained by calling the class instance attributes defined in the _metadict values. Because scan origin is a sequence, it is split in x and y components. This method is used to export sample properties as a json file.

generate_random_particles(N_particles=100, Ms=480000.0, seed=42, rmin=[0.1, 0.1, 0.1], rmax=[0.9, 0.9, 0.9], identifier=None)

Generate a sample of dipole particles randomly distributed across the sample region. The dipole moments of the particles are randomly generated based on the saturation magnetization value Ms

Parameters:

N_particles

Number of particles

Ms

Saturation magnetisation

seed

random number generator seed

rmin, rmax

minimum and maximum scale factors for the limits of the locations of the particles. The factors scale the sample dimensions in every dimension. For example, particles spread over the sample but close to the surface can be modelled by

rmin = [0.1, 0.1, 0.7] rmax = [0.9, 0.9, 0.9]

This means particle positions in the x- and y-directions will vary between 0.1 and 0.9 of Lx, and in the z-direction between 0.7*Lz and 0.9*Lz.

identifier

N array with integers representing particles

Parameters:

• N_particles (int)

• Ms (float)

• seed (int)

• rmin (list[float])

• rmax (list[float])

• identifier (list[int] | None)

generate_particles_from_array(positions, dipole_moments, volumes, quadrupole_moments=None, octupole_moments=None, identifier=None)

Generate particles in the sample from arrays specified manually

Parameters:

positions

N x 3 array (m units)

dipole_moments

N x 3 array (A m^2 unitS)

volumes

N x 3 array (m^3 units)

quadrupole_moments

N x 5 array with quadrupole moments

octupole_moments

N x 7 array with octupole moments

identifier

N array with integers representing particles

Parameters:

• positions (list[list[float]])

• dipole_moments (list[list[float]])

• volumes (list[float])

• quadrupole_moments (list[float] | None)

• octupole_moments (list[float] | None)

• identifier (list[int] | None)

Notes

The multipole options need to be redefined (it depends on the basis we are expressing the multipole expansion)

generate_measurement_mesh()

Generate the magnetic flux array at the scan surface, i.e. calculate the total Bz contribution from the particles at every grid point of the scan surface

generate_noised_Bz_array(std_dev, seed=4242)

Add uncorrelated noise to the magnetic flux (Bz array). The new array is stored in self.Bz_array_noised. The seed is either an integer or a random number generator. Noise is added from a Gaussian distribution with a given std_dev standard deviation.

Parameters:

• std_dev (float)

• seed (int | numpy.random.RandomState)

save_data(filename='TIME_STAMP', basedir='', noised_array=False)

Save the system properties as a json file and relevant arrays in a npz file: Bz_array, particle_positions, magnetization, volumes, and identifiers.

Parameters:

filename

Name appended to the dictionary and arrays base name

basedir

An optional directory to which data is going to be stored

noised_array

Save the noised Bz_array instead of the original array

Parameters:

• filename (str)

• basedir (str)

• noised_array (bool)

plot_sample(ax, contours=30, contourlines=15, contourf_args=dict(cmap='RdYlBu'), contour_args=dict(colors='k', linewidths=0.2), scatter_args=dict(c='k'), dimension_scale=1.0, data_scale=1.0, noised_array=False, imshow_args=None)

(WILL BE REMOVED IN FUTURE) Plot the scan surface and the particles beneath using their xy position

Optional:

If imshow_args is specified, this functions uses imshow instead of contourf to plot the colored background with Bz_array. In this case, all the contourf args are ignored

Returns :: cf, c1, c2

where cf is the contour plot object showing Bz, c1 its contour lines and c2 the scatter plot with the particle positions

mmt_multipole_inversion.__author__ = 'D. Cortés-Ortuño, K. Fabian, L. V. de Groot'

mmt_multipole_inversion.__copyright__ = 'Copyright 2022 D. Cortés-Ortuño, K. Fabian, L. V. de Groot'

mmt_multipole_inversion.__email__ = 'd.i.cortes@uu.nl'

mmt_multipole_inversion.__license__ = 'MIT'

mmt_multipole_inversion.__summary__ = 'Library to generate scan grid measurements from multipole sources and perform numerical inversions'

mmt_multipole_inversion.__title__ = 'mmt_multipole_inversion'

mmt_multipole_inversion.__uri__ = 'https://github.com/Micromagnetic-Tomography/mmt_multipole_inversion'

mmt_multipole_inversion.__version__ = '1.0'