doc: adding more docstrings and type hints

Author: lachlangrose

LoopStructural/modelling/features/_base_geological_feature.py

@@ -12,7 +12,24 @@ class BaseFeature:
     Base class for geological features.
     """
 
-    def __init__(self, name, model=None, faults=[], regions=[], builder=None):
+    def __init__(self, name : str, model=None, faults: list=[], regions: list=[], builder=None):
+        """Base geological feature, this is a virtucal class and should not be
+        used directly. Inheret from this to implement a new type of geological
+        feature or use one of the exisitng implementations
+
+        Parameters
+        ----------
+        name : 
+            Name of the geological feature to add
+        model : GeologicalModel, optional
+            the model the feature is associated with, by default None
+        faults : list, optional
+            any faults that fault this feature, by default []
+        regions : list, optional
+            any regions that affect this feature, by default []
+        builder : GeologicalFeatureBuilder, optional
+            the builder of the feature, by default None
+        """
         self.name = name
         self.type = FeatureType.BASE
         self.regions = regions
@@ -44,9 +61,12 @@ def model(self):
 
     @model.setter
     def model(self, model):
+        from LoopStructural import GeologicalModel
         # causes circular import, could delay import?
-        # if type(model) == GeologicalModel:
-        self._model = model
+        if type(model) == GeologicalModel:
+            self._model = model
+        else:
+            raise TypeError("Model must be a GeologicalModel")
 
     def toggle_faults(self):
         """
@@ -79,6 +99,18 @@ def add_region(self, region):
         self.regions.append(region)
 
     def __call__(self, xyz):
+        """ Calls evaluate_value method
+
+        Parameters
+        ----------
+        xyz : np.ndarray
+            location to evaluate feature
+
+        Returns
+        -------
+        np.ndarray
+            the value of the feature at the locations
+        """
         return self.evaluate_value(xyz)
 
     def evaluate_value(self, pos):
@@ -94,11 +126,27 @@ def evaluate_gradient(self, pos):
         raise NotImplementedError
 
     def min(self):
+        """Calculate the min value of the geological feature
+        in the model
+
+        Returns
+        -------
+        minimum, float
+            min value of the feature evaluated on a regular grid in the model domain
+        """
         if self.model is None:
             return 0
         return np.nanmin(self.evaluate_value(self.model.regular_grid((10, 10, 10))))
 
     def max(self):
+        """Calculate the maximum value of the geological feature
+        in the model
+
+        Returns
+        -------
+        maximum, float
+            max value of the feature evaluated on a regular grid in the model domain
+        """
         if self.model is None:
             return 0
         return np.nanmax(self.evaluate_value(self.model.regular_grid((10, 10, 10))))

LoopStructural/modelling/features/_cross_product_geological_feature.py

@@ -12,8 +12,9 @@
 
 
 class CrossProductGeologicalFeature(BaseFeature):
-    def __init__(self, name, geological_feature_a, geological_feature_b):
+    def __init__(self, name : str, geological_feature_a : BaseFeature, geological_feature_b: BaseFeature):
         """
+    
         Create a geological feature for a vector field using the cross
         product between
         two existing features
@@ -22,18 +23,29 @@ def __init__(self, name, geological_feature_a, geological_feature_b):
         name: feature name
         geological_feature_a: first feature
         geological_feature_b: second feature
+        
+
+        Parameters
+        ----------
+        name : str
+            name of the feature
+        geological_feature_a : BaseFeature
+            Left hand side of cross product
+        geological_feature_b : BaseFeature
+            Right hand side of cross product
         """
         super().__init__(name)
         self.geological_feature_a = geological_feature_a
         self.geological_feature_b = geological_feature_b
         self.value_feature = None
 
-    def evaluate_gradient(self, locations):
+    def evaluate_gradient(self, locations : np.ndarray) ->np.ndarray:
         """
         Calculate the gradient of the geological feature by using numpy to
         calculate the cross
         product between the two existing feature gradients.
         This means both features have to be evaluated for the locations
+        
         Parameters
         ----------
         locations
@@ -48,7 +60,7 @@ def evaluate_gradient(self, locations):
         # v2 /= np.linalg.norm(v2,axis=1)[:,None]
         return np.cross(v1, v2, axisa=1, axisb=1)
 
-    def evaluate_value(self, evaluation_points):
+    def evaluate_value(self, evaluation_points : np.ndarray) -> np.ndarray:
         """
         Return 0 because there is no value for this feature
         Parameters

LoopStructural/modelling/features/_geological_feature.py

@@ -4,6 +4,7 @@
 from LoopStructural.modelling.features import BaseFeature
 from LoopStructural.utils import getLogger
 from LoopStructural.modelling.features import FeatureType
+from LoopStructural.interpolators import GeologicalInterpolator
 import numpy as np
 
 from LoopStructural.utils import getLogger, LoopValueError
@@ -34,24 +35,23 @@ class GeologicalFeature(BaseFeature):
 
     def __init__(
         self,
-        name,
-        interpolator,
+        name : str,
+        interpolator : GeologicalInterpolator,
         builder=None,
-        regions=[],
-        faults=[],
+        regions : list=[],
+        faults : list =[],
         model=None,
     ):
         """Default constructor for geological feature
 
         Parameters
         ----------
-        name: string
+        name: str
         interpolator : GeologicalInterpolator
         builder : GeologicalFeatureBuilder
-        data :
-        region :
-        type :
+        region : list
         faults : list
+        model : GeologicalModel
 
 
         """
@@ -73,14 +73,14 @@ def __setitem__(self, key, item):
     def set_model(self, model):
         self.model = model
 
-    def evaluate_value(self, evaluation_points):
+    def evaluate_value(self, evaluation_points : np.ndarray) -> np.ndarray:
         """
         Evaluate the scalar field value of the geological feature at the locations
         specified
 
         Parameters
         ----------
-        evaluation_points : numpy array
+        evaluation_points : np.ndarray
             location to evaluate the scalar value
 
         Returns
@@ -116,7 +116,7 @@ def evaluate_value(self, evaluation_points):
             v[mask] = self.interpolator.evaluate_value(evaluation_points[mask, :])
         return v
 
-    def evaluate_gradient(self, evaluation_points):
+    def evaluate_gradient(self, evaluation_points : np.ndarray) -> np.ndarray:
         """
 
         Parameters
@@ -127,6 +127,7 @@ def evaluate_gradient(self, evaluation_points):
         Returns
         -------
 
+
         """
         if evaluation_points.shape[1] != 3:
             raise LoopValueError("Need Nx3 array of xyz points to evaluate gradient")
@@ -192,41 +193,3 @@ def evaluate_value_misfit(self):
         diff /= self.max() - self.min()
         return diff
 
-    def mean(self):
-        """
-        Calculate average of the support values
-
-        Returns
-        -------
-        mean : double
-            average value of the feature evaluated on a (10,10,10) grid in model area
-
-        """
-        if self.model is None:
-            return 0
-        return np.mean(self.evaluate_value(self.model.regular_grid((10, 10, 10))))
-
-    def min(self):
-        """
-
-        Returns
-        -------
-        min : double
-            min value of the feature evaluated on a (10,10,10) grid in model area
-        """
-        if self.model is None:
-            return 0
-        return np.nanmin(self.evaluate_value(self.model.regular_grid((10, 10, 10))))
-
-    def max(self):
-        """
-        Calculate average of the support values
-
-        Returns
-        -------
-        max : double
-            max value of the feature evaluated on a (10,10,10) grid in model area
-        """
-        if self.model is None:
-            return 0
-        return np.nanmax(self.evaluate_value(self.model.regular_grid((10, 10, 10))))

LoopStructural/modelling/features/_lambda_geological_feature.py

@@ -20,20 +20,63 @@ def __init__(
         faults=[],
         builder=None,
     ):
+        """_summary_
+
+        Parameters
+        ----------
+        function : _type_, optional
+            _description_, by default None
+        name : str, optional
+            _description_, by default "unnamed_lambda"
+        gradient_function : _type_, optional
+            _description_, by default None
+        model : _type_, optional
+            _description_, by default None
+        regions : list, optional
+            _description_, by default []
+        faults : list, optional
+            _description_, by default []
+        builder : _type_, optional
+            _description_, by default None
+        """
         BaseFeature.__init__(self, name, model, faults, regions, builder)
         self.type = FeatureType.LAMBDA
         self.function = function
         self.gradient_function = gradient_function
 
-    def evaluate_value(self, xyz):
+    def evaluate_value(self, xyz : np.ndarray) -> np.ndarray:
+        """_summary_
+
+        Parameters
+        ----------
+        xyz : np.ndarray
+            _description_
+
+        Returns
+        -------
+        np.ndarray
+            _description_
+        """
         v = np.zeros((xyz.shape[0]))
         if self.function is None:
             v[:] = np.nan
         else:
             v[:] = self.function(xyz)
         return v
 
-    def evaluate_gradient(self, xyz):
+    def evaluate_gradient(self, xyz : np.ndarray) -> np.ndarray:
+        """_summary_
+
+        Parameters
+        ----------
+        xyz : np.ndarray
+            _description_
+
+        Returns
+        -------
+        np.ndarray
+            _description_
+        """
         v = np.zeros((xyz.shape[0], 3))
         if self.gradient_function is None:
             v[:, :] = np.nan

LoopStructural/modelling/features/_structural_frame.py

@@ -11,7 +11,7 @@
 
 
 class StructuralFrame(BaseFeature):
-    def __init__(self, name, features, fold=None):
+    def __init__(self, name : str, features: list, fold=None):
         """
         Structural frame is a curvilinear coordinate system defined by
         structural observations associated with a fault or fold.