computils 0.0.1__tar.gz → 0.0.2__tar.gz

{computils-0.0.1 → computils-0.0.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: computils
-Version: 0.0.1
-Summary: A package collecting functionality for various numerical computations (numerical differentiation, interpolation, optimization, sorting, ).
+Version: 0.0.2
+Summary: A package collecting functionality for various numerical computations (numerical differentiation, interpolation, optimization, sorting, parallelization).
 Author-email: Karim Moussa <research@k-moussa.com>
 Project-URL: Homepage, https://github.com/k-moussa/computils
 Classifier: Programming Language :: Python :: 3

{computils-0.0.1 → computils-0.0.2}/pyproject.toml

@@ -5,18 +5,20 @@ requires = [
 "scipy >= 1.13.0",
 "numba >= 0.59.1",
 "splines >= 0.3.1",
+"psutil>=5.9.0",
 ]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "computils"
-version = "0.0.1"
+version = "0.0.2"
 authors = [
   { name="Karim Moussa", email="research@k-moussa.com" },
 ]
-description = "A package collecting functionality for various numerical computations (numerical differentiation, interpolation, optimization, sorting, )."
+description = "A package collecting functionality for various numerical computations (numerical differentiation, interpolation, optimization, sorting, parallelization)."
 readme = "README.md"
 requires-python = ">=3.7"
+
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: MIT License",

{computils-0.0.1 → computils-0.0.2}/src/computils/__init__.py

@@ -11,12 +11,12 @@ from .globals import *
 from .factory import create_interpolator
 from .sorting_algorithms import index_eq, find_le, find_ge, find_gt, find_lt
 from .finite_difference import compute_derivative, compute_gradient, compute_jacobian, compute_hessian
-from .type_utils import size
-from .fast_eval import fast_matrix_inversion, fast_determinant, fast_quadratic_form, fast_diag_mult_AD, \
-    fast_diag_mult_DA, fast_columnwise_bilinear_form
+from .type_utils import size, to_1d_array, to_float_if_singleton, has_nan, compute_hash, dicts_to_array, dict_to_array
+from .fast_eval import fast_matrix_inversion, fast_determinant, fast_quadratic_form, fast_columnwise_bilinear_form
 from .gaussian_elim_spp import compute_inverse_using_gauss_elim_spp
 from .matrix_computations import robust_inverse, is_diagonal
 from .parameter_transformations import impose_lower_bound, inverse_impose_lower_bound, impose_upper_bound, \
     inverse_impose_upper_bound, impose_bounds, inverse_impose_bounds, impose_upper_bound_sum, \
     inverse_impose_upper_bound_sum
 from .performance_checking import compute_average_running_time
+from .parallelization import BatchAllocation, get_batch_allocations, get_n_physical_cores

{computils-0.0.1 → computils-0.0.2}/src/computils/factory.py

@@ -8,5 +8,13 @@ def create_interpolator(x: np.ndarray,
                         y: np.ndarray,
                         inter_type: InterpolationType,
                         extra_type: ExtrapolationType = ExtrapolationType.nan) -> Interpolator:
+    """ Creates an instance of the Interpolator class with the given inter- and extrapolation types.
+
+    :param x:
+    :param y:
+    :param inter_type:
+    :param extra_type:
+    :return: an instance of the Interpolator class with the given inter- and extrapolation types.
+    """
 
     return InternalInterpolator(x=x, y=y, inter_type=inter_type, extra_type=extra_type)

{computils-0.0.1 → computils-0.0.2}/src/computils/fast_eval.py

@@ -7,6 +7,12 @@ from scipy.linalg import inv, det
 
 
 def fast_matrix_inversion(M: np.ndarray) -> np.ndarray:
+    """ Performs fast matrix inversion.
+
+    :param M:
+    :return: The inverse of M.
+    """
+
     if M.size == 1:
         return 1.0 / M
     elif issparse(M):
@@ -16,6 +22,11 @@ def fast_matrix_inversion(M: np.ndarray) -> np.ndarray:
 
 
 def fast_determinant(M: np.ndarray) -> float:
+    """ Computes the determinant of M.
+
+    :param M:
+    :return: det(M).
+    """
     if M.size == 1:
         return np.abs(M[0, 0])
     else:
@@ -24,17 +35,13 @@ def fast_determinant(M: np.ndarray) -> float:
 
 def fast_quadratic_form(A: np.ndarray,
                         x: np.ndarray) -> float:
-    return (np.dot(x.T, np.dot(A, x)))[0, 0]
+    """ Computes the quadratic form x'Ax.
 
-
-def fast_diag_mult_AD(A: np.ndarray,
-                      D: np.ndarray) -> np.ndarray:
-    return np.multiply(A, np.diag(D))
-
-
-def fast_diag_mult_DA(A: np.ndarray,
-                      D: np.ndarray) -> np.ndarray:
-    return np.multiply(np.diag(D)[:, None], A)
+    :param A: An (n,n) array.
+    :param x: An (n,1) array.
+    :return: the quadratic form x'Ax.
+    """
+    return (np.dot(x.T, np.dot(A, x)))[0, 0]
 
 
 def fast_columnwise_bilinear_form(A: np.ndarray,

computils-0.0.2/src/computils/globals.py

@@ -0,0 +1,71 @@
+""" This module collects all exposed types."""
+
+import numpy as np
+from enum import Enum
+from abc import ABC, abstractmethod
+from typing import final, Union
+
+MACHINE_EPS: final = float(2 ** (-53))  #: max relative error corresponding to 1/2 ULP
+SQUARE_ROOT_MACHINE_EPS: final = np.sqrt(MACHINE_EPS)  #:
+CUBE_ROOT_MACHINE_EPS: final = np.cbrt(MACHINE_EPS)  #:
+FOURTH_ROOT_MACHINE_EPS: final = np.power(MACHINE_EPS, 1/4)  #:
+
+Integer: final = Union[int, np.int8, np.int16, np.int32, np.int64, np.uint8, np.uint16, np.uint32, np.uint64]  #:
+Float: final = Union[float, np.float16, np.float32, np.float64, np.float128]  #:
+Complex: final = Union[complex, np.complex64, np.complex128, np.complex256]  #:
+Scalar: final = Union[Integer, Float, Complex]  #:
+Bool: final = Union[bool, np.bool_]
+
+IntOrArray: final = Union[Integer, np.ndarray]  #:
+FloatOrArray: final = Union[Float, np.ndarray]  #:
+ComplexOrArray: final = Union[Complex, np.ndarray]   #:
+ScalarOrArray: final = Union[Scalar, np.ndarray]   #:
+BoolOrArray = Union[Bool, np.ndarray]  #:
+
+
+# 128-bit integers generated using entropy gathered from the OS, for fixing the seed of NumPy generators.
+SEED128_1: final = 137088887599416403785824428186011523708
+SEED128_2: final = 230453062773196406322953725600125856954
+SEED128_3: final = 334883455271001690768699206953238296696
+SEED128_4: final = 69805789651723487751993596682833892465
+SEED128_5: final = 107997836754270478432192384195731366045
+SEED128_6: final = 61384398454038591198002507585631369346
+SEED128_7: final = 165303562401480433055547884045914282112
+SEED128_8: final = 215418768511176275020128984871223831370
+SEED128_9: final = 247520618467519227348322182729719821192
+SEED128_10: final = 260473913589332506348144405693894964574
+
+
+class InterpolationType(Enum):
+    linear = 0  #: linear interpolation
+    ncs = 1  #: natural cubic spline
+    ccs = 2  #: clamped cubic spline
+    pmc = 3  #: piecewise monotone cubic [FC80]
+    pchip = 4  #: piecewise cubic Hermite interpolation polynomial [FB84]
+
+
+class ExtrapolationType(Enum):
+    nan = 0  #: set extrapolated values to nan
+    flat = 1  #: set all extrapolated values equal to the nearest interpolated value (constant or flat extrapolation).
+
+
+class Interpolator(ABC):
+    def __init__(self,
+                 inter_type: InterpolationType,
+                 extra_type: ExtrapolationType):
+        """ Class to perform inter- and extrapolation.
+
+        :param inter_type: interpolation type.
+        :param extra_type: extrapolation type.
+        """
+
+        self.inter_type: InterpolationType = inter_type  #: the interpolation type
+        self.extra_type: ExtrapolationType = extra_type  #: the extrapolation type
+
+    @abstractmethod
+    def __call__(self, x: ScalarOrArray) -> ScalarOrArray:
+        """ Returns the inter- or extrapolated value(s) at the given domain value(s) 'x'.
+
+        :param x: domain value(s) at which to compute the inter- or extrapolated value.
+        :return: the inter- or extrapolated value(s).
+        """

{computils-0.0.1 → computils-0.0.2}/src/computils/matrix_computations.py

@@ -20,4 +20,10 @@ def robust_inverse(square_matrix: np.ndarray) -> np.ndarray:
 
 
 def is_diagonal(matrix: np.ndarray) -> bool:
+    """ Determines if the given matrix is diagonal.
+
+    :param matrix:
+    :return: True if matrix is diagonal, False otherwise.
+    """
+
     return np.count_nonzero(matrix - np.diag(np.diagonal(matrix))) == 0

computils-0.0.2/src/computils/parallelization.py

@@ -0,0 +1,75 @@
+""" This module contains functionality for parallelization. """
+
+from math import floor
+from psutil import cpu_count
+from typing import List
+
+
+class BatchAllocation:
+    def __init__(self,
+                 batch_id: int,
+                 n_cores: int,
+                 indices: List[int]):
+        """ Initializes a BatchAllocation object.
+
+        :param batch_id: unique number to identify batch.
+        :param n_cores: >= 1, number of physical cores allocated to this batch.
+        :param indices: contains the indices of the elements allocated to this batch.
+        """
+
+        self.batch_id: int = batch_id  #: id number to identify a batch
+        self.n_cores: int = n_cores  #: the number of cores allocated to the batch
+        self.indices: List[int] = indices  #: the indices allocated to the batch.
+
+    def batch_size(self) -> int:
+        """ Returns the number of indices allocated to the batch.
+
+        :return: the number of indices allocated to the batch.
+        """
+        return len(self.indices)
+
+
+def get_batch_allocations(n_elements: int,
+                          n_cores: int = None) -> List[BatchAllocation]:
+    """ Returns an allocation of elements over batches such that the maximum number of elements per core is minimized.
+
+    :param n_elements: the number of elements to be allocated over the cores.
+    :param n_cores: optional, number of physical cores to be used for the batch allocations. If None, all physical
+        cores are used.
+    :return: a list with batch allocations.
+    """
+
+    if n_cores is None:
+        n_cores = get_n_physical_cores()
+
+    n_batches = min(n_elements, n_cores)
+    indices = list(range(n_elements))
+
+    lower_bound_cores_per_batch = floor(n_cores / n_batches)
+    lower_bound_elements_per_batch = floor(n_elements / n_batches)
+    batch_allocations = []
+    for i in range(n_batches):
+        indices_for_batch = [indices.pop() for j in range(lower_bound_elements_per_batch)]
+        allocation = BatchAllocation(batch_id=i, n_cores=lower_bound_cores_per_batch,
+                                     indices=indices_for_batch)
+        batch_allocations.append(allocation)
+
+    n_remaining_cores = n_cores - n_batches * lower_bound_cores_per_batch
+    while n_remaining_cores > 0:
+        batch_index = n_batches - n_remaining_cores
+        batch_allocations[batch_index].n_cores += 1
+        n_remaining_cores -= 1
+
+    while len(indices) > 0:
+        batch_index = n_batches - len(indices)
+        batch_allocations[batch_index].indices.append(indices.pop())
+
+    return batch_allocations
+
+
+def get_n_physical_cores() -> int:
+    """ Returns the number of physical cores on your machine.
+
+    :return: the number of physical cores on your machine.
+    """
+    return cpu_count(logical=False)

{computils-0.0.1 → computils-0.0.2}/src/computils/parameter_transformations.py

@@ -4,26 +4,70 @@ import numpy as np
 
 
 def impose_lower_bound(transformed_parameter: float, lower_bound: float) -> float:
+    """ Imposes a lower bound on transformed_parameter.
+
+    :param transformed_parameter: any real number.
+    :param lower_bound: any real number.
+    :return: the corresponding parameter value with the lower bound imposed.
+    """
+
     return np.exp(transformed_parameter) + lower_bound
 
 
 def inverse_impose_lower_bound(parameter: float, lower_bound: float) -> float:
+    """ Applies the inverse lower-bound transformation to parameter.
+
+    :param parameter: a real number which adheres to the given lower bound.
+    :param lower_bound: any real number.
+    :return: the transformed parameter, which can take on any real number.
+    """
+
     return np.log(parameter - lower_bound)
 
 
 def impose_upper_bound(transformed_parameter: float, upper_bound: float) -> float:
+    """ Imposes an upper bound on transformed_parameter.
+
+    :param transformed_parameter: any real number.
+    :param upper_bound: any real number.
+    :return: the corresponding parameter value with the upper bound imposed.
+    """
+
     return -np.exp(transformed_parameter) + upper_bound
 
 
 def inverse_impose_upper_bound(parameter: float, upper_bound: float) -> float:
+    """ Applies the inverse upper-bound transformation to parameter.
+
+    :param parameter: a real number which adheres to the given upper bound.
+    :param upper_bound: any real number.
+    :return: the transformed parameter, which can take on any real number.
+    """
+
     return np.log(upper_bound - parameter)
 
 
 def impose_bounds(transformed_parameter: float, lower_bound: float, upper_bound: float) -> float:
+    """ Imposes a lower and an upper bound on transformed_parameter.
+
+    :param transformed_parameter: any real number.
+    :param lower_bound: any real number.
+    :param upper_bound: any real number strictly larger than lower bound.
+    :return: a real number which adheres to the given bounds.
+    """
+
     return lower_bound + (upper_bound - lower_bound)/(1.0 + np.exp(-transformed_parameter))
 
 
 def inverse_impose_bounds(parameter: float, lower_bound: float, upper_bound: float) -> float:
+    """ Applies the inverse bounds transformation to parameter.
+
+    :param parameter: a real number which adheres to the given bounds.
+    :param lower_bound: any real number.
+    :param upper_bound: any real number strictly larger than lower bound.
+    :return: the transformed parameter, which can take on any real number.
+    """
+
     z = (parameter - lower_bound)/(upper_bound - lower_bound)
     return np.log(z) - np.log(1.0 - z)
 

{computils-0.0.1 → computils-0.0.2}/src/computils/sorting_algorithms.py

@@ -38,7 +38,7 @@ def find_lt(a: Sequence,
     
     :param a: 
     :param x: an object with '<' and '==' operators.
-    :return: 
+    :return: the rightmost value in a that is less than x.
     """
 
     _check_args(a=a, x=x)
@@ -55,7 +55,7 @@ def find_le(a: Sequence,
 
     :param a: 
     :param x: an object with '<' and '==' operators.
-    :return: 
+    :return: the rightmost value in a that is less than or equal to x.
     """
 
     _check_args(a=a, x=x)
@@ -72,7 +72,7 @@ def find_gt(a: Sequence,
 
     :param a: 
     :param x: an object with '<' and '==' operators.
-    :return: 
+    :return: the leftmost value in a that is greater than x.
     """
 
     _check_args(a=a, x=x)
@@ -87,11 +87,11 @@ def find_ge(a: Sequence,
             x: Any) -> Any:
     """ Returns the leftmost value in a that is greater than or equal to x.
 
-        Remark: raises a value error if 
+    Remark: raises a value error if
 
     :param a: 
     :param x: an object with '<' and '==' operators.
-    :return: 
+    :return: the leftmost value in a that is greater than or equal to x.
     """
 
     _check_args(a=a, x=x)

computils-0.0.2/src/computils/type_utils.py

@@ -0,0 +1,106 @@
+""" This module implements helping functions for the introduced types. """
+
+import hashlib
+import numpy as np
+from typing import Union, Iterable, List, Dict
+from .globals import ScalarOrArray, FloatOrArray
+
+
+def size(x: ScalarOrArray) -> int:
+    """ Returns the number of elements in x.
+
+    :param x:
+    :return: the number of elements in x.
+    """
+
+    if isinstance(x, np.ndarray):
+        return x.size
+    else:
+        return 1
+
+
+def to_1d_array(x: Union[float, int, Iterable, np.ndarray]) -> np.ndarray:
+    """  Transforms x into a 1d array.
+
+    :param x:
+    :return: a 1-dimensional array corresponding to x.
+    """
+
+    return np.asarray(x).reshape(1, -1)[0, :]
+
+
+def to_float_if_singleton(x: FloatOrArray) -> FloatOrArray:
+    """ Transforms x into a Float if it has a single element.
+
+    :param x:
+    :return: x if it is an array, or x as a float if it has only a single element.
+    """
+
+    if x.size == 1:
+        return x.flatten()[0]
+    else:
+        return x
+
+
+def has_nan(x: np.ndarray) -> bool:
+    """ Checks whether any element in x is NaN.
+
+    :param x:
+    :return: True if any element in x is NaN, False otherwise.
+    """
+    return np.isnan(np.sum(x))
+
+
+def compute_hash(a: np.ndarray,
+                 n_chars: int = -1,
+                 include_dtype: bool = False,
+                 include_shape: bool = False) -> str:
+    """ Returns a hash for the given array a. The hashing algorithm for np arrays is based on
+    https://stackoverflow.com/questions/64753916/unique-identifier-for-numpy-array
+
+    :param a:
+    :param n_chars: the number of characters in the hashing string.
+    :param include_dtype: if True also incorporate the dtype in the hash.
+    :param include_shape: if True also incorporate the shape in the hash (so two arrays with identical elements but a different shape receive a different hash string).
+    :return: the hash string corresponding to the given array.
+    """
+
+    data = bytes()
+    if include_dtype:
+        data += str(a.dtype).encode('ascii')
+        data += b','
+    if include_shape:
+        data += str(a.shape).encode('ascii')
+        data += b','
+    data += a.tobytes()
+    hash_values = hashlib.sha256(data).hexdigest()
+    return hash_values[:n_chars]
+
+
+def dicts_to_array(dicts: List[dict]) -> np.ndarray:
+    """ Converts a list of dicts with indices as keys to an array.
+
+    :param dicts:
+    :return: array corresponding to the list.
+    """
+
+    result_dict = {}
+    for d in dicts:
+        result_dict.update(d)
+
+    return dict_to_array(result_dict)
+
+
+def dict_to_array(d: Dict[int, float]) -> np.ndarray:
+    """ Convert a dict with indices as keys to an array.
+
+    :param d:
+    :return: array corresponding to the dict.
+    """
+
+    idx = np.array(list(d.keys()))
+    val = np.array(list(d.values()))
+
+    out = np.zeros(shape=val.shape)
+    out[idx[:]] = val
+    return out

{computils-0.0.1 → computils-0.0.2}/src/computils.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: computils
-Version: 0.0.1
-Summary: A package collecting functionality for various numerical computations (numerical differentiation, interpolation, optimization, sorting, ).
+Version: 0.0.2
+Summary: A package collecting functionality for various numerical computations (numerical differentiation, interpolation, optimization, sorting, parallelization).
 Author-email: Karim Moussa <research@k-moussa.com>
 Project-URL: Homepage, https://github.com/k-moussa/computils
 Classifier: Programming Language :: Python :: 3

{computils-0.0.1 → computils-0.0.2}/src/computils.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ src/computils/gaussian_elim_spp.py
 src/computils/globals.py
 src/computils/interpolation.py
 src/computils/matrix_computations.py
+src/computils/parallelization.py
 src/computils/parameter_transformations.py
 src/computils/performance_checking.py
 src/computils/sorting_algorithms.py

computils-0.0.1/src/computils/globals.py

@@ -1,64 +0,0 @@
-""" This module collects all exposed types."""
-
-import numpy as np
-from enum import Enum
-from abc import ABC, abstractmethod
-from typing import final, Union
-
-MACHINE_EPS: final = float(2 ** (-53))  # max relative error corresponding to 1/2 ULP
-SQUARE_ROOT_MACHINE_EPS: final = np.sqrt(MACHINE_EPS)
-CUBE_ROOT_MACHINE_EPS: final = np.cbrt(MACHINE_EPS)
-FOURTH_ROOT_MACHINE_EPS: final = np.power(MACHINE_EPS, 1/4)
-
-Integer: final = Union[int, np.int8, np.int16, np.int32, np.int64, np.uint8, np.uint16, np.uint32, np.uint64]
-Float: final = Union[float, np.float16, np.float32, np.float64, np.float128]
-Complex: final = Union[complex, np.complex64, np.complex128, np.complex256]
-Scalar: final = Union[Integer, Float, Complex]
-
-IntOrArray: final = Union[Integer, np.ndarray]
-FloatOrArray: final = Union[Float, np.ndarray]
-ComplexOrArray: final = Union[Complex, np.ndarray]
-ScalarOrArray: final = Union[Scalar, np.ndarray]
-
-
-# 128-bit integers generated using entropy gathered from the OS, for fixing the seed of NumPy generators.
-SEED128_1: final = 137088887599416403785824428186011523708
-SEED128_2: final = 230453062773196406322953725600125856954
-SEED128_3: final = 334883455271001690768699206953238296696
-SEED128_4: final = 69805789651723487751993596682833892465
-SEED128_5: final = 107997836754270478432192384195731366045
-SEED128_6: final = 61384398454038591198002507585631369346
-SEED128_7: final = 165303562401480433055547884045914282112
-SEED128_8: final = 215418768511176275020128984871223831370
-SEED128_9: final = 247520618467519227348322182729719821192
-SEED128_10: final = 260473913589332506348144405693894964574
-
-
-class InterpolationType(Enum):
-    linear = 0
-    ncs = 1  # natural cubic spline
-    ccs = 2  # clamped cubic spline
-    pmc = 3  # piecewise monotone cubic [FC80]
-    pchip = 4  # [FB84]
-
-
-class ExtrapolationType(Enum):
-    nan = 0
-    flat = 1
-
-
-class Interpolator(ABC):
-    def __init__(self,
-                 inter_type: InterpolationType,
-                 extra_type: ExtrapolationType):
-
-        self.inter_type: InterpolationType = inter_type
-        self.extra_type: ExtrapolationType = extra_type
-
-    @abstractmethod
-    def __call__(self, x: ScalarOrArray) -> ScalarOrArray:
-        """
-
-        :param x:
-        :return:
-        """

computils-0.0.1/src/computils/type_utils.py

@@ -1,11 +0,0 @@
-""" Implements helping functions for the introduced types. """
-
-import numpy as np
-from .globals import ScalarOrArray
-
-
-def size(x: ScalarOrArray) -> int:
-    if isinstance(x, np.ndarray):
-        return x.size
-    else:
-        return 1