From 9cdce3dcd42da93c29d8a365df0fed07a04443a8 Mon Sep 17 00:00:00 2001
From: dominiquef
Date: Tue, 29 Jul 2025 15:52:28 -0700
Subject: [PATCH 1/9] Move files. Split regularization module
---
docs/_toc.yml | 36 ++---
.../background.ipynb} | 37 +++--
.../data_misfit.ipynb | 9 +-
.../depth_of_investigation.ipynb | 0
.../images/apply_mask.png | Bin
.../images/beta_optimal.png | Bin
.../images/beta_too_high.png | Bin
.../images/beta_too_low.png | Bin
.../images/cell_size_estimate.png | Bin
.../images/common_survey.png | Bin
.../images/correct_floor.png | Bin
.../images/correct_floor_plot.png | Bin
.../images/cutoff_options.png | Bin
.../images/dc_mesh_diagram.png | Bin
.../images/extent_to_pad.png | Bin
.../images/forward_mag_susc.png | Bin
.../images/inversion_ui.png | Bin
.../images/joint_coupling.png | Bin
.../images/joint_survey.png | Bin
.../images/joint_surveys.png | Bin
.../images/joint_ui.png | Bin
.../images/large_floor.png | Bin
.../images/large_floor_plot.png | Bin
.../images/mag_mesh_diagram.png | Bin
.../images/mag_mesh_options.png | Bin
.../images/masked_model.png | Bin
.../images/mesh_core.png | Bin
.../images/mesh_dc.png | Bin
.../images/percent.png | Bin
.../images/percent_floor.png | Bin
.../images/percent_floor_plot.png | Bin
.../images/save_sensitivities.png | Bin
.../images/sensitivity_mask.png | Bin
.../images/sensitivity_models.png | Bin
.../images/setup.png | Bin
.../images/setup_plot.png | Bin
.../images/small_floor.png | Bin
.../images/small_floor_plot.png | Bin
.../images/tradeoff_setup.png | Bin
.../images/uijson.png | Bin
docs/{inversion => fundamentals}/index.ipynb | 12 +-
.../joint_inversion.ipynb | 0
.../mesh_design.ipynb | 0
.../optimization.ipynb | 0
.../regularization}/images/flat_models.png | Bin
.../regularization}/images/lp_norm.png | Bin
.../images/reference_model.png | Bin
.../images/regularization_alpha.png | Bin 0 -> 19548 bytes
.../images/regularization_lp.png | Bin
.../images/smallness_norm_setup.png | Bin
.../images/smoothness_norm_setup.png | Bin
.../regularization}/images/sparse_models.png | Bin
.../regularization/regularization.ipynb | 127 +++++++++++++++++
.../regularization/sparse.ipynb} | 128 ++----------------
.../inversion/images/regularization_alpha.png | Bin 44829 -> 0 bytes
docs/tutorials/airborne_tem.ipynb | 2 +-
docs/tutorials/dc_resistivity.ipynb | 2 +-
docs/tutorials/gravity.ipynb | 2 +-
docs/tutorials/magnetic.ipynb | 2 +-
docs/tutorials/tipper.ipynb | 2 +-
60 files changed, 198 insertions(+), 161 deletions(-)
rename docs/{inversion/fundamentals.ipynb => fundamentals/background.ipynb} (88%)
rename docs/{inversion => fundamentals}/data_misfit.ipynb (95%)
rename docs/{inversion => fundamentals}/depth_of_investigation.ipynb (100%)
rename docs/{inversion => fundamentals}/images/apply_mask.png (100%)
rename docs/{inversion => fundamentals}/images/beta_optimal.png (100%)
rename docs/{inversion => fundamentals}/images/beta_too_high.png (100%)
rename docs/{inversion => fundamentals}/images/beta_too_low.png (100%)
rename docs/{inversion => fundamentals}/images/cell_size_estimate.png (100%)
rename docs/{inversion => fundamentals}/images/common_survey.png (100%)
rename docs/{inversion => fundamentals}/images/correct_floor.png (100%)
rename docs/{inversion => fundamentals}/images/correct_floor_plot.png (100%)
rename docs/{inversion => fundamentals}/images/cutoff_options.png (100%)
rename docs/{inversion => fundamentals}/images/dc_mesh_diagram.png (100%)
rename docs/{inversion => fundamentals}/images/extent_to_pad.png (100%)
rename docs/{inversion => fundamentals}/images/forward_mag_susc.png (100%)
rename docs/{inversion => fundamentals}/images/inversion_ui.png (100%)
rename docs/{inversion => fundamentals}/images/joint_coupling.png (100%)
rename docs/{inversion => fundamentals}/images/joint_survey.png (100%)
rename docs/{inversion => fundamentals}/images/joint_surveys.png (100%)
rename docs/{inversion => fundamentals}/images/joint_ui.png (100%)
rename docs/{inversion => fundamentals}/images/large_floor.png (100%)
rename docs/{inversion => fundamentals}/images/large_floor_plot.png (100%)
rename docs/{inversion => fundamentals}/images/mag_mesh_diagram.png (100%)
rename docs/{inversion => fundamentals}/images/mag_mesh_options.png (100%)
rename docs/{inversion => fundamentals}/images/masked_model.png (100%)
rename docs/{inversion => fundamentals}/images/mesh_core.png (100%)
rename docs/{inversion => fundamentals}/images/mesh_dc.png (100%)
rename docs/{inversion => fundamentals}/images/percent.png (100%)
rename docs/{inversion => fundamentals}/images/percent_floor.png (100%)
rename docs/{inversion => fundamentals}/images/percent_floor_plot.png (100%)
rename docs/{inversion => fundamentals}/images/save_sensitivities.png (100%)
rename docs/{inversion => fundamentals}/images/sensitivity_mask.png (100%)
rename docs/{inversion => fundamentals}/images/sensitivity_models.png (100%)
rename docs/{inversion => fundamentals}/images/setup.png (100%)
rename docs/{inversion => fundamentals}/images/setup_plot.png (100%)
rename docs/{inversion => fundamentals}/images/small_floor.png (100%)
rename docs/{inversion => fundamentals}/images/small_floor_plot.png (100%)
rename docs/{inversion => fundamentals}/images/tradeoff_setup.png (100%)
rename docs/{inversion => fundamentals}/images/uijson.png (100%)
rename docs/{inversion => fundamentals}/index.ipynb (82%)
rename docs/{inversion => fundamentals}/joint_inversion.ipynb (100%)
rename docs/{inversion => fundamentals}/mesh_design.ipynb (100%)
rename docs/{inversion => fundamentals}/optimization.ipynb (100%)
rename docs/{inversion => fundamentals/regularization}/images/flat_models.png (100%)
rename docs/{inversion => fundamentals/regularization}/images/lp_norm.png (100%)
rename docs/{inversion => fundamentals/regularization}/images/reference_model.png (100%)
create mode 100644 docs/fundamentals/regularization/images/regularization_alpha.png
rename docs/{inversion => fundamentals/regularization}/images/regularization_lp.png (100%)
rename docs/{inversion => fundamentals/regularization}/images/smallness_norm_setup.png (100%)
rename docs/{inversion => fundamentals/regularization}/images/smoothness_norm_setup.png (100%)
rename docs/{inversion => fundamentals/regularization}/images/sparse_models.png (100%)
create mode 100644 docs/fundamentals/regularization/regularization.ipynb
rename docs/{inversion/regularization.ipynb => fundamentals/regularization/sparse.ipynb} (54%)
delete mode 100644 docs/inversion/images/regularization_alpha.png
diff --git a/docs/_toc.yml b/docs/_toc.yml
index 7a2c0d1b..638336e8 100644
--- a/docs/_toc.yml
+++ b/docs/_toc.yml
@@ -4,15 +4,17 @@
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/mesh_design
+ - file: fundamentals/joint_inversion
+ - file: fundamentals/depth_of_investigation
+ - file: fundamentals/optimization
- file: tutorials/introduction
sections:
- file: tutorials/background
@@ -22,13 +24,13 @@ chapters:
- file: tutorials/tipper
- file: tutorials/airborne_tem
- file: tutorials/joint_inversion
-- file: case_studies/index
- sections:
- - file: case_studies/Forrestania/forrestania
- sections:
- - file: case_studies/Forrestania/open_code
- sections:
- - file: case_studies/Forrestania/python_code/gravity
- - file: case_studies/Forrestania/python_code/magnetics
- - file: case_studies/Forrestania/python_code/joint_grav_mag
+#- file: case_studies/index
+# sections:
+# - file: case_studies/Forrestania/forrestania
+# sections:
+# - file: case_studies/Forrestania/open_code
+# sections:
+# - file: case_studies/Forrestania/python_code/gravity
+# - file: case_studies/Forrestania/python_code/magnetics
+# - file: case_studies/Forrestania/python_code/joint_grav_mag
- file: THIRD_PARTY_SOFTWARE
diff --git a/docs/inversion/fundamentals.ipynb b/docs/fundamentals/background.ipynb
similarity index 88%
rename from docs/inversion/fundamentals.ipynb
rename to docs/fundamentals/background.ipynb
index c8e1e6f5..969dadc7 100644
--- a/docs/inversion/fundamentals.ipynb
+++ b/docs/fundamentals/background.ipynb
@@ -83,19 +83,7 @@
"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"
@@ -103,7 +91,7 @@
},
{
"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)"
]
},
{
diff --git a/docs/inversion/data_misfit.ipynb b/docs/fundamentals/data_misfit.ipynb
similarity index 95%
rename from docs/inversion/data_misfit.ipynb
rename to docs/fundamentals/data_misfit.ipynb
index d20ef329..1c24293b 100644
--- a/docs/inversion/data_misfit.ipynb
+++ b/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."
]
},
{
diff --git a/docs/inversion/depth_of_investigation.ipynb b/docs/fundamentals/depth_of_investigation.ipynb
similarity index 100%
rename from docs/inversion/depth_of_investigation.ipynb
rename to docs/fundamentals/depth_of_investigation.ipynb
diff --git a/docs/inversion/images/apply_mask.png b/docs/fundamentals/images/apply_mask.png
similarity index 100%
rename from docs/inversion/images/apply_mask.png
rename to docs/fundamentals/images/apply_mask.png
diff --git a/docs/inversion/images/beta_optimal.png b/docs/fundamentals/images/beta_optimal.png
similarity index 100%
rename from docs/inversion/images/beta_optimal.png
rename to docs/fundamentals/images/beta_optimal.png
diff --git a/docs/inversion/images/beta_too_high.png b/docs/fundamentals/images/beta_too_high.png
similarity index 100%
rename from docs/inversion/images/beta_too_high.png
rename to docs/fundamentals/images/beta_too_high.png
diff --git a/docs/inversion/images/beta_too_low.png b/docs/fundamentals/images/beta_too_low.png
similarity index 100%
rename from docs/inversion/images/beta_too_low.png
rename to docs/fundamentals/images/beta_too_low.png
diff --git a/docs/inversion/images/cell_size_estimate.png b/docs/fundamentals/images/cell_size_estimate.png
similarity index 100%
rename from docs/inversion/images/cell_size_estimate.png
rename to docs/fundamentals/images/cell_size_estimate.png
diff --git a/docs/inversion/images/common_survey.png b/docs/fundamentals/images/common_survey.png
similarity index 100%
rename from docs/inversion/images/common_survey.png
rename to docs/fundamentals/images/common_survey.png
diff --git a/docs/inversion/images/correct_floor.png b/docs/fundamentals/images/correct_floor.png
similarity index 100%
rename from docs/inversion/images/correct_floor.png
rename to docs/fundamentals/images/correct_floor.png
diff --git a/docs/inversion/images/correct_floor_plot.png b/docs/fundamentals/images/correct_floor_plot.png
similarity index 100%
rename from docs/inversion/images/correct_floor_plot.png
rename to docs/fundamentals/images/correct_floor_plot.png
diff --git a/docs/inversion/images/cutoff_options.png b/docs/fundamentals/images/cutoff_options.png
similarity index 100%
rename from docs/inversion/images/cutoff_options.png
rename to docs/fundamentals/images/cutoff_options.png
diff --git a/docs/inversion/images/dc_mesh_diagram.png b/docs/fundamentals/images/dc_mesh_diagram.png
similarity index 100%
rename from docs/inversion/images/dc_mesh_diagram.png
rename to docs/fundamentals/images/dc_mesh_diagram.png
diff --git a/docs/inversion/images/extent_to_pad.png b/docs/fundamentals/images/extent_to_pad.png
similarity index 100%
rename from docs/inversion/images/extent_to_pad.png
rename to docs/fundamentals/images/extent_to_pad.png
diff --git a/docs/inversion/images/forward_mag_susc.png b/docs/fundamentals/images/forward_mag_susc.png
similarity index 100%
rename from docs/inversion/images/forward_mag_susc.png
rename to docs/fundamentals/images/forward_mag_susc.png
diff --git a/docs/inversion/images/inversion_ui.png b/docs/fundamentals/images/inversion_ui.png
similarity index 100%
rename from docs/inversion/images/inversion_ui.png
rename to docs/fundamentals/images/inversion_ui.png
diff --git a/docs/inversion/images/joint_coupling.png b/docs/fundamentals/images/joint_coupling.png
similarity index 100%
rename from docs/inversion/images/joint_coupling.png
rename to docs/fundamentals/images/joint_coupling.png
diff --git a/docs/inversion/images/joint_survey.png b/docs/fundamentals/images/joint_survey.png
similarity index 100%
rename from docs/inversion/images/joint_survey.png
rename to docs/fundamentals/images/joint_survey.png
diff --git a/docs/inversion/images/joint_surveys.png b/docs/fundamentals/images/joint_surveys.png
similarity index 100%
rename from docs/inversion/images/joint_surveys.png
rename to docs/fundamentals/images/joint_surveys.png
diff --git a/docs/inversion/images/joint_ui.png b/docs/fundamentals/images/joint_ui.png
similarity index 100%
rename from docs/inversion/images/joint_ui.png
rename to docs/fundamentals/images/joint_ui.png
diff --git a/docs/inversion/images/large_floor.png b/docs/fundamentals/images/large_floor.png
similarity index 100%
rename from docs/inversion/images/large_floor.png
rename to docs/fundamentals/images/large_floor.png
diff --git a/docs/inversion/images/large_floor_plot.png b/docs/fundamentals/images/large_floor_plot.png
similarity index 100%
rename from docs/inversion/images/large_floor_plot.png
rename to docs/fundamentals/images/large_floor_plot.png
diff --git a/docs/inversion/images/mag_mesh_diagram.png b/docs/fundamentals/images/mag_mesh_diagram.png
similarity index 100%
rename from docs/inversion/images/mag_mesh_diagram.png
rename to docs/fundamentals/images/mag_mesh_diagram.png
diff --git a/docs/inversion/images/mag_mesh_options.png b/docs/fundamentals/images/mag_mesh_options.png
similarity index 100%
rename from docs/inversion/images/mag_mesh_options.png
rename to docs/fundamentals/images/mag_mesh_options.png
diff --git a/docs/inversion/images/masked_model.png b/docs/fundamentals/images/masked_model.png
similarity index 100%
rename from docs/inversion/images/masked_model.png
rename to docs/fundamentals/images/masked_model.png
diff --git a/docs/inversion/images/mesh_core.png b/docs/fundamentals/images/mesh_core.png
similarity index 100%
rename from docs/inversion/images/mesh_core.png
rename to docs/fundamentals/images/mesh_core.png
diff --git a/docs/inversion/images/mesh_dc.png b/docs/fundamentals/images/mesh_dc.png
similarity index 100%
rename from docs/inversion/images/mesh_dc.png
rename to docs/fundamentals/images/mesh_dc.png
diff --git a/docs/inversion/images/percent.png b/docs/fundamentals/images/percent.png
similarity index 100%
rename from docs/inversion/images/percent.png
rename to docs/fundamentals/images/percent.png
diff --git a/docs/inversion/images/percent_floor.png b/docs/fundamentals/images/percent_floor.png
similarity index 100%
rename from docs/inversion/images/percent_floor.png
rename to docs/fundamentals/images/percent_floor.png
diff --git a/docs/inversion/images/percent_floor_plot.png b/docs/fundamentals/images/percent_floor_plot.png
similarity index 100%
rename from docs/inversion/images/percent_floor_plot.png
rename to docs/fundamentals/images/percent_floor_plot.png
diff --git a/docs/inversion/images/save_sensitivities.png b/docs/fundamentals/images/save_sensitivities.png
similarity index 100%
rename from docs/inversion/images/save_sensitivities.png
rename to docs/fundamentals/images/save_sensitivities.png
diff --git a/docs/inversion/images/sensitivity_mask.png b/docs/fundamentals/images/sensitivity_mask.png
similarity index 100%
rename from docs/inversion/images/sensitivity_mask.png
rename to docs/fundamentals/images/sensitivity_mask.png
diff --git a/docs/inversion/images/sensitivity_models.png b/docs/fundamentals/images/sensitivity_models.png
similarity index 100%
rename from docs/inversion/images/sensitivity_models.png
rename to docs/fundamentals/images/sensitivity_models.png
diff --git a/docs/inversion/images/setup.png b/docs/fundamentals/images/setup.png
similarity index 100%
rename from docs/inversion/images/setup.png
rename to docs/fundamentals/images/setup.png
diff --git a/docs/inversion/images/setup_plot.png b/docs/fundamentals/images/setup_plot.png
similarity index 100%
rename from docs/inversion/images/setup_plot.png
rename to docs/fundamentals/images/setup_plot.png
diff --git a/docs/inversion/images/small_floor.png b/docs/fundamentals/images/small_floor.png
similarity index 100%
rename from docs/inversion/images/small_floor.png
rename to docs/fundamentals/images/small_floor.png
diff --git a/docs/inversion/images/small_floor_plot.png b/docs/fundamentals/images/small_floor_plot.png
similarity index 100%
rename from docs/inversion/images/small_floor_plot.png
rename to docs/fundamentals/images/small_floor_plot.png
diff --git a/docs/inversion/images/tradeoff_setup.png b/docs/fundamentals/images/tradeoff_setup.png
similarity index 100%
rename from docs/inversion/images/tradeoff_setup.png
rename to docs/fundamentals/images/tradeoff_setup.png
diff --git a/docs/inversion/images/uijson.png b/docs/fundamentals/images/uijson.png
similarity index 100%
rename from docs/inversion/images/uijson.png
rename to docs/fundamentals/images/uijson.png
diff --git a/docs/inversion/index.ipynb b/docs/fundamentals/index.ipynb
similarity index 82%
rename from docs/inversion/index.ipynb
rename to docs/fundamentals/index.ipynb
index 235e55f9..506dafab 100644
--- a/docs/inversion/index.ipynb
+++ b/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",
""
]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "2308931b-c540-4082-8b20-b4d011e127af",
+ "metadata": {},
+ "outputs": [],
+ "source": []
}
],
"metadata": {
diff --git a/docs/inversion/joint_inversion.ipynb b/docs/fundamentals/joint_inversion.ipynb
similarity index 100%
rename from docs/inversion/joint_inversion.ipynb
rename to docs/fundamentals/joint_inversion.ipynb
diff --git a/docs/inversion/mesh_design.ipynb b/docs/fundamentals/mesh_design.ipynb
similarity index 100%
rename from docs/inversion/mesh_design.ipynb
rename to docs/fundamentals/mesh_design.ipynb
diff --git a/docs/inversion/optimization.ipynb b/docs/fundamentals/optimization.ipynb
similarity index 100%
rename from docs/inversion/optimization.ipynb
rename to docs/fundamentals/optimization.ipynb
diff --git a/docs/inversion/images/flat_models.png b/docs/fundamentals/regularization/images/flat_models.png
similarity index 100%
rename from docs/inversion/images/flat_models.png
rename to docs/fundamentals/regularization/images/flat_models.png
diff --git a/docs/inversion/images/lp_norm.png b/docs/fundamentals/regularization/images/lp_norm.png
similarity index 100%
rename from docs/inversion/images/lp_norm.png
rename to docs/fundamentals/regularization/images/lp_norm.png
diff --git a/docs/inversion/images/reference_model.png b/docs/fundamentals/regularization/images/reference_model.png
similarity index 100%
rename from docs/inversion/images/reference_model.png
rename to docs/fundamentals/regularization/images/reference_model.png
diff --git a/docs/fundamentals/regularization/images/regularization_alpha.png b/docs/fundamentals/regularization/images/regularization_alpha.png
new file mode 100644
index 0000000000000000000000000000000000000000..5d894269fd664f8b9c9faab2c65f0ce913e0e5cd
GIT binary patch
literal 19548
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
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "17654719-df2b-4903-8217-5487f098b204",
+ "metadata": {},
+ "source": []
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.17"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/inversion/regularization.ipynb b/docs/fundamentals/regularization/sparse.ipynb
similarity index 54%
rename from docs/inversion/regularization.ipynb
rename to docs/fundamentals/regularization/sparse.ipynb
index a40f8315..19e98cf6 100644
--- a/docs/inversion/regularization.ipynb
+++ b/docs/fundamentals/regularization/sparse.ipynb
@@ -1,113 +1,5 @@
{
"cells": [
- {
- "cell_type": "markdown",
- "id": "3a9fd274",
- "metadata": {},
- "source": [
- "(regularization)=\n",
- "\n",
- "# Constraints (Regularization)\n",
- "\n",
- "This section focuses on the regularization functions, or constraints, that can be used to inject \"geological knowledge\" into the inversion process. More specifically, this section covers the weighted least-squares regularization functions:\n",
- "\n",
- "- [Conventional L2-norm](l2-norm)\n",
- "\n",
- "- [General Lp-norms](lp-norm)\n",
- "\n",
- "While often referred to as an \"unconstrained inversion\", one could argue that the conventional model norm regularizations do still incorporate some degree of geological information, at least in the form of physical property distribution. Exactly what kind of a priori information is available dictates the complexity of the constraints. For more advanced petrophysical and/or geometric constraints, see the [Joint Inversion](./joint_inversion.ipynb) section."
- ]
- },
- {
- "cell_type": "markdown",
- "id": "3e78e630",
- "metadata": {},
- "source": [
- "(l2-norm)=\n",
- "\n",
- "## L2-norm regularization\n",
- "\n",
- "The conventional L2-norm regularization function imposes constraints based on the least-square measure with respect to the inversion model value\n",
- "\n",
- "$$\n",
- "\\phi(m) = \\| f(\\mathbf{m}) \\|_2^2 \\;,\n",
- "$$\n",
- "\n",
- "where $f(\\mathbf{m})$ is any linear function of the model $\\mathbf{m}$. The following sections introduce the conventional model \"smallness\" and \"smoothness\" functions.\n",
- "\n",
- "\n",
- "### Model smallness\n",
- "\n",
- "In the seminal work of {cite:t}`TikhonovArsenin77`, the function $f(\\mathbf{m})$ simply measures the deviation between the inversion model from a reference\n",
- "\n",
- "$$\n",
- "f_s(\\mathbf{m}) = \\mathbf{m} - \\mathbf{m}_{ref} \\;,\n",
- "$$\n",
- "\n",
- "where $\\mathbf{m}_{ref}$ is a reference model. This function tries to keep the model \"small\", as large deviations from the reference value are penalized more heavily. The reference model can vary in complexity, from a constant background value to a full 3D geological representation of the physical property. This constitutes our first constraint.\n",
- "\n",
- "\n",
- "\n",
- "\n",
- "(smooth-ref)=\n",
- "\n",
- "### Model smoothness\n",
- "\n",
- "A second set of terms can be added to the regularization function to apply constraints on the model gradients, or roughness of the solution. Following the notation used in {cite:t}`LiOldenburg1998` and others before,\n",
- "\n",
- "$$\n",
- "f_x(\\mathbf{m}) = \\mathbf{G}_x (\\mathbf{m} - \\mathbf{m}_{ref}) \\;,\n",
- "$$\n",
- "\n",
- "where $\\mathbf{G}_x$ is a finite difference operator that measures the gradient of the model $\\mathbf{m}$ along one of the Cartesian directions (`x` for Easting). This function keeps the model \"smooth\", as large gradients (sharp contrasts) are penalized strongly. Two additional terms are needed to measure the model gradients along the Northing ($f_y$) and vertical ($f_z$) direction.\n",
- "\n",
- "\n",
- "### Scaling\n",
- "\n",
- "For 3D inverse problems, the full regularization function contains 4 terms: one for the reference model and three terms for the smoothness measures along the three Cartesian axes:\n",
- "\n",
- "$$\n",
- "\\phi_m = \\sum_{i = s,x,y,z} \\alpha_i \\| \\mathbf{W}_i f_i(\\mathbf{m}) \\|_2^2\n",
- "$$\n",
- "\n",
- "Note that we have added scaling parameters $\\alpha_i$ to each function. The role of those multipliers is two-fold:\n",
- "\n",
- "- User-defined weights to emphasize the contribution of a particular function\n",
- "\n",
- "- Dimensionality scaling to level the functions with each other.\n",
- "\n",
- "Dimensionality scales arise from the difference operators:\n",
- "\n",
- "$$\n",
- "\\phi_x(m) = \\sum_{i=1}^{N_{fx}} \\left(\\frac{\\Delta m_i}{h_{xi}}\\right)^2\n",
- "$$\n",
- "\n",
- "such that $\\Delta m_i$ is the difference in model values between two cells separated by a distance $h_{xi}$ along the x-axis. When adding together the [reference](#Model smallness) and [model smoothnedd](#Model smoothness) terms in the regularization, it is obvious that the scale factor of $h^{-2}$ would favor $\\phi_m$ to have a larger impact on the solution. The standard practice is to weight down the influence of the reference model accordingly.\n",
- "\n",
- "\n",
- "**Note**\n",
- "\n",
- "For all SimPEG inversions, dimensionality scaling of $h^2$ is applied directly for the gradient terms by the program, allowing the default state to be all 1s for simplicity.\n",
- "\n",
- "\n",
- "\n",
- "\n",
- "\n",
- "\n",
- "### Model weights (future option)\n",
- "\n",
- "\n",
- "Any of the regularization functions mentioned above can be further augmented with weights associated with each model cell such that\n",
- "\n",
- "$$\n",
- "\\phi_i = \\| \\mathbf{W}_i f_i(\\mathbf{m}) \\|_2^2\n",
- "$$\n",
- "\n",
- "where $\\mathbf{W}_i$ contains positive values that change the relative strength of the regularization function in specific volumes of the 3D space. This is typically done for advanced constraints to reflect variable degrees of confidence in the reference geological model (e.g. high near the surface, low at depth). This option is currently not available but it is planned to be included in geoapps v0.12.0.\n",
- "\n",
- ""
- ]
- },
{
"cell_type": "markdown",
"id": "d1c00010",
@@ -118,17 +10,25 @@
"## Sparse regularization\n",
"\n",
"\n",
- "It is possible to generalize the conventional least-squares approach such that we can recover different solutions with variable degrees of sparsity {cite:t}`fournier_2019`. The goal is to explore the model space by changing our assumption about the character of the solution, in terms of volume of the anomalies and sharpness of contrasts between domains. We can do this by changing the \"ruler\" by which we evaluate the model function $f(\\mathbf{m})$.\n",
+ "It is possible to generalize the conventional least-squares approach such that we can recover different solutions with variable degrees of sparsity. The goal is to explore the model space by changing our assumption about the character of the solution, in terms of the volume of the anomalies and the sharpness of their edges. We can do this by changing the \"ruler\" by which we evaluate the model function $f(\\mathbf{m})$.\n",
"\n",
"\n",
"### Approximated $L_p$-norm\n",
"\n",
- "Since the general $L_p$ norm is not linear with respect to the model, an approximation is used where\n",
+ "The general $L_p$ norm measure \n",
"\n",
"$$\n",
"\\phi(m) = \\| f(\\mathbf{m}) \\|_p\n",
"$$\n",
"\n",
+ "can also be expressed as\n",
+ "\n",
+ "$$\n",
+ "\\phi(m) = \\sum_{j}^M {|f(m)_i |}^p\n",
+ "$$\n",
+ "\n",
+ "For $p<=1$, the function is non-linear with respect to the model. It is possible to approximate the function in a linearized form as \n",
+ "\n",
"$$\n",
"\\sum_{j}^M {|f(m)_i |}^p \\approx \\sum_{i} {\\frac{ {f(m)_i}^2}{\\left( {{f(m)_i}}^{2} + \\epsilon^2 \\right)^{1-p/2 }}}\n",
"$$\n",
@@ -152,7 +52,7 @@
"\\mathbf{R}_i = {\\frac{1}{\\left( {{f(m)^{(k-1)}_i}}^{2} + \\epsilon^2 \\right)^{1-p/2 }}}\\,.\n",
"$$\n",
"\n",
- "Here the superscript $(k)$ denotes the inversion iteration number. This is also known as an iterative re-weighted least-squares (IRLS) method. For more details on the implementation refer to {cite:t}`fournier_2019`.\n",
+ "Here, the superscript $(k)$ denotes the iteration step of the inversion. This is also known as an iterative re-weighted least-squares (IRLS) method. For more details on the implementation, refer to {cite:t}`fournier_2019`.\n",
"\n",
"The next two sub-sections apply this methodology to the [model smallness](reference-model) and [model smoothness](model-smoothness) regularizers.\n",
"\n",
@@ -178,7 +78,7 @@
"$$\n",
"\n",
"\n",
- "That is, we ask the inversion to recover anomalies that have small volumes but large physical property contrasts. This is desirable if we know the geological bodies to be discrete and compact (e.g. kimberlite pip, dyke, etc.). The example below demonstrates the outcome of an inversion for different combinations of norms applied to the model\n",
+ "That is, we ask the inversion to recover anomalies that have small volumes but large physical property contrasts. This is desirable if we know the geological bodies to be discrete and compact (e.g. kimberlite pipe, dyke, etc.). The example below demonstrates the outcome of an inversion for different combinations of norms applied to the model\n",
"\n",
"```{figure} ./images/sparse_models.png\n",
"---\n",
@@ -188,14 +88,14 @@
"\n",
"The [figure above](sparse_model) shows vertical sections through the true and recovered models (from left to right) with L2, L1 and L0-norm on the model values.\n",
"\n",
- "Note that as $p \\rightarrow 0$ the volume of the anomaly shrinks to a few non-zero elements while the physical property contrasts increase. They generally agree on the center position of the anomaly but differ greatly on the extent and shape.\n",
+ "Note that as $p \\rightarrow 0$ the volume of the anomaly shrinks to a few non-zero elements while the physical property contrasts increase. They generally agree on the center position of the anomaly but differ significantly in their extent and shape.\n",
"\n",
"\n",
"\n",
"No smoothness constraints were used ($\\alpha_{x,y,z} = 0$), only a penalty on the reference model ($m_{ref} = 0$).\n",
"\n",
"\n",
- "All those models fit the data to the target [data misfit](data_misfit) and are therefore valid solutions to the inversion.\n",
+ "All those models fit the data to the target [data misfit](data-misfit) and are therefore valid solutions to the inversion.\n",
"\n",
""
]
diff --git a/docs/inversion/images/regularization_alpha.png b/docs/inversion/images/regularization_alpha.png
deleted file mode 100644
index 7699a766110dcd0eff61497a474019ce5a59fff6..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 44829
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
x(@%7G5h>iIgW3-Fa{Xn<2yO|Q{
Date: Wed, 30 Jul 2025 15:44:38 -0700
Subject: [PATCH 2/9] Add reformat reg section. Fix links
---
docs/_toc.yml | 1 +
.../regularization/regularization.ipynb | 64 +++++++----
.../regularization/rotated_gradients.ipynb | 45 ++++++++
docs/fundamentals/regularization/sparse.ipynb | 108 +++++++++---------
docs/tutorials/airborne_tem.ipynb | 8 +-
docs/tutorials/dc_resistivity.ipynb | 10 +-
docs/tutorials/joint_inversion.ipynb | 12 ++
docs/tutorials/magnetic.ipynb | 10 +-
docs/tutorials/tipper.ipynb | 22 ++--
9 files changed, 181 insertions(+), 99 deletions(-)
create mode 100644 docs/fundamentals/regularization/rotated_gradients.ipynb
diff --git a/docs/_toc.yml b/docs/_toc.yml
index 638336e8..036676fa 100644
--- a/docs/_toc.yml
+++ b/docs/_toc.yml
@@ -11,6 +11,7 @@ chapters:
- 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
diff --git a/docs/fundamentals/regularization/regularization.ipynb b/docs/fundamentals/regularization/regularization.ipynb
index 4e56945b..c0d90bae 100644
--- a/docs/fundamentals/regularization/regularization.ipynb
+++ b/docs/fundamentals/regularization/regularization.ipynb
@@ -9,11 +9,10 @@
"\n",
"# Regularization (Constraints)\n",
"\n",
- "This section focuses on the regularization functions, or constraints, that can be used to inject \"geological knowledge\" into the inversion process. More specifically, this section covers the weighted least-squares regularization functions.\n",
+ "This section focuses on the regularization functions, or model constraints, that can inject \"geological knowledge\" into the inversion process. More specifically, this section covers the weighted least-squares regularization functions. Readers are invited to visit the following sections for more advanced options\n",
"\n",
- "While often referred to as an \"unconstrained inversion\", one could argue that the conventional model norm regularizations do still incorporate some degree of geological information, at least in the form of physical property distribution. The type of a priori information available dictates the complexity of the constraints. The next sections cover more advanced features\n",
- "\n",
- "- [Sparse Lp-norms](lp-norm)"
+ "- [Sparse Lp-norms](lp-norm)\n",
+ "- [Rotate Gradients](rotated-gradients)"
]
},
{
@@ -25,22 +24,22 @@
"\n",
"## Least-squares regularization\n",
"\n",
- "The conventional L2-norm regularization function imposes constraints based on the least-squares measures, either of the model and/or its spatial gradients. We can express these various constraints as\n",
+ "The conventional L2-norm regularization function imposes constraints based on least-squares measures, either of the model and/or its spatial gradients. We can express these various constraints as\n",
"\n",
"$$\n",
- "\\phi(m) = \\| \\mathbf{W} f(\\mathbf{m}) \\|_2^2 \\;,\n",
+ "\\phi(m) = \\| f(\\mathbf{m}) \\|_2^2 \\;,\n",
"$$\n",
"\n",
- "where $f(\\mathbf{m})$ is any linear function of the model $\\mathbf{m}$. The generic matrix $\\mathbf{W}$ contains weights that can be used to tune the influence of the function spatially. See the section on [Weights](weights) for more details on the matter.\n",
+ "where $f(\\mathbf{m})$ is any linear function of the model $\\mathbf{m}$. While often referred to as an *unconstrained inversion*, one could argue that the conventional least-squares regularization does still incorporate first-degree information about the geological background, at least in the form of physical property distribution.\n",
"\n",
"(small-ref)=\n",
"\n",
"### Model smallness (reference)\n",
"\n",
- "In the seminal work of {cite:t}`TikhonovArsenin77`, the function $f(\\mathbf{m})$ simply measures the deviation between the inversion model from a reference\n",
+ "In the seminal work of {cite:t}`TikhonovArsenin77`, the function $f(\\mathbf{m})$ simply measures the deviation between the inversion model from a reference value\n",
"\n",
"$$\n",
- "f_s(\\mathbf{m}) = \\mathbf{m} - \\mathbf{m}_{ref} \\;,\n",
+ "\\phi_s = \\| \\mathbf{m} - \\mathbf{m}_{ref} \\|\n",
"$$\n",
"\n",
"where $\\mathbf{m}_{ref}$ is a reference model. This function tries to keep the model \"small\", in terms of deviation from the reference values. The reference model can vary in complexity, from a constant background value to a full 3D geological representation of the physical property. \n",
@@ -55,42 +54,61 @@
"A second set of terms can be added to the regularization function to apply constraints on the model gradients, or the roughness, of the solution. Following the notation used in {cite:t}`LiOldenburg1998`,\n",
"\n",
"$$\n",
- "f_x(\\mathbf{m}) = \\mathbf{G}_x (\\mathbf{m} - \\mathbf{m}_{ref}) \\;,\n",
+ "\\phi_i(\\mathbf{m}) = \\| \\mathbf{G}_i (\\mathbf{m} - \\mathbf{m}_{ref}) \\|\\;,\n",
+ "$$\n",
+ "\n",
+ "where $\\mathbf{G}_i$ is a finite difference operator that measures the gradient of the model $\\mathbf{m}$ along one of the Cartesian directions. For 3D inversions, three functions are needed to measure the model gradients along the Easting ($f_x$), Northing ($f_y$) and vertical ($f_z$) directions. These functions enforce the model to remain smooth, as large gradients (sharp contrasts) are penalized strongly. \n",
+ "\n",
+ "For 3D inverse problems, the full regularization function contains 4 terms: one for the reference model and three terms for the smoothness measures along the three Cartesian axes:\n",
+ "\n",
+ "$$\n",
+ "\\phi_m = \\sum_{i = s,x,y,z} \\| \\mathbf{W}_i f_i(\\mathbf{m}) \\|_2^2\n",
"$$\n",
"\n",
- "where $\\mathbf{G}_x$ is a finite difference operator that measures the gradient of the model $\\mathbf{m}$ along one of the Cartesian directions (`x` for Easting). These functions enforce the model to remain smooth, as large gradients (sharp contrasts) are penalized strongly. Two additional terms are needed to measure the model gradients along the Northing ($f_y$) and vertical ($f_z$) direction.\n",
+ "Weighting matrices $\\mathbf{W}_i$ are added to each function to scale the constraints among each other. \n",
"\n",
"(weights)=\n",
"\n",
- "### Scaling\n",
+ "### Weights\n",
"\n",
- "For 3D inverse problems, the full regularization function contains 4 terms: one for the reference model and three terms for the smoothness measures along the three Cartesian axes:\n",
+ "The weighting matrices $\\mathbf{W}_i$ are made up of default and user-defined weights\n",
"\n",
"$$\n",
- "\\phi_m = \\sum_{i = s,x,y,z} \\| \\mathbf{W}_i f_i(\\mathbf{m}) \\|_2^2\n",
+ "\\mathbf{W}_i = \\mathbf{W}_h * \\mathbf{W}_j * \\mathbf{W}_u\n",
"$$\n",
"\n",
- "Note that we have added scaling parameters $\\alpha_i$ to each function. The role of those multipliers is two-fold:\n",
+ "#### User-defined weights ($\\mathbf{W}_u$)\n",
"\n",
- "- User-defined weights to emphasize the contribution of a particular function. This is typically done for advanced constraints to reflect variable degrees of confidence in the reference geological model (e.g. high near the surface, low at depth). \n",
+ "User-defined weights can be tuned to emphasize the contribution of a particular function. This can be done globally, as a constant, or locally on a cell-by-cell basis. Weights may reflect variable degrees of confidence in the reference geological model (e.g. high near the surface, low at depth), or to accentuate specific trends in the model.\n",
"\n",
- "- Default scaling to level the functions with each other.\n",
+ "\n",
+ "\n",
+ "\n",
+ "#### Sensitivity-based weights ($\\mathbf{W}_j$)\n",
"\n",
- "Dimensionality scales arise from the difference operators:\n",
+ "Sensitivity-based weights are computed as the sum-squares the rows of the sensitivities\n",
"\n",
"$$\n",
- "\\phi_x(m) = \\sum_{i=1}^{N_{fx}} \\left(\\frac{\\Delta m_i}{h_{xi}}\\right)^2\n",
+ "\\mathbf{W}_j = [\\sum_{i=1}^{N} \\mathbf{J}_{ij}^2 + \\epsilon ]^{1/4} \\;,\n",
"$$\n",
"\n",
- "such that $\\Delta m_i$ is the difference in model values between two cells separated by a distance $h_{xi}$ along the x-axis. When adding together the [reference](small-ref) and [model smoothness](smooth-ref) terms in the regularization, it is obvious that the scale factor of $h^{-2}$ would favor $\\phi_m$ to have a larger impact on the solution. The standard practice is to weigh down the influence of the reference model accordingly.\n",
+ "where $\\mathbf{J}$ are the sensitivities (Jacobian) of the forward problem. The weighting attempts to compensate for the strong influence of the misfit function near the receiver locations, which would favour a model with high complexity near the surface. A small constant $\\epsilon$ is added to threshold the weights in regions of extremely low sensitivity.\n",
"\n",
"\n",
- "**Note**\n",
+ "#### Dimensionality scaling ($\\mathbf{W}_h$)\n",
"\n",
- "For all SimPEG inversions, dimensionality scaling of $h^2$ is applied directly for the gradient terms by the program, allowing the default state to be all 1s for simplicity.\n",
+ "Dimensionality scaling is applied to the gradient terms $\\phi_{i=(x,y,z)}$ as constants to account for length scales in the *smoothness* terms\n",
"\n",
+ "$$\n",
+ "\\mathbf{W}_{hi} = h_i \n",
+ "$$\n",
"\n",
- "\n",
+ "where $h$ is defined by the smallest cell dimension in each dimension $i=x,y,z$. This default scaling brings the *smallness* and *smoothness* terms to be dimensionally equivalent, which would otherwise be\n",
+ "\n",
+ "$$\n",
+ "dim\\; \\phi_s = M^2, \\; \n",
+ "dim\\; \\phi_x = \\frac{M^2}{H^2}\n",
+ "$$\n",
"\n",
"\n",
""
diff --git a/docs/fundamentals/regularization/rotated_gradients.ipynb b/docs/fundamentals/regularization/rotated_gradients.ipynb
new file mode 100644
index 00000000..f7574b08
--- /dev/null
+++ b/docs/fundamentals/regularization/rotated_gradients.ipynb
@@ -0,0 +1,45 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "d1c00010",
+ "metadata": {},
+ "source": [
+ "(rotated-gradients)=\n",
+ "\n",
+ "# Rotated Gradients\n",
+ "\n",
+ "This section provides details about the rotation of gradient penalties to enforce trends in the model."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "35b60ef2-b3c4-4074-b7ce-4e8835a5c3f4",
+ "metadata": {},
+ "outputs": [],
+ "source": []
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.17"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/fundamentals/regularization/sparse.ipynb b/docs/fundamentals/regularization/sparse.ipynb
index 19e98cf6..013e9cc1 100644
--- a/docs/fundamentals/regularization/sparse.ipynb
+++ b/docs/fundamentals/regularization/sparse.ipynb
@@ -7,59 +7,10 @@
"source": [
"(lp-norm)=\n",
"\n",
- "## Sparse regularization\n",
+ "# Sparse regularization\n",
"\n",
"\n",
- "It is possible to generalize the conventional least-squares approach such that we can recover different solutions with variable degrees of sparsity. The goal is to explore the model space by changing our assumption about the character of the solution, in terms of the volume of the anomalies and the sharpness of their edges. We can do this by changing the \"ruler\" by which we evaluate the model function $f(\\mathbf{m})$.\n",
- "\n",
- "\n",
- "### Approximated $L_p$-norm\n",
- "\n",
- "The general $L_p$ norm measure \n",
- "\n",
- "$$\n",
- "\\phi(m) = \\| f(\\mathbf{m}) \\|_p\n",
- "$$\n",
- "\n",
- "can also be expressed as\n",
- "\n",
- "$$\n",
- "\\phi(m) = \\sum_{j}^M {|f(m)_i |}^p\n",
- "$$\n",
- "\n",
- "For $p<=1$, the function is non-linear with respect to the model. It is possible to approximate the function in a linearized form as \n",
- "\n",
- "$$\n",
- "\\sum_{j}^M {|f(m)_i |}^p \\approx \\sum_{i} {\\frac{ {f(m)_i}^2}{\\left( {{f(m)_i}}^{2} + \\epsilon^2 \\right)^{1-p/2 }}}\n",
- "$$\n",
- "\n",
- "where $p$ is any constant between $[0,\\;2]$. This is a decent approximation of the $l_p$-norm for any of the functions presented in the [L2-norm](l2-norm) section.\n",
- "\n",
- "\n",
- "\n",
- "Note that choosing a different $l_p$-norm greatly changes how we measure the function $f(m)$. Rather than simply increasing exponentially with the size of $f(m)$, small norms increase the penalty on low $f(m)$ values.\n",
- "As $p\\rightarrow 0$, we attempt to recover as few non-zero elements, which in turn favour sparse solutions.\n",
- "\n",
- "Since it is a non-linear function with respect to $\\mathbf{m}$, we must first linearize it as\n",
- "\n",
- "$$\n",
- "\\| f(\\mathbf{m})_i \\|_p \\approx \\| \\mathbf{R}_i f(\\mathbf{m})_i\\|\n",
- "$$\n",
- "\n",
- "where\n",
- "\n",
- "$$\n",
- "\\mathbf{R}_i = {\\frac{1}{\\left( {{f(m)^{(k-1)}_i}}^{2} + \\epsilon^2 \\right)^{1-p/2 }}}\\,.\n",
- "$$\n",
- "\n",
- "Here, the superscript $(k)$ denotes the iteration step of the inversion. This is also known as an iterative re-weighted least-squares (IRLS) method. For more details on the implementation, refer to {cite:t}`fournier_2019`.\n",
- "\n",
- "The next two sub-sections apply this methodology to the [model smallness](reference-model) and [model smoothness](model-smoothness) regularizers.\n",
- "\n",
- "\n",
- "\n",
- "\n",
- ""
+ "It is possible to generalize the conventional least-squares approach such that we can recover different solutions with variable degrees of sparsity. By sparsity, we mean fewer model cells (or gradients) away from the reference, but with larger values. The goal is to explore the model space by changing our assumption about the character of the solution, in terms of the volume of the anomalies and the sharpness of their edges. We can do this by changing the \"ruler\" by which we evaluate the model function $f(\\mathbf{m})$."
]
},
{
@@ -69,7 +20,7 @@
"source": [
"(reference-model)=\n",
"\n",
- "### Smallness norm model\n",
+ "## Smallness norm model\n",
"\n",
"The first option is to impose sparsity assumptions on the model values.\n",
"\n",
@@ -107,11 +58,11 @@
"source": [
"(model-smoothness)=\n",
"\n",
- "### Smoothness norm model\n",
+ "## Smoothness norm model\n",
"\n",
"Next, we explore the effect of applying sparse norms on the model gradients. We have two options.\n",
"\n",
- "#### Gradient type: Total\n",
+ "### Gradient type: Total\n",
"\n",
"The favoured approach is to measure the total gradient of the model\n",
"\n",
@@ -139,7 +90,7 @@
"\n",
"No reference model was used ($\\alpha_s = 0$) with uniform norm values on all three Cartesian components.\n",
"\n",
- "All those models also fit the data to the target [data misfit](data_misfit) and are therefore valid solutions to the inversion. Note that as $p \\rightarrow 0$ the edges of the anomaly become tighter while variability inside the body diminishes. They generally agree on the center position of the anomaly but differ greatly on the extent and shape.\n",
+ "All those models also fit the data to the target [data misfit](data-misfit) and are therefore valid solutions to the inversion. Note that as $p \\rightarrow 0$ the edges of the anomaly become tighter while variability inside the body diminishes. They generally agree on the center position of the anomaly but differ greatly on the extent and shape.\n",
"\n",
"\n",
"\n",
@@ -190,6 +141,53 @@
"To be continued..."
]
},
+ {
+ "cell_type": "markdown",
+ "id": "e8b6527c-842e-4b8f-8619-bb96ff3deffc",
+ "metadata": {},
+ "source": [
+ "### Background: Approximated $L_p$-norm\n",
+ "\n",
+ "The standard $L_p$ norm measure is generally written as\n",
+ "\n",
+ "$$\n",
+ "\\phi(m) = \\| f(\\mathbf{m}) \\|_p ] \\;,\n",
+ "$$\n",
+ "\n",
+ "which can also be expressed as\n",
+ "\n",
+ "$$\n",
+ "\\phi(m) = \\sum_{j}^M {|f(m)_i |}^p \\;.\n",
+ "$$\n",
+ "\n",
+ "For $p<=1$, the function is non-linear with respect to the model. It is possible to approximate the function in a linearized form as \n",
+ "\n",
+ "$$\n",
+ "\\sum_{j}^M {|f(m)_i |}^p \\approx \\sum_{i} {\\frac{ {f(m)_i}^2}{\\left( {{f(m)_i}}^{2} + \\epsilon^2 \\right)^{1-p/2 }}}\n",
+ "$$\n",
+ "\n",
+ "where $p$ is any constant between $[0,\\;2]$. This is a decent approximation of the $l_p$-norm for any of the functions presented in the [L2-norm](l2-norm) section.\n",
+ "\n",
+ "\n",
+ "\n",
+ "Note that choosing a different $l_p$-norm greatly changes how we measure the function $f(m)$. Rather than simply increasing exponentially with the size of $f(m)$, small norms increase the penalty on low $f(m)$ values.\n",
+ "As $p\\rightarrow 0$, we attempt to recover as few non-zero elements, which in turn favour sparse solutions.\n",
+ "\n",
+ "Since it is a non-linear function with respect to $\\mathbf{m}$, we must first linearize it as\n",
+ "\n",
+ "$$\n",
+ "\\| f(\\mathbf{m})_i \\|_p \\approx \\| \\mathbf{R}_i \\mathbf{W}_i f(\\mathbf{m})_i\\|\n",
+ "$$\n",
+ "\n",
+ "where\n",
+ "\n",
+ "$$\n",
+ "\\mathbf{R}_i = {\\frac{1}{\\left( {{f(m)^{(k-1)}_i}}^{2} + \\epsilon^2 \\right)^{1-p/2 }}}\\,.\n",
+ "$$\n",
+ "\n",
+ "Here, the superscript $(k)$ denotes the iteration step of the inversion. This is also known as an iterative re-weighted least-squares (IRLS) method. For more details on the implementation, refer to {cite:t}`fournier_2019`."
+ ]
+ },
{
"cell_type": "markdown",
"id": "2bf887ab",
diff --git a/docs/tutorials/airborne_tem.ipynb b/docs/tutorials/airborne_tem.ipynb
index 75191c57..d9ce0bcf 100644
--- a/docs/tutorials/airborne_tem.ipynb
+++ b/docs/tutorials/airborne_tem.ipynb
@@ -125,9 +125,9 @@
"\n",
"### Refinements\n",
"\n",
- "- For the first refinement, we insert 4 cells for the first three octree levels along the flight path. The refinement is done radially around the segments of the flight path curve to assure good numerical accuracy near the receiver locations. This is especially important for EM methods with low frequencies.\n",
+ "- For the first refinement, we insert 4 cells for the first three octree levels along the flight path. The refinement is done radially around the segments of the flight path curve to ensure good numerical accuracy near the receiver locations. This is especially important for EM methods with low frequencies.\n",
"\n",
- "- We use a second refinement along topography to get a coarse but continuous air-ground interface outside the area or interest.\n",
+ "- We use a second refinement along topography to get a coarse but continuous air-ground interface outside the area of interest.\n",
"\n",
"- Lastly, we refine a \"horizon\" to get a core region at depth with increasing cell size directly below the survey. This is our volume of interest most strongly influenced by the data.\n",
"\n",
@@ -136,10 +136,10 @@
"scale: 50%\n",
"name: atem_refinement\n",
"---\n",
- "Refinement strategy used for the atem modeling.\n",
+ "Refinement strategy used for the atem modelling.\n",
"```\n",
"\n",
- "See [Mesh creation](mesh_design) section for general details on the parameters."
+ "See [Mesh creation](mesh-design) section for general details on the parameters."
]
},
{
diff --git a/docs/tutorials/dc_resistivity.ipynb b/docs/tutorials/dc_resistivity.ipynb
index 27a45d29..5b5eb3e3 100644
--- a/docs/tutorials/dc_resistivity.ipynb
+++ b/docs/tutorials/dc_resistivity.ipynb
@@ -84,11 +84,11 @@
"\n",
"### Refinements\n",
"\n",
- "- The first refinement adds more cells around each pole location, radially outward. This assures good numerical accuracy, espatially on the outer boundary of the survey area.\n",
+ "- The first refinement adds more cells around each pole location, radially outward. This assures good numerical accuracy, especially on the outer boundary of the survey area.\n",
"\n",
- "- A second refinement is used along topography to get a coarse but continuous air-ground interface outside the area or interest.\n",
+ "- A second refinement is used along topography to get a coarse but continuous air-ground interface outside the area of interest.\n",
"\n",
- "- The third refinement \"horizon\" is used to get a core region at depth with increasing cell size directly below the survey. This is our volume of interest most strongly influence by the data. We use a maximum distance of 100 m to limit the refinement away from the survey lines. In the case of remote electrodes, this parameter prevents from discretization finely everywhere in between.\n",
+ "- The third refinement, \"horizon\", is used to get a core region at depth with increasing cell size directly below the survey. This is our volume of interest most strongly influenced by the data. We use a maximum distance of 100 m to limit the refinement away from the survey lines. In the case of remote electrodes, this parameter prevents discretization from applying everywhere in between.\n",
"\n",
"\n",
"```{figure} ./images/dc/dc_refinement.png\n",
@@ -96,10 +96,10 @@
"scale: 50%\n",
"name: dc_refinement\n",
"---\n",
- "Refinement strategy used for the direct-current modeling.\n",
+ "Refinement strategy used for the direct-current modelling.\n",
"```\n",
"\n",
- "See [Mesh creation](mesh_design) section for general details on the parameters.\n"
+ "See [Mesh creation](mesh-design) section for general details on the parameters.\n"
]
},
{
diff --git a/docs/tutorials/joint_inversion.ipynb b/docs/tutorials/joint_inversion.ipynb
index 9b807f46..21a7fb18 100644
--- a/docs/tutorials/joint_inversion.ipynb
+++ b/docs/tutorials/joint_inversion.ipynb
@@ -16,6 +16,18 @@
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.17"
}
},
"nbformat": 4,
diff --git a/docs/tutorials/magnetic.ipynb b/docs/tutorials/magnetic.ipynb
index 37811327..fefb112d 100644
--- a/docs/tutorials/magnetic.ipynb
+++ b/docs/tutorials/magnetic.ipynb
@@ -82,21 +82,21 @@
"\n",
"### Refinements\n",
"\n",
- "- For the first refinement, we insert two cells around our survey lines. The refinement is done radially around the segments of the curve to assure that the air-ground interface near the receivers are modeled with the finest cell size.\n",
+ "- For the first refinement, we insert two cells around our survey lines. The refinement is done radially around the segments of the curve to ensure that the air-ground interface near the receivers is modelled with the finest cell size.\n",
"\n",
- "- A second refinement is used along topography to get a coarse but continuous air-ground interface outside the area or interest.\n",
+ "- A second refinement is used along topography to get a coarse but continuous air-ground interface outside the area of interest.\n",
"\n",
- "- The third refinement \"horizon\" is used to get a core region at depth with increasing cell size directly below the survey. This is our volume of interest most strongly influence by the data.\n",
+ "- The third refinement, \"horizon\", is used to get a core region at depth with increasing cell size directly below the survey. This is our volume of interest most strongly influenced by the data.\n",
"\n",
"```{figure} ./images/magnetics/mesh_refinement.png\n",
"---\n",
"scale: 50%\n",
"name: mag_refinement\n",
"---\n",
- "Refinement strategy used for the magnetic modeling.\n",
+ "Refinement strategy used for the magnetic modelling.\n",
"```\n",
"\n",
- "See [Mesh creation](mesh_design) section for general details on the parameters.\n"
+ "See [Mesh creation](mesh-design) section for general details on the parameters.\n"
]
},
{
diff --git a/docs/tutorials/tipper.ipynb b/docs/tutorials/tipper.ipynb
index 123c15d6..7528827d 100644
--- a/docs/tutorials/tipper.ipynb
+++ b/docs/tutorials/tipper.ipynb
@@ -88,9 +88,9 @@
"\n",
"### Refinements\n",
"\n",
- "- For the first refinement, we insert 4 cells for the first three octree levels along the flight path. The refinement is done radially around the segments of the flight path curve to assure good numerical accuracy near the receiver locations. This is especially important for EM methods with low frequencies.\n",
+ "- For the first refinement, we insert 4 cells for the first three octree levels along the flight path. The refinement is done radially around the segments of the flight path curve to ensure good numerical accuracy near the receiver locations. This is especially important for EM methods with low frequencies.\n",
"\n",
- "- We use a second refinement along topography to get a coarse but continuous air-ground interface outside the area or interest.\n",
+ "- We use a second refinement along topography to get a coarse but continuous air-ground interface outside the area of interest.\n",
"\n",
"- Lastly, we refine a \"horizon\" to get a core region at depth with increasing cell size directly below the survey. This is our volume of interest most strongly influenced by the data.\n",
"\n",
@@ -99,10 +99,10 @@
"scale: 50%\n",
"name: tipper_refinement\n",
"---\n",
- "Refinement strategy used for the tipper modeling.\n",
+ "Refinement strategy used for the tipper modelling.\n",
"```\n",
"\n",
- "See [Mesh creation](mesh_design) section for general details on the parameters."
+ "See [Mesh creation](mesh-design) section for general details on the parameters."
]
},
{
@@ -114,7 +114,7 @@
"\n",
"**Runtime: ~2.0 h**\n",
"\n",
- "Tipper data involves 2 receiver configuration (x and y), with two components (real and imaginary) and measured over 6 frequencies. Balancing all this data can be challenging and time consuming. Here we adopt a variable floor strategy based on the 10th percentile of each data layer.\n",
+ "Tipper data involves 2 receiver configurations (x and y), with two components (real and imaginary) and measured over 6 frequencies. Balancing all this data can be challenging and time-consuming. Here, we adopt a variable floor strategy based on the 10th percentile of each data layer.\n",
"\n",
"```{figure} ./images/tipper/tipper_uncerts.png\n",
"---\n",
@@ -125,7 +125,7 @@
"\n",
"This approach is a good starting point, but experimentation is generally required.\n",
"\n",
- "After running the inversion we recover the following solution:\n",
+ "After running the inversion, we recover the following solution:\n",
"\n",
"\n",
"```{figure} ./images/tipper/tipper_unconstrained.png\n",
@@ -134,11 +134,19 @@
"---\n",
"(Left) Horizontal section at 120 m elevation after reaching target misfit (iteration 5).\n",
"\n",
- "(Right)(top) 2D profiles of observed versus predicted data for all 4 channels and 6 frequencies and (bottom) vertical section through the conductivity model below the same line.\n",
+ "(Right)(top) 2D profiles of observed versus predicted data for all 4 channels and 6 frequencies, and (bottom) vertical section through the conductivity model below the same line.\n",
"```\n",
"\n",
"Despite our simplistic floor uncertainties, the inversion managed to converge fairly quickly to a reasonable model that fits our data well. We have recovered a clear conductor at depth that overlaps with the ore body. However, the inversion could not resolve the thin conductive overburden layer, as expected by the low frequency range of the tipper system."
]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "6db10672-d6a6-4cf9-bb21-03ae881dff7b",
+ "metadata": {},
+ "outputs": [],
+ "source": []
}
],
"metadata": {
From a88bf8435e8f01d926c601961abdcda088d4b084 Mon Sep 17 00:00:00 2001
From: dominiquef
Date: Fri, 1 Aug 2025 14:10:53 -0700
Subject: [PATCH 3/9] More content
---
.../images/create_orientation.png | Bin 0 -> 76645 bytes
.../images/flin_flon_no_rotation.png | Bin 0 -> 200769 bytes
.../images/flin_flon_rotated.png | Bin 0 -> 189767 bytes
.../images/gradient_direction.png | Bin 0 -> 77178 bytes
.../regularization/images/set_orientation.png | Bin 0 -> 30393 bytes
.../images/smallness_norm_setup.png | Bin 61204 -> 32391 bytes
.../images/smoothness_norm_setup.png | Bin 57958 -> 32060 bytes
.../regularization/regularization.ipynb | 48 ++++------
.../regularization/rotated_gradients.ipynb | 53 +++++++++--
docs/fundamentals/regularization/sparse.ipynb | 83 +++++++-----------
docs/references.bib | 9 ++
docs/tutorials/magnetic.ipynb | 5 +-
12 files changed, 111 insertions(+), 87 deletions(-)
create mode 100644 docs/fundamentals/regularization/images/create_orientation.png
create mode 100644 docs/fundamentals/regularization/images/flin_flon_no_rotation.png
create mode 100644 docs/fundamentals/regularization/images/flin_flon_rotated.png
create mode 100644 docs/fundamentals/regularization/images/gradient_direction.png
create mode 100644 docs/fundamentals/regularization/images/set_orientation.png
diff --git a/docs/fundamentals/regularization/images/create_orientation.png b/docs/fundamentals/regularization/images/create_orientation.png
new file mode 100644
index 0000000000000000000000000000000000000000..e83e7a569b1d93de0227db0768d4cdadd6664aff
GIT binary patch
literal 76645
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