[DOC] Tut1 updated

Author: Leguark

examples/tutorials/ch1_fundamentals/ch1_1_basics.py

@@ -52,7 +52,7 @@
 geo_model: gp.data.GeoModel = gp.create_geomodel(
     project_name='Tutorial_ch1_1_Basics',
     extent=[0, 2000, 0, 2000, 0, 750],
-    refinement=4,  # * Here we define the number of octree levels. If octree levels are defined, the resolution is ignored.
+    refinement=6,  # * Here we define the number of octree levels. If octree levels are defined, the resolution is ignored.
     importer_helper=gp.data.ImporterHelper(
         path_to_orientations=data_path + "/data/input_data/getting_started/simple_fault_model_orientations.csv",
         path_to_surface_points=data_path + "/data/input_data/getting_started/simple_fault_model_points.csv",
@@ -68,10 +68,14 @@
 #    simplifies the process of passing multiple arguments needed for importing data and will likely see further 
 #    extensions in the future. Currently, one of its uses is to handle `pooch` arguments for downloading data from the internet.
 #
-# 
+#
+#
+# ### Reviewing the Imported Data
+#
+# Now that the `geo_model` object is set up and the data imported from the CSV files, we review the data imported using the properties `surface_points_copy` and `orientations_copy`.
+#
+# Using `structural_frame.element_id_name_map`, we can see which ID corresponds to which structural element name in the data.
 
-# The input data can be reviewed using the properties `surface_points` and `orientations`. However, note that at this point,
-# the sequence of formations and their assignment to series are still arbitrary. We will rectify this in the subsequent steps.
 
 # %% 
 geo_model.surface_points_copy
@@ -107,7 +111,13 @@
 # "newer" series.
 #
 # By default, we create a simple sequence inferred from the data:
-# 
+#
+#
+# ## Setting Up the Structural Framework
+#
+# Each data entry includes an ID that corresponds to a formation name, which GemPy uses to create a base structural framework.
+# However, the sequence of these formations is still arbitrary, as they have all automatically been assigned to the default
+# structural group in our `geo_model` object. We will fix this in the subsequent steps.
 
 # %%
 geo_model.structural_frame
@@ -124,6 +134,35 @@
 # input data. 
 # 
 
+# ### Declaring the Sequential Order of Structural Elements (Geological Formations)
+#
+# In our model, we want the geological units to appear in the correct chronological order. This order could be determined by a sequence
+# of stratigraphic deposition, unconformities due to erosion, or other lithological genesis events like igneous intrusions. A similar
+# age-related order is declared for faults in our model. In GemPy, we use the function `gempy.map_stack_to_surfaces` to assign formations
+# or faults to different sequential series by declaring them in a Python dictionary.
+
+#
+# The correct ordering of series is crucial for model construction! It's possible to assign several surfaces to one series. The order of
+# units within a series only affects the color code, so we recommend maintaining consistency. The order can be defined by simply changing
+# the order of the lists within the `gempy.core.data.StructuralFrame.structural_groups` and `gempy.core.data.StructuralGroups.elements` attributes.
+#
+# Faults are treated as independent groups and must be younger than the groups they affect. The relative order between different faults
+# defines their tectonic relationship (the first entry is the youngest).
+#
+# For a model with simple sequential stratigraphy, all layer formations can be assigned to one series without an issue. All unit
+# boundaries and their order would then be determined by interface points. However, to model more complex lithostratigraphical
+# relations and interactions, separate series definitions become important. For example, modeling an unconformity or an intrusion
+# that disrupts older stratigraphy would require declaring a younger series.
+#
+# By default, a simple sequence/group is created inferred from the data as shown above.
+#
+# Our example model comprises four main layers (plus an underlying basement that is automatically generated by GemPy) and one main
+# normal fault displacing those layers. Assuming a simple stratigraphy where each younger unit was deposited onto the underlying
+# older one, we can assign these layer formations to one structural group called "Strat_Series". For the fault, we declare a
+# respective "Fault_Series" as the first key entry in the mapping dictionary. We could give any other names to these series;
+# the formations, however, have to be referred to as named in the input data.
+#
+# In the following, we map the "Main Fault" to the "Fault Series" and the individual formations to the "Strat Series".
 
 # %%
 gp.map_stack_to_surfaces(
@@ -135,6 +174,10 @@
     }
 )
 
+# %%
+# Note how the structural frame still indicates the "Fault Series" group to have a relation type "erode".
+# We still need to tell GemPy that we want this group to be a fault. We do this using the function `set_is_fault`.
+
 geo_model.structural_frame  # Display the resulting structural frame
 
 # %% 
@@ -162,31 +205,29 @@
 # Visualizing input data
 # ~~~~~~~~~~~~~~~~~~~~~~
 # 
-# We can also visualize our input data. This might for example be useful
-# to check if all points and measurements are defined the way we want them
-# to. Using the function :obj:`gempy_viewer.plot2d`, we attain a 2D projection of our
-# data points onto a plane of chosen *direction* (we can choose this
-# attribute to be either :math:`x`, :math:`y` or :math:`z`).
-# 
+# Since we have already imported our input data, we can go ahead and visualize it in 2D and 3D. This can be useful to check if all points
+# and orientations are defined the way we want them to be. Using the function `gempy_viewer.plot2d`, we obtain a 2D projection of our
+# data points onto a plane of the chosen *direction* (we can choose this attribute to be either $x$, $y$ or $z$, with the default being $y$).
+# Below, we can freely switch the direction and check out the projection from different sides to get a good idea.
+
 
 # %%
 plot = gpv.plot_2d(geo_model, show_lith=False, show_boundaries=False)
 
 # %%
-# Using  :obj:`gempy_viewer.plot_3d`, # we can also visualize this data in 3D. Note that
-# direct 3D visualization in GemPy requires `the Visualization
-# Toolkit <https://www.vtk.org/>`__ (VTK) to be installed.
-# 
+ #Beyond 2D, however, we can also visualize our input data in full 3D using `gempy_viewer.plot_3d`. Note that direct 3D visualization
+# in GemPy requires [the Visualization Toolkit](https://www.vtk.org/) (VTK) to be installed.
+
 
 # %%
 gpv.plot_3d(geo_model, image=False, plotter_type='basic')
 
 # %%
 # Model Generation
 # ~~~~~~~~~~~~~~~~
-# Once we've correctly defined all our primary information in our 
-# `gempy.core.data.GeoModel` object (referred to as `geo_model` in these tutorials),
-# we can proceed to the next step: preparing the input data for interpolation.
+# Once we've correctly defined all our primary information in our `gempy.core.data.GeoModel` object (referred to as `geo_model`
+# in these tutorials), we can proceed with the model computation step. We can go ahead and save the solution of a specific computation
+# as we do below, but solutions are also stored within the `gempy.core.data.GeoModel` object for future reference.
 #
 #
 # .. admonition:: New in GemPy 3!  Numpy and TensorFlow backend