better documentation

setup.py

@@ -6,6 +6,7 @@
     PyScaffold helps you to put up the scaffold of your new Python project.
     Learn more under: https://pyscaffold.org/
 """
+
 from setuptools import setup
 
 if __name__ == "__main__":

src/ellalgo/ell1d.py

@@ -14,7 +14,7 @@ def __init__(self, interval: Tuple[float, float]) -> None:
         interval.
 
         :param interval: The `interval` parameter is a tuple of two floats representing the lower and
-        upper bounds of a range
+            upper bounds of a range
 
         :type interval: Tuple[float, float]
         """
@@ -46,7 +46,7 @@ def set_xc(self, x: float) -> None:
         The function sets the value of the private variable `_xc` to the given float value `x`.
 
         :param x: The parameter `x` is a float value that represents the value to be assigned to the
-        `_xc` attribute
+            `_xc` attribute
         :type x: float
         """
         self._xc = x
@@ -64,13 +64,13 @@ def update(self, cut: Tuple[float, float], central_cut=False) -> CutStatus:
         The `update` function updates an ellipsoid core using a single cut.
 
         :param cut: The `cut` parameter is a tuple containing two floats: `grad` and `beta`. `grad`
-        represents the gradient, and `beta` represents the beta value
+            represents the gradient, and `beta` represents the beta value
 
         :type cut: Tuple[float, float]
 
         :param central_cut: A boolean parameter that indicates whether the cut is a central cut or not.
-        If it is set to True, the cut is a central cut. If it is set to False, the cut is not a central
-        cut, defaults to False (optional)
+            If it is set to True, the cut is a central cut. If it is set to False, the cut is not a central
+            cut, defaults to False (optional)
 
         :return: a `CutStatus` enum value and the "volumn" of the ellipsoid (`tau`).
 

src/ellalgo/ell_calc.py

@@ -46,8 +46,8 @@ def calc_single_or_parallel(
         :param beta: The parameter `beta` can be of type `int`, `float`, or a list of two elements
 
         :param tsq: The `tsq` parameter is a floating-point number that represents the square of the
-        tolerance for the ellipsoid algorithm. It is used in the calculations performed by the
-        `calc_single_or_parallel` method
+            tolerance for the ellipsoid algorithm. It is used in the calculations performed by the
+            `calc_single_or_parallel` method
 
         :type tsq: float
 
@@ -72,17 +72,17 @@ def calc_single_or_parallel_central_cut(
         based on the input parameters.
 
         :param beta: The parameter `beta` is of type `_type_` and represents some value. The specific
-        details of its purpose and usage are not provided in the code snippet
+            details of its purpose and usage are not provided in the code snippet
 
         :param tsq: tsq is a float value representing the squared tau-value
 
         :type tsq: float
 
         :return: a tuple containing the following elements:
-        1. CutStatus: The status of the cut calculation.
-        2. float: The calculated value.
-        3. float: The calculated value.
-        4. float: The calculated value.
+            1. CutStatus: The status of the cut calculation.
+            2. float: The calculated value.
+            3. float: The calculated value.
+            4. float: The calculated value.
 
         Examples:
             >>> from ellalgo.ell_calc import EllCalc
@@ -219,7 +219,7 @@ def calc_deep_cut_q(
         :param beta: The parameter `beta` represents a float value
         :type beta: float
         :param tsq: tsq is the square of the threshold value. It is a float value that represents the
-        threshold squared
+            threshold squared
         :type tsq: float
         :return: The function `calc_deep_cut_q` returns a tuple of four values: `CutStatus`, `float`, `float`, `float`.
 

src/ellalgo/ell_stable.py

@@ -111,7 +111,7 @@ def update_q(self, cut) -> CutStatus:
         cut status based on a given cut.
 
         :param cut: The `cut` parameter is of type `_type_` and it represents the cut that needs to be
-        updated
+            updated
         :return: a `CutStatus` object.
 
         Examples:

src/ellalgo/ell_typing.py

@@ -31,7 +31,7 @@ def update(self, gamma) -> None:
         The `update` function updates a gamma object.
 
         :param gamma: The `gamma` parameter is of type `Any`, which means it can accept any type of value.
-        It is used as an argument to update the gamma object
+            It is used as an argument to update the gamma object
         """
         pass
 
@@ -44,13 +44,13 @@ def assess_optim(self, xc: ArrayType, gamma) -> Tuple[Cut, Optional[float]]:
         parameters.
 
         :param xc: An array of values that represents the current solution or point in the optimization
-        process
+            process
 
         :type xc: ArrayType
 
         :param gamma: The `gamma` parameter is the value that we are trying to optimize or minimize. It
-        could be a numerical value, a function, or any other type of object that represents the optimization
-        goal
+            could be a numerical value, a function, or any other type of object that represents the optimization
+            goal
         """
         pass
 
@@ -66,7 +66,7 @@ def assess_feas_q(
         a cut, an array, and a boolean value.
 
         :param xc: An array of some type. It represents a variable or a set of variables that need to be
-        assessed for feasibility
+            assessed for feasibility
 
         :type xc: ArrayType
 
@@ -88,13 +88,13 @@ def assess_optim_q(
         containing a cut, an array, an optional float, and a boolean value.
 
         :param xc: An array or list representing the current solution or configuration being assessed for
-        optimization
+            optimization
 
         :type xc: ArrayType
 
         :param gamma: The `gamma` parameter is the desired value or condition that the optimization
-        algorithm is trying to achieve. It could be a specific value, a range of values, or a certain
-        condition that needs to be satisfied
+            algorithm is trying to achieve. It could be a specific value, a range of values, or a certain
+            condition that needs to be satisfied
 
         :param retry: A boolean flag indicating whether to retry the optimization if it fails
 
@@ -125,7 +125,7 @@ def update_deep_cut(self, cut: Cut) -> CutStatus:
         a `CutStatus` object.
 
         :param cut: The `cut` parameter is an instance of the `Cut` class. It represents a deep-cut that
-        needs to be updated
+            needs to be updated
 
         :type cut: Cut
         """
@@ -137,7 +137,7 @@ def update_central_cut(self, cut: Cut) -> CutStatus:
         status of the cut.
 
         :param cut: The "cut" parameter is an instance of the Cut class. It represents the central cut that
-        needs to be updated
+            needs to be updated
 
         :type cut: Cut
         """

src/ellalgo/oracles/ldlt_mgr.py

@@ -39,7 +39,7 @@ def __init__(self, ndim: int):
         and pre-allocates storage.
 
         :param ndim: The parameter ndim represents the dimension of the object. It is an integer value that
-        determines the size of the object being constructed
+            determines the size of the object being constructed
 
         :type ndim: int
         """
@@ -76,13 +76,13 @@ def factor(self, get_elem: Callable[[int, int], float]) -> bool:
         The function performs LDLT Factorization on a symmetric matrix using lazy evaluation.
 
         :param get_elem: The `get_elem` parameter is a callable function that is used to access the elements
-        of a symmetric matrix. It takes two integer arguments `i` and `j` and returns the value of the
-        element at the `(i, j)` position in the matrix
+            of a symmetric matrix. It takes two integer arguments `i` and `j` and returns the value of the
+            element at the `(i, j)` position in the matrix
 
         :type get_elem: Callable[[int, int], float]
 
         :return: The function `factor` returns a boolean value indicating whether the matrix is symmetric
-        positive definite (SPD).
+            positive definite (SPD).
 
         Examples:
             >>> mat = np.array([[1.0, 0.5, 0.5], [0.5, 1.25, 0.75], [0.5, 0.75, 1.5]])
@@ -115,13 +115,13 @@ def factor_with_allow_semidefinite(
         if the matrix is positive definite.
 
         :param get_elem: The `get_elem` parameter is a callable function that takes two integer arguments
-        `i` and `j` and returns a float value. This function is used to access the elements of a symmetric
-        matrix `mat`. The `factor_with_allow_semidefinite` method performs LDLT Factorization on
+            `i` and `j` and returns a float value. This function is used to access the elements of a symmetric
+            matrix `mat`. The `factor_with_allow_semidefinite` method performs LDLT Factorization on
 
         :type get_elem: Callable[[int, int], float]
 
         :return: The function `factor_with_allow_semidefinite` returns a boolean value indicating whether
-        the matrix is symmetric positive definite (SPD).
+            the matrix is symmetric positive definite (SPD).
 
         Examples:
             >>> mat = np.array([[1.0, 0.5, 0.5], [0.5, 1.25, 0.75], [0.5, 0.75, 1.5]])
@@ -154,7 +154,7 @@ def is_spd(self):
         if it is.
 
         :return: a boolean value. It returns True if the matrix A is symmetric positive definite (spd), and
-        False otherwise.
+            False otherwise.
 
         Examples:
             >>> mat = np.array([[1.0, 0.5, 0.5], [0.5, 1.25, 0.75], [0.5, 0.75, 1.5]])
@@ -205,7 +205,7 @@ def sym_quad(self, mat: np.ndarray):
         :type mat: np.ndarray
 
         :return: The function `sym_quad` returns the result of the dot product between `v` and the matrix
-        product of `mat[start:ndim, start:ndim]` and `v`.
+            product of `mat[start:ndim, start:ndim]` and `v`.
 
         Examples:
             >>> mat = np.array([[1.0, 2.0, 3.0], [2.0, 3.5, 5.0], [3.0, 5.0, 6.0]])

src/ellalgo/oracles/profit_oracle.py

@@ -95,14 +95,14 @@ def assess_feas(self, y: Arr, gamma: float) -> Optional[Cut]:
         :type y: Arr
 
         :param gamma: The `gamma` parameter is the best-so-far optimal value. It represents the gamma
-        value that the optimization algorithm is trying to achieve or improve upon
+            value that the optimization algorithm is trying to achieve or improve upon
 
         :type gamma: float
 
         :return: The function `assess_feas` returns an optional Cut. The `Cut` object represents a
-        linear constraint in the form of a tuple `(grad, fj)`, where `grad`
-        is a numpy array representing the coefficients of the linear constraint and `fj` is a float
-        representing the right-hand side of the constraint.
+            linear constraint in the form of a tuple `(grad, fj)`, where `grad`
+            is a numpy array representing the coefficients of the linear constraint and `fj` is a float
+            representing the right-hand side of the constraint.
 
         See also:
             cutting_plane_optim
@@ -125,14 +125,14 @@ def assess_optim(self, y: Arr, gamma: float) -> Tuple[Cut, Optional[float]]:
         :type y: Arr
 
         :param gamma: The `gamma` parameter is the best-so-far optimal value. It represents the gamma
-        value that the optimization algorithm is trying to achieve or improve upon
+            value that the optimization algorithm is trying to achieve or improve upon
 
         :type gamma: float
 
         :return: The function `assess_optim` returns a tuple containing a `Cut` object and an optional float
-        value. The `Cut` object represents a linear constraint in the form of a tuple `(g, fj)`, where `g`
-        is a numpy array representing the coefficients of the linear constraint and `fj` is a float
-        representing the right-hand side of the constraint.
+            value. The `Cut` object represents a linear constraint in the form of a tuple `(g, fj)`, where `g`
+            is a numpy array representing the coefficients of the linear constraint and `fj` is a float
+            representing the right-hand side of the constraint.
 
         See also:
             cutting_plane_optim
@@ -176,12 +176,12 @@ def __init__(
         ProfitOracle object.
 
         :param params: The `params` parameter is a tuple of three floats: `unit_price`, `scale`, and
-        `limit`. These parameters are used to calculate `params_rb` in the code
+            `limit`. These parameters are used to calculate `params_rb` in the code
 
         :type params: Tuple[float, float, float]
 
         :param elasticities: The elasticities parameter is a numpy array that represents the output
-        elasticities. It is used in the ProfitOracle function
+            elasticities. It is used in the ProfitOracle function
 
         :type elasticities: Arr
 
@@ -190,7 +190,7 @@ def __init__(
         :type price_out: Arr
 
         :param vparams: The `vparams` parameter is a tuple containing five float values: `e1`, `e2`, `e3`,
-        `e4`, and `e5`
+            `e4`, and `e5`
 
         :type vparams: Tuple[float, float, float, float, float]
         """
@@ -213,12 +213,12 @@ def assess_optim(self, y: Arr, gamma: float) -> Tuple[Cut, Optional[float]]:
         :type y: Arr
 
         :param gamma: The `gamma` parameter is the best-so-far optimal value. It represents the current
-        best value that has been achieved in the optimization process
+            best value that has been achieved in the optimization process
 
         :type gamma: float
 
         :return: The function `assess_optim` returns a tuple containing a `Cut` object and an optional float
-        value.
+            value.
 
         See also:
             cutting_plane_optim
@@ -260,13 +260,13 @@ def __init__(self, params, elasticities, price_out) -> None:
         The function initializes an instance of a class with given parameters and arrays.
 
         :param params: The `params` parameter is a tuple containing three float values: `unit_price`,
-        `scale`, and `limit`
+            `scale`, and `limit`
 
         :param elasticities: The elasticities parameter is an array that represents the output elasticities.
-        It contains the elasticity values for each output
+            It contains the elasticity values for each output
 
         :param price_out: The `price_out` parameter is an array that represents the output prices of the
-        goods or services. It contains the prices of different outputs
+            goods or services. It contains the prices of different outputs
         """
         self.omega = ProfitOracle(params, elasticities, price_out)
         self.yd = np.array([0.0, 0.0])
@@ -283,7 +283,7 @@ def assess_optim_q(
         :type y: Arr
 
         :param gamma: The `gamma` parameter is the best-so-far optimal value. It represents the current
-        best value that the optimization algorithm has found
+            best value that the optimization algorithm has found
 
         :type gamma: float