MiraGeoscience · sebhmg · Nov 21, 2025 · Nov 25, 2025 · Nov 25, 2025 · Nov 25, 2025
diff --git a/docs/THIRD_PARTY_SOFTWARE.rst b/docs/THIRD_PARTY_SOFTWARE.rst
@@ -17,9 +17,15 @@ compatibly licensed.  We list these here.
    * - `discretize <https://simpeg.xyz/>`_
      - MIT
      - Discretization tools for finite volume and inverse problems
+   * - `geoapps-utils <https://github.com/MiraGeoscience/geoapps-utils>`_
+     - MIT
+     - Collection of utilities for creating applications and manipulating geoh5 objects
    * - `geoh5py <https://github.com/MiraGeoscience/geoh5py>`_
      - LGPL-3.0-or-later
      - Python API for geoh5, an open file format for geoscientific data
+   * - `grid-apps <https://github.com/MiraGeoscience/grid-apps>`_
+     - MIT
+     - Grid creation and manipulation using GEOH5 format.
    * - `numpy <https://github.com/numpy/numpy>`_
      - BSD-3-Clause
      - Fundamental package for array computing in Python
@@ -32,6 +38,9 @@ compatibly licensed.  We list these here.
    * - `pymatsolver <https://github.com/simpeg/pymatsolver/>`_
      - MIT
      - Matrix Solvers for Python.
+   * - `Rtree <https://github.com/Toblerity/rtree>`_
+     - MIT
+     - Spatial index for Python GIS
    * - `scikit-learn <https://github.com/scikit-learn/scikit-learn/>`_
      - BSD-3-Clause
      - A set of python modules for machine learning and data mining
@@ -41,6 +50,12 @@ compatibly licensed.  We list these here.
    * - `simpeg <https://simpeg.xyz/>`_
      - MIT
      - SimPEG: Simulation and Parameter Estimation in Geophysics
+   * - `threadpoolctl <https://github.com/joblib/threadpoolctl>`_
+     - BSD-3-Clause
+     - helpers to limit the number of threads used in the threadpool-backed of common native libraries used for scientific computing and data science
    * - `tqdm <https://github.com/tqdm>`_
      - MPL-2.0 or MIT
      - A Fast, Extensible Progress Bar for Python and CLI
+   * - `trimesh <https://trimesh.org/>`_
+     - MIT
+     - Python library for loading and using triangular meshes
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -34,4 +34,10 @@ chapters:
         - file: case_studies/Forrestania/python_code/unconstrained_gravity_inv_training
         - file: case_studies/Forrestania/python_code/unconstrained_magnetics_inv_training
         - file: case_studies/Forrestania/python_code/joint_grav_mag
+- file: plate-simulation/index
+  sections:
+  - file: plate-simulation/usage
+    title: Basic Usage
+  - file: plate-simulation/methodology
+    title: Methodology
 - file: THIRD_PARTY_SOFTWARE
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -15,7 +15,7 @@ dependencies:
   - discretize
   - pip
   - ipykernel
-  - jupyter-book
+  - jupyter-book=1.0
   - jupytext
   - notebook
   - zarr

diff --git a/docs/images/plate-simulation/basic_usage/analyst_geophysics_menu.png b/docs/images/plate-simulation/basic_usage/analyst_geophysics_menu.png
diff --git a/docs/images/plate-simulation/index.png b/docs/images/plate-simulation/index.png
diff --git a/docs/images/plate-simulation/methodology/copy_options.png b/docs/images/plate-simulation/methodology/copy_options.png
diff --git a/docs/images/plate-simulation/methodology/data/simpeg_group_creation.png b/docs/images/plate-simulation/methodology/data/simpeg_group_creation.png
diff --git a/docs/images/plate-simulation/methodology/data/simpeg_group_edit_options.png b/docs/images/plate-simulation/methodology/data/simpeg_group_edit_options.png
diff --git a/docs/images/plate-simulation/methodology/data/simpeg_group_options.png b/docs/images/plate-simulation/methodology/data/simpeg_group_options.png
diff --git a/docs/images/plate-simulation/methodology/data/simulation_options.png b/docs/images/plate-simulation/methodology/data/simulation_options.png
diff --git a/docs/images/plate-simulation/methodology/make_plate_images.pub b/docs/images/plate-simulation/methodology/make_plate_images.pub
diff --git a/docs/images/plate-simulation/methodology/mesh/mesh_options.png b/docs/images/plate-simulation/methodology/mesh/mesh_options.png
diff --git a/docs/images/plate-simulation/methodology/mesh/refinement.png b/docs/images/plate-simulation/methodology/mesh/refinement.png
diff --git a/docs/images/plate-simulation/methodology/model/basement_options.png b/docs/images/plate-simulation/methodology/model/basement_options.png
diff --git a/docs/images/plate-simulation/methodology/model/n_plates_options.png b/docs/images/plate-simulation/methodology/model/n_plates_options.png
diff --git a/docs/images/plate-simulation/methodology/model/overburden_and_basement.png b/docs/images/plate-simulation/methodology/model/overburden_and_basement.png
diff --git a/docs/images/plate-simulation/methodology/model/overburden_options.png b/docs/images/plate-simulation/methodology/model/overburden_options.png
diff --git a/docs/images/plate-simulation/methodology/model/plate_location.png b/docs/images/plate-simulation/methodology/model/plate_location.png
diff --git a/docs/images/plate-simulation/methodology/model/plate_location_options.png b/docs/images/plate-simulation/methodology/model/plate_location_options.png
diff --git a/docs/images/plate-simulation/methodology/model/plate_options.png b/docs/images/plate-simulation/methodology/model/plate_options.png
diff --git a/docs/images/plate-simulation/methodology/model/plate_orientation.png b/docs/images/plate-simulation/methodology/model/plate_orientation.png
diff --git a/docs/images/plate-simulation/methodology/model/plate_orientation_options.png b/docs/images/plate-simulation/methodology/model/plate_orientation_options.png
diff --git a/docs/images/plate-simulation/methodology/model/plate_resistivity_option.png b/docs/images/plate-simulation/methodology/model/plate_resistivity_option.png
diff --git a/docs/images/plate-simulation/methodology/model/plate_size.png b/docs/images/plate-simulation/methodology/model/plate_size.png
diff --git a/docs/images/plate-simulation/methodology/model/plate_size_options.png b/docs/images/plate-simulation/methodology/model/plate_size_options.png
diff --git a/docs/images/plate-simulation/methodology/model/three_plates.png b/docs/images/plate-simulation/methodology/model/three_plates.png
diff --git a/docs/images/plate-simulation/methodology/results.png b/docs/images/plate-simulation/methodology/results.png
diff --git a/docs/images/plate-simulation/methodology/sweep_option.png b/docs/images/plate-simulation/methodology/sweep_option.png
diff --git a/docs/images/plate-simulation/methodology/uijson.png b/docs/images/plate-simulation/methodology/uijson.png
diff --git a/docs/plate-simulation/index.rst b/docs/plate-simulation/index.rst
@@ -0,0 +1,21 @@
+.. _plate_simulation_index:
+
+Plate Simulation
+================
+
+.. figure:: /images/plate-simulation/index.png
+   :align: center
+   :width: 100%
+
+The plate-simulation application is a tool for simulating geophysical data over
+a simple two-layer earth model with plate(s).  It relies on the
+`discretize <https://discretize.simpeg.xyz/en/main/>`_
+and `SimPEG <https://simpeg.xyz/>`_ projects to create a refined octree mesh and
+simulate data over the parameterized model.  The mesh, model and simulation
+details are parameterized in a ui.json file that can be rendered in
+`Geoscience ANALYST Pro <https://www.mirageoscience.com/mining-industry-software/geoscience-analyst-pro/>`_.
+
+See:
+
+- :ref:`Basic Usage <plate_simulation_usage>`
+- :ref:`Methodology <plate_simulation_methodology>`
diff --git a/docs/plate-simulation/methodology.rst b/docs/plate-simulation/methodology.rst
@@ -0,0 +1,274 @@
+.. _plate_simulation_methodology:
+
+Plate Simulation: Methodology
+=============================
+
+In order to simulate geophysical data from a physical property model, we
+need three things: a computational mesh, a discretization of the model
+within that mesh and a means to simulate the data.  Plate simulation
+relies on `discretize <https://discretize.simpeg.xyz/en/main/>`_ for
+octree mesh creation, and `SimPEG <https://simpeg.xyz/>`_ for finite
+volume based forward modeling.  Plate simulation includes a module for
+generating a simple two-layer model with embedded plate anomalies within
+octree meshes. In this section, we will discuss all three of these
+components, their interface exposed by the ui.json file, and the storage
+of results.
+
+.. figure:: /images/plate-simulation/methodology/uijson.png
+    :align: center
+    :width: 80%
+
+    *Merged images of both tabs of the ui.json rendered interface.*
+
+.. contents::
+
+.. toctree::
+   :maxdepth: 3
+
+Octree Mesh
+-----------
+
+In order to accurately simulate our earth model, we need a mesh
+that is refined in key areas, while being coarse enough elsewhere to
+efficiently simulate data.  The plate simulation package includes
+refinements at the earth-air interface, the transmitter and receiver
+sites and on the surface of plates.
+
+.. figure:: /images/plate-simulation/methodology/mesh/refinement.png
+    :align: center
+    :width: 100%
+
+    *Octree mesh refinement for earth-air interface, receiver sites,
+    and within the mesh.*
+
+The meshing can be controlled by options exposed in the ui.json.
+Those options are significantly reduced compared with the octree creation from
+`grid-app <https://mirageoscience-grid-apps.readthedocs-hosted.com/>`_
+since we have tailored many of the parameters to suit the needs of plate simulation.
+
+.. figure:: /images/plate-simulation/methodology/mesh/mesh_options.png
+    :align: center
+
+    *Octree mesh parameters exposed in the ui.json.*
+
+Geological Model
+----------------
+
+The plate simulation package includes a module for generating
+plate(s) embedded in a two-layer Earth model within octree meshes.
+There are many permutations of this simple geological scenario
+leading to a complex interface. To simplify things, we have
+broken the discussion into two sub-sections: background
+(basement and overburden) and plates.
+
+Background
+~~~~~~~~~~
+
+All model values within plate-simulation are to be provided in
+ohm-metres.  The basement resistivity is actually closer to a
+halfspace in the sense that it fills the model anywhere outside
+of the overburden and plate.  So the basement resistivity should
+be chosen as an effective resistivity for the whole geological
+section.  This should be quite reasonable for most applications
+where the differences in resistivity between layers is much smaller
+than the difference between overburden and any anomalous bodies
+(plates).
+
+.. figure:: /images/plate-simulation/methodology/model/basement_options.png
+    :align: center
+
+    *Basement resistivity option.*
+
+The overburden is discretized by the resistivity and thickness
+of the layer.  The thickness is referenced to the earth-air
+interface and extends into the earth by the amount specified
+in the thickness parameter.
+
+.. figure:: /images/plate-simulation/methodology/model/overburden_options.png
+    :align: center
+
+    *Overburden resistivity and thickness options.*
+
+.. figure:: /images/plate-simulation/methodology/model/overburden_and_basement.png
+    :align: center
+    :width: 100%
+
+    *Model section highlighting the overburden and basement boundary.*
+
+Plates
+~~~~~~
+
+In this section we will discuss the various plate options available
+through the ui.json and their impact on the resulting discretized
+model.
+
+.. figure:: /images/plate-simulation/methodology/model/plate_options.png
+    :align: center
+
+    *Plate options available in the ui.json.*
+
+The first set of options allows the user to specify the number of
+plates and their spacing.
+
+.. figure:: /images/plate-simulation/methodology/model/n_plates_options.png
+    :align: center
+
+    *Number of plates and spacing options.*
+
+For all choices of ``n>1``, the plates will be evenly spaced at the requested
+spacing and will share the same resistivity, size and orientation.
+
+.. figure:: /images/plate-simulation/methodology/model/three_plates.png
+    :align: center
+    :width: 100%
+
+    *Model created by choosing three plates spaced at 200m.*
+
+The plate resistivity is expected to be entered in ohm-metres.
+
+.. figure:: /images/plate-simulation/methodology/model/plate_resistivity_option.png
+    :align: center
+
+    *Plate resistivity option.*
+
+The size of the plate is given as a 'thickness', 'strike length', and
+'dip length'.
+
+.. figure:: /images/plate-simulation/methodology/model/plate_size_options.png
+    :align: center
+
+    *Plate size options.*
+
+The image below shows a dipping plate with annotations showing the size
+parameters for that particular plate.
+
+.. figure:: /images/plate-simulation/methodology/model/plate_size.png
+    :align: center
+    :width: 100%
+
+    *A dipping plate striking northeast with annotations for its thickness,
+    strike length and dip length.*
+
+The orientation of the plate is provided in terms of a dip and dip direction.
+The dip is defined as the angle between the horizontal projection of the plate
+normal and the plate tangent sharing the same origin.  The dip direction is
+measured between the horizontal projection of the plate normal and the North
+arrow. See the image below for a visual representation of these angles.
+
+.. figure:: /images/plate-simulation/methodology/model/plate_orientation.png
+    :align: center
+    :width: 100%
+
+    *Plate orientation options.  Plate orientation is given as a dip and dip direction.
+    The dip (b) is defined as the angle between the horizontal the projection of the
+    plate normal (n\') and the plate tangent sharing the same origin (t).  The dip
+    direction (a) is the angle measured between the horizontal projection of the plate
+    normal (n\') and due north (N).*
+
+The location of the plate can be provided in both relative and absolute terms.
+The position parameters are given as an easting, northing, and elevation.  If the
+relative locations checkbox is chosen, then the easting and northing will be
+relative to the center of the survey and the elevation will be relative to one of
+the available references.  The elevation may either be referenced to the earth-air
+interface or the overburden provided by the ``Depth reference`` dropdown.  Either of
+these choice can be relative to the minimum, maximum, or mean of the points making
+up the reference surface as given by the ``Reference type`` dropdown.  In all of these
+cases the distance provided will act as a depth below the reference to the *top of
+plate* in the *z negative down* convention.  If the relative locations checkbox is not
+chosen, then the easting, northing, and elevation is simply the location of the
+center of the plate.
+
+.. figure:: /images/plate-simulation/methodology/model/plate_location_options.png
+    :align: center
+
+    *Plate location options in relative mode. Notice the* ``Elevation`` *is given as
+    negative to ensure the top of the plate is below the selected min of the
+    overburden.*
+
+.. figure:: /images/plate-simulation/methodology/model/plate_location.png
+    :align: center
+    :width: 100%
+
+    *Example of a relative elevation referenced 100m below the minimum of the
+    overburden layer.*
+
+Data Simulation
+---------------
+
+.. _simpeg_group_options:
+
+The simulation parameters control the forward modeling of the plate model
+discretized within the octree mesh.  Rather than exposing the parameters within
+the plate simulation interface all over again, we simply allow the user to
+select an existing forward modelling SimPEG group.  It is expected that the
+user will have already edited those options and provided at least a topography
+and survey object as well as selected one or more components to simulate.  The
+user may also provide a name to the new SimPEG group that will be used to store
+the results.
+
+
+.. figure:: /images/plate-simulation/methodology/data/simpeg_group_options.png
+    :align: center
+
+    *Selecting the initialized forward modelling SimPEG group and naming the
+    group that will store the plate simulation results.*
+
+The required SimPEG group can be created within Geoscience ANALYST through the
+``Geophysics`` menu under ``SimPEG Python Interface`` entry.
+
+.. figure:: /images/plate-simulation/methodology/data/simpeg_group_creation.png
+    :align: center
+    :width: 100%
+
+    *Creating a SimPEG group to be selected within the plate simulation interface.*
+
+Once created, the options can be edited by right-clicking the group and choosing
+the 'Edit Options' entry.
+
+.. figure:: /images/plate-simulation/methodology/data/simpeg_group_edit_options.png
+    :align: center
+
+    *Editing the SimPEG group options.*
+
+Since plate-simulation will create its own mesh and model, the mesh and
+conductivity selections can be ignored.  Selecting a value will not conflict
+with the plate-simulation objects and will simply be ignored.  In contrast, the
+survey, topography and at least one component must be selected to run the simulation.
+
+.. figure:: /images/plate-simulation/methodology/data/simulation_options.png
+    :align: center
+    :width: 80%
+
+    *Simulation options with annotations for required and not required components.*
+
+Results
+-------
+
+The results of the simulation are stored in the SimPEG group named in the
+:ref:`simpeg group option <simpeg_group_options>` section.
+
+.. figure:: /images/plate-simulation/methodology/results.png
+    :align: center
+
+    *Results group containing a survey object with all the simulated data channels
+    stored in property groups, and an octree mesh containing the model parameterized
+    in the interface.*
+
+To iterate on the design of experiment, simply copy the options, edit, and
+run again.
+
+.. figure:: /images/plate-simulation/methodology/copy_options.png
+    :align: center
+
+    *Copying the options to run a new simulation.*
+
+If the user wishes to sweep one or more of the input parameters to run a large number of
+simulations, they can use the ``generate sweep file`` option to write a file used
+by the `param-sweeps <https://github.com/MiraGeoscience/param-sweeps>`_ package to do just
+that. It is beyond the scope of this document to discuss the use of that package;
+refer to its README for further details.
+
+.. figure:: /images/plate-simulation/methodology/sweep_option.png
+    :align: center
+
+    *Generating a sweep file to run multiple simulations.*
diff --git a/docs/plate-simulation/usage.rst b/docs/plate-simulation/usage.rst
@@ -0,0 +1,35 @@
+.. _plate_simulation_usage:
+
+Plate Simulation: Basic usage
+=============================
+
+The main entry points to the various modules is the `plate_simulation.ui.json <https://github.com/MiraGeoscience/plate-simulation/blob/develop/plate_simulation-assets/uijson/plate_simulation.ui.json>`_
+file. The ``ui.json`` has the dual purpose of (1) rendering a user-interface from
+Geoscience ANALYST and (2) storing the input parameters chosen by the user for the
+program to run. To learn more about the ui.json interface visit the
+`UIJson documentation <https://mirageoscience-geoh5py.readthedocs-hosted.com/en/latest/content/uijson_format/usage.html>`_ page.
+
+
+User-interface
+--------------
+
+The user-interface is accessible from Geoscience ANALYST Pro Geophysics menu.
+
+.. figure:: /images/plate-simulation/basic_usage/analyst_geophysics_menu.png
+        :align: center
+        :width: 800
+
+
+From command line
+-----------------
+
+The application can also be run from the command line if all required fields in the ui.json are provided.
+This is useful for more advanced users wanting to automate the mesh creation process or re-run an existing mesh with different parameters.
+
+To run the application from the command line, use the following command in a Conda Prompt:
+
+``conda activate plate-simulation``
+
+``python -m plate-simulation.driver input_file.json``
+
+where ``input_file.json`` is the path to the input file on disk.