organizing the docs - put the content in a content folder. put the SimPEG core api docs in core_api

This commit is contained in:
Lindsey Heagy
2016-05-30 17:06:29 -07:00
parent 414418a996
commit 5e8d3fbc78
57 changed files with 122 additions and 95 deletions
+197
View File
@@ -0,0 +1,197 @@
.. _api_FDEM:
.. math::
\renewcommand{\div}{\nabla\cdot\,}
\newcommand{\grad}{\vec \nabla}
\newcommand{\curl}{{\vec \nabla}\times\,}
Frequency Domain Electromagnetics
*********************************
Electromagnetic (EM) geophysical methods are used in a variety of applications
from resource exploration, including for hydrocarbons and minerals, to
environmental applications, such as groundwater monitoring. The primary
physical property of interest in EM is electrical conductivity, which
describes the ease with which electric current flows through a material.
Background
==========
Electromagnetic phenomena are governed by Maxwell's equations. They describe
the behavior of EM fields and fluxes. Electromagnetic theory for geophysical
applications by Ward and Hohmann (1988) is a highly recommended resource on
this topic.
Fourier Transform Convention
----------------------------
In order to examine Maxwell's equations in the frequency domain, we must first
define our choice of harmonic time-dependence by choosing a Fourier transform
convention. We use the :math:`e^{i \omega t}` convention, so we define our
Fourier Transform pair as
.. math ::
F(\omega) = \int_{-\infty}^{\infty} f(t) e^{- i \omega t} dt \\
f(t) = \frac{1}{2\pi}\int_{-\infty}^{\infty} F(\omega) e^{i \omega t} d \omega
where :math:`\omega` is angular frequency, :math:`t` is time, :math:`F(\omega)` is the function defined in the frequency domain and :math:`f(t)` is the function defined in the time domain.
Maxwell's Equations
===================
In the frequency domain, Maxwell's equations are given by
.. math ::
\curl \vec{E} + i \omega \vec{B} = \vec{S_m}\\
\curl \vec{H} - \vec{J} - i \omega \vec{D} = \vec{S_e} \\
\div \vec{B} = 0 \\
\div \vec{D} = \rho_f
where:
- :math:`\vec{E}` : electric field (:math:`V/m` )
- :math:`\vec{H}` : magnetic field (:math:`A/m` )
- :math:`\vec{B}` : magnetic flux density (:math:`Wb/m^2` )
- :math:`\vec{D}` : electric displacement / electric flux density (:math:`C/m^2` )
- :math:`\vec{J}` : electric current density (:math:`A/m^2` )
- :math:`\vec{S_m}` : magnetic source term (:math:`V/m^2` )
- :math:`\vec{S_e}` : electric source term (:math:`A/m^2` )
- :math:`\rho_f` : free charge density (:math:`\Omega m` )
Constitutive Relations
----------------------
The fields and fluxes are related through the constitutive relations. At each frequency, they are given by
.. math ::
\vec{J} = \sigma \vec{E} \\
\vec{B} = \mu \vec{H} \\
\vec{D} = \varepsilon \vec{E}
where:
- :math:`\sigma` : electrical conductivity (:math:`S/m`)
- :math:`\mu` : magnetic permeability (:math:`H/m`)
- :math:`\varepsilon` : dielectric permittivity (:math:`F/m`)
:math:`\sigma`, :math:`\mu`, :math:`\varepsilon` are physical properties which depend on the material. :math:`\sigma` describes how easily electric current passes through a material, :math:`\mu` describes how easily a material is magnetized, and :math:`\varepsilon` describes how easily a material is electrically polarized. In most geophysical applications of EM, :math:`\sigma` is the the primary physical property of interest, and :math:`\mu`, :math:`\varepsilon` are assumed to have their free-space values :math:`\mu_0 = 4\pi \times 10^{-7} H/m` , :math:`\varepsilon_0 = 8.85 \times 10^{-12} F/m`
Quasi-static Approximation
--------------------------
For the frequency range typical of most geophysical surveys, the contribution of the electric displacement is negligible compared to the electric current density. In this case, we use the Quasi-static approximation and assume that this term can be neglected, giving
.. math ::
\nabla \times \vec{E} + i \omega \vec{B} = \vec{S_m} \\
\nabla \times \vec{H} - \vec{J} = \vec{S_e}
Implementation in SimPEG.EM
===========================
We consider two formulations in SimPEG.EM, both first-order and both in terms of one field and one flux. We allow for the definition of magnetic and electric sources (see for example: Ward and Hohmann, starting on page 144). The E-B formulation is in terms of the electric field and the magnetic flux:
.. math ::
\nabla \times \vec{E} + i \omega \vec{B} = \vec{S}_m \\
\nabla \times \mu^{-1} \vec{B} - \sigma \vec{E} = \vec{S}_e
The H-J formulation is in terms of the current density and the magnetic field:
.. math ::
\nabla \times \sigma^{-1} \vec{J} + i \omega \mu \vec{H} = \vec{S}_m \\
\nabla \times \vec{H} - \vec{J} = \vec{S}_e
Discretizing
------------
For both formulations, we use a finite volume discretization
and discretize fields on cell edges, fluxes on cell faces and
physical properties in cell centers. This is particularly
important when using symmetry to reduce the dimensionality of a problem
(for instance on a 2D CylMesh, there are :math:`r`, :math:`z` faces and :math:`\theta` edges)
.. figure:: ../../images/finitevolrealestate.png
:align: center
:scale: 60 %
For the two formulations, the discretization of the physical properties, fields and fluxes are summarized below.
.. figure:: ../../images/ebjhdiscretizations.png
:align: center
:scale: 60 %
Note that resistivity is the inverse of conductivity, :math:`\rho = \sigma^{-1}`.
E-B Formulation
---------------
.. math ::
\mathbf{C} \mathbf{e} + i \omega \mathbf{b} = \mathbf{s_m} \\
\mathbf{C^T} \mathbf{M^f_{\mu^{-1}}} \mathbf{b} - \mathbf{M^e_\sigma} \mathbf{e} = \mathbf{M^e} \mathbf{s_e}
H-J Formulation
---------------
.. math ::
\mathbf{C^T} \mathbf{M^f_\rho} \mathbf{j} + i \omega \mathbf{M^e_\mu} \mathbf{h} = \mathbf{M^e} \mathbf{s_m} \\
\mathbf{C} \mathbf{h} - \mathbf{j} = \mathbf{s_e}
.. Forward Problem
.. ===============
.. Inverse Problem
.. ===============
API
===
FDEM Problem
------------
.. automodule:: SimPEG.EM.FDEM.ProblemFDEM
:show-inheritance:
:members:
:undoc-members:
FDEM Survey
-----------
.. automodule:: SimPEG.EM.FDEM.SurveyFDEM
:show-inheritance:
:members:
:undoc-members:
.. automodule:: SimPEG.EM.FDEM.SrcFDEM
:show-inheritance:
:members:
:undoc-members:
.. automodule:: SimPEG.EM.FDEM.RxFDEM
:show-inheritance:
:members:
:undoc-members:
FDEM Fields
-----------
.. automodule:: SimPEG.EM.FDEM.FieldsFDEM
:show-inheritance:
:members:
:undoc-members:
+387
View File
@@ -0,0 +1,387 @@
.. _api_TDEM:
.. math::
\renewcommand{\div}{\nabla\cdot\,}
\newcommand{\grad}{\vec \nabla}
\newcommand{\curl}{{\vec \nabla}\times\,}
\newcommand {\J}{{\vec J}}
\renewcommand{\H}{{\vec H}}
\newcommand {\E}{{\vec E}}
\newcommand{\dcurl}{{\mathbf C}}
\newcommand{\dgrad}{{\mathbf G}}
\newcommand{\Acf}{{\mathbf A_c^f}}
\newcommand{\Ace}{{\mathbf A_c^e}}
\renewcommand{\S}{{\mathbf \Sigma}}
\newcommand{\St}{{\mathbf \Sigma_\tau}}
\newcommand{\T}{{\mathbf T}}
\newcommand{\Tt}{{\mathbf T_\tau}}
\newcommand{\diag}[1]{\,{\sf diag}\left( #1 \right)}
\newcommand{\M}{{\mathbf M}}
\newcommand{\MfMui}{{\M^f_{\mu^{-1}}}}
\newcommand{\MeSig}{{\M^e_\sigma}}
\newcommand{\MeSigInf}{{\M^e_{\sigma_\infty}}}
\newcommand{\MeSigO}{{\M^e_{\sigma_0}}}
\newcommand{\Me}{{\M^e}}
\newcommand{\Mes}[1]{{\M^e_{#1}}}
\newcommand{\Mee}{{\M^e_e}}
\newcommand{\Mej}{{\M^e_j}}
\newcommand{\BigO}[1]{\mathcal{O}\bigl(#1\bigr)}
\newcommand{\bE}{\mathbf{E}}
\newcommand{\bH}{\mathbf{H}}
\newcommand{\B}{\vec{B}}
\newcommand{\D}{\vec{D}}
\renewcommand{\H}{\vec{H}}
\newcommand{\s}{\vec{s}}
\newcommand{\bfJ}{\bf{J}}
\newcommand{\vecm}{\vec m}
\renewcommand{\Re}{\mathsf{Re}}
\renewcommand{\Im}{\mathsf{Im}}
\renewcommand {\j} { {\vec j} }
\newcommand {\h} { {\vec h} }
\renewcommand {\b} { {\vec b} }
\newcommand {\e} { {\vec e} }
\newcommand {\c} { {\vec c} }
\renewcommand {\d} { {\vec d} }
\renewcommand {\u} { {\vec u} }
\newcommand{\I}{\vec{I}}
Time Domain Electromagnetics
****************************
.. _api_TDEM_derivation:
Time-Domain EM Derivation
=========================
The following shows the derivation for the TDEM problem. We use the b-formulation below.
(More to come soon..!)
Sensitivity Calculation
-----------------------
.. math::
\begin{align}
\dcurl \e^{(t+1)} + \frac{\b^{(t+1)} - \b^{(t)}}{\delta t} = 0 \\
\dcurl^\top \MfMui \b^{(t+1)} - \MeSig \e^{(t+1)} = \Me \j_s^{(t+1)}
\end{align}
Using Gauss-Newton to solve the inverse problem requires the ability to calculate the product of the
Jacobian and a vector, as well as the transpose of the Jacobian times a vector.
The above system can be rewritten as:
.. math::
\begin{align}
\mathbf{A} \u^{(t+1)} + \mathbf{B} \u^{(t)}= \s^{(t+1)}
\end{align}
where
.. math::
\begin{align}
\mathbf{A} =
\left[
\begin{array}{cc}
\frac{1}{\delta t} \MfMui & \MfMui\dcurl \\
\dcurl^\top \MfMui & -\MeSig
\end{array}
\right] \\
\mathbf{B} =
\left[
\begin{array}{cc}
-\frac{1}{\delta t} \MfMui & 0 \\
0 & 0
\end{array}
\right] \\
\u^{(k)} = \left[
\begin{array}{c}
\b^{(k)}\\
\e^{(k)}
\end{array}
\right] \\
\s^{(k)} = \left[
\begin{array}{c}
0\\
\Me \j^{(k)}_s
\end{array}
\right]
\end{align}
.. note::
Here we have multiplied through by \\(\\MfMui\\) to make A and B symmetric!
The entire time dependent system can be written in a single matrix expression
.. math::
\begin{align}
\hat{\mathbf{A}} \hat{u} = \hat{s}
\end{align}
where
.. math::
\begin{align}
\mathbf{\hat{A}} = \left[
\begin{array}{cccc}
A & 0 & & \\
B & A & & \\
& \ddots & \ddots & \\
& & B & A
\end{array}
\right] \\
\hat{u} = \left[
\begin{array}{c}
\u^{(1)} \\
\u^{(2)} \\
\vdots \\
\u^{(N)}
\end{array} \right]\\
\hat{s} = \left[
\begin{array}{c}
\s^{(1)} - \mathbf{B} \u^{(0)} \\
\s^{(2)} \\
\vdots \\
\s^{(N)}
\end{array}
\right]
\end{align}
For the fields \\(\\u\\), the measured data is given by
.. math::
\begin{align}
\vec{d} = \mathbf{Q} \u
\end{align}
The sensitivity matrix **J** is then defined as
.. math::
\begin{align}
\mathbf{J} = \mathbf{Q} \frac{\partial \u}{\partial \sigma}
\end{align}
Defining the function \\(\\c(m,\\u)\\) to be
.. math::
\begin{align}
\vec{c}(m,\u) = \hat{\mathbf{A}} \vec{u} - \vec{q} = \vec{0}
\end{align}
then
.. math::
\begin{align}
\frac{\partial \vec{c}}{\partial m} \partial m
+ \frac{\partial \vec{c}}{\partial \u} \partial \vec{u} = 0
\end{align}
or
.. math::
\begin{align}
\frac{\partial \vec{u}}{\partial m} = -\left(\frac{\partial \vec{c}}{\partial \u} \right)^{-1} \frac{\partial \vec{c}}{\partial m}
\end{align}
Differentiating, we find that
.. math::
\begin{align}
\frac{\partial \vec{c}}{\partial \hat{u}} = \hat{\mathbf{A}}
\end{align}
and
.. math::
\begin{align}
\frac{\partial \vec{c}}{\partial \sigma} = \mathbf{G}_\sigma =
\left[
\begin{array}{c}
g_\sigma^{(1)}\\
g_\sigma^{(2)}\\
\vdots \\
g_\sigma^{(N)}
\end{array}
\right]
\end{align}
with
.. math::
\begin{align}
g_\sigma^{(n)} =
\left[
\begin{array}{c}
\mathbf{0} \\
- \diag{\e^{(n)}} \Ace \diag{\vec{V}}
\end{array}
\right]
\end{align}
Implementing **J** times a vector
---------------------------------
Multiplying **J** onto a vector can be broken into three steps
* Compute \\(\\vec{p} = \\mathbf{G}m\\)
* Solve \\(\\hat{\\mathbf{A}} \\vec{y} = \\vec{p}\\)
* Compute \\(\\vec{w} = -\\mathbf{Q} \\vec{y}\\)
.. math::
\begin{align}
\vec{p}^{(n)} = \left[
\begin{array}{c}
\vec{p}_b^{(n)} \\
\vec{p}_e^{(n)}
\end{array}
\right] \\
\vec{p}_b^{(n)} = 0 \\
\vec{p}_e^{(n)} = - \diag{\e^{(n)}} \Ace \diag{V} m
\end{align}
For all time steps:
.. math::
\begin{align}
\frac{1}{\delta t} \MfMui\vec{y}_{b}^{(t+1)} + \MfMui\dcurl \vec{y}_{e}^{(t+1)}
- \frac{1}{\delta t} \MfMui \vec{y}_{b}^{(t)}
= \vec{p}_b^{(t+1)} \\
\dcurl^\top \MfMui \vec{y}_b^{(t+1)} - \MeSig \vec{y}_e^{(t+1)} = \vec{p}_e^{(t+1)}
\end{align}
and
.. math::
\begin{align}
\left( \MfMui \dcurl \MeSig^{-1} \dcurl^\top \MfMui + \frac{1}{\delta t} \MfMui \right) \vec{y}_{b}^{(t+1)} =
\frac{1}{\delta t} \MfMui \vec{y}_b^{(t)}
+ \MfMui \dcurl \MeSig^{-1} \vec{p}_e^{(t+1)} + \vec{p}_b^{(t+1)} \\
\vec{y}_e^{(t+1)} = \MeSig^{-1} \dcurl^\top \MfMui \vec{y}_b^{(t+1)} - \MeSig^{-1} \vec{p}_e^{(t+1)}
\end{align}
.. note::
For the first time step, \\\(t=0\\\), the term: \\\(\\frac{1}{\\delta t} \\MfMui \\vec{y}_b^{(0)}\\\) is zero.
Implementing **J** transpose times a vector
-------------------------------------------
Multiplying \\(\\mathbf{J}^\\top\\) onto a vector can be broken into three steps
* Compute \\(\\vec{p} = \\mathbf{Q}^\\top \\vec{v}\\)
* Solve \\(\\hat{\\mathbf{A}}^\\top \\vec{y} = \\vec{p}\\)
* Compute \\(\\vec{w} = -\\mathbf{G}^\\top y\\)
.. math::
\mathbf{\hat{A}}^\top = \left[
\begin{array}{cccc}
A & B & & \\
& \ddots & \ddots & \\
& & A & B \\
& & 0 & A
\end{array}
\right]
For the all time-steps (going backwards in time):
.. math::
A \vec{y}^{(t)} + B \vec{y}^{(t+1)} = \vec{p}^{(t)}
.. math::
\begin{align}
\frac{1}{\delta t} \MfMui\vec{y}_{b}^{(t)} + \MfMui\dcurl \vec{y}_{e}^{(t)}
- \frac{1}{\delta t} \MfMui \vec{y}_{b}^{(t+1)}
= \vec{p}_b^{(t)} \\
\dcurl^\top \MfMui \vec{y}_b^{(t)} - \MeSig \vec{y}_e^{(t)} = \vec{p}_e^{(t)}
\end{align}
and
.. math::
\begin{align}
\left( \MfMui \dcurl \MeSig^{-1} \dcurl^\top \MfMui + \frac{1}{\delta t} \MfMui \right) \vec{y}_{b}^{(t)} =
\frac{1}{\delta t} \MfMui \vec{y}_b^{(t+1)}
+ \MfMui \dcurl \MeSig^{-1} \vec{p}_e^{(t)} + \vec{p}_b^{(t)} \\
\vec{y}_e^{(t)} = \MeSig^{-1} \dcurl^\top \MfMui \vec{y}_b^{(t)} - \MeSig^{-1} \vec{p}_e^{(t)}
\end{align}
.. note::
For the last time step, \\\(t=N\\\), the term: \\\(\\frac{1}{\\delta t} \\MfMui \\vec{y}_b^{(N+1)}\\\) is zero.
TDEM - B formulation
====================
.. automodule:: SimPEG.EM.TDEM.TDEM_b
:show-inheritance:
:members:
:undoc-members:
Field Storage
=============
.. autoclass:: SimPEG.EM.TDEM.BaseTDEM.FieldsTDEM
:show-inheritance:
:members:
:undoc-members:
:inherited-members:
TDEM Survey Classes
===================
.. autoclass:: SimPEG.EM.TDEM.SurveyTDEM.SurveyTDEM
:show-inheritance:
:members:
:undoc-members:
:inherited-members:
Base Classes
============
.. automodule:: SimPEG.EM.TDEM.BaseTDEM
:show-inheritance:
:members:
:undoc-members:
:inherited-members:
+34
View File
@@ -0,0 +1,34 @@
simpegEM Utilities
******************
SimPEG for EM provides a few EM specific utility codes,
sources, and analytic functions.
Utilities for Electromagnetics
==============================
.. automodule:: SimPEG.EM.Utils
:show-inheritance:
:members:
:undoc-members:
:inherited-members:
Analytic Functions - Time
=========================
.. automodule:: SimPEG.EM.Analytics.TDEM
:show-inheritance:
:members:
:undoc-members:
:inherited-members:
Analytic Functions - Frequency
==============================
.. automodule:: SimPEG.EM.Analytics.FDEM
:show-inheritance:
:members:
:undoc-members:
:inherited-members:
+33
View File
@@ -0,0 +1,33 @@
Overview of Electromagnetics in SimPEG
**************************************
The API
=======
Physical Properties
-------------------
.. autoclass:: SimPEG.EM.Base.EMPropMap
:show-inheritance:
:members:
:undoc-members:
Problem
-------
.. autoclass:: SimPEG.EM.Base.BaseEMProblem
:show-inheritance:
:members:
:undoc-members:
Survey
------
.. autoclass:: SimPEG.EM.Base.BaseEMSurvey
:show-inheritance:
:members:
:undoc-members:
+27
View File
@@ -0,0 +1,27 @@
Electromagnetics
================
`SimPEG.EM` uses SimPEG as the framework for the forward and inverse
electromagnetics geophysical problems.
To solve for predicted data, we follow the framework shown below. The model is
what we invert for. This is mapped to a physical property on the simulation
mesh. A source which is used to excite the system is specified. Having a model
and a source, we can solve Maxwell's equations for fields. We sample these
fields with recievers to give us predicted data.
.. image:: ../../images/simpegEM_noMath.png
:scale: 50%
.. toctree::
:maxdepth: 2
api_basic
api_FDEM
api_TDEM
api_Utils