pymoo 0.6.1.1__cp311-cp311-macosx_10_9_universal2.whl → 0.6.1.2__cp311-cp311-macosx_10_9_universal2.whl

pymoo/core/individual.py

@@ -1,23 +1,91 @@
-import copy
+"""
+Module containing infrastructure for representing individuals in 
+population-based optimization algorithms.
+"""
+
+# public API for when using ``from pymoo.core.individual import *``
+__all__ = [
+    "default_config",
+    "Individual",
+    "calc_cv",
+    "constr_to_cv",
+]
 
+import copy
+from typing import Optional
+from typing import Tuple
+from typing import Union
+from warnings import warn
 import numpy as np
 
 
-def default_config():
-    return dict(cache=True,
-                cv_eps=0.0,
-                cv_ieq=dict(scale=None, eps=0.0, pow=None, func=np.sum),
-                cv_eq=dict(scale=None, eps=1e-4, pow=None, func=np.sum)
-                )
+def default_config() -> dict:
+    """
+    Get default constraint violation configuration settings.
+
+    Returns
+    -------
+    out : dict
+        A dictionary of default constraint violation settings.
+    """
+    return dict(
+        cache = True,
+        cv_eps = 0.0,
+        cv_ieq = dict(scale=None, eps=0.0, pow=None, func=np.sum),
+        cv_eq = dict(scale=None, eps=1e-4, pow=None, func=np.sum),
+    )
 
 
 class Individual:
+    """
+    Base class for representing an individual in a population-based 
+    optimization algorithm.
+    """
+
+    # function: function to generate default configuration settings
     default_config = default_config
 
-    def __init__(self, config=None, **kwargs) -> None:
+    def __init__(
+            self, 
+            config: Optional[dict] = None, 
+            **kwargs: dict,
+        ) -> None:
+        """
+        Constructor for the ``Invididual`` class.
+
+        Parameters
+        ----------
+        config : dict, None
+            A dictionary of configuration metadata.
+            If ``None``, use a class-dependent default configuration.
+        kwargs : dict
+            Additional keyword arguments containing data which is to be stored 
+            in the ``Individual``.
+        """
+        # set decision variable vector to None
+        self._X = None
+
+        # set values objective(s), inequality constraint(s), equality 
+        # contstraint(s) to None
+        self._F = None
+        self._G = None
+        self._H = None
+        
+        # set first derivatives of objective(s), inequality constraint(s), 
+        # equality contstraint(s) to None
+        self._dF = None
+        self._dG = None
+        self._dH = None
+        
+        # set second derivatives of objective(s), inequality constraint(s), 
+        # equality contstraint(s) to None
+        self._ddF = None
+        self._ddG = None
+        self._ddH = None
+
+        # set constraint violation value to None
+        self._CV = None
 
-        self._X, self._F, self._G, self._H, self._dF, self._dG, self._dH = None, None, None, None, None, None, None
-        self._ddF, self._ddG, self._ddH, self._CV, = None, None, None, None
         self.evaluated = None
 
         # initialize all the local variables
@@ -39,8 +107,21 @@ class Individual:
             else:
                 self.data[k] = v
 
-    def reset(self, data=True):
-
+    def reset(
+            self, 
+            data: bool = True,
+        ) -> None:
+        """
+        Reset the value of objective(s), inequality constraint(s), equality 
+        constraint(s), their first and second derivatives, the constraint 
+        violation, and the metadata to empty values.
+
+        Parameters
+        ----------
+        data : bool
+            Whether to reset metadata associated with the ``Individiual``.
+        """
+        # create an empty array to share
         empty = np.array([])
 
         # design variables
@@ -70,7 +151,23 @@ class Individual:
         # a set storing what has been evaluated
         self.evaluated = set()
 
-    def has(self, key):
+    def has(
+            self, 
+            key: str,
+        ) -> bool:
+        """
+        Determine whether an individual has a provided key or not.
+
+        Parameters
+        ----------
+        key : str
+            The key for which to test.
+        
+        Returns
+        -------
+        out : bool
+            Whether the ``Individual`` has the provided key.
+        """
         return hasattr(self.__class__, key) or key in self.data
 
     # -------------------------------------------------------
@@ -78,39 +175,112 @@ class Individual:
     # -------------------------------------------------------
 
     @property
-    def X(self):
+    def X(self) -> np.ndarray:
+        """
+        Get the decision vector for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The decision variable for the individual.
+        """
         return self._X
 
     @X.setter
-    def X(self, value):
+    def X(self, value: np.ndarray) -> None:
+        """
+        Set the decision vector for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The decision variable for the individual.
+        """
         self._X = value
 
     @property
-    def F(self):
+    def F(self) -> np.ndarray:
+        """
+        Get the objective function vector for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The objective function vector for the individual.
+        """
         return self._F
 
     @F.setter
-    def F(self, value):
+    def F(self, value: np.ndarray) -> None:
+        """
+        Set the objective function vector for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The objective function vector for the individual.
+        """
         self._F = value
 
     @property
-    def G(self):
+    def G(self) -> np.ndarray:
+        """
+        Get the inequality constraint vector for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The inequality constraint vector for the individual.
+        """
         return self._G
 
     @G.setter
-    def G(self, value):
+    def G(self, value: np.ndarray) -> None:
+        """
+        Set the inequality constraint vector for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The inequality constraint vector for the individual.
+        """
         self._G = value
 
     @property
-    def H(self):
+    def H(self) -> np.ndarray:
+        """
+        Get the equality constraint vector for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The equality constraint vector for the individual.
+        """
         return self._H
 
     @H.setter
-    def H(self, value):
+    def H(self, value: np.ndarray) -> None:
+        """
+        Get the equality constraint vector for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The equality constraint vector for the individual.
+        """
         self._H = value
 
     @property
-    def CV(self):
+    def CV(self) -> np.ndarray:
+        """
+        Get the constraint violation vector for an individual by either reading 
+        it from the cache or calculating it.
+
+        Returns
+        -------
+        out : np.ndarray
+            The constraint violation vector for an individual.
+        """
         config = self.config
         cache = config["cache"]
 
@@ -121,11 +291,28 @@ class Individual:
             return self._CV
 
     @CV.setter
-    def CV(self, value):
+    def CV(self, value: np.ndarray) -> None:
+        """
+        Set the constraint violation vector for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The constraint violation vector for the individual.
+        """
         self._CV = value
 
     @property
-    def FEAS(self):
+    def FEAS(self) -> np.ndarray:
+        """
+        Get whether an individual is feasible for each constraint.
+
+        Returns
+        -------
+        out : np.ndarray
+            An array containing whether each constraint is feasible for an 
+            individual.
+        """
         eps = self.config.get("cv_eps", 0.0)
         return self.CV <= eps
 
@@ -134,27 +321,75 @@ class Individual:
     # -------------------------------------------------------
 
     @property
-    def dF(self):
+    def dF(self) -> np.ndarray:
+        """
+        Get the objective function vector first derivatives for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The objective function vector first derivatives for the individual.
+        """
         return self._dF
 
     @dF.setter
-    def dF(self, value):
+    def dF(self, value: np.ndarray) -> None:
+        """
+        Set the objective function vector first derivatives for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The objective function vector first derivatives for the individual.
+        """
         self._dF = value
 
     @property
-    def dG(self):
+    def dG(self) -> np.ndarray:
+        """
+        Get the inequality constraint(s) first derivatives for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The inequality constraint(s) first derivatives for the individual.
+        """
         return self._dG
 
     @dG.setter
-    def dG(self, value):
+    def dG(self, value: np.ndarray) -> None:
+        """
+        Set the inequality constraint(s) first derivatives for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The inequality constraint(s) first derivatives for the individual.
+        """
         self._dG = value
 
     @property
-    def dH(self):
+    def dH(self) -> np.ndarray:
+        """
+        Get the equality constraint(s) first derivatives for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The equality constraint(s) first derivatives for the individual.
+        """
         return self._dH
 
     @dH.setter
-    def dH(self, value):
+    def dH(self, value: np.ndarray) -> None:
+        """
+        Set the equality constraint(s) first derivatives for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The equality constraint(s) first derivatives for the individual.
+        """
         self._dH = value
 
     # -------------------------------------------------------
@@ -162,27 +397,75 @@ class Individual:
     # -------------------------------------------------------
 
     @property
-    def ddF(self):
+    def ddF(self) -> np.ndarray:
+        """
+        Get the objective function vector second derivatives for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The objective function vector second derivatives for the individual.
+        """
         return self._ddF
 
     @ddF.setter
-    def ddF(self, value):
+    def ddF(self, value: np.ndarray) -> None:
+        """
+        Set the objective function vector second derivatives for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The objective function vector second derivatives for the individual.
+        """
         self._ddF = value
 
     @property
-    def ddG(self):
+    def ddG(self) -> np.ndarray:
+        """
+        Get the inequality constraint(s) second derivatives for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The inequality constraint(s) second derivatives for the individual.
+        """
         return self._ddG
 
     @ddG.setter
-    def ddG(self, value):
+    def ddG(self, value: np.ndarray) -> None:
+        """
+        Set the inequality constraint(s) second derivatives for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The inequality constraint(s) second derivatives for the individual.
+        """
         self._ddG = value
 
     @property
-    def ddH(self):
+    def ddH(self) -> np.ndarray:
+        """
+        Get the equality constraint(s) second derivatives for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The equality constraint(s) second derivatives for the individual.
+        """
         return self._ddH
 
     @ddH.setter
-    def ddH(self, value):
+    def ddH(self, value: np.ndarray) -> None:
+        """
+        Set the equality constraint(s) second derivatives for an individual.
+
+        Parameters
+        ----------
+        value : np.ndarray
+            The equality constraint(s) second derivatives for the individual.
+        """
         self._ddH = value
 
     # -------------------------------------------------------
@@ -190,22 +473,56 @@ class Individual:
     # -------------------------------------------------------
 
     @property
-    def x(self):
+    def x(self) -> np.ndarray:
+        """
+        Convenience property. Get the decision vector for an individual.
+
+        Returns
+        -------
+        out : np.ndarray
+            The decision variable for the individual.
+        """
         return self.X
 
     @property
-    def f(self):
+    def f(self) -> float:
+        """
+        Convenience property. Get the first objective function value for an individual.
+
+        Returns
+        -------
+        out : float
+            The first objective function value for the individual.
+        """
         return self.F[0]
 
     @property
-    def cv(self):
+    def cv(self) -> Union[float,None]:
+        """
+        Convenience property. Get the first constraint violation value for an 
+        individual by either reading it from the cache or calculating it.
+
+        Returns
+        -------
+        out : float, None
+            The constraint violation vector for an individual.
+        """
         if self.CV is None:
             return None
         else:
             return self.CV[0]
 
     @property
-    def feas(self):
+    def feas(self) -> bool:
+        """
+        Convenience property. Get whether an individual is feasible for the 
+        first constraint.
+
+        Returns
+        -------
+        out : bool
+            Whether an individual is feasible for the first constraint.
+        """
         return self.FEAS[0]
 
     # -------------------------------------------------------
@@ -213,25 +530,86 @@ class Individual:
     # -------------------------------------------------------
 
     @property
-    def feasible(self):
+    def feasible(self) -> np.ndarray:
+        """
+        Deprecated. Get whether an individual is feasible for each constraint.
+
+        Returns
+        -------
+        out : np.ndarray
+            An array containing whether each constraint is feasible for an 
+            individual.
+        """
+        warn(
+            "The ``feasible`` property for ``pymoo.core.individual.Individual`` is deprecated",
+            DeprecationWarning,
+            stacklevel = 2,
+        )
         return self.FEAS
 
     # -------------------------------------------------------
     # Other Functions
     # -------------------------------------------------------
 
-    def set_by_dict(self, **kwargs):
+    def set_by_dict(
+            self, 
+            **kwargs: dict
+        ) -> None:
+        """
+        Set an individual's data or metadata using values in a dictionary.
+
+        Parameters
+        ----------
+        kwargs : dict
+            Keyword arguments defining the data to set.
+        """
         for k, v in kwargs.items():
             self.set(k, v)
 
-    def set(self, key, value):
+    def set(
+            self, 
+            key: str, 
+            value: object,
+        ) -> 'Individual':
+        """
+        Set an individual's data or metadata based on a key and value.
+
+        Parameters
+        ----------
+        key : str
+            Key of the data for which to set.
+        value : object
+            Value of the data for which to set.
+        
+        Returns
+        -------
+        out : Individual
+            A reference to the ``Individual`` for which values were set.
+        """
         if hasattr(self, key):
             setattr(self, key, value)
         else:
             self.data[key] = value
         return self
 
-    def get(self, *keys):
+    def get(
+            self, 
+            *keys: Tuple[str,...],
+        ) -> Union[tuple,object]:
+        """
+        Get the values for one or more keys for an individual.
+
+        Parameters
+        ----------
+        keys : tuple
+            A tuple of keys for which to get values.
+
+        Returns
+        -------
+        out : tuple, object
+            If more than one key provided, return a ``tuple`` of retrieved values.
+            If a single key provided, return the retrieved value.
+        """
         ret = []
 
         for key in keys:
@@ -249,13 +627,54 @@ class Individual:
         else:
             return tuple(ret)
 
-    def duplicate(self, key, new_key):
+    def duplicate(
+            self, 
+            key: str, 
+            new_key: str,
+        ) -> None:
+        """
+        Duplicate a key to a new key.
+
+        Parameters
+        ----------
+        key : str
+            Name of the key to duplicated.
+        new_key : str
+            Name of the key to which to duplicate the original key.
+        """
         self.set(new_key, self.get(key))
 
-    def new(self):
+    def new(self) -> 'Individual':
+        """
+        Create a new instance of this class.
+
+        Returns
+        -------
+        out : Individual
+            A new instance of an ``Individual``.
+        """
         return self.__class__()
 
-    def copy(self, other=None, deep=True):
+    def copy(
+            self, 
+            other: Optional['Individual'] = None, 
+            deep: bool = True,
+        ) -> 'Individual':
+        """
+        Copy an individual.
+
+        Parameters
+        ----------
+        other : Individual, None
+            The individual to copy. If ``None``, assumed to be self.
+        deep : bool
+            Whether to deep copy the individual.
+        
+        Returns
+        -------
+        out : Individual
+            A copy of the individual.
+        """
         obj = self.new()
 
         # if not provided just copy yourself
@@ -275,7 +694,29 @@ class Individual:
         return obj
 
 
-def calc_cv(G=None, H=None, config=None):
+def calc_cv(
+        G: Optional[np.ndarray] = None, 
+        H: Optional[np.ndarray] = None, 
+        config: Optional[dict] = None,
+    ) -> np.ndarray:
+    """
+    Calculate the constraint violation(s) for a set of inequality constraint(s), 
+    equality constraint(s), and a scoring configuration.
+
+    Parameters
+    ----------
+    G : np.ndarray, None
+        A vector of inequality constraint(s).
+    H : np.ndarray, None
+        A vector of equality constraint(s).
+    config : dict, None
+        A dictionary of constraint violation scoring configuration settings.
+    
+    Returns
+    -------
+    out : np.ndarray
+        An array of constraint violations for each objective.
+    """
     if G is None:
         G = np.array([])
 
@@ -302,7 +743,29 @@ def calc_cv(G=None, H=None, config=None):
     return np.array(ieq_cv) + np.array(eq_cv)
 
 
-def constr_to_cv(c, eps=0.0, scale=None, pow=None, func=np.mean):
+def constr_to_cv(
+        c: Union[np.ndarray,None], 
+        eps: float = 0.0, 
+        scale: Optional[float] = None, 
+        pow: Optional[float] = None, 
+        func: object = np.mean,
+    ) -> float:
+    """
+    Convert a constraint to a constraint violation.
+
+    c : np.ndarray
+        An array of constraint violations.
+    eps : float
+        Error tolerance bounds.
+    scale : float, None
+        The scale to apply to a constraint violation.
+        If ``None``, no scale alteration is applied.
+    pow : float, None
+        A power to apply to a constraint violation.
+        If ``None``, no power alteration is applied.
+    func : function
+        A function to convert multiple constraint violations into a single score.
+    """
     if c is None or len(c) == 0:
         return 0.0