docs: adding more documentation on structural frames and faults

Loop3D · Oct 19, 2022 · 2fab248 · 2fab248
1 parent 0e5482a
commit 2fab248
Show file tree

Hide file tree

Showing 5 changed files with 44 additions and 0 deletions.
diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml
@@ -0,0 +1,9 @@
+version: "3"
+
+services:
+  structural:
+    build:
+      context: ./
+    volumes:
+      - ../:/LoopStructural
+    command: ./LoopStructural/docs/build_docs.sh
diff --git a/docs/source/images/fault_frame_figure.png b/docs/source/images/fault_frame_figure.png
diff --git a/docs/source/images/structural_frame.png b/docs/source/images/structural_frame.png
diff --git a/docs/source/user_guide/fault_modelling.rst b/docs/source/user_guide/fault_modelling.rst
@@ -58,3 +58,22 @@ The hanging wall of the fault is identified by the positive component of the fau
 
 If `faultfunction` is used the displacement used is provided by faultfunction(coord_0,coord_1,coord_2) for every location in the model.
 A generic faultfunction can be used by passing `faultfunction=`BaseFault`.
+
+How fault modelling works
+=========================
+Faults are modelled in LoopStructural by applying a kinematic operator to the geological feature that is being modelled. 
+The kinematic operator applies the kinematics of the fault in reverse to effectively restore observations or locations to their position prior to faulting. 
+For example to interpolated a folded surface we first construct a fault frame using the observations of the fault surface and slip direction. 
+The displacement of the fault can be constrained using a function of the fault coordinates.
+
+.. image-sg:: /images/fault_frame.png
+   :alt: figure showing fault frame 
+   :srcset: /images/fault_frame.png
+   :class: sphx-glr-single-img
+
+The fault can then be added to the older features that are faulted.
+Before interpolating a geological feature the associated faults, stored in the :attr:`LoopStructural.modelling.features.BaseFeature.faults` attribute of t are applied to the data points constraining the interpolation.
+The geological feature can be built using the restored data. 
+When the feature is evaluated, the locations being evaluated are first past through the list of faults using the :meth:`LoopStructural.modelling.features.BaseFeature._apply_faults`.
+The `apply_faults` method should be called whenever :meth:`LoopStructural.modelling.features.BaseFeature.evaluate_value` or :meth:`LoopStructural.modelling.features.BaseFeature.evaluate_gradient` are overriden.
+
diff --git a/docs/source/user_guide/structural_frames.rst b/docs/source/user_guide/structural_frames.rst
@@ -0,0 +1,16 @@
+Structural Frames
+=================
+
+Structural frames form the basis of many of the geological features that are built using LoopStructural.
+A structural frame is a curvilinear coordinate system with three coordinates:
+* Major structrural feature
+* Structural direction
+* Additional/Intermediate direction
+
+These coordinates correspond to the different elements of geological structures that are observed and recorded by geologists in the field.
+For example, when modelling faults the major structural feature is the fault surface and the structural direction is the fault slip direction.
+For folds, the major structural is the axial foliation and the structural direction is the fold axis.
+
+Each coordinate of the structural frame are represented by three implicit functions. 
+The major structural feature is interpolated first as this is the field usually associated with more observations.
+The structural direction is interpolated using any associated observations, or conceptual knowledge (for example the expected fault slip direction or fold axis) and an additonal constraint to enforce orthogonality between the structural direction and the already interpolated major structural feature.