Add missing docstrings, fix outdated ones

Author: ndem0

ezyrb/approximation/ann.py

@@ -50,6 +50,19 @@ class ANN(Approximation):
     def __init__(self, layers, function, stop_training, loss=None,
                  optimizer=torch.optim.Adam, lr=0.001, l2_regularization=0,
                  frequency_print=10, last_identity=True):
+        """
+        Initialize an Artificial Neural Network.
+        
+        :param list layers: Ordered list with the number of neurons of each hidden layer.
+        :param function: Activation function(s) for each layer.
+        :param stop_training: Stopping criteria for training (iterations and/or tolerance).
+        :param loss: Loss function to use. Default is MSELoss.
+        :param optimizer: Optimizer class to use. Default is Adam.
+        :param float lr: Learning rate. Default is 0.001.
+        :param float l2_regularization: L2 regularization coefficient. Default is 0.
+        :param int frequency_print: Frequency of printing during training. Default is 10.
+        :param bool last_identity: Whether the last activation is identity. Default is True.
+        """
         if loss is None:
             loss = torch.nn.MSELoss()
 
@@ -121,15 +134,13 @@ def _list_to_sequential(layers, functions):
 
     def _build_model(self, points, values):
         """
-        Build the torch model.
-        Considering the number of neurons per layer (self.layers), a
-        feed-forward NN is defined:
-        -  activation function from layer i>=0 to layer i+1:
-           self.function[i]; activation function at the output layer:
-           Identity (by default).
-        :param numpy.ndarray points: the coordinates of the given (training)
-        points.
-        :param numpy.ndarray values: the (training) values in the points.
+        Build the torch neural network model.
+        
+        Constructs a feed-forward neural network with the specified layers
+        and activation functions.
+        
+        :param numpy.ndarray points: The coordinates of the training points.
+        :param numpy.ndarray values: The training values at the points.
         """
         layers = self.layers.copy()
         layers.insert(0, points.shape[1])

ezyrb/approximation/gpr.py

@@ -38,6 +38,14 @@ class GPR(Approximation):
 
     """
     def __init__(self, kern=None, normalizer=True, optimization_restart=20):
+        """
+        Initialize a Gaussian Process Regressor.
+        
+        :param kern: Kernel object from sklearn. Default is None.
+        :param bool normalizer: Whether to normalize values. Default is True.
+        :param int optimization_restart: Number of restarts for optimization.
+            Default is 20.
+        """
 
         self.X_sample = None
         self.Y_sample = None

ezyrb/approximation/kneighbors_regressor.py

@@ -7,10 +7,26 @@
 
 class KNeighborsRegressor(NeighborsRegressor):
     """
-    K-Neighbors Regressor.
+    K-Neighbors Regressor for multidimensional approximation.
 
     :param kwargs: arguments passed to the internal instance of
         KNeighborsRegressor.
+    
+    :Example:
+    
+        >>> import numpy as np
+        >>> from ezyrb import KNeighborsRegressor
+        >>> x = np.random.uniform(-1, 1, size=(20, 2))
+        >>> y = np.array([np.sin(x[:, 0]), np.cos(x[:, 1])]).T
+        >>> knn = KNeighborsRegressor(n_neighbors=3)
+        >>> knn.fit(x, y)
+        >>> new_x = np.array([[0.5, 0.5]])
+        >>> y_pred = knn.predict(new_x)
     """
     def __init__(self, **kwargs):
+        """
+        Initialize a K-Neighbors Regressor.
+        
+        :param kwargs: Arguments passed to sklearn's KNeighborsRegressor.
+        """
         self.regressor = Regressor(**kwargs)

ezyrb/approximation/linear.py

@@ -18,6 +18,12 @@ class Linear(Approximation):
         default is numpy.nan.
     """
     def __init__(self, fill_value=np.nan):
+        """
+        Initialize a Linear interpolator.
+        
+        :param float fill_value: Value for points outside the convex hull.
+            Default is numpy.nan.
+        """
         self.fill_value = fill_value
         self.interpolator = None
 

ezyrb/approximation/neighbors_regressor.py

@@ -7,9 +7,21 @@
 class NeighborsRegressor(Approximation):
     """
     A generic superclass for wrappers of *NeighborsRegressor from sklearn.
+    
+    This class provides a common interface for neighbor-based regression methods.
 
-    :param kwargs: arguments passed to the internal instance of
+    :param kwargs: Arguments passed to the internal instance of
         *NeighborsRegressor.
+    
+    :Example:
+    
+        >>> import numpy as np
+        >>> from ezyrb import KNeighborsRegressor
+        >>> x = np.random.uniform(-1, 1, size=(20, 2))
+        >>> y = np.sin(x[:, 0]) + np.cos(x[:, 1])
+        >>> knn = KNeighborsRegressor(n_neighbors=5)
+        >>> knn.fit(x, y)
+        >>> y_pred = knn.predict(x[:5])
     """
     def fit(self, points, values):
         """

ezyrb/approximation/radius_neighbors_regressor.py

@@ -7,10 +7,26 @@
 
 class RadiusNeighborsRegressor(NeighborsRegressor):
     """
-    Radius Neighbors Regressor.
+    Radius Neighbors Regressor for multidimensional approximation.
 
     :param kwargs: arguments passed to the internal instance of
         RadiusNeighborsRegressor.
+    
+    :Example:
+    
+        >>> import numpy as np
+        >>> from ezyrb import RadiusNeighborsRegressor
+        >>> x = np.random.uniform(-1, 1, size=(20, 2))
+        >>> y = np.sin(x[:, 0]) * np.cos(x[:, 1])
+        >>> rnn = RadiusNeighborsRegressor(radius=0.5)
+        >>> rnn.fit(x, y)
+        >>> new_x = np.array([[0.0, 0.0]])
+        >>> y_pred = rnn.predict(new_x)
     """
     def __init__(self, **kwargs):
+        """
+        Initialize a Radius Neighbors Regressor.
+        
+        :param kwargs: Arguments passed to sklearn's RadiusNeighborsRegressor.
+        """
         self.regressor = Regressor(**kwargs)

ezyrb/database.py

@@ -7,7 +7,7 @@
 
 class Database():
     """
-    Database class
+    Database class for storing parameter-snapshot pairs.
 
     :param array_like parameters: the input parameters
     :param array_like snapshots: the input snapshots
@@ -16,6 +16,20 @@ class Database():
     :param Scale scaler_snapshots: the scaler for the snapshots. Default is
         None meaning no scaling.
     :param array_like space: the input spatial data
+    
+    :Example:
+    
+        >>> import numpy as np
+        >>> from ezyrb import Database, Parameter, Snapshot
+        >>> params = np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
+        >>> snapshots = np.random.rand(3, 100)
+        >>> db = Database(params, snapshots)
+        >>> print(len(db))
+        3
+        >>> print(db.parameters_matrix.shape)
+        (3, 2)
+        >>> print(db.snapshots_matrix.shape)
+        (3, 100)
     """
     def __init__(self, parameters=None, snapshots=None, space=None):
         self._pairs = []

ezyrb/parameter.py

@@ -2,8 +2,33 @@
 import numpy as np
 
 class Parameter:
+    """
+    Class for representing a parameter in the reduced order model.
+    
+    This class encapsulates parameter values and provides validation
+    to ensure parameters are 1-dimensional arrays.
+    
+    :param array_like values: The parameter values as a 1D array.
+    
+    :Example:
+    
+        >>> import numpy as np
+        >>> from ezyrb import Parameter
+        >>> param = Parameter([1.0, 2.5, 3.0])
+        >>> print(param.values)
+        [1.  2.5 3. ]
+        >>> param2 = Parameter(np.array([4.5, 5.5]))
+        >>> print(param2.values)
+        [4.5 5.5]
+    """
 
     def __init__(self, values):
+        """
+        Initialize a Parameter object.
+        
+        :param array_like values: The parameter values. Can be a Parameter
+            instance or an array-like object that can be converted to a 1D numpy array.
+        """
         if isinstance(values, Parameter):
             self.values = values.values
         else:
@@ -16,6 +41,12 @@ def values(self):
 
     @values.setter
     def values(self, new_values):
+        """
+        Set the parameter values with validation.
+        
+        :param array_like new_values: The new parameter values.
+        :raises ValueError: If the new values are not a 1D array.
+        """
         if np.asarray(new_values).ndim != 1:
             raise ValueError('only 1D array are usable as parameter.')
 

ezyrb/plugin/aggregation.py

@@ -42,6 +42,14 @@ class Aggregation(Plugin):
     """
 
     def __init__(self, fit_function=None, predict_function=Linear()):
+        """
+        Initialize the Aggregation plugin.
+        
+        :param fit_function: Regression model to fit weights in validation set.
+            If None, uses standard space-dependent methods. Default is None.
+        :param predict_function: Regression model to predict weights in test set.
+            Default is Linear().
+        """
         super().__init__()
         self.fit_function = fit_function
         self.predict_function = predict_function

ezyrb/plugin/automatic_shift.py

@@ -50,6 +50,16 @@ class AutomaticShiftSnapshots(Plugin):
     """
     def __init__(self, shift_network, interp_network, interpolator,
                  parameter_index=0, reference_index=0, barycenter_loss=0):
+        """
+        Initialize the AutomaticShiftSnapshots plugin.
+        
+        :param shift_network: Neural network for learning the shift function.
+        :param interp_network: Neural network for interpolation.
+        :param Approximation interpolator: Interpolator for shifted snapshots evaluation.
+        :param int parameter_index: Index of parameter component. Default is 0.
+        :param int reference_index: Index of reference snapshot. Default is 0.
+        :param float barycenter_loss: Weight for barycenter loss term. Default is 0.
+        """
         super().__init__()
 
         self.interpolator = interpolator
@@ -61,6 +71,7 @@ def __init__(self, shift_network, interp_network, interpolator,
 
     def _train_interp_network(self):
         """
+        Train the interpolation network on the reference snapshot.
         """
         self.interp_network.fit(
             self.reference_snapshot.space.reshape(-1, 1),
@@ -69,6 +80,9 @@ def _train_interp_network(self):
 
     def _train_shift_network(self, db):
         """
+        Train the shift network using the database snapshots.
+        
+        :param Database db: The database containing snapshots.
         """
         ref_center = torch.tensor(np.average(
             self.reference_snapshot.space * self.reference_snapshot.values))