[DOC] First pass to mik

Author: Leguark

examples/examples/real/mik.py

@@ -1,25 +1,26 @@
 """
-Alesmodel: Plotting Sections and Maps
-======================================
+Unknown Model: Importing Borehole Data and Building a 3D Geological Model with GemPy
+====================================================================================
 """
 
-# %% md
-# <img src="https://docs.gempy.org/_static/logos/gempy.png" alt="drawing" width="400"/>
-#
-# # 2.2 From Drillhole Data to GemPy Model
-#
-# In this section, we will explore how to take borehole or drillhole data and convert it into a format compatible with GemPy, creating a 3D geological model. Borehole data is commonly collected in the mining, oil, and gas industries and contains information about subsurface geological formations, including lithologies, stratigraphy, and the geometry of layers or faults.
+# %%
+# In this section, we will explore how to take borehole or drillhole data and convert it into a format compatible with GemPy,
+# creating a 3D geological model. Borehole data is commonly collected in the mining, oil, and gas industries and contains 
+# information about subsurface geological formations, including lithologies, stratigraphy, and the geometry of layers or faults.
 #
-# For this, we will rely on several helper functions from the `subsurface` package to extract borehole data and translate it into a 3D structure that GemPy can use for modeling.
+# For this, we will rely on several helper functions from the `subsurface` package to extract borehole data and translate it 
+# into a 3D structure that GemPy can use for modeling.
 # We will cover:
 #
 # - Downloading the borehole data
 # - Processing the data using `subsurface`
 # - Visualizing borehole locations and lithology data in 3D
-
-# %%
-# ### Downloading Borehole Data
-# The borehole data is hosted online, and we can use the `pooch` library to download it directly. `pooch` is a library for fetching datasets from the internet. We will download a CSV file that contains the borehole information, including collar positions, survey data, and lithology logs.
+#
+# Downloading Borehole Data
+# """""""""""""""""""""""""
+# The borehole data is hosted online, and we can use the `pooch` library to download it directly. `pooch` is a library for 
+# fetching datasets from the internet. We will download a CSV file that contains the borehole information, including collar
+# positions, survey data, and lithology logs.
 #
 # Let's start by downloading the dataset and inspecting its content.
 
@@ -46,7 +47,6 @@
 # Importing GemPy
 import gempy as gp
 
-#
 # %% md
 # We use `pooch` to download the dataset into a temp file:
 # %%
@@ -57,9 +57,11 @@
 raw_borehole_data_csv = pooch.retrieve(url, known_hash)
 
 # %% md
-# Now we can use `subsurface` function to help us reading csv files into pandas dataframes that the package can understand. Since the combination of styles data is provided can highly vary from project to project, `subsurface` provides some *helpers* functions to parse different combination of .csv
-# %%
+# Now we can use `subsurface` function to help us reading csv files into pandas dataframes that the package can understand. 
+# Since the combination of styles data is provided can highly vary from project to project, `subsurface` provides some *helpers* 
+# functions to parse different combination of .csv
 
+# %%
 # Read the collar data from the CSV
 collar_df: pd.DataFrame = read_collar(
     GenericReaderFilesHelper(
@@ -86,18 +88,24 @@
 )
 
 # %%
-# ### Visualizing the Borehole Collars
-# Once we have the borehole collars data, we can visualize them in 3D using the `pyvista` package. This gives us a good overview of where the boreholes are located in space. In this visualization, each borehole will be represented by a point, and we will label the boreholes using their IDs.
+# Visualizing the Borehole Collars
+# """"""""""""""""""""""""""""""""
+# Once we have the borehole collars data, we can visualize them in 3D using the `pyvista` package. This gives us a good 
+# overview of where the boreholes are located in space. In this visualization, each borehole will be represented by a point, 
+# and we will label the boreholes using their IDs.
 well_mesh = to_pyvista_points(collars.collar_loc)
 
 # Plot the collar points
 pv_plot([well_mesh], image_2d=True)
 
 # %%
-# ### Reading Borehole Survey Data
-# Borehole surveys give us information about the trajectory of each borehole, including its depth (measured depth). The survey data allows us to compute the full 3D path of each wellbore. We will use the `read_survey` function from `subsurface` to read this data.
-# %%
+# Reading Borehole Survey Data
+# """"""""""""""""""""""""""""
+# Borehole surveys give us information about the trajectory of each borehole, including its depth (measured depth). 
+# The survey data allows us to compute the full 3D path of each wellbore. We will use the `read_survey` function from 
+# `subsurface` to read this data.
 
+# %%
 # Create the Survey object
 survey_df: pd.DataFrame = read_survey(
     GenericReaderFilesHelper(
@@ -112,8 +120,11 @@
 survey
 
 # %%
-# ### Reading Lithology Data
-# Next, we will read the lithology data. Lithology logs describe the rock type or geological unit encountered at different depths within each borehole. Using `read_lith`, we will extract the lithology data, which includes the top and base depths of each geological formation within the borehole, as well as the formation name.
+# Reading Lithology Data
+# """"""""""""""""""""""
+# Next, we will read the lithology data. Lithology logs describe the rock type or geological unit encountered at different 
+# depths within each borehole. Using `read_lith`, we will extract the lithology data, which includes the top and base depths
+# of each geological formation within the borehole, as well as the formation name.
 
 # %%
 # Your code here:
@@ -134,10 +145,14 @@
 
 lith
 # %%
-# ### Creating a Borehole Set and Visualizing in 3D
-# Now that we have both the collar data and the lithology logs, we can combine them into a `BoreholeSet` object. This object combines the collar, survey, and lithology data and allows us to create a 3D visualization of the borehole trajectories and their associated lithologies.
+# Creating a Borehole Set and Visualizing in 3D
+# """""""""""""""""""""""""""""""""""""""""""""
+# Now that we have both the collar data and the lithology logs, we can combine them into a `BoreholeSet` object. This object 
+# combines the collar, survey, and lithology data and allows us to create a 3D visualization of the borehole trajectories and
+# their associated lithologies.
 #
-# We will use `pyvista` to plot the borehole trajectories as lines, and we will color them according to their lithologies. Additionally, we will label the collars for easy identification.
+# We will use `pyvista` to plot the borehole trajectories as lines, and we will color them according to their lithologies. 
+# Additionally, we will label the collars for easy identification.
 
 # Combine collar and survey into a BoreholeSet
 borehole_set = BoreholeSet(
@@ -147,16 +162,16 @@
 )
 
 # %%
-
 # Visualize boreholes with pyvista
+import matplotlib.pyplot as plt
+
 well_mesh = to_pyvista_line(
     line_set=borehole_set.combined_trajectory,
     active_scalar="lith_ids",
     radius=40
 )
 
 p = init_plotter()
-import matplotlib.pyplot as plt
 
 # Set colormap for lithologies
 boring_cmap = plt.get_cmap(name="viridis", lut=14)
@@ -174,25 +189,21 @@
     bold=True
 )
 
-# Show 3D plot or save a 2D image depending on the flag
-if plot3D := False:
-    p.show()
-else:
-    img = p.show(screenshot=True)
-    img = p.last_image
-    fig = plt.imshow(img)
-    plt.axis('off')
-    plt.show(block=False)
-    p.close()
+
+p.show()
 
 # %% md
-# ## Structural Elements from Borehole Set
+# Structural Elements from Borehole Set
+# """""""""""""""""""""""""""""""""""""
 #
-# Now that we have successfully imported and visualized the borehole data, we can move on to creating the geological formations (or structural elements) based on the borehole data. Each lithological unit will be associated with a unique identifier and a color, allowing us to distinguish between different formations when we visualize the model.
+# Now that we have successfully imported and visualized the borehole data, we can move on to creating the geological 
+# formations (or structural elements) based on the borehole data. Each lithological unit will be associated with a unique 
+# identifier and a color, allowing us to distinguish between different formations when we visualize the model.
 #
-# GemPy offers the function `gempy.structural_elements_from_borehole_set`, which extracts these structural elements from the borehole data and associates each one with a name, ID, and color.
-# %%
+# GemPy offers the function `gempy.structural_elements_from_borehole_set`, which extracts these structural elements from 
+# the borehole data and associates each one with a name, ID, and color.
 
+# %%
 # Initialize the color generator for formations
 colors_generator = gp.data.ColorsGenerator()
 
@@ -257,13 +268,16 @@
 
 
 # %% md
-# ## Initializing the GemPy Model
-#
-# After defining the geological formations, we need to initialize the GemPy model. The first step in this process is to create a `GeoModel` object, which serves as the core container for all data related to the geological model.
+# Initializing the GemPy Model
+# """"""""""""""""""""""""""""
+# After defining the geological formations, we need to initialize the GemPy model. The first step in this process is to 
+# create a `GeoModel` object, which serves as the core container for all data related to the geological model.
 #
-# We will also define a **regular grid** to interpolate the geological layers. GemPy uses a meshless interpolator to create geological models in 3D space, but grids are convenient for visualization and computation.
+# We will also define a **regular grid** to interpolate the geological layers. GemPy uses a meshless interpolator to 
+# create geological models in 3D space, but grids are convenient for visualization and computation.
 #
-# GemPy supports various grid types, such as regular grids for visualization, custom grids, topographic grids, and more. For this example, we will use a regular grid with a medium resolution.
+# GemPy supports various grid types, such as regular grids for visualization, custom grids, topographic grids, and more.
+# For this example, we will use a regular grid with a medium resolution.
 
 # %%
 import gempy_viewer as gpv
@@ -274,16 +288,19 @@
     elements=elements,
     structural_relation=gp.data.StackRelationType.ERODE
 )
+
 # Define the structural frame
 structural_frame = gp.data.StructuralFrame(
     structural_groups=[group],
     color_gen=colors_generator
 )
 
 # %% md
-# ### Defining Model Extent and Grid Resolution
-#
-# We now determine the extent of our model based on the surface points provided. This ensures that the grid covers the entire area where the geological data points are located. Additionally, we set a grid resolution of 50x50x50 for a balance between performance and model detail.
+# Defining Model Extent and Grid Resolution
+# """""""""""""""""""""""""""""""""""""""""
+# We now determine the extent of our model based on the surface points provided. This ensures that the grid covers the
+# entire area where the geological data points are located. Additionally, we set a grid resolution of 50x50x50 for a 
+# balance between performance and model detail.
 
 all_surface_points_coords: gp.data.SurfacePointsTable = structural_frame.surface_points_copy
 extent_from_data = all_surface_points_coords.xyz.min(axis=0), all_surface_points_coords.xyz.max(axis=0)
@@ -304,9 +321,10 @@
 )
 
 # %% md
-# ### 3D Visualization of the Model
-#
-# After initializing the GeoModel, we can proceed to visualize it in 3D using GemPy's `plot_3d` function. This function allows us to see the full 3D geological model with all the defined formations.
+# 3D Visualization of the Model
+# """""""""""""""""""""""""""""
+# After initializing the GeoModel, we can proceed to visualize it in 3D using GemPy's `plot_3d` function. This function 
+# allows us to see the full 3D geological model with all the defined formations.
 
 gempy_plot = gpv.plot_3d(
     model=geo_model,
@@ -319,9 +337,10 @@
 )
 
 # %% md
-# ### Adding Boreholes and Collars to the Visualization
-#
-# To enhance the 3D model, we can combine the geological formations with the borehole trajectories and collar points that we visualized earlier. This will give us a complete picture of the subsurface, showing both the lithological units and the borehole paths.
+# Adding Boreholes and Collars to the Visualization
+# """""""""""""""""""""""""""""""""""""""""""""""""
+# To enhance the 3D model, we can combine the geological formations with the borehole trajectories and collar points that we
+# visualized earlier. This will give us a complete picture of the subsurface, showing both the lithological units and the borehole paths.
 
 sp_mesh: pyvista.PolyData = gempy_plot.surface_points_mesh
 
@@ -361,17 +380,20 @@
 
 
 # %% md
-# ## Step-by-Step Model Building
-#
-# When building a geological model, it's often better to proceed step by step, adding one surface at a time, rather than trying to interpolate all formations at once. This allows for better control over the model and helps avoid potential issues from noisy or irregular data.
+# Step-by-Step Model Building
+# """""""""""""""""""""""""""
+# When building a geological model, it's often better to proceed step by step, adding one surface at a time, rather
+# than trying to interpolate all formations at once. This allows for better control over the model and helps avoid 
+# potential issues from noisy or irregular data.
 #
 
 # %% md
-# ### Surfaces
-# 
-# ### Adding Surfaces and Formations
-#
-# In GemPy, surfaces mark the bottom of each geological unit. For our model, we will add the first two formations along with the basement, which always needs to be defined. After this, we can visualize the surfaces in 2D.
+# Surfaces
+# """"""""
+# Adding Surfaces and Formations
+# """""""""""""""""""""""""""""
+# In GemPy, surfaces mark the bottom of each geological unit. For our model, we will add the first two formations 
+# along with the basement, which always needs to be defined. After this, we can visualize the surfaces in 2D.
 
 # %%
 group = gp.data.StructuralGroup(
@@ -409,7 +431,8 @@
 # %% md
 # ## Model Computation
 #
-# Now that we have the necessary surface points and orientations, we can compute the final geological model. The `compute_model` function will take all the input data and perform the interpolation to generate the 3D subsurface structure.
+# Now that we have the necessary surface points and orientations, we can compute the final geological model. The 
+# `compute_model` function will take all the input data and perform the interpolation to generate the 3D subsurface structure.
 
 geo_model.interpolation_options
 
@@ -430,9 +453,12 @@
 # -----
 # ## Conclusion
 #
-# In this tutorial, we have demonstrated how to take borehole data and create a 3D geological model in GemPy. We explored how to extract structural elements from borehole data, set up a regular grid for interpolation, and visualize the resulting model in both 2D and 3D.
+# In this tutorial, we have demonstrated how to take borehole data and create a 3D geological model in GemPy. We explored 
+# how to extract structural elements from borehole data, set up a regular grid for interpolation, and visualize the 
+# resulting model in both 2D and 3D.
 #
-# GemPy's flexibility allows you to iteratively build models and refine your inputs for more accurate results, and it integrates seamlessly with borehole data for subsurface geological modeling.
+# GemPy's flexibility allows you to iteratively build models and refine your inputs for more accurate results, and it
+# integrates seamlessly with borehole data for subsurface geological modeling.
 #
 # For further reading and resources, check out:
 

examples/tutorials/a_getting_started/get_started.py

@@ -3,12 +3,13 @@
 ===============
 
 """
+
 # %%
 # Welcome to our introductory notebook on GemPy! Here, we will cover the essentials of GemPy, introducing you to the core concepts of
 # geomodeling and demonstrating how you can leverage these to create your own geological models. We will guide you through building a
 # model from scratch, based on a conceptual 2D cross-section with boreholes. This simple example will highlight key workflow steps 
 # and structural features that GemPy can model.
-
+#
 # Installation
 # """"""""""""
 # 
@@ -36,6 +37,8 @@
 import matplotlib.pyplot as plt
 import matplotlib.image as mpimg
 
+# sphinx_gallery_thumbnail_number = 11
+
 # %% md
 # Main Classes and Objects in GemPy
 # """"""""""""""""""""""""""""""""" 
@@ -75,20 +78,25 @@
 # This object will contain all other data structures and necessary functionality. Here’s what we will do:
 # 
 # 1. **Name the Model**: Assign a name to our model.
+#
 # 2. **Define Extent**: Specify the extent in x, y, and z. The extent should make sense depending on your use case and should enclose all 
-# relevant data in a representative space. For this example, we align the extent with the cross-section we imported:
+#    relevant data in a representative space. For this example, we align the extent with the cross-section we imported:
+#
 #     - **X** is parallel to the section.
-#     - **Y** is perpendicular. Since we have no data along y, a narrow extent makes sense. We choose an extent of 400, defining it as 
-#      -200 to 200, placing the cross-section at y=0 (in the middle).
-#     - **Z**, representing depth, takes a negative value since we are modeling the subsurface.
+#     - **Y** is perpendicular. Since we have no data along y, a narrow extent makes sense. We choose an extent of 400, defining it as -200 to 200, 
+#       placing the cross-section at y=0 (in the middle).
+#     - **Z** representing depth, takes a negative value since we are modeling the subsurface.
+#
 # 3. **Initialize Structural Framework**: Set up a default structural framework.
+#
 # 4. **Define either resolution or refinement**: In GemPy 3, you can use either regular grids or octrees.
 #     - **Regular grids**: Define a resolution (and refinement=None). A medium resolution of 50x50x50, for example, results in 125,000 voxels.
-#     Model voxels are prisms, not cubes, so resolution can differ from extent. Avoid exceeding 100 cells in each direction (1,000,000 voxels)
-#     to prevent high computational costs.
+#       Model voxels are prisms, not cubes, so resolution can differ from extent. Avoid exceeding 100 cells in each direction (1,000,000 voxels)
+#       to prevent high computational costs.
 #     - **Octrees**: Define a level of refinement (and resolution=None). Higher refinement levels increase computational costs.
-
+#
 # .. admonition:: Note on choice of modeling grids 
+#
 #    Which type of grid is used depends on the use case. Note that as of the current version of GemPy 3, 
 #    the rendering of surfaces uses dual-contouring, which is based on octrees. So even if you choose regular grids, octree-based computing will
 #    be executed additionally in order to render the surfaces in 3D.