# Natural Source Electromagnetics¶

SimPEG (Simulation and Parameter Estimation in Geophysics) is a python package for simulation and gradient based parameter estimation in the context of geoscience applications.

Uses SimPEG as the framework for the forward and inverse magnetotellurics geophysical problems.

This package within SimPEG currently includes

• Magnetotellurics
• Impedance

• Tipper

With support to other methods such

• ZTEM

under development

## API¶

### NSEM Problem¶

class SimPEG.EM.NSEM.ProblemNSEM.BaseNSEMProblem(mesh, **kwargs)[source]

Base class for all Natural source problems.

Optional Properties:

Other Properties:

surveyPair
dataPair
fieldsPair
Solver
solverOpts = {}
verbose = False
Jvec(m, v, f=None)[source]

Function to calculate the data sensitivities dD/dm times a vector.

Parameters
• m (numpy.ndarray) – conductivity model (nP,)

• v (numpy.ndarray) – vector which we take sensitivity product with (nP,)

• (optional) u (SimPEG.EM.NSEM.FieldsNSEM) – NSEM fields object, if not given it is calculated

Return type

numpy.ndarray

Returns

Jv (nData,) Data sensitivities wrt m

Jtvec(m, v, f=None)[source]

Function to calculate the transpose of the data sensitivities (dD/dm)^T times a vector.

Parameters
• m (numpy.ndarray) – inversion model (nP,)

• v (numpy.ndarray) – vector which we take adjoint product with (nP,)

• f (optional) (SimPEG.EM.NSEM.FieldsNSEM) – NSEM fields object, if not given it is calculated

Return type

numpy.ndarray

Returns

Jtv (nP,) Data sensitivities wrt m

class SimPEG.EM.NSEM.ProblemNSEM.Problem1D_ePrimSec(mesh, **kwargs)[source]

A NSEM problem soving a e formulation and primary/secondary fields decomposion.

By eliminating the magnetic flux density using

$\mathbf{b} = \frac{1}{i \omega}\left(-\mathbf{C} \mathbf{e} \right)$

we can write Maxwell’s equations as a second order system in $$\mathbf{e}$$ only:

$\left[ \mathbf{C}^{\top} \mathbf{M_{\mu^{-1}}^e } \mathbf{C} + i \omega \mathbf{M_{\sigma}^f} \right] \mathbf{e}_{s} = i \omega \mathbf{M_{\sigma_{s}}^f } \mathbf{e}_{p}$

which we solve for $$\mathbf{e_s}$$. The total field $$\mathbf{e} = \mathbf{e_p} + \mathbf{e_s}$$.

The primary field is estimated from a background model (commonly half space ).

Optional Properties:

Other Properties:

fieldsPair
property MeMui

Edge inner product matrix

property MfSigma

Edge inner product matrix

MfSigmaDeriv(u)[source]

Edge inner product matrix

property sigmaPrimary

A background model, use for the calculation of the primary fields.

getA(freq)[source]

Function to get the A matrix.

Parameters

freq (float) – Frequency

Return type

scipy.sparse.csr_matrix

Returns

A

getADeriv(freq, u, v, adjoint=False)[source]

The derivative of A wrt sigma

getRHS(freq)[source]

Function to return the right hand side for the system. :param float freq: Frequency :rtype: numpy.ndarray :return: RHS for 1 polarizations, primary fields (nF, 1)

getRHSDeriv(freq, v, adjoint=False)[source]

The derivative of the RHS wrt sigma

fields(m=None)[source]

Function to calculate all the fields for the model m.

Parameters

m (numpy.ndarray) – Conductivity model (nC,)

Return type

SimPEG.EM.NSEM.FieldsNSEM.Fields1D_ePrimSec

Returns

NSEM fields object containing the solution

class SimPEG.EM.NSEM.ProblemNSEM.Problem3D_ePrimSec(mesh, **kwargs)[source]

A NSEM problem solving a e formulation and a primary/secondary fields decompostion.

By eliminating the magnetic flux density using

$\mathbf{b} = \frac{1}{i \omega}\left(-\mathbf{C} \mathbf{e} \right)$

we can write Maxwell’s equations as a second order system in $$\mathbf{e}$$ only:

$\left[\mathbf{C}^{\top} \mathbf{M_{\mu^{-1}}^f} \mathbf{C} + i \omega \mathbf{M_{\sigma}^e} \right] \mathbf{e}_{s} = i \omega \mathbf{M_{\sigma_{p}}^e} \mathbf{e}_{p}$

which we solve for $$\mathbf{e_s}$$. The total field $$\mathbf{e} = \mathbf{e_p} + \mathbf{e_s}$$.

The primary field is estimated from a background model (commonly as a 1D model).

Optional Properties:

Other Properties:

fieldsPair
property sigmaPrimary

A background model, use for the calculation of the primary fields.

getA(freq)[source]

Function to get the A system.

Parameters

freq (float) – Frequency

Return type

scipy.sparse.csr_matrix

Returns

A

getADeriv(freq, u, v, adjoint=False)[source]

Calculate the derivative of A wrt m.

Parameters
• freq (float) – Frequency

• u (SimPEG.EM.NSEM.FieldsNSEM) – NSEM Fields object

• v (numpy.ndarray) – vector of size (nU,) (adjoint=False) and size (nP,) (adjoint=True)

Return type

numpy.ndarray

Returns

Calculated derivative (nP,) (adjoint=False) and (nU,)[NOTE return as a (nU/2,2) columnwise polarizations] (adjoint=True) for both polarizations

getRHS(freq)[source]

Function to return the right hand side for the system.

Parameters

freq (float) – Frequency

Return type

numpy.ndarray

Returns

RHS for both polarizations, primary fields (nE, 2)

getRHSDeriv(freq, v, adjoint=False)[source]

The derivative of the RHS with respect to the model and the source

Parameters
• freq (float) – Frequency

• v (numpy.ndarray) – vector of size (nU,) (adjoint=False) and size (nP,) (adjoint=True)

Return type

numpy.ndarray

Returns

fields(m=None)[source]

Function to calculate all the fields for the model m.

Parameters

(nC,) m (numpy.ndarray) – Conductivity model

Return type

SimPEG.EM.NSEM.FieldsNSEM

Returns

Fields object with of the solution

### NSEM Survey¶

class SimPEG.EM.NSEM.SurveyNSEM.Survey(srcList, **kwargs)[source]

Survey class for NSEM.

Requried :param list srcList: List of sources associated with the survey

Optional

srcPair
property freqs

Frequencies

property nFreq

Number of frequencies

getSrcByFreq(freq)[source]

Returns the sources associated with a specific frequency.

eval(f)[source]

Evalute and return Data given calculated fields

Parameters

f (SimPEG.EM.NSEM.FieldsNSEM) – A NSEM fileds object to evaluate data from

Retype

SimPEG.EM.NSEM.Data

Returns

NSEM Data object

evalDeriv(f)[source]

This function s the derivative of projects the fields onto the data space.

$\frac{\partial d_\text{pred}}{\partial u} = \mathbf{P}$
class SimPEG.EM.NSEM.SurveyNSEM.Data(survey, dobs=None, standard_deviation=None, floor=None)[source]

Bases: SimPEG.Survey.Data, SimPEG.EM.NSEM.Utils.plotUtils.DataNSEMPlotMethods

Data class for NSEMdata. Stores the data vector indexed by the survey.

Required :param SimPEG.EM.NSEM.SurveyNSEM survey: NSEM survey object

Optional :param numpy.ndarray v: Vector of the data in order matching of the survey :param numpy.ndarray standard_deviation: Vector of the standard_deviation of data in order matching of the survey :param numpy.ndarray floor: Vector of the noise floor of the data in order matching of the survey

toRecArray(returnType='RealImag')[source]

Returns a numpy.recarray for a SimpegNSEM impedance data object.

Optional :param str returnType: Switches between returning a rec array where the impedance is split to real and imaginary (‘RealImag’) or is a complex (‘Complex’) :rtype: numpy.recarray :return: Record array with data, with indexed columns

classmethod fromRecArray(recArray, srcType='primary')[source]

Class method that reads in a numpy record array to NSEMdata object.

Required :param numpy.recarray recArray: Record array with the data. Has to have (‘freq’,’x’,’y’,’z’) columns and some (‘zxx’,’zxy’,’zyx’,’zyy’,’tzx’,’tzy’)

Optional :param string srcType: The type of SimPEG.EM.NSEM.SrcNSEM to be used

class SimPEG.EM.NSEM.SrcNSEM.BaseNSEMSrc(rxList, freq)[source]

Sources for the NSEM problem. Use the SimPEG BaseSrc, since the source fields share properties with the transmitters.

param float freq

The frequency of the source

param list rxList

A list of receivers associated with the source

Required Properties:

• integrate (Boolean): integrate the source term?, a boolean, Default: False

• loc (Array): location of the source, a list or numpy array of <class ‘float’>, <class ‘int’> with shape (*, 3) or (3)

freq = None

Frequency (float)

class SimPEG.EM.NSEM.SrcNSEM.Planewave_xy_1DhomotD(rxList, freq)[source]

NSEM source for both polarizations (x and y) for the total Domain.

It calculates fields calculated based on conditions on the boundary of the domain.

Required Properties:

• integrate (Boolean): integrate the source term?, a boolean, Default: False

• loc (Array): location of the source, a list or numpy array of <class ‘float’>, <class ‘int’> with shape (*, 3) or (3)

class SimPEG.EM.NSEM.SrcNSEM.Planewave_xy_1Dprimary(rxList, freq)[source]

NSEM planewave source for both polarizations (x and y) estimated from a single 1D primary models.

Required Properties:

• integrate (Boolean): integrate the source term?, a boolean, Default: False

• loc (Array): location of the source, a list or numpy array of <class ‘float’>, <class ‘int’> with shape (*, 3) or (3)

ePrimary(problem)[source]

Primary electric field

Parameters

prob (BaseFDEMProblem) – FDEM Problem

Return type

numpy.ndarray

Returns

primary electric field

bPrimary(problem)[source]

Primary magnetic flux density

Parameters

prob (BaseFDEMProblem) – FDEM Problem

Return type

numpy.ndarray

Returns

primary magnetic flux density

S_e(problem)[source]

Get the electrical field source

S_eDeriv(problem, v, adjoint=False)[source]

The derivative of S_e with respect to

S_eDeriv_m(problem, v, adjoint=False)[source]

Get the derivative of S_e wrt to sigma (m)

class SimPEG.EM.NSEM.SrcNSEM.Planewave_xy_3Dprimary(rxList, freq)[source]

NSEM source for both polarizations (x and y) given a 3D primary model. It assigns fields calculated from the 1D model as fields in the full space of the problem.

Required Properties:

• integrate (Boolean): integrate the source term?, a boolean, Default: False

• loc (Array): location of the source, a list or numpy array of <class ‘float’>, <class ‘int’> with shape (*, 3) or (3)

ePrimary(problem)[source]

Primary electric field

Parameters

prob (BaseFDEMProblem) – FDEM Problem

Return type

numpy.ndarray

Returns

primary electric field

bPrimary(problem)[source]

Primary magnetic flux density

Parameters

prob (BaseFDEMProblem) – FDEM Problem

Return type

numpy.ndarray

Returns

primary magnetic flux density

S_e(problem)[source]

Get the electrical field source

S_eDeriv_m(problem, v, adjoint=False)[source]

Get the derivative of S_e wrt to sigma (m)

Module RxNSEM.py

class SimPEG.EM.NSEM.RxNSEM.BaseRxNSEM_Point(locs, orientation=None, component=None)[source]

Assumes that the data locations are xyz coordinates.

Parameters
• locs (numpy.ndarray) – receiver locations (ie. np.r_[x,y,z])

• orientation (string) – receiver orientation ‘x’, ‘y’ or ‘z’

• component (string) – real or imaginary component ‘real’ or ‘imag’

property mesh
property src
property f
property Pex
property Pey
property Pbx
property Pby
property Pbz
eval(src, mesh, f, return_complex=False)[source]

Function to evaluate datum for this receiver

evalDeriv(src, mesh, f, v, adjoint=False)[source]

Function to evaluate datum for this receiver

class SimPEG.EM.NSEM.RxNSEM.Point_impedance1D(locs, component=None)[source]

Natural source 1D impedance receiver class

Parameters

component (string) – real or imaginary component ‘real’ or ‘imag’

orientation = 'yx'
property mesh
property src
property f
property Pex
property Pbx
eval(src, mesh, f, return_complex=False)[source]

Project the fields to natural source data.

Parameters
• src (SimPEG.EM.NSEM.SrcNSEM) – NSEM source

• mesh (discretize.TensorMesh) – Mesh defining the topology of the problem

• f (SimPEG.EM.NSEM.FieldsNSEM) – NSEM fields object of the source

• (optional) return_complex (bool) – Flag for return the complex evaluation

Return type

numpy.ndarray

Returns

evalDeriv(src, mesh, f, v, adjoint=False)[source]

method evalDeriv

The derivative of the projection wrt u

Parameters
• src (SimPEG.EM.NSEM.SrcNSEM) – NSEM source

• mesh (discretize.TensorMesh) – Mesh defining the topology of the problem

• f (SimPEG.EM.NSEM.FieldsNSEM) – NSEM fields object of the source

• v (numpy.ndarray) – vector of size (nU,) (adjoint=False) and size (nD,) (adjoint=True)

Return type

numpy.ndarray

Returns

class SimPEG.EM.NSEM.RxNSEM.Point_impedance3D(locs, orientation=None, component=None)[source]

Natural source 3D impedance receiver class

Parameters
• locs (numpy.ndarray) – receiver locations (ie. np.r_[x,y,z])

• orientation (string) – receiver orientation ‘xx’, ‘xy’, ‘yx’ or ‘yy’

• component (string) – real or imaginary component ‘real’ or ‘imag’

eval(src, mesh, f, return_complex=False)[source]

Project the fields to natural source data.

Parameters
• src (SrcNSEM) – The source of the fields to project

• mesh (discretize.TensorMesh) – topological mesh corresponding to the fields

• f (FieldsNSEM) – Natural source fields object to project

Return type

numpy.ndarray

Returns

component of the impedance evaluation

evalDeriv(src, mesh, f, v, adjoint=False)[source]

The derivative of the projection wrt u

Parameters
• src (SimPEG.EM.NSEM.SrcNSEM) – NSEM source

• mesh (discretize.TensorMesh) – Mesh defining the topology of the problem

• f (SimPEG.EM.NSEM.FieldsNSEM) – NSEM fields object of the source

• v (numpy.ndarray) – vector of size (nU,) (adjoint=False) and size (nD,) (adjoint=True)

Return type

numpy.ndarray

Returns

class SimPEG.EM.NSEM.RxNSEM.Point_tipper3D(locs, orientation=None, component=None)[source]

Natural source 3D tipper receiver base class

Parameters
• locs (numpy.ndarray) – receiver locations (ie. np.r_[x,y,z])

• orientation (string) – receiver orientation ‘x’, ‘y’ or ‘z’

• component (string) – real or imaginary component ‘real’ or ‘imag’

eval(src, mesh, f, return_complex=False)[source]

Project the fields to natural source data.

Parameters
• src (SrcNSEM) – The source of the fields to project

• mesh (discretize.TensorMesh) – Mesh defining the topology of the problem

• f (FieldsNSEM) – Natural source fields object to project

Return type

numpy.ndarray

Returns

Evaluated component of the impedance data

evalDeriv(src, mesh, f, v, adjoint=False)[source]

The derivative of the projection wrt u

Parameters
• src (SimPEG.EM.NSEM.SrcNSEM) – NSEM source

• mesh (discretize.TensorMesh) – Mesh defining the topology of the problem

• f (SimPEG.EM.NSEM.FieldsNSEM) – NSEM fields object of the source

• v (numpy.ndarray) – Random vector of size

Return type

numpy.ndarray

Returns

### NSEM Fields¶

class SimPEG.EM.NSEM.FieldsNSEM.BaseNSEMFields(mesh, survey, **kwargs)[source]

Field Storage for a NSEM method.

knownFields = {}
dtype

alias of builtins.complex

class SimPEG.EM.NSEM.FieldsNSEM.Fields1D_ePrimSec(mesh, survey, **kwargs)[source]

Fields storage for the 1D NSEM solution.

Solving for e fields, using primary/secondary formulation

knownFields = {'e_1dSolution': 'F'}
aliasFields = {'b_1d': ['e_1dSolution', 'E', '_b'], 'b_1dPrimary': ['e_1dSolution', 'E', '_bPrimary'], 'b_1dSecondary': ['e_1dSolution', 'E', '_bSecondary'], 'e_1d': ['e_1dSolution', 'F', '_e'], 'e_1dPrimary': ['e_1dSolution', 'F', '_ePrimary'], 'e_1dSecondary': ['e_1dSolution', 'F', '_eSecondary']}
class SimPEG.EM.NSEM.FieldsNSEM.Fields3D_ePrimSec(mesh, survey, **kwargs)[source]

Fields storage for the 3D NSEM solution. Labels polarizations by px and py.

param SimPEG object mesh

The solution mesh

param SimPEG object survey

A survey object

knownFields = {'e_pxSolution': 'E', 'e_pySolution': 'E'}
aliasFields = {'b_px': ['e_pxSolution', 'F', '_b_px'], 'b_pxPrimary': ['e_pxSolution', 'F', '_b_pxPrimary'], 'b_pxSecondary': ['e_pxSolution', 'F', '_b_pxSecondary'], 'b_py': ['e_pySolution', 'F', '_b_py'], 'b_pyPrimary': ['e_pySolution', 'F', '_b_pyPrimary'], 'b_pySecondary': ['e_pySolution', 'F', '_b_pySecondary'], 'e_px': ['e_pxSolution', 'E', '_e_px'], 'e_pxPrimary': ['e_pxSolution', 'E', '_e_pxPrimary'], 'e_pxSecondary': ['e_pxSolution', 'E', '_e_pxSecondary'], 'e_py': ['e_pySolution', 'E', '_e_py'], 'e_pyPrimary': ['e_pySolution', 'E', '_e_pyPrimary'], 'e_pySecondary': ['e_pySolution', 'E', '_e_pySecondary']}