diff --git a/docs/THIRD_PARTY_SOFTWARE.rst b/docs/THIRD_PARTY_SOFTWARE.rst index 75e658dd4..1066c930b 100644 --- a/docs/THIRD_PARTY_SOFTWARE.rst +++ b/docs/THIRD_PARTY_SOFTWARE.rst @@ -17,9 +17,15 @@ compatibly licensed. We list these here. * - `discretize `_ - MIT - Discretization tools for finite volume and inverse problems + * - `geoapps-utils `_ + - MIT + - Collection of utilities for creating applications and manipulating geoh5 objects * - `geoh5py `_ - LGPL-3.0-or-later - Python API for geoh5, an open file format for geoscientific data + * - `grid-apps `_ + - MIT + - Grid creation and manipulation using GEOH5 format. * - `numpy `_ - BSD-3-Clause - Fundamental package for array computing in Python @@ -32,6 +38,9 @@ compatibly licensed. We list these here. * - `pymatsolver `_ - MIT - Matrix Solvers for Python. + * - `Rtree `_ + - MIT + - Spatial index for Python GIS * - `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 `_ - MIT - SimPEG: Simulation and Parameter Estimation in Geophysics + * - `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 `_ - MPL-2.0 or MIT - A Fast, Extensible Progress Bar for Python and CLI + * - `trimesh `_ + - MIT + - Python library for loading and using triangular meshes diff --git a/docs/_toc.yml b/docs/_toc.yml index 0bcf4b085..5686cb83f 100644 --- 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/images/plate-simulation/basic_usage/analyst_geophysics_menu.png b/docs/images/plate-simulation/basic_usage/analyst_geophysics_menu.png new file mode 100644 index 000000000..5f3c007f8 Binary files /dev/null and b/docs/images/plate-simulation/basic_usage/analyst_geophysics_menu.png differ diff --git a/docs/images/plate-simulation/index.png b/docs/images/plate-simulation/index.png new file mode 100644 index 000000000..c3923d0d2 Binary files /dev/null and b/docs/images/plate-simulation/index.png differ diff --git a/docs/images/plate-simulation/methodology/copy_options.png b/docs/images/plate-simulation/methodology/copy_options.png new file mode 100644 index 000000000..b27b6c9c2 Binary files /dev/null and b/docs/images/plate-simulation/methodology/copy_options.png differ diff --git a/docs/images/plate-simulation/methodology/data/simpeg_group_creation.png b/docs/images/plate-simulation/methodology/data/simpeg_group_creation.png new file mode 100644 index 000000000..4abfd1459 Binary files /dev/null and b/docs/images/plate-simulation/methodology/data/simpeg_group_creation.png differ 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 new file mode 100644 index 000000000..9af867036 Binary files /dev/null and b/docs/images/plate-simulation/methodology/data/simpeg_group_edit_options.png differ diff --git a/docs/images/plate-simulation/methodology/data/simpeg_group_options.png b/docs/images/plate-simulation/methodology/data/simpeg_group_options.png new file mode 100644 index 000000000..6a8f2274d Binary files /dev/null and b/docs/images/plate-simulation/methodology/data/simpeg_group_options.png differ diff --git a/docs/images/plate-simulation/methodology/data/simulation_options.png b/docs/images/plate-simulation/methodology/data/simulation_options.png new file mode 100644 index 000000000..7478120b6 Binary files /dev/null and b/docs/images/plate-simulation/methodology/data/simulation_options.png differ diff --git a/docs/images/plate-simulation/methodology/make_plate_images.pub b/docs/images/plate-simulation/methodology/make_plate_images.pub new file mode 100644 index 000000000..b49b4c867 Binary files /dev/null and b/docs/images/plate-simulation/methodology/make_plate_images.pub differ diff --git a/docs/images/plate-simulation/methodology/mesh/mesh_options.png b/docs/images/plate-simulation/methodology/mesh/mesh_options.png new file mode 100644 index 000000000..110132ab9 Binary files /dev/null and b/docs/images/plate-simulation/methodology/mesh/mesh_options.png differ diff --git a/docs/images/plate-simulation/methodology/mesh/refinement.png b/docs/images/plate-simulation/methodology/mesh/refinement.png new file mode 100644 index 000000000..4a9a92090 Binary files /dev/null and b/docs/images/plate-simulation/methodology/mesh/refinement.png differ diff --git a/docs/images/plate-simulation/methodology/model/basement_options.png b/docs/images/plate-simulation/methodology/model/basement_options.png new file mode 100644 index 000000000..74949f126 Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/basement_options.png differ diff --git a/docs/images/plate-simulation/methodology/model/n_plates_options.png b/docs/images/plate-simulation/methodology/model/n_plates_options.png new file mode 100644 index 000000000..e2a9234c0 Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/n_plates_options.png differ diff --git a/docs/images/plate-simulation/methodology/model/overburden_and_basement.png b/docs/images/plate-simulation/methodology/model/overburden_and_basement.png new file mode 100644 index 000000000..62ac7eb6d Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/overburden_and_basement.png differ diff --git a/docs/images/plate-simulation/methodology/model/overburden_options.png b/docs/images/plate-simulation/methodology/model/overburden_options.png new file mode 100644 index 000000000..2a5e3beb5 Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/overburden_options.png differ diff --git a/docs/images/plate-simulation/methodology/model/plate_location.png b/docs/images/plate-simulation/methodology/model/plate_location.png new file mode 100644 index 000000000..50557ea99 Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/plate_location.png differ diff --git a/docs/images/plate-simulation/methodology/model/plate_location_options.png b/docs/images/plate-simulation/methodology/model/plate_location_options.png new file mode 100644 index 000000000..8e8f85b5e Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/plate_location_options.png differ diff --git a/docs/images/plate-simulation/methodology/model/plate_options.png b/docs/images/plate-simulation/methodology/model/plate_options.png new file mode 100644 index 000000000..77c881901 Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/plate_options.png differ diff --git a/docs/images/plate-simulation/methodology/model/plate_orientation.png b/docs/images/plate-simulation/methodology/model/plate_orientation.png new file mode 100644 index 000000000..9e2c77251 Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/plate_orientation.png differ diff --git a/docs/images/plate-simulation/methodology/model/plate_orientation_options.png b/docs/images/plate-simulation/methodology/model/plate_orientation_options.png new file mode 100644 index 000000000..1329d0730 Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/plate_orientation_options.png differ diff --git a/docs/images/plate-simulation/methodology/model/plate_resistivity_option.png b/docs/images/plate-simulation/methodology/model/plate_resistivity_option.png new file mode 100644 index 000000000..af56b9bde Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/plate_resistivity_option.png differ diff --git a/docs/images/plate-simulation/methodology/model/plate_size.png b/docs/images/plate-simulation/methodology/model/plate_size.png new file mode 100644 index 000000000..1b8a6d6c7 Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/plate_size.png differ diff --git a/docs/images/plate-simulation/methodology/model/plate_size_options.png b/docs/images/plate-simulation/methodology/model/plate_size_options.png new file mode 100644 index 000000000..184fc6a99 Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/plate_size_options.png differ diff --git a/docs/images/plate-simulation/methodology/model/three_plates.png b/docs/images/plate-simulation/methodology/model/three_plates.png new file mode 100644 index 000000000..92196fd0d Binary files /dev/null and b/docs/images/plate-simulation/methodology/model/three_plates.png differ diff --git a/docs/images/plate-simulation/methodology/results.png b/docs/images/plate-simulation/methodology/results.png new file mode 100644 index 000000000..03766238e Binary files /dev/null and b/docs/images/plate-simulation/methodology/results.png differ diff --git a/docs/images/plate-simulation/methodology/sweep_option.png b/docs/images/plate-simulation/methodology/sweep_option.png new file mode 100644 index 000000000..5629a42b3 Binary files /dev/null and b/docs/images/plate-simulation/methodology/sweep_option.png differ diff --git a/docs/images/plate-simulation/methodology/uijson.png b/docs/images/plate-simulation/methodology/uijson.png new file mode 100644 index 000000000..4a4b8c2be Binary files /dev/null and b/docs/images/plate-simulation/methodology/uijson.png differ diff --git a/docs/plate-simulation/index.rst b/docs/plate-simulation/index.rst new file mode 100644 index 000000000..eb8b29512 --- /dev/null +++ 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 `_ +and `SimPEG `_ 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 `_. + +See: + +- :ref:`Basic Usage ` +- :ref:`Methodology ` diff --git a/docs/plate-simulation/methodology.rst b/docs/plate-simulation/methodology.rst new file mode 100644 index 000000000..87bbeeea5 --- /dev/null +++ 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 `_ for +octree mesh creation, and `SimPEG `_ 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 `_ +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 ` 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 `_ 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 new file mode 100644 index 000000000..f940b6ca8 --- /dev/null +++ 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 `_ +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 `_ 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.