From 5e8d3fbc782e7286cfa7d15602c322651fcbcada Mon Sep 17 00:00:00 2001 From: Lindsey Heagy Date: Mon, 30 May 2016 17:06:29 -0700 Subject: [PATCH] organizing the docs - put the content in a `content` folder. put the SimPEG core api docs in `core_api` --- SimPEG/Examples/__init__.py | 6 +- docs/api_FiniteVolume.rst | 19 ----- .../{ => content/api_core}/api_DataMisfit.rst | 0 docs/{ => content/api_core}/api_DiffOps.rst | 0 docs/{ => content/api_core}/api_Examples.rst | 2 +- docs/content/api_core/api_FiniteVolume.rst | 27 +++++++ .../api_core}/api_ForwardProblem.rst | 6 +- .../api_core}/api_InnerProducts.rst | 72 +++++++++++++----- docs/{ => content/api_core}/api_Inversion.rst | 0 .../api_core}/api_InversionComponents.rst | 0 docs/{ => content/api_core}/api_Maps.rst | 0 docs/{ => content/api_core}/api_Mesh.rst | 0 docs/{ => content/api_core}/api_MeshCode.rst | 0 .../api_core}/api_Optimization.rst | 0 docs/{ => content/api_core}/api_PropMaps.rst | 0 .../api_core}/api_Regularization.rst | 0 docs/{ => content/api_core}/api_Solver.rst | 0 docs/{ => content/api_core}/api_Tests.rst | 0 docs/{ => content/api_core}/api_Utilities.rst | 0 docs/{ => content/api_core}/api_Utils.rst | 0 .../{ => content/api_core}/api_bigPicture.rst | 10 +-- .../{ => content/api_core}/api_installing.rst | 0 docs/{ => content}/dc/index.rst | 0 docs/{ => content}/em/api_FDEM.rst | 23 ++++-- docs/{ => content}/em/api_TDEM.rst | 0 docs/{ => content}/em/api_Utils.rst | 0 docs/{ => content}/em/api_basic.rst | 0 docs/{ => content}/em/index.rst | 2 +- .../examples/DC_Analytic_Dipole.rst | 0 .../examples/DC_Forward_PseudoSection.rst | 0 .../examples/EM_FDEM_1D_Inversion.rst | 0 .../EM_FDEM_Analytic_MagDipoleWholespace.rst | 0 .../examples/EM_Schenkel_Morrison_Casing.rst | 0 .../examples/EM_TDEM_1D_Inversion.rst | 0 .../examples/FLOW_Richards_1D_Celia1990.rst | 0 .../examples/Inversion_Linear.rst | 0 .../examples/MT_1D_ForwardAndInversion.rst | 0 docs/{ => content}/examples/MT_3D_Foward.rst | 0 .../examples/Mesh_Basic_ForwardDC.rst | 0 .../examples/Mesh_Basic_PlotImage.rst | 0 .../examples/Mesh_Basic_Types.rst | 0 .../examples/Mesh_Operators_CahnHilliard.rst | 0 .../examples/Mesh_QuadTree_Creation.rst | 0 .../examples/Mesh_QuadTree_FaceDiv.rst | 0 .../examples/Mesh_QuadTree_HangingNodes.rst | 0 .../examples/Mesh_Tensor_Creation.rst | 0 .../examples/Utils_surface2ind_topo.rst | 0 docs/{ => content}/flow/index.rst | 0 docs/{ => content}/ip/index.rst | 0 docs/{ => content}/mt/index.rst | 0 docs/examples/Inversion_IRLS.rst | 26 ------- .../InversionWorkflow-PreSimPEG.png | Bin docs/{ => images}/InversionWorkflow.png | Bin docs/{ => images}/SimPEGFrameworkRevised.png | Bin docs/{ => images}/simpeg-framework.png | Bin docs/{ => images}/simpeg-logo.png | Bin docs/index.rst | 24 +++--- 57 files changed, 122 insertions(+), 95 deletions(-) delete mode 100644 docs/api_FiniteVolume.rst rename docs/{ => content/api_core}/api_DataMisfit.rst (100%) rename docs/{ => content/api_core}/api_DiffOps.rst (100%) rename docs/{ => content/api_core}/api_Examples.rst (93%) create mode 100644 docs/content/api_core/api_FiniteVolume.rst rename docs/{ => content/api_core}/api_ForwardProblem.rst (94%) rename docs/{ => content/api_core}/api_InnerProducts.rst (75%) rename docs/{ => content/api_core}/api_Inversion.rst (100%) rename docs/{ => content/api_core}/api_InversionComponents.rst (100%) rename docs/{ => content/api_core}/api_Maps.rst (100%) rename docs/{ => content/api_core}/api_Mesh.rst (100%) rename docs/{ => content/api_core}/api_MeshCode.rst (100%) rename docs/{ => content/api_core}/api_Optimization.rst (100%) rename docs/{ => content/api_core}/api_PropMaps.rst (100%) rename docs/{ => content/api_core}/api_Regularization.rst (100%) rename docs/{ => content/api_core}/api_Solver.rst (100%) rename docs/{ => content/api_core}/api_Tests.rst (100%) rename docs/{ => content/api_core}/api_Utilities.rst (100%) rename docs/{ => content/api_core}/api_Utils.rst (100%) rename docs/{ => content/api_core}/api_bigPicture.rst (97%) rename docs/{ => content/api_core}/api_installing.rst (100%) rename docs/{ => content}/dc/index.rst (100%) rename docs/{ => content}/em/api_FDEM.rst (87%) rename docs/{ => content}/em/api_TDEM.rst (100%) rename docs/{ => content}/em/api_Utils.rst (100%) rename docs/{ => content}/em/api_basic.rst (100%) rename docs/{ => content}/em/index.rst (93%) rename docs/{ => content}/examples/DC_Analytic_Dipole.rst (100%) rename docs/{ => content}/examples/DC_Forward_PseudoSection.rst (100%) rename docs/{ => content}/examples/EM_FDEM_1D_Inversion.rst (100%) rename docs/{ => content}/examples/EM_FDEM_Analytic_MagDipoleWholespace.rst (100%) rename docs/{ => content}/examples/EM_Schenkel_Morrison_Casing.rst (100%) rename docs/{ => content}/examples/EM_TDEM_1D_Inversion.rst (100%) rename docs/{ => content}/examples/FLOW_Richards_1D_Celia1990.rst (100%) rename docs/{ => content}/examples/Inversion_Linear.rst (100%) rename docs/{ => content}/examples/MT_1D_ForwardAndInversion.rst (100%) rename docs/{ => content}/examples/MT_3D_Foward.rst (100%) rename docs/{ => content}/examples/Mesh_Basic_ForwardDC.rst (100%) rename docs/{ => content}/examples/Mesh_Basic_PlotImage.rst (100%) rename docs/{ => content}/examples/Mesh_Basic_Types.rst (100%) rename docs/{ => content}/examples/Mesh_Operators_CahnHilliard.rst (100%) rename docs/{ => content}/examples/Mesh_QuadTree_Creation.rst (100%) rename docs/{ => content}/examples/Mesh_QuadTree_FaceDiv.rst (100%) rename docs/{ => content}/examples/Mesh_QuadTree_HangingNodes.rst (100%) rename docs/{ => content}/examples/Mesh_Tensor_Creation.rst (100%) rename docs/{ => content}/examples/Utils_surface2ind_topo.rst (100%) rename docs/{ => content}/flow/index.rst (100%) rename docs/{ => content}/ip/index.rst (100%) rename docs/{ => content}/mt/index.rst (100%) delete mode 100644 docs/examples/Inversion_IRLS.rst rename docs/{ => images}/InversionWorkflow-PreSimPEG.png (100%) rename docs/{ => images}/InversionWorkflow.png (100%) rename docs/{ => images}/SimPEGFrameworkRevised.png (100%) rename docs/{ => images}/simpeg-framework.png (100%) rename docs/{ => images}/simpeg-logo.png (100%) diff --git a/SimPEG/Examples/__init__.py b/SimPEG/Examples/__init__.py index 3c771f77..e788cd4c 100644 --- a/SimPEG/Examples/__init__.py +++ b/SimPEG/Examples/__init__.py @@ -38,7 +38,7 @@ if __name__ == '__main__': # Create the examples dir in the docs folder. fName = os.path.realpath(__file__) - docExamplesDir = os.path.sep.join(fName.split(os.path.sep)[:-3] + ['docs', 'examples']) + docExamplesDir = os.path.sep.join(fName.split(os.path.sep)[:-3] + ['docs', 'content', 'examples']) shutil.rmtree(docExamplesDir) os.makedirs(docExamplesDir) @@ -95,12 +95,12 @@ if __name__ == '__main__': from SimPEG import Examples Examples.%s.run() -.. literalinclude:: ../../SimPEG/Examples/%s.py +.. literalinclude:: ../../../../SimPEG/Examples/%s.py :language: python :linenos: """%(name,doc,name,name) - rst = os.path.sep.join((filePath.split(os.path.sep)[:-3] + ['docs', 'examples', name + '.rst'])) + rst = os.path.sep.join((filePath.split(os.path.sep)[:-3] + ['docs', 'content', 'examples', name + '.rst'])) print 'Creating: %s.rst'%name f = open(rst, 'w') diff --git a/docs/api_FiniteVolume.rst b/docs/api_FiniteVolume.rst deleted file mode 100644 index 40e9b879..00000000 --- a/docs/api_FiniteVolume.rst +++ /dev/null @@ -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 `_). 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 diff --git a/docs/api_DataMisfit.rst b/docs/content/api_core/api_DataMisfit.rst similarity index 100% rename from docs/api_DataMisfit.rst rename to docs/content/api_core/api_DataMisfit.rst diff --git a/docs/api_DiffOps.rst b/docs/content/api_core/api_DiffOps.rst similarity index 100% rename from docs/api_DiffOps.rst rename to docs/content/api_core/api_DiffOps.rst diff --git a/docs/api_Examples.rst b/docs/content/api_core/api_Examples.rst similarity index 93% rename from docs/api_Examples.rst rename to docs/content/api_core/api_Examples.rst index 68589fb3..40b34949 100644 --- a/docs/api_Examples.rst +++ b/docs/content/api_core/api_Examples.rst @@ -7,7 +7,7 @@ Examples :maxdepth: 1 :glob: - examples/* + ../examples/* External Notebooks diff --git a/docs/content/api_core/api_FiniteVolume.rst b/docs/content/api_core/api_FiniteVolume.rst new file mode 100644 index 00000000..7952c56a --- /dev/null +++ b/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 `_). 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 diff --git a/docs/api_ForwardProblem.rst b/docs/content/api_core/api_ForwardProblem.rst similarity index 94% rename from docs/api_ForwardProblem.rst rename to docs/content/api_core/api_ForwardProblem.rst index 250a3618..7d85aab5 100644 --- a/docs/api_ForwardProblem.rst +++ b/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. diff --git a/docs/api_InnerProducts.rst b/docs/content/api_core/api_InnerProducts.rst similarity index 75% rename from docs/api_InnerProducts.rst rename to docs/content/api_core/api_InnerProducts.rst index 13d532eb..b1d253b1 100644 --- a/docs/api_InnerProducts.rst +++ b/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 ------- diff --git a/docs/api_Inversion.rst b/docs/content/api_core/api_Inversion.rst similarity index 100% rename from docs/api_Inversion.rst rename to docs/content/api_core/api_Inversion.rst diff --git a/docs/api_InversionComponents.rst b/docs/content/api_core/api_InversionComponents.rst similarity index 100% rename from docs/api_InversionComponents.rst rename to docs/content/api_core/api_InversionComponents.rst diff --git a/docs/api_Maps.rst b/docs/content/api_core/api_Maps.rst similarity index 100% rename from docs/api_Maps.rst rename to docs/content/api_core/api_Maps.rst diff --git a/docs/api_Mesh.rst b/docs/content/api_core/api_Mesh.rst similarity index 100% rename from docs/api_Mesh.rst rename to docs/content/api_core/api_Mesh.rst diff --git a/docs/api_MeshCode.rst b/docs/content/api_core/api_MeshCode.rst similarity index 100% rename from docs/api_MeshCode.rst rename to docs/content/api_core/api_MeshCode.rst diff --git a/docs/api_Optimization.rst b/docs/content/api_core/api_Optimization.rst similarity index 100% rename from docs/api_Optimization.rst rename to docs/content/api_core/api_Optimization.rst diff --git a/docs/api_PropMaps.rst b/docs/content/api_core/api_PropMaps.rst similarity index 100% rename from docs/api_PropMaps.rst rename to docs/content/api_core/api_PropMaps.rst diff --git a/docs/api_Regularization.rst b/docs/content/api_core/api_Regularization.rst similarity index 100% rename from docs/api_Regularization.rst rename to docs/content/api_core/api_Regularization.rst diff --git a/docs/api_Solver.rst b/docs/content/api_core/api_Solver.rst similarity index 100% rename from docs/api_Solver.rst rename to docs/content/api_core/api_Solver.rst diff --git a/docs/api_Tests.rst b/docs/content/api_core/api_Tests.rst similarity index 100% rename from docs/api_Tests.rst rename to docs/content/api_core/api_Tests.rst diff --git a/docs/api_Utilities.rst b/docs/content/api_core/api_Utilities.rst similarity index 100% rename from docs/api_Utilities.rst rename to docs/content/api_core/api_Utilities.rst diff --git a/docs/api_Utils.rst b/docs/content/api_core/api_Utils.rst similarity index 100% rename from docs/api_Utils.rst rename to docs/content/api_core/api_Utils.rst diff --git a/docs/api_bigPicture.rst b/docs/content/api_core/api_bigPicture.rst similarity index 97% rename from docs/api_bigPicture.rst rename to docs/content/api_core/api_bigPicture.rst index e24037ab..0b0f1110 100644 --- a/docs/api_bigPicture.rst +++ b/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 diff --git a/docs/api_installing.rst b/docs/content/api_core/api_installing.rst similarity index 100% rename from docs/api_installing.rst rename to docs/content/api_core/api_installing.rst diff --git a/docs/dc/index.rst b/docs/content/dc/index.rst similarity index 100% rename from docs/dc/index.rst rename to docs/content/dc/index.rst diff --git a/docs/em/api_FDEM.rst b/docs/content/em/api_FDEM.rst similarity index 87% rename from docs/em/api_FDEM.rst rename to docs/content/em/api_FDEM.rst index 60b38d1c..65589c70 100644 --- a/docs/em/api_FDEM.rst +++ b/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 % diff --git a/docs/em/api_TDEM.rst b/docs/content/em/api_TDEM.rst similarity index 100% rename from docs/em/api_TDEM.rst rename to docs/content/em/api_TDEM.rst diff --git a/docs/em/api_Utils.rst b/docs/content/em/api_Utils.rst similarity index 100% rename from docs/em/api_Utils.rst rename to docs/content/em/api_Utils.rst diff --git a/docs/em/api_basic.rst b/docs/content/em/api_basic.rst similarity index 100% rename from docs/em/api_basic.rst rename to docs/content/em/api_basic.rst diff --git a/docs/em/index.rst b/docs/content/em/index.rst similarity index 93% rename from docs/em/index.rst rename to docs/content/em/index.rst index 4f95a339..c94c6fc2 100644 --- a/docs/em/index.rst +++ b/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% diff --git a/docs/examples/DC_Analytic_Dipole.rst b/docs/content/examples/DC_Analytic_Dipole.rst similarity index 100% rename from docs/examples/DC_Analytic_Dipole.rst rename to docs/content/examples/DC_Analytic_Dipole.rst diff --git a/docs/examples/DC_Forward_PseudoSection.rst b/docs/content/examples/DC_Forward_PseudoSection.rst similarity index 100% rename from docs/examples/DC_Forward_PseudoSection.rst rename to docs/content/examples/DC_Forward_PseudoSection.rst diff --git a/docs/examples/EM_FDEM_1D_Inversion.rst b/docs/content/examples/EM_FDEM_1D_Inversion.rst similarity index 100% rename from docs/examples/EM_FDEM_1D_Inversion.rst rename to docs/content/examples/EM_FDEM_1D_Inversion.rst diff --git a/docs/examples/EM_FDEM_Analytic_MagDipoleWholespace.rst b/docs/content/examples/EM_FDEM_Analytic_MagDipoleWholespace.rst similarity index 100% rename from docs/examples/EM_FDEM_Analytic_MagDipoleWholespace.rst rename to docs/content/examples/EM_FDEM_Analytic_MagDipoleWholespace.rst diff --git a/docs/examples/EM_Schenkel_Morrison_Casing.rst b/docs/content/examples/EM_Schenkel_Morrison_Casing.rst similarity index 100% rename from docs/examples/EM_Schenkel_Morrison_Casing.rst rename to docs/content/examples/EM_Schenkel_Morrison_Casing.rst diff --git a/docs/examples/EM_TDEM_1D_Inversion.rst b/docs/content/examples/EM_TDEM_1D_Inversion.rst similarity index 100% rename from docs/examples/EM_TDEM_1D_Inversion.rst rename to docs/content/examples/EM_TDEM_1D_Inversion.rst diff --git a/docs/examples/FLOW_Richards_1D_Celia1990.rst b/docs/content/examples/FLOW_Richards_1D_Celia1990.rst similarity index 100% rename from docs/examples/FLOW_Richards_1D_Celia1990.rst rename to docs/content/examples/FLOW_Richards_1D_Celia1990.rst diff --git a/docs/examples/Inversion_Linear.rst b/docs/content/examples/Inversion_Linear.rst similarity index 100% rename from docs/examples/Inversion_Linear.rst rename to docs/content/examples/Inversion_Linear.rst diff --git a/docs/examples/MT_1D_ForwardAndInversion.rst b/docs/content/examples/MT_1D_ForwardAndInversion.rst similarity index 100% rename from docs/examples/MT_1D_ForwardAndInversion.rst rename to docs/content/examples/MT_1D_ForwardAndInversion.rst diff --git a/docs/examples/MT_3D_Foward.rst b/docs/content/examples/MT_3D_Foward.rst similarity index 100% rename from docs/examples/MT_3D_Foward.rst rename to docs/content/examples/MT_3D_Foward.rst diff --git a/docs/examples/Mesh_Basic_ForwardDC.rst b/docs/content/examples/Mesh_Basic_ForwardDC.rst similarity index 100% rename from docs/examples/Mesh_Basic_ForwardDC.rst rename to docs/content/examples/Mesh_Basic_ForwardDC.rst diff --git a/docs/examples/Mesh_Basic_PlotImage.rst b/docs/content/examples/Mesh_Basic_PlotImage.rst similarity index 100% rename from docs/examples/Mesh_Basic_PlotImage.rst rename to docs/content/examples/Mesh_Basic_PlotImage.rst diff --git a/docs/examples/Mesh_Basic_Types.rst b/docs/content/examples/Mesh_Basic_Types.rst similarity index 100% rename from docs/examples/Mesh_Basic_Types.rst rename to docs/content/examples/Mesh_Basic_Types.rst diff --git a/docs/examples/Mesh_Operators_CahnHilliard.rst b/docs/content/examples/Mesh_Operators_CahnHilliard.rst similarity index 100% rename from docs/examples/Mesh_Operators_CahnHilliard.rst rename to docs/content/examples/Mesh_Operators_CahnHilliard.rst diff --git a/docs/examples/Mesh_QuadTree_Creation.rst b/docs/content/examples/Mesh_QuadTree_Creation.rst similarity index 100% rename from docs/examples/Mesh_QuadTree_Creation.rst rename to docs/content/examples/Mesh_QuadTree_Creation.rst diff --git a/docs/examples/Mesh_QuadTree_FaceDiv.rst b/docs/content/examples/Mesh_QuadTree_FaceDiv.rst similarity index 100% rename from docs/examples/Mesh_QuadTree_FaceDiv.rst rename to docs/content/examples/Mesh_QuadTree_FaceDiv.rst diff --git a/docs/examples/Mesh_QuadTree_HangingNodes.rst b/docs/content/examples/Mesh_QuadTree_HangingNodes.rst similarity index 100% rename from docs/examples/Mesh_QuadTree_HangingNodes.rst rename to docs/content/examples/Mesh_QuadTree_HangingNodes.rst diff --git a/docs/examples/Mesh_Tensor_Creation.rst b/docs/content/examples/Mesh_Tensor_Creation.rst similarity index 100% rename from docs/examples/Mesh_Tensor_Creation.rst rename to docs/content/examples/Mesh_Tensor_Creation.rst diff --git a/docs/examples/Utils_surface2ind_topo.rst b/docs/content/examples/Utils_surface2ind_topo.rst similarity index 100% rename from docs/examples/Utils_surface2ind_topo.rst rename to docs/content/examples/Utils_surface2ind_topo.rst diff --git a/docs/flow/index.rst b/docs/content/flow/index.rst similarity index 100% rename from docs/flow/index.rst rename to docs/content/flow/index.rst diff --git a/docs/ip/index.rst b/docs/content/ip/index.rst similarity index 100% rename from docs/ip/index.rst rename to docs/content/ip/index.rst diff --git a/docs/mt/index.rst b/docs/content/mt/index.rst similarity index 100% rename from docs/mt/index.rst rename to docs/content/mt/index.rst diff --git a/docs/examples/Inversion_IRLS.rst b/docs/examples/Inversion_IRLS.rst deleted file mode 100644 index 64a072f1..00000000 --- a/docs/examples/Inversion_IRLS.rst +++ /dev/null @@ -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: diff --git a/docs/InversionWorkflow-PreSimPEG.png b/docs/images/InversionWorkflow-PreSimPEG.png similarity index 100% rename from docs/InversionWorkflow-PreSimPEG.png rename to docs/images/InversionWorkflow-PreSimPEG.png diff --git a/docs/InversionWorkflow.png b/docs/images/InversionWorkflow.png similarity index 100% rename from docs/InversionWorkflow.png rename to docs/images/InversionWorkflow.png diff --git a/docs/SimPEGFrameworkRevised.png b/docs/images/SimPEGFrameworkRevised.png similarity index 100% rename from docs/SimPEGFrameworkRevised.png rename to docs/images/SimPEGFrameworkRevised.png diff --git a/docs/simpeg-framework.png b/docs/images/simpeg-framework.png similarity index 100% rename from docs/simpeg-framework.png rename to docs/images/simpeg-framework.png diff --git a/docs/simpeg-logo.png b/docs/images/simpeg-logo.png similarity index 100% rename from docs/simpeg-logo.png rename to docs/images/simpeg-logo.png diff --git a/docs/index.rst b/docs/index.rst index 8b27ee1b..fb6fb4f3 100644 --- a/docs/index.rst +++ b/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