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]

Bases: SimPEG.EM.FDEM.ProblemFDEM.BaseFDEMProblem

Base class for all Natural source problems.

Optional Properties:

  • model (Model): Inversion model., a numpy array of <class ‘float’>, <class ‘int’> with shape (*) or (*, *)

  • mu (PhysicalProperty): Magnetic Permeability (H/m), a physical property, Default: 1.2566370614359173e-06

  • muMap (Mapping): Mapping of Magnetic Permeability (H/m) to the inversion model., a SimPEG Map

  • mui (PhysicalProperty): Inverse Magnetic Permeability (m/H), a physical property

  • muiMap (Mapping): Mapping of Inverse Magnetic Permeability (m/H) to the inversion model., a SimPEG Map

  • rho (PhysicalProperty): Electrical resistivity (Ohm m), a physical property

  • rhoMap (Mapping): Mapping of Electrical resistivity (Ohm m) to the inversion model., a SimPEG Map

  • sigma (PhysicalProperty): Electrical conductivity (S/m), a physical property

  • sigmaMap (Mapping): Mapping of Electrical conductivity (S/m) to the inversion model., a SimPEG Map

Other Properties:

  • muDeriv (Derivative): Derivative of Magnetic Permeability (H/m) wrt the model.

  • muiDeriv (Derivative): Derivative of Inverse Magnetic Permeability (m/H) wrt the model.

  • rhoDeriv (Derivative): Derivative of Electrical resistivity (Ohm m) wrt the model.

  • sigmaDeriv (Derivative): Derivative of Electrical conductivity (S/m) wrt the model.

surveyPair

alias of SimPEG.EM.NSEM.SurveyNSEM.Survey

dataPair

alias of SimPEG.EM.NSEM.SurveyNSEM.Data

fieldsPair

alias of SimPEG.EM.NSEM.FieldsNSEM.BaseNSEMFields

Solver

alias of SimPEG.Utils.SolverUtils.SolverLU

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]

Bases: SimPEG.EM.NSEM.ProblemNSEM.BaseNSEMProblem

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:

  • model (Model): Inversion model., a numpy array of <class ‘float’>, <class ‘int’> with shape (*) or (*, *)

  • mu (PhysicalProperty): Magnetic Permeability (H/m), a physical property, Default: 1.2566370614359173e-06

  • muMap (Mapping): Mapping of Magnetic Permeability (H/m) to the inversion model., a SimPEG Map

  • mui (PhysicalProperty): Inverse Magnetic Permeability (m/H), a physical property

  • muiMap (Mapping): Mapping of Inverse Magnetic Permeability (m/H) to the inversion model., a SimPEG Map

  • rho (PhysicalProperty): Electrical resistivity (Ohm m), a physical property

  • rhoMap (Mapping): Mapping of Electrical resistivity (Ohm m) to the inversion model., a SimPEG Map

  • sigma (PhysicalProperty): Electrical conductivity (S/m), a physical property

  • sigmaMap (Mapping): Mapping of Electrical conductivity (S/m) to the inversion model., a SimPEG Map

Other Properties:

  • muDeriv (Derivative): Derivative of Magnetic Permeability (H/m) wrt the model.

  • muiDeriv (Derivative): Derivative of Inverse Magnetic Permeability (m/H) wrt the model.

  • rhoDeriv (Derivative): Derivative of Electrical resistivity (Ohm m) wrt the model.

  • sigmaDeriv (Derivative): Derivative of Electrical conductivity (S/m) wrt the model.

fieldsPair

alias of SimPEG.EM.NSEM.FieldsNSEM.Fields1D_ePrimSec

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]

Bases: SimPEG.EM.NSEM.ProblemNSEM.BaseNSEMProblem

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:

  • model (Model): Inversion model., a numpy array of <class ‘float’>, <class ‘int’> with shape (*) or (*, *)

  • mu (PhysicalProperty): Magnetic Permeability (H/m), a physical property, Default: 1.2566370614359173e-06

  • muMap (Mapping): Mapping of Magnetic Permeability (H/m) to the inversion model., a SimPEG Map

  • mui (PhysicalProperty): Inverse Magnetic Permeability (m/H), a physical property

  • muiMap (Mapping): Mapping of Inverse Magnetic Permeability (m/H) to the inversion model., a SimPEG Map

  • rho (PhysicalProperty): Electrical resistivity (Ohm m), a physical property

  • rhoMap (Mapping): Mapping of Electrical resistivity (Ohm m) to the inversion model., a SimPEG Map

  • sigma (PhysicalProperty): Electrical conductivity (S/m), a physical property

  • sigmaMap (Mapping): Mapping of Electrical conductivity (S/m) to the inversion model., a SimPEG Map

Other Properties:

  • muDeriv (Derivative): Derivative of Magnetic Permeability (H/m) wrt the model.

  • muiDeriv (Derivative): Derivative of Inverse Magnetic Permeability (m/H) wrt the model.

  • rhoDeriv (Derivative): Derivative of Electrical resistivity (Ohm m) wrt the model.

  • sigmaDeriv (Derivative): Derivative of Electrical conductivity (S/m) wrt the model.

fieldsPair

alias of SimPEG.EM.NSEM.FieldsNSEM.Fields3D_ePrimSec

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

Calculated derivative (nP,) (adjoint=False) and (nU,2) (adjoint=True) for both polarizations

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]

Bases: SimPEG.Survey.BaseSurvey

Survey class for NSEM.

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

Optional

srcPair

alias of SimPEG.EM.NSEM.SrcNSEM.BaseNSEMSrc

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]

Bases: SimPEG.EM.FDEM.SrcFDEM.BaseFDEMSrc

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]

Bases: SimPEG.EM.NSEM.SrcNSEM.BaseNSEMSrc

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]

Bases: SimPEG.EM.NSEM.SrcNSEM.BaseNSEMSrc

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]

Bases: SimPEG.EM.NSEM.SrcNSEM.BaseNSEMSrc

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

Receivers for the NSEM problem

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

Bases: SimPEG.Survey.BaseRx

Natural source receiver base class.

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]

Bases: SimPEG.Survey.BaseRx

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

Evaluated data for the receiver

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

Calculated derivative (nD,) (adjoint=False) and (nP,2) (adjoint=True) for both polarizations

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

Bases: SimPEG.EM.NSEM.RxNSEM.BaseRxNSEM_Point

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

Calculated derivative (nD,) (adjoint=False) and (nP,2) (adjoint=True) for both polarizations

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

Bases: SimPEG.EM.NSEM.RxNSEM.BaseRxNSEM_Point

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

Calculated derivative (nD,) (adjoint=False) and (nP,2) (adjoint=True) for both polarizations

NSEM Fields

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

Bases: SimPEG.Fields.Fields

Field Storage for a NSEM method.

knownFields = {}
dtype

alias of builtins.complex

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

Bases: SimPEG.EM.NSEM.FieldsNSEM.BaseNSEMFields

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]

Bases: SimPEG.EM.NSEM.FieldsNSEM.BaseNSEMFields

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']}