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

docs/api_FiniteVolume.rst

@@ -1,19 +0,0 @@
-.. _api_FiniteVolume:
-
-Finite Volume
-*************
-
-Any numerical implementation requires the discretization of continuous functions into discrete approximations. These approximations are typically organized in a mesh, which defines boundaries, locations, and connectivity. Of specific interest to geophysical simulations, we require that averaging, interpolation and differential operators be defined for any mesh. In SimPEG, we have implemented a staggered mimetic finite volume approach (`Hyman and Shashkov, 1999 <http://math.lanl.gov/~mac/papers/numerics/HS99B.pdf>`_). This approach requires the definitions of variables at either cell-centers, nodes, faces, or edges as seen in the figure below.
-
-.. image:: images/finitevolrealestate.png
-   :width: 400 px
-   :alt: FiniteVolume
-   :align: center
-
-
-.. toctree::
-   :maxdepth: 2
-
-   api_Mesh
-   api_DiffOps
-   api_InnerProducts

docs/content/api_core/api_Examples.rst

@@ -7,7 +7,7 @@ Examples
     :maxdepth: 1
     :glob:
 
-    examples/*
+    ../examples/*
 
 
 External Notebooks

docs/content/api_core/api_FiniteVolume.rst

@@ -0,0 +1,27 @@
+.. _api_FiniteVolume:
+
+Finite Volume
+*************
+
+Any numerical implementation requires the discretization of continuous
+functions into discrete approximations. These approximations are typically
+organized in a mesh, which defines boundaries, locations, and connectivity. Of
+specific interest to geophysical simulations, we require that averaging,
+interpolation and differential operators be defined for any mesh. In SimPEG,
+we have implemented a staggered mimetic finite volume approach (`Hyman and
+Shashkov, 1999 <http://math.lanl.gov/~mac/papers/numerics/HS99B.pdf>`_). This
+approach requires the definitions of variables at either cell-centers, nodes,
+faces, or edges as seen in the figure below.
+
+.. image:: ../../images/finitevolrealestate.png
+   :width: 400 px
+   :alt: FiniteVolume
+   :align: center
+
+
+.. toctree::
+   :maxdepth: 2
+
+   api_Mesh
+   api_DiffOps
+   api_InnerProducts

docs/content/api_core/api_ForwardProblem.rst

@@ -52,13 +52,15 @@ We can take the derivative of the PDE:
 
     \nabla_m c(m, u) \partial m + \nabla_u c(m, u) \partial u = 0
 
-If the forward problem is invertible, then we can rearrange for \\(\\frac{\\partial u}{\\partial m}\\):
+If the forward problem is invertible, then we can rearrange for
+\\(\\frac{\\partial u}{\\partial m}\\):
 
 .. math::
 
     J = - P \left( \nabla_u c(m, u) \right)^{-1} \nabla_m c(m, u)
 
-This can often be computed given a vector (i.e. \\(J(v)\\)) rather than stored, as \\(J\\) is a large dense matrix.
+This can often be computed given a vector (i.e. \\(J(v)\\)) rather than
+stored, as \\(J\\) is a large dense matrix.
 
 
 

docs/content/api_core/api_InnerProducts.rst

@@ -4,7 +4,10 @@
 Inner Products
 **************
 
-By using the weak formulation of many of the PDEs in geophysical applications, we can rapidly develop discretizations. Much of this work, however, needs a good understanding of how to approximate inner products on our discretized meshes. We will define the inner product as:
+By using the weak formulation of many of the PDEs in geophysical applications,
+we can rapidly develop discretizations. Much of this work, however, needs a
+good understanding of how to approximate inner products on our discretized
+meshes. We will define the inner product as:
 
 .. math::
 
@@ -14,12 +17,15 @@ where a and b are either scalars or vectors.
 
 .. note::
 
-    The InnerProducts class is a base class providing inner product matrices for meshes and cannot run on its own.
+    The InnerProducts class is a base class providing inner product matrices
+    for meshes and cannot run on its own.
 
 
 Example problem for DC resistivity
 ----------------------------------
-We will start with the formulation of the Direct Current (DC) resistivity problem in geophysics.
+
+We will start with the formulation of the Direct Current (DC) resistivity
+problem in geophysics.
 
 
 .. math::
@@ -28,12 +34,13 @@ We will start with the formulation of the Direct Current (DC) resistivity proble
 
         \nabla\cdot \vec{j} = q
 
-In the following discretization, \\\( \\sigma \\\) and \\\( \\phi \\\)
-will be discretized on the cell-centers and the flux, \\\(\\vec{j}\\\),
+In the following discretization, :math:`\sigma` and :math:`\phi`
+will be discretized on the cell-centers and the flux, :math:`\vec{j}`,
 will be on the faces. We will use the weak formulation to discretize
 the DC resistivity equation.
 
-We can define in weak form by integrating with a general face function \\\(\\vec{f}\\\):
+We can define in weak form by integrating with a general face function
+:math:`\vec{f}`:
 
 .. math::
 
@@ -61,9 +68,16 @@ We can then discretize for every cell:
 
 .. note::
 
-    We have discretized the dot product above, but remember that we do not really have a single vector \\\(\\mathbf{J}\\\), but approximations of \\\(\\vec{j}\\\) on each face of our cell. In 2D that means 2 approximations of \\\(\\mathbf{J}_x\\\) and 2 approximations of \\\(\\mathbf{J}_y\\\). In 3D we also have 2 approximations of \\\(\\mathbf{J}_z\\\).
+    We have discretized the dot product above, but remember that we do not
+    really have a single vector :math:`\mathbf{J}`, but approximations of
+    :math:`\vec{j}` on each face of our cell. In 2D that means 2
+    approximations of :math:`\mathbf{J}_x` and 2 approximations of
+    :math:`\mathbf{J}_y`. In 3D we also have 2 approximations of
+    :math:`\mathbf{J}_z`.
 
-Regardless of how we choose to approximate this dot product, we can represent this in vector form (again this is for every cell), and will generalize for the case of anisotropic (tensor) sigma.
+Regardless of how we choose to approximate this dot product, we can represent
+this in vector form (again this is for every cell), and will generalize for
+the case of anisotropic (tensor) sigma.
 
 .. math::
 
@@ -71,14 +85,17 @@ Regardless of how we choose to approximate this dot product, we can represent th
     -\phi^{\top} v_{\text{cell}} \mathbf{D}_{\text{cell}} \mathbf{F})
     + \text{BC}
 
-We multiply by  square-root of volume on each side of the tensor conductivity to keep symmetry in the system. Here \\\(\\mathbf{J}_c\\\) is the Cartesian \\\(\\mathbf{J}\\\) (on the faces that we choose to use in our approximation) and must be calculated differently depending on the mesh:
+We multiply by  square-root of volume on each side of the tensor conductivity
+to keep symmetry in the system. Here :math:`\mathbf{J}_c` is the Cartesian
+:math:`\mathbf{J}` (on the faces that we choose to use in our approximation)
+and must be calculated differently depending on the mesh:
 
 .. math::
     \mathbf{J}_c = \mathbf{Q}_{(i)}\mathbf{J}_\text{TENSOR} \\
     \mathbf{J}_c = \mathbf{N}_{(i)}^{-1}\mathbf{Q}_{(i)}\mathbf{J}_\text{Curv}
 
-Here the \\\(i\\\) index refers to where we choose to approximate this integral, as discussed in the note above.
-We will approximate this integral by taking the fluxes clustered around every node of the cell, there are 8 combinations in 3D, and 4 in 2D. We will use a projection matrix \\\( \\mathbf{Q}_{(i)} \\\) to pick the appropriate fluxes. So, now that we have 8 approximations of this integral, we will just take the average. For the TensorMesh, this looks like:
+Here the :math:`i` index refers to where we choose to approximate this integral, as discussed in the note above.
+We will approximate this integral by taking the fluxes clustered around every node of the cell, there are 8 combinations in 3D, and 4 in 2D. We will use a projection matrix :math:`\mathbf{Q}_{(i)}` to pick the appropriate fluxes. So, now that we have 8 approximations of this integral, we will just take the average. For the TensorMesh, this looks like:
 
 .. math::
 
@@ -107,10 +124,12 @@ By defining the faceInnerProduct (8 combinations of fluxes in 3D, 4 in 2D, 2 in
         \sum_{i=1}^{2^d}
         \mathbf{P}_{(i)}^{\top} \Sigma^{-1} \mathbf{P}_{(i)}
 
-Where \\\(d\\\) is the dimension of the mesh.
-The \\\( \\mathbf{M}^f \\\) is returned when given the input of \\\( \\Sigma^{-1} \\\).
+Where :math:`d` is the dimension of the mesh.
+The :math:`\mathbf{M}^f` is returned when given the input of :math:`\Sigma^{-1}`.
 
-Here each \\( \\mathbf{P} \\in \\mathbb{R}^{(d*nC, nF)} \\\) is a combination of the projection, volume, and any normalization to Cartesian coordinates (where the dot product is well defined):
+Here each :math:`\mathbf{P} ~ \in ~ \mathbb{R}^{(d*nC, nF)}` is a combination
+of the projection, volume, and any normalization to Cartesian coordinates
+(where the dot product is well defined):
 
 .. math::
 
@@ -129,7 +148,10 @@ If ``returnP=True`` is requested in any of these methods the projection matrices
     # In 1D
     P = [P0, P1]
 
-The derivation for ``edgeInnerProducts`` is exactly the same, however, when we approximate the integral using the fields around each node, the projection matrices look a bit different because we have 12 edges in 3D instead of just 6 faces. The interface to the code is exactly the same.
+The derivation for ``edgeInnerProducts`` is exactly the same, however, when we
+approximate the integral using the fields around each node, the projection
+matrices look a bit different because we have 12 edges in 3D instead of just 6
+faces. The interface to the code is exactly the same.
 
 
 Defining Tensor Properties
@@ -137,7 +159,8 @@ Defining Tensor Properties
 
 **For 3D:**
 
-Depending on the number of columns (either 1, 3, or 6) of mu, the material property is interpreted as follows:
+Depending on the number of columns (either 1, 3, or 6) of mu, the material
+property is interpreted as follows:
 
 .. math::
 
@@ -188,13 +211,16 @@ Which is nice and easy to invert if necessary, however, in the fully anisotropic
 Taking Derivatives
 ------------------
 
-We will take the derivative of the fully anisotropic tensor for a 3D mesh, the other cases are easier and will not be discussed here. Let us start with one part of the sum which makes up \\\(\\mathbf{M}^f_\\Sigma\\\) and take the derivative when this is multiplied by some vector \\\(\\mathbf{v}\\\):
+We will take the derivative of the fully anisotropic tensor for a 3D mesh, the
+other cases are easier and will not be discussed here. Let us start with one
+part of the sum which makes up :math:`\mathbf{M}^f_\Sigma` and take the
+derivative when this is multiplied by some vector :math:`\mathbf{v}`:
 
 .. math::
 
     \mathbf{P}^\top \boldsymbol{\Sigma} \mathbf{Pv}
 
-Here we will let \\\( \\mathbf{Pv} = \\mathbf{y} \\\) and \\\(\\mathbf{y}\\\) will have the form:
+Here we will let :math:`\mathbf{Pv} = \mathbf{y}` and :math:`\mathbf{y}` will have the form:
 
 .. math::
 
@@ -233,7 +259,9 @@ Here we will let \\\( \\mathbf{Pv} = \\mathbf{y} \\\) and \\\(\\mathbf{y}\\\) wi
         \end{matrix}
     \right]
 
-Now it is easy to take the derivative with respect to any one of the parameters, for example, \\\(\\frac{\\partial}{\\partial\\boldsymbol{\\sigma}_1}\\\)
+Now it is easy to take the derivative with respect to any one of the
+parameters, for example,
+:math:`\frac{\partial}{\partial\boldsymbol{\sigma}_1}`
 
 .. math::
     \frac{\partial}{\partial \boldsymbol{\sigma}_1}\left(\mathbf{P}^\top\Sigma\mathbf{y}\right)
@@ -247,7 +275,8 @@ Now it is easy to take the derivative with respect to any one of the parameters,
         \end{matrix}
     \right]
 
-Whereas \\\(\\frac{\\partial}{\\partial\\boldsymbol{\\sigma}_4}\\\), for example, is:
+Whereas :math:`\frac{\partial}{\partial\boldsymbol{\sigma}_4}`, for
+example, is:
 
 .. math::
     \frac{\partial}{\partial \boldsymbol{\sigma}_4}\left(\mathbf{P}^\top\Sigma\mathbf{y}\right)
@@ -261,7 +290,8 @@ Whereas \\\(\\frac{\\partial}{\\partial\\boldsymbol{\\sigma}_4}\\\), for example
         \end{matrix}
     \right]
 
-These are computed for each of the 8 projections, horizontally concatenated, and returned.
+These are computed for each of the 8 projections, horizontally concatenated,
+and returned.
 
 The API
 -------

docs/content/api_core/api_bigPicture.rst

@@ -35,7 +35,7 @@ The Big Picture
 Defining a well-posed inverse problem and solving it is a complex task that requires many components that must interact. It is helpful
 to view this task as a workflow in which various elements are explicitly identified and integrated. The figure below outlines the inversion components that consists of inputs, implementation, and evaluation. The inputs are composed of the geophysical data, the equations which are a mathematical description of the governing physics, and prior knowledge or assumptions about the setting. The implementation consists of two broad categories: the forward simulation and the inversion. The **forward simulation** is the means by which we solve the governing equations given a model and the **inversion components** evaluate and update this model. We are considering a gradient based approach, which updates the model through an optimization routine. The output of this implementation is a model, which, prior to interpretation, must be evaluated. This requires considering, and often re-assessing, the choices and assumptions made in both the input and implementation stages.
 
-.. image:: InversionWorkflow-PreSimPEG.png
+.. image:: ../../images/InversionWorkflow-PreSimPEG.png
    :width: 400 px
    :alt: Components
    :align: center
@@ -46,7 +46,7 @@ A Comprehensive Framework
 
 There are an overwhelming amount of choices to be made as one works through the forward modeling and inversion process (see figure above). As a result, software implementations of this workflow often become complex and highly interdependent, making it difficult to interact with and to ask other scientists to pick up and change. Our approach to handling this complexity is to propose a framework, (see below), that compartmentalizes the implementation of inversions into various units. We present it in this specific modular style, as each unit contains a targeted subset of choices crucial to the inversion process.
 
-.. image:: InversionWorkflow.png
+.. image:: ../../images/InversionWorkflow.png
    :width: 400 px
    :alt: Framework
    :align: center
@@ -56,14 +56,14 @@ The process of obtaining an acceptable model from an inversion generally require
 The arrows in the figure above indicate what each class takes as a primary argument. For example, both the :class:`SimPEG.Problem.BaseProblem` and :class:`SimPEG.Regularization.BaseRegularization` classes take a :class:`SimPEG.Mesh.BaseMesh.BaseMesh` class as an argument. The diagram does not show class inheritance, as each of the base classes outlined have many subtypes that can be interchanged. The :class:`SimPEG.Mesh.BaseMesh.BaseMesh` class, for example, could be a regular Cartesian mesh :class:`SimPEG.Mesh.TensorMesh` or a cylindrical coordinate mesh :class:`SimPEG.Mesh.CylMesh`, which have many properties in common. These common features, such as both meshes being created from tensor products, can be exploited through inheritance of base classes, and differences can be expressed through subtype polymorphism. Please look at the documentation here for more in-depth information.
 
 
-.. include:: ../CITATION.rst
+.. include:: ../../../CITATION.rst
 
 Authors
 -------
 
-.. include:: ../AUTHORS.rst
+.. include:: ../../../AUTHORS.rst
 
 License
 -------
 
-.. include:: ../LICENSE
+.. include:: ../../../LICENSE

docs/content/em/api_FDEM.rst

@@ -9,17 +9,28 @@
 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.
+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.
+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
+
+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 \\
@@ -31,6 +42,7 @@ where :math:`\omega` is angular frequency, :math:`t` is time, :math:`F(\omega)`
 
 Maxwell's Equations
 ===================
+
 In the frequency domain, Maxwell's equations are given by
 
 .. math ::
@@ -104,19 +116,20 @@ The H-J formulation is in terms of the current density and the magnetic field:
 
 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
+.. 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
+.. figure:: ../../images/ebjhdiscretizations.png
     :align: center
     :scale: 60 %
 

docs/content/em/index.rst

@@ -12,7 +12,7 @@ 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
+.. image:: ../../images/simpegEM_noMath.png
     :scale: 50%
 
 

docs/examples/Inversion_IRLS.rst

@@ -1,26 +0,0 @@
-.. _examples_Inversion_IRLS:
-
-.. --------------------------------- ..
-..                                   ..
-..    THIS FILE IS AUTO GENEREATED   ..
-..                                   ..
-..    SimPEG/Examples/__init__.py    ..
-..                                   ..
-.. --------------------------------- ..
-
-
-Inversion: Linear Problem
-=========================
-
-Here we go over the basics of creating a linear problem and inversion.
-
-
-
-.. plot::
-
-    from SimPEG import Examples
-    Examples.Inversion_IRLS.run()
-
-.. literalinclude:: ../../SimPEG/Examples/Inversion_IRLS.py
-    :language: python
-    :linenos:

docs/index.rst

@@ -41,8 +41,8 @@ About SimPEG
 .. toctree::
    :maxdepth: 2
 
-   api_bigPicture
-   api_installing
+   content/api_core/api_bigPicture
+   content/api_core/api_installing
 
 Examples
 ********
@@ -50,7 +50,7 @@ Examples
 .. toctree::
    :maxdepth: 2
 
-   api_Examples
+   content/api_core/api_Examples
 
 Packages
 ********
@@ -58,11 +58,11 @@ Packages
 .. toctree::
    :maxdepth: 3
 
-   em/index
-   dc/index
-   ip/index
-   mt/index
-   flow/index
+   content/em/index
+   content/dc/index
+   content/ip/index
+   content/mt/index
+   content/flow/index
 
 Finite Volume
 *************
@@ -70,7 +70,7 @@ Finite Volume
 .. toctree::
    :maxdepth: 3
 
-   api_FiniteVolume
+   content/api_core/api_FiniteVolume
 
 Forward Problems
 ****************
@@ -78,7 +78,7 @@ Forward Problems
 .. toctree::
    :maxdepth: 3
 
-   api_ForwardProblem
+   content/api_core/api_ForwardProblem
 
 Inversion Components
 ********************
@@ -86,7 +86,7 @@ Inversion Components
 .. toctree::
    :maxdepth: 3
 
-   api_InversionComponents
+   content/api_core/api_InversionComponents
 
 Utility Codes
 *************
@@ -94,7 +94,7 @@ Utility Codes
 .. toctree::
    :maxdepth: 3
 
-   api_Utilities
+   content/api_core/api_Utilities
 
 
 Project Index & Search