docs: make the documentation build complete

LoopStructural/modelling/core/geological_model.py

@@ -636,12 +636,13 @@ def set_stratigraphic_column(self, stratigraphic_column, cmap="tab20"):
 
         Notes
         -----
-        stratigraphic_column is a nested dictionary with the format
-        {'group':
+        stratigraphic_column is a nested dictionary with the format::
+
+            {'group':
                 {'series1':
                             {'min':0., 'max':10.,'id':0,'colour':}
                 }
-        }
+            }
 
         """
         warnings.warn(

LoopStructural/utils/dtm_creator.py

@@ -1,5 +1,5 @@
-from ctypes import Union
 from pathlib import Path
+from typing import Union
 
 from .logging import getLogger
 

docs/requirements.txt

@@ -1,6 +1,3 @@
-sphinx
-sphinx_gallery
-sphinxcontrib-bibtex
-pydata_sphinx_theme
-myst-parser
-sphinx-design
+# Build the docs with the project and its docs extra:
+#   pip install -r docs/requirements.txt
+.[docs]

docs/source/getting_started/about.rst

@@ -11,7 +11,7 @@ The interpolation algorithms behind LoopStructural are implementations of resear
 Within LoopStructural we have implemented three discrete interpolation algorithms for implicit 3D modelling:
 
 * A Piecewise Linear Interpolation algorithm where the interpolation is performed on a tetraheral mesh minimising the second derivative of the implicit funtion between neighbouring tetrahedron.
-This interpolation algorithm is an implementation of the discrete smooth interpolation algorithm included in Gocad-Skua, which is heavily based on the work of Frank et al., 2007 and Caumon et al., 2007.
+  This interpolation algorithm is an implementation of the discrete smooth interpolation algorithm included in Gocad-Skua, which is heavily based on the work of Frank et al., 2007 and Caumon et al., 2007.
 
 * This interpolation algorithm can also be framed by minimising the second derivatives using finite different on a regular cartesian grid which has been presented by Irakarama et al.,
 

docs/source/getting_started/contributors_guide.rst

@@ -31,7 +31,7 @@ If you would like to contribute code to LoopStructural please open an `issue <ht
 a bug report or a feature request and then submit a pull request and link it to this issue.
 
 Getting setup
-~~~~~~~~~~~
+~~~~~~~~~~~~~
 To get started, fork and clone the repository. It's then best to get started with conda::
 
     conda activate
@@ -82,6 +82,7 @@ Commit messages
 A changelog is automatically generated from the commit message, the following keywords are identified in the commit log.
 
 .. code-block::
+
     <type>[optional scope]: <description>
 
     [optional body]

docs/source/getting_started/index.rst

@@ -9,4 +9,3 @@ Getting Started
    about
    contributors_guide
    loopstructural_design
-   CHANGELOG

docs/source/index.rst

@@ -52,7 +52,7 @@ evaluate the scalar field and gradient of the interpolator at some random locati
     model = GeologicalModel(bb[0,:],bb[1,:])
     model.data = data
     # nelements specifies the number of discrete interpolation elements
-    # 'stratí' is the feature name in the data dataframe
+    # 'strati' is the feature name in the data dataframe
     model.create_and_add_foliation('strati',nelements=1e5)
     model.update()
     # get the value of the interpolator at some random locations
@@ -84,6 +84,7 @@ constraints.
    :force_static:
 
     from LoopStructural import BoundingBox, InterpolatorBuilder
+    from LoopStructural.geometry import StructuredGrid
     from LoopStructural.utils import EuclideanTransformation
     from LoopStructural.datasets import load_claudius
 
@@ -105,8 +106,13 @@ constraints.
         .build()
     )
     # Set the number of elements in the bounding box to 10000 and create a structured grid
+    # to hold the results
     bounding_box.nelements = 10000
-    mesh = bounding_box.structured_grid()
+    mesh = StructuredGrid(
+        origin=bounding_box.origin,
+        step_vector=bounding_box.step_vector,
+        nsteps=bounding_box.nsteps,
+    )
     # add the interpolated values to the mesh at the nodes
     mesh.properties["v"] = interpolator.evaluate_value(mesh.nodes)
 
@@ -128,12 +134,6 @@ constraints.
    getting_started/index
    _auto_examples/index
    user_guide/index
-
-
-   .. toctree::
-   :caption: LoopStructural API
-   :hidden:
-
    API
 
 

docs/source/user_guide/debugging.rst

@@ -43,7 +43,7 @@ Interpolator is taking a long time
 - Check how many elements you are using, :code:`1e5` should take under 5 minutes on a modern laptop
 - How many faults are associated with the feature? :code:`len(feature.faults)`, you can remove the faults by setting this to an empty list
 
-.. code-block:
+.. code-block::
 
     faults = feature.faults 
     feature.faults = []
@@ -74,7 +74,7 @@ No displacement
 - Check that the displacement is large enough that it should be visible. E.g. compare displacement to model bounding box
 - Has the fault frame interpolated correctly? Coordinates 0 and 1 should both have values.
 
-.. code-block:
+.. code-block::
 
     view.add_scalar_field(fault[0])
     view.add_scalar_field(fault[1])
@@ -84,13 +84,13 @@ No displacement
 - Is the fault parallel to the feature being faulted?
 - Has the fault been added to the feature being faulted?
 
-.. code-block:
+.. code-block::
 
     print([f.name for f in faulted_feature.faults])
 
 - Is the fault displacement vector correct? Add the vector field to the visualisation
 
-.. code-block:
+.. code-block::
 
     view = LavaVuModelViewer(model)
     view.add_vector_field(model['fault'][1],locations=model.regular_grid()[::200]) #random 200 locations

docs/source/user_guide/index.rst

@@ -11,10 +11,12 @@ for a list of topics covered in this section.
 
    what_is_a_geological_model
    input_data
+   preparing_data
    geological_model
+   structural_frames
    interpolation_options
    native_solver
    fold_modelling
    fault_modelling
    visualisation
-   debugging
+   debugging

docs/source/user_guide/interpolation_options.rst

@@ -168,7 +168,7 @@ Iterative solvers:
 * algorithmic multigrid solver - using pyamg
 * lsqr - this solver uses the rectangular matrix directly, therefore does not require computing A.T A and A.T B. Uses scipy
 
-.. code-block:
+.. code-block::
 
   model.create_and_add_foliation('my_foliation',solver='lu')
   model.create_and_add_foliation('my_foliation',solver='chol')
@@ -185,7 +185,7 @@ You can also pass a function that solves
 
 to LoopStructural if you want to use another solver by using the `external` keyword . 
 
-.. code-block:
+.. code-block::
 
   def mysolver(A,B):
     from scipy.sparse.linalg import gmres
@@ -195,7 +195,7 @@ to LoopStructural if you want to use another solver by using the `external` keyw
 
  The solution to the least squares problem will be stored in the interpolator object and can be easily accessed:
 
-.. code-block:
+.. code-block::
 
   model.create_and_add_foliation('my_foliation',solver='pyamg')
   pyamg_solution = model['my_foliation'].interpolator.c[model['my_foliation'].interpolator.region]

docs/source/user_guide/what_is_a_geological_model.rst

@@ -49,6 +49,7 @@ The interpolator can be evaluated on a grid to visualise the geometry of the geo
     import numpy as np
     import pandas as pd
     from LoopStructural import InterpolatorBuilder, BoundingBox
+    from LoopStructural.geometry import StructuredGrid
     from LoopStructural.visualisation import Loop3DView
 
     bounding_box = BoundingBox(np.array([-2, -2, -2]), np.array([2, 2, 2]))
@@ -60,7 +61,11 @@ The interpolator can be evaluated on a grid to visualise the geometry of the geo
         .add_normal_constraints(vector.values).setup_interpolator()
         .build()
     )
-    mesh = bounding_box.structured_grid()
+    mesh = StructuredGrid(
+        origin=bounding_box.origin,
+        step_vector=bounding_box.step_vector,
+        nsteps=bounding_box.nsteps,
+    )
     mesh.properties['val'] = interpolator.evaluate_value(mesh.nodes)
     view = Loop3DView()
     view.add_mesh(mesh.vtk())
@@ -118,7 +123,11 @@ If we were to change the length of the vector we would change the distance betwe
         .add_normal_constraints(vector.values).setup_interpolator()
         .build()
     )
-    mesh2 = bounding_box.structured_grid()
+    mesh2 = StructuredGrid(
+        origin=bounding_box.origin,
+        step_vector=bounding_box.step_vector,
+        nsteps=bounding_box.nsteps,
+    )
     mesh2.properties['val'] = interpolator.evaluate_value(mesh2.nodes)
     view = Loop3DView()
     view.add_mesh(mesh2.vtk().contour([-1, 0, 1]),color='red')
@@ -151,6 +160,7 @@ Following the example above we will use two lines of points with a value of 0 an
     import numpy as np
     import pandas as pd
     from LoopStructural import InterpolatorBuilder, BoundingBox
+    from LoopStructural.geometry import StructuredGrid
     from LoopStructural.visualisation import Loop3DView
 
     x = np.linspace(0, 1, 10)
@@ -175,7 +185,11 @@ Following the example above we will use two lines of points with a value of 0 an
         .setup_interpolator()
         .build()
     )
-    mesh = bounding_box.structured_grid()
+    mesh = StructuredGrid(
+        origin=bounding_box.origin,
+        step_vector=bounding_box.step_vector,
+        nsteps=bounding_box.nsteps,
+    )
     mesh.properties["val"] = interpolator.evaluate_value(mesh.nodes)
     view = Loop3DView()
     view.add_mesh(mesh.vtk().contour([0, 0.5]), opacity=0.4)

examples/1_basic/plot_2_surface_modelling.py

@@ -98,6 +98,8 @@
 # add a foliation using the `create_and_add_foliation` method.
 
 # Define stratigraphic column with scalar field ranges for each unit
+# the default column ends in an empty 'Basement' group; start from an empty column
+model.stratigraphic_column.clear(basement=False)
 vals = [0, 60, 250, 330, 600]
 for i in range(len(vals) - 1):
     model.stratigraphic_column.add_unit(

examples/1_basic/plot_3_model_visualisation.py

@@ -28,6 +28,8 @@
 model = GeologicalModel(bb[0, :], bb[1, :])
 model.data = data
 strati = model.create_and_add_foliation("strati",nelements=1e4)
+# the default column ends in an empty 'Basement' group; start from an empty column
+model.stratigraphic_column.clear(basement=False)
 vals = [0, 60, 250, 330, 600]
 for i in range(len(vals) - 1):
     model.stratigraphic_column.add_unit(

examples/1_basic/plot_5_using_stratigraphic_column.py

@@ -60,6 +60,8 @@
 
 # "strati" (oldest group) - four units from shallowest to deepest, the
 # last of which extends to infinite thickness
+# the default column ends in an empty 'Basement' group; start from an empty column
+model.stratigraphic_column.clear(basement=False)
 model.stratigraphic_column.add_unit("unit2", thickness=60, id=1)
 model.stratigraphic_column.add_unit("unit3", thickness=190, id=2)
 model.stratigraphic_column.add_unit("unit4", thickness=80, id=3)

examples/4_advanced/plot_2_using_logging.py

@@ -35,6 +35,8 @@ def build_claudius_model():
     model = GeologicalModel(bb[0, :], bb[1, :])
     model.data = data
 
+    # the default column ends in an empty 'Basement' group; start from an empty column
+    model.stratigraphic_column.clear(basement=False)
     vals = [0, 60, 250, 330, 600]
     for i in range(len(vals) - 1):
         model.stratigraphic_column.add_unit(

packages/loop_interpolation/src/loop_interpolation/_finite_difference_interpolator.py

@@ -142,15 +142,17 @@ def setup_interpolator(self, **kwargs):
         Default masks are the second derivative in x,y,z direction and the second
         derivative of x wrt y and y wrt z and z wrt x. Custom masks can be used
         by specifying the operator as a 3d numpy array
-        e.g. [ [ [ 0 0 0 ]
-                 [ 0 1 0 ]
-                 [ 0 0 0 ] ]
-                 [ [ 1 1 1 ]
-                 [ 1 1 1 ]
-                 [ 1 1 1 ] ]
-                 [ [ 0 0 0 ]
-                 [ 0 1 0 ]
-                 [ 0 0 0 ] ]
+        e.g.::
+
+            [ [ [ 0 0 0 ]
+                [ 0 1 0 ]
+                [ 0 0 0 ] ]
+              [ [ 1 1 1 ]
+                [ 1 1 1 ]
+                [ 1 1 1 ] ]
+              [ [ 0 0 0 ]
+                [ 0 1 0 ]
+                [ 0 0 0 ] ] ]
 
         Returns
         -------

pyproject.toml

@@ -66,6 +66,9 @@ docs = [
     "sphinxcontrib-bibtex",
     "myst-parser",
     "sphinx-design",
+    "trame",
+    "trame-vtk",
+    "trame-vuetify",
 ]
 [project.urls]
 Documentation = 'https://Loop3d.org/LoopStructural/'