Add docs and example geoh5

Author: domfournier

docs/fundamentals/regularization/images/fold_data.png

@@ -106,24 +106,24 @@
    "source": [
     "## Example\n",
     "\n",
-    "This section demonstrates the use of rotated gradients on a semi-realistic synthetic example. \n",
-    "\n",
-    "### Setup \n",
-    "\n",
-    "The model has been generated with the help of [Gempy](https://app.readthedocs.com/projects/mirageoscience-gempy-drivers/builds/?version__slug=stable). The model comprises a folded and faulted magnetic layer (0.5 SI) dipping 20 degrees towards East. The geometry is meant to mimic a banded-iron formation.\n",
+    "This section demonstrates the use of rotated gradients on a semi-realistic synthetic example. The geometry of the model is meant to mimic a banded-iron formation buried under a hill.  The goal is to demonstrate the benefit of applying directional constraints to the inversion to better resolve layer-like bodies at depth.\n",
     "\n",
     "```{figure} ./images/fold_model.png\n",
     "---\n",
-    "scale: 30%\n",
+    "width: 500pt\n",
     "---\n",
+    "Synthetic model made up of a folded dipping magnetic layer.  \n",
     "```\n",
     "\n",
-    "From this model, we simulate residual magnetic field data along an East-West survey, 200 m line spacing and a mean terrain clearance of 150 m. For simplicity, we use a vertical inducing field with a magnitude of 50,000 nT.\n",
+    "The model comprises a folded and faulted magnetic layer (0.5 SI) dipping 20 degrees towards East. The model has been generated with a few structural control points provided to the [Gempy](https://app.readthedocs.com/projects/mirageoscience-gempy-drivers/builds/?version__slug=stable) application.\n",
     "\n",
-    "```{figure} ./images/fold_model.png\n",
+    "From this model, we simulate residual magnetic field data along an East-West survey, 200 m line spacing, with a mean terrain clearance of 150 m. For simplicity, we use a vertical inducing field with a magnitude of 50,000 nT.\n",
+    "\n",
+    "```{figure} ./images/fold_data.png\n",
     "---\n",
-    "scale: 30%\n",
+    "width: 500pt\n",
     "---\n",
+    "(Left) Horizontal section through the discrete model and RMI data. (Right) Vertical section through the model and (top) data profile.\n",
     "```\n",
     "\n",
     "The basic components (data, model and topography) to reproduce this example can be [downloaded here]()."
@@ -134,44 +134,58 @@
    "id": "6bdbf088-2983-4975-99f5-cb1fba3d2741",
    "metadata": {},
    "source": [
-    "### Standard unconstrained inversion\n",
+    "### Unconstrained inversion\n",
     "\n",
     "As a starting point, we invert the magnetic data with standard constraints (lower bounds and reference value of 0 SI). \n",
-    "The resulting smooth model shows clear breaks between the survey lines and poorly resolves the dip of the magnetic layer. The subsequent compact model further exacerbates these issues. \n",
+    "The resulting model shows clumping of the magnetic anomalies around the survey lines. This is somewhat expected from an unconstrained inversion, as the regularization function dominates in regions of low sensitivity. The shape and dip of the magnetic layer become even more diffuse at depth. The subsequent compact model only slightly improves the model by shrinking the volume of the magnetic highs.\n",
     "\n",
+    "```{figure} ./images/fold_inverted_no_rot.png\n",
+    "---\n",
+    "width: 500pt\n",
+    "---\n",
+    "(Top) Horizontal and (bottom) vertical sections through the (left) true, (middle) inverted-smooth and (right) recovered inverted-compact model **without** using rotated gradients.\n",
+    "```\n",
     "\n",
     "### Directional constraints\n",
     "\n",
-    "To improve the continuity of the magnetic layer across lines and down-dip, we can provide trend information to the inversion from our structural control points.\n",
+    "To improve the continuity of the magnetic layer across lines and down-dip, we provide trend information to the inversion with data provided by the structural control points. \n",
     "\n",
-    "We interpolate the dip and dip direction data from the `structural markers` to the inversion mesh. We use the Radial Basis Function (RBF) application, but users may want to experiment with different interpolation algorithms.\n",
+    "First, we interpolate the dip and dip-direction data from the `structural markers` to the inversion mesh using the Radial Basis Function (RBF) application. Following the instructions presented in the [previous section](rotated-gradients), we group the interpolated data as type `Dip Direction & Dip`. Users can then validate the constraint by displaying the vectors onto sections of the mesh. \n",
     "\n",
-    "```{figure} ./images/fold_model.png\n",
+    "```{figure} ./images/fold_structural_interp.png\n",
     "---\n",
-    "scale: 30%\n",
+    "width: 500pt\n",
     "---\n",
+    "(Left) Perspective view of the structural constraints with dip and direction. (Right) Interpolated dip and direction onto the inversion mesh, also group as `Dip Direction & Dip` for visualization and inversion.\n",
     "```\n",
     "\n",
-    "Following the instructions presented in the [previous section](rotated-gradients), we group the interpolated data as type `Dip Direction & Dip`. Users can validate the constraint by displaying the vectors onto sections of the mesh. Once created, the orientation information is provided to the inversion. \n",
+    "To further accentuate the trend, we decrease the weight of the `Z-smoothness weight`, now oriented perpendicular to the plane of rotation. By doing so, we increase the relative strength of the smoothing (and sparsity) along the local dip and strike of the magnetic layer. \n",
     "\n",
-    "```{figure} ./images/invert_fault_equal.png\n",
+    "```{figure} ./images/fold_parameters.png\n",
     "---\n",
-    "scale: 30%\n",
+    "width: 300pt\n",
     "---\n",
+    "Regularization parameters used for the sparse rotated gradient inversion.\n",
     "```\n",
     "\n",
-    "The resulting model shows an improved \n",
-    "\n",
-    "\n",
-    "We can further improve this result by decreasing the relative weight applied to the gradient penalty perpendicular (z) to the rotated plane.\n",
+    "After reaching the target misfit, both the smooth and sparse models show a clear improvement in resolving a continuous magnetic layer. In cross-section, the dip and thickness of the layer are significantly improved at depth, although the dip angle is slightly overestimated. \n",
     "\n",
-    "```{figure} ./images/invert_fault_wz0p5.png\n",
+    "```{figure} ./images/fold_inverted_rotated_wz0p1.png\n",
     "---\n",
-    "scale: 30%\n",
+    "width: 500pt\n",
     "---\n",
+    "(Top) Horizontal and (bottom) vertical sections through the (left) true, (middle) inverted-smooth and (right) recovered inverted-compact model **with** rotated gradients.\n",
     "```\n",
     "\n"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f93867e9-7e87-4dd1-a120-8ad22dae5703",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {