GEOPY-2111: Add docs on rotated gradient options

docs/_toc.yml

@@ -4,15 +4,18 @@
 format: jb-book
 root: intro
 chapters:
-- file: inversion/index
+- file: fundamentals/index
   sections:
-  - file: inversion/fundamentals
-  - file: inversion/data_misfit
-  - file: inversion/regularization
-  - file: inversion/mesh_design
-  - file: inversion/joint_inversion
-  - file: inversion/depth_of_investigation
-  - file: inversion/optimization
+  - file: fundamentals/background
+  - file: fundamentals/data_misfit
+  - file: fundamentals/regularization/regularization
+    sections:
+    - file: fundamentals/regularization/sparse
+    - file: fundamentals/regularization/rotated_gradients
+  - file: fundamentals/mesh_design
+  - file: fundamentals/joint_inversion
+  - file: fundamentals/depth_of_investigation
+  - file: fundamentals/optimization
 - file: tutorials/introduction
   sections:
   - file: tutorials/background

docs/case_studies/Forrestania/forrestania.ipynb

@@ -5,7 +5,7 @@
    "id": "34c04eea-4ec5-468f-90aa-0f4bea2b44f3",
    "metadata": {},
    "source": [
-    "(forrestania)=\n",
+    "(forrestania-main)=\n",
     "\n",
     "# Forrestania: Joint grav/mag\n",
     "\n",
@@ -29,6 +29,14 @@
     "\n",
     "- [Gravity](gravity-code)\n",
     "- [Magnetics](magnetics-code)\n",
+    "```\n",
+    "\n",
+    "```{table}\n",
+    "| **Authors** |  |\n",
+    "|  :--- | :--- |\n",
+    "| [Glenn Pears](https://www.mirageoscience.com/consulting-services/geological-consultants-and-geophysical-consultants/#gp) | glennp@mirageoscience.com |\n",
+    "| [Polyanna Rowe](https://github.com/polyye) |  polyannar@mirageoscience.com |\n",
+    "| [Dominique Fournier](https://github.com/domfournier) |  dominiquef@mirageoscience.com |\n",
     "```"
    ]
   },

docs/case_studies/Forrestania/open_code.ipynb

@@ -14,7 +14,7 @@
     "---\n",
     "```\n",
     "\n",
-    "This section demonstrates the processing and inversion of the Forrestania datasets using purely open-source packages. For an equivalent and streamlined version, see the parent [Forrestania](#Forrestania) case study.\n",
+    "This section demonstrates the processing and inversion of the Forrestania datasets using purely open-source packages. For an equivalent and streamlined version, see the parent [Forrestania](forrestania-main) case study.\n",
     "\n",
     "- [Gravity inversion](gravity-code)\n",
     "- [Magnetics inversion](magnetics-code)\n",

docs/case_studies/Forrestania/python_code/joint_grav_mag.ipynb

@@ -35,6 +35,13 @@
     "> This workflow closely follows the methodology and structure of the official [SimPEG Tutorials](https://simpeg.xyz/user-tutorials/).\n",
     "\n",
     "```{figure} ../images/open_code.png\n",
+    "```\n",
+    "\n",
+    "```{table}\n",
+    "| **Authors** |  |\n",
+    "|  :--- | :--- |\n",
+    "| [Polyanna Rowe](https://github.com/polyye) |  polyannar@mirageoscience.com |\n",
+    "| [Dominique Fournier](https://github.com/domfournier) |  dominiquef@mirageoscience.com |\n",
     "```"
    ]
   },

docs/case_studies/Forrestania/python_code/unconstrained_gravity_inv_training.ipynb

@@ -12,7 +12,7 @@
     "This section demonstrates the processing and inversion of the **Forrestania gravity dataset** using purely open-source packages.\n",
     "\n",
     "For an equivalent and streamlined version, see the parent case study here:  \n",
-    "👉 [Forrestania Case Study](https://mirageoscience-simpeg-drivers.readthedocs-hosted.com/en/geopy-2297/case_studies/Forrestania/forrestania.html#forrestania)\n",
+    "👉 [Forrestania Case Study](forrestania-main)\n",
     "\n",
     "> 💡 **Note**:  \n",
     "> The steps taken in this tutorial are strongly based on the official [SimPEG Tutorials](https://simpeg.xyz/user-tutorials/).\n",
@@ -21,6 +21,14 @@
     "---\n",
     "name: Landing Image\n",
     "---\n",
+    "```\n",
+    "\n",
+    "\n",
+    "```{table}\n",
+    "| **Authors** |  |\n",
+    "|  :--- | :--- |\n",
+    "| [Polyanna Rowe](https://github.com/polyye) |  polyannar@mirageoscience.com |\n",
+    "| [Dominique Fournier](https://github.com/domfournier) |  dominiquef@mirageoscience.com |\n",
     "```"
    ]
   },

docs/case_studies/Forrestania/python_code/unconstrained_magnetics_inv_training.ipynb

@@ -12,7 +12,7 @@
     "This section demonstrates the processing and inversion of the Forrestania airborne **magnetic** dataset using purely open-source packages. \n",
     "\n",
     "For an equivalent and streamlined version, see the parent case study here:  \n",
-    "👉 [Forrestania Case Study](https://mirageoscience-simpeg-drivers.readthedocs-hosted.com/en/geopy-2297/case_studies/Forrestania/forrestania.html#forrestania)\n",
+    "👉 [Forrestania Case Study](forrestania-main)\n",
     "\n",
     "> 💡 **Note**:  \n",
     "\n",
@@ -22,6 +22,13 @@
     "---\n",
     "name: Landing Image\n",
     "---\n",
+    "```\n",
+    "\n",
+    "```{table}\n",
+    "| **Authors** |  |\n",
+    "|  :--- | :--- |\n",
+    "| [Polyanna Rowe](https://github.com/polyye) |  polyannar@mirageoscience.com |\n",
+    "| [Dominique Fournier](https://github.com/domfournier) |  dominiquef@mirageoscience.com |\n",
     "```"
    ]
   },

docs/inversion/fundamentals.ipynb → docs/fundamentals/background.ipynb

@@ -83,27 +83,15 @@
    "metadata": {
     "lines_to_next_cell": 2
    },
-   "outputs": [
-    {
-     "ename": "ModuleNotFoundError",
-     "evalue": "No module named 'numpy'",
-     "output_type": "error",
-     "traceback": [
-      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
-      "\u001b[1;31mModuleNotFoundError\u001b[0m                       Traceback (most recent call last)",
-      "Cell \u001b[1;32mIn[1], line 1\u001b[0m\n\u001b[1;32m----> 1\u001b[0m \u001b[38;5;28;01mimport\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;21;01mnumpy\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;28;01mas\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;21;01mnp\u001b[39;00m\n\u001b[0;32m      2\u001b[0m \u001b[38;5;28;01mfrom\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;21;01mnumpy\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mlinalg\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;28;01mimport\u001b[39;00m LinAlgError\n",
-      "\u001b[1;31mModuleNotFoundError\u001b[0m: No module named 'numpy'"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "import numpy as np\n",
     "from numpy.linalg import LinAlgError"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 2,
    "id": "f4503466",
    "metadata": {},
    "outputs": [],
@@ -122,10 +110,21 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 3,
    "id": "d94c5ea7",
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "array([1.])"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
    "source": [
     "np.dot(F, [0.5, 0.25])"
    ]
@@ -175,7 +174,7 @@
     "where the data weights $\\mathbf{W}_d$ are diagonal matrices with estimated data uncertainties. More details can be found in the [data misfit](data_misfit.ipynb) module.\n",
     "\n",
     "\n",
-    "- $\\phi_m$ is a [regularization](regularization.ipynb) function measuring how well we **fit geological assumptions**\n",
+    "- $\\phi_m$ is a [regularization](regularization) function measuring how well we **fit geological assumptions**\n",
     "\n",
     "$$\n",
     "\\phi_m =\\sum_{i=1}^{N}\\left(w_i f(m_i - {m}_i^{ref})\\right)^2\n",
@@ -188,7 +187,7 @@
     "\\phi_m = (\\mathbf{m} - \\mathbf{m}^{ref})^T \\mathbf{R}^T \\mathbf{R}(\\mathbf{m} - \\mathbf{m}^{ref})\n",
     "$$\n",
     "\n",
-    "where the operator $\\mathbf{R}$ describe all functions used to guide the solution to a reference model $\\mathbf{m}_{ref}$. More details can be found in the [regularization](regularization.ipynb) module. A solution for the minimum of the objective function can be computed by taking its partial derivatives with respect to the model and setting it to zero\n",
+    "where the operator $\\mathbf{R}$ describe all functions used to guide the solution to a reference model $\\mathbf{m}_{ref}$. More details can be found in the [regularization](regularization) module. A solution for the minimum of the objective function can be computed by taking its partial derivatives with respect to the model and setting it to zero\n",
     "\n",
     "$$\n",
     "\\frac{\\delta \\phi(m)}{\\delta m} = \\frac{\\delta \\phi_d}{\\delta m} + \\beta \\frac{\\delta \\phi_m}{\\delta m} = 0\n",
@@ -285,7 +284,7 @@
    "id": "11b58143",
    "metadata": {},
    "source": [
-    "We have found a solution to this under-determined problem: $m = [0.2,\\; 0.4]$. This result is known as the `least-norm` solution, which differs from the true answer $m = [0.5, \\;0.25]$. Other \"better\" solutions could be found if more information is provided to the inverse problem to push the model towards expected values. This will be the topic of the [Regularization Section](regularization.ipynb)"
+    "We have found a solution to this under-determined problem: $m = [0.2,\\; 0.4]$. This result is known as the `least-norm` solution, which differs from the true answer $m = [0.5, \\;0.25]$. Other \"better\" solutions could be found if more information is provided to the inverse problem to push the model towards expected values. This will be the topic of the [Regularization Section](regularization)"
    ]
   },
   {

docs/inversion/data_misfit.ipynb → docs/fundamentals/data_misfit.ipynb

@@ -5,6 +5,8 @@
    "id": "43572ed1",
    "metadata": {},
    "source": [
+    "(data-misfit)=\n",
+    "\n",
     "# Data Fitting\n",
     "\n",
     "The data misfit function ($\\phi_d$) measures the quality of a model $\\mathbf{m}$ at **fitting the observed data**. It generally takes the form\n",
@@ -13,19 +15,18 @@
     "\\phi_d =\\sum_{i=1}^{N}\\left(\\frac{d_i^{pred} - {d}_i^{obs}}{w_i}\\right)^2 \\;.\n",
     "$$\n",
     "\n",
-    "It measures the sum of **weighted residual** between observed ($\\mathbf{d}^{obs}$) and predicted ($\\mathbf{d}^{pred}$) data. In matrix form, this least-square measure can be written as\n",
+    "It measures the sum of **weighted residual** between observed ($\\mathbf{d}^{obs}$) and predicted ($\\mathbf{d}^{pred}$) data. In matrix form, this least-squares measure can be written as\n",
     "\n",
     "$$\n",
     "\\phi_d =(F(\\mathbf{m}) - \\mathbf{d}^{obs})^T \\mathbf{W}_d^T \\mathbf{W}_d (F(\\mathbf{m}) - \\mathbf{d}^{obs})\\;,\n",
     "$$\n",
     "\n",
-    "where $F(\\mathbf{m})$ is a forward simulation of data (gravity, magnetic, EM, etc.) due to a model $m$. The $\\mathbf{W}_d$ is a diagonal matrix holding the data weights ($\\frac{1}{\\mathbf{w}}$), also referred to as **data uncertainties**. The larger the weights, the less importance a given datum has on the solution. There are many sources of **noise** that can yield large data residuals:\n",
-    "\n",
+    "where $F(\\mathbf{m})$ is a forward simulation of data (gravity, magnetic, EM, etc.) due to a model $m$. The $\\mathbf{W}_d$ is a diagonal matrix holding the data weights ($\\frac{1}{\\mathbf{w}}$), also referred to as **data uncertainties**. The larger the weights, the less important a datum is to drive the solution. There are many sources of **noise** that can yield large data residuals:\n",
     "\n",
     " - Experimental noise from $\\mathbf{d}^{obs}$, generally introduced during acquisition (positioning, instrumental noise)\n",
     " - Numerical noise introduced by $F(\\mathbf{m})$ from our inability to perfectly simulate the physics (discretization, interpolation, etc.)\n",
     "\n",
-    "In all cases, we may never expect the data residual to completely vanish, but we may allow it to be within an *acceptable* level of fitness for modelling purposes."
+    "In all cases, we may never expect the data residual to vanish completely, but we may allow it to be within an *acceptable* level of fitness for modelling purposes."
    ]
   },
   {
@@ -74,7 +75,7 @@
    "source": [
     "#### Noise floor too high\n",
     "\n",
-    "With a high floor, the inversion is dominated by the [regularization](regularization.ipynb) function and the data remains underfitted - there is coherent signal in the observed data that is not accounted for. The model is very smooth and we have a poor recovery of the shape of the susceptible body."
+    "With a high floor, the inversion is dominated by the [regularization](regularization) function. As the data remains underfitted, a coherent signal remains unaccounted for. The model is very smooth, and we have a poor recovery of the shape of the susceptible body."
    ]
   },
   {

docs/inversion/index.ipynb → docs/fundamentals/index.ipynb

@@ -10,11 +10,11 @@
     "This module documents the use of [SimPEG](https://simpeg.xyz/) for geophysical data inversion with user-interface (UIjson) made available through the [Mira Geoscience-geoapps](https://mirageoscience-geoapps.readthedocs-hosted.com/) project. While the code itself has its own documentation, there is a need to demonstrate the effect of parameters controlling the inversion. This document is meant to be a reference guide with practical examples to help practitioners with their inversion work.\n",
     "\n",
     "\n",
-    "- [Background](fundamentals.ipynb): An overview of the inversion framework.\n",
+    "- [Background](background.ipynb): An overview of the inversion framework.\n",
     "\n",
     "- [Data Fit](data_misfit.ipynb): Assigning uncertainties and global target (data misfit).\n",
     "\n",
-    "- [Constraints](regularization.ipynb): Adding modeling constraints (regularization).\n",
+    "- [Regularization (Constraints)](regularization): Adding modeling constraints (regularization).\n",
     "\n",
     "- [Mesh Design](mesh_design.ipynb): Designing an inversion mesh.\n",
     "\n",
@@ -24,6 +24,14 @@
     "\n",
     "![inversion_ui](./images/inversion_ui.png)"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2308931b-c540-4082-8b20-b4d011e127af",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {