desdeo 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

desdeo/tools/reference_vectors.py

@@ -1,20 +1,7 @@
-from enum import Enum
-from itertools import combinations, product
-from typing import Sequence
+from itertools import combinations
 
 import numpy as np
 from scipy.special import comb
-from scipy.stats.qmc import LatinHypercube
-
-from desdeo.problem import Problem
-from desdeo.tools.message import (
-    DictMessage,
-    Message,
-    PolarsDataFrameMessage,
-    ReferenceVectorMessageTopics,
-    TerminatorMessageTopics,
-)
-from desdeo.tools.patterns import Publisher, Subscriber
 
 
 def normalize(vectors):
@@ -119,344 +106,124 @@ def rotate_toward(initial_vector, final_vector, other_vectors, degrees: float =
     return (rotate(initial_vector, rotated_vector, other_vectors), False)
 
 
-class VectorCreationOptions(Enum):
-    """Enum class for reference vector creation methods."""
-
-    SIMPLEX = "Uniform"
-    """Uniformly distributed reference vectors created using simplex lattice design.
-    This method is generates distributions with specific numbers of reference vectors.
-    Check: https://www.itl.nist.gov/div898/handbook/pri/section5/pri542.htm for more information."""
-    S_ENERGY = "s-energy"
-    """Reference vectors created using Riesz s-energy criterion. This method is used to distribute
-    an arbitrary number of reference vectors in the objective space while minimizing the s-energy.
-    Currently not implemented."""
-
-
-class VectorTypeOptions(Enum):
-    """Enum class for reference vector normalization methods."""
-
-    SPHERICAL = "Spherical"
-    """Normalize the reference vectors to a hypersphere, i.e. the second norm is equal to 1."""
-    PLANAR = "Planar"
-    """Normalize the reference vectors to a plane, i.e. the first norm is equal to 1."""
-
-
-class ReferenceVectors(Subscriber):
-    """Class object for reference vectors."""
-
-    def __init__(
-        self,
-        problem: Problem,
-        publisher: Publisher,
-        adaptation_frequency: int = 0,
-        verbosity: int = 2,
-        lattice_resolution: int | None = None,
-        number_of_vectors: int | None = None,
-        creation_type: VectorCreationOptions = VectorCreationOptions.SIMPLEX,
-    ):
-        """Create a Reference vectors object.
-
-        Parameters
-        ----------
-        problem : Problem
-            Problem object.
-        publisher : Publisher
-            Publisher object.
-        adaptation_frequency : int, optional
-            The number of generations in between reference vector adaptation. By default 0, i.e. no adaptation.
-        verbosity : int, optional
-            Verbosity level. By default 2.
-        lattice_resolution : int
-            Number of divisions along an axis when creating the simplex lattice. If not specified, the lattice resolution
-            is calculated based on the desired number of vectors.
-        number_of_vectors : int
-            Number of reference vectors to be created. If not specified, the number of vectors is calculated based on
-            the lattice resolution. By default None.
-        creation_type : VectorCreationOptions
-            Method for creating reference vectors. By default VectorCreationOptions.SIMPLEX. Currently only
-            VectorCreationOptions.SIMPLEX is implemented. Future versions will include VectorCreationOptions.S_ENERGY.
-        """
-        interested_topics = [TerminatorMessageTopics.GENERATION]
-        provided_topics: list[ReferenceVectorMessageTopics] = []
-        match verbosity:
-            case 0:
-                provided_topics: list[ReferenceVectorMessageTopics] = []
-            case 1:
-                provided_topics = [ReferenceVectorMessageTopics.STATE]
-            case 2:
-                provided_topics = [
-                    ReferenceVectorMessageTopics.STATE,
-                    ReferenceVectorMessageTopics.REFERENCE_VECTORS_SPHERICAL,
-                    ReferenceVectorMessageTopics.REFERENCE_VECTORS_PLANAR,
-                ]
-
-        super().__init__(
-            publisher, interested_topics=interested_topics, provided_topics=provided_topics, verbosity=verbosity
-        )
-        self.number_of_objectives = number_of_objectives
-        self.lattice_resolution = lattice_resolution
-        self.number_of_vectors = number_of_vectors
-        self.adaptation_frequency = adaptation_frequency
-        self.generation_at_last_adaptation = 0
-
-        if creation_type == VectorCreationOptions.S_ENERGY:
-            raise NotImplementedError("Riesz s-energy criterion not implemented.")
-            if number_of_vectors is None:
-                raise ValueError("Number of vectors must be specified for Riesz s-energy criterion.")
-        if not (lattice_resolution or number_of_vectors):
-            raise ValueError("Either lattice_resolution or number_of_vectors must be specified.")
-
-        if number_of_vectors is not None:
-            temp_lattice_resolution = 0
-            while True:
-                temp_lattice_resolution += 1
-                temp_number_of_vectors = comb(
-                    temp_lattice_resolution + self.number_of_objectives - 1,
-                    self.number_of_objectives - 1,
-                    exact=True,
-                )
-                if temp_number_of_vectors > number_of_vectors:
-                    break
-            self.lattice_resolution = temp_lattice_resolution - 1
-
-        self.creation_type = creation_type
-        self.values: np.ndarray = None
-        self.values_planar: np.ndarray = None
-        if self.creation_type == VectorCreationOptions.SIMPLEX:
-            self._create_simplex()
-        self.initial_values = np.copy(self.values)
-        self.initial_values_planar = np.copy(self.values_planar)
-        self.neighbouring_angles()
-
-    def _create_simplex(self):
-        """Create the reference vectors using simplex lattice design."""
-        if self.lattice_resolution is None:
-            raise ValueError("Lattice resolution must be specified.")
-
-        number_of_vectors: int = comb(
-            self.lattice_resolution + self.number_of_objectives - 1,
-            self.number_of_objectives - 1,
+def approx_lattice_resolution(number_of_vectors: int, num_dims: int) -> int:
+    """
+    Approximate the lattice resolution based on the number of vectors and dimensions.
+
+    Args:
+        number_of_vectors (int): Desired number of reference vectors.
+        num_dims (int): Number of objectives (dimensions).
+
+    Returns:
+        int: The smallest lattice resolution that produces more than the desired number of vectors.
+    """
+    temp_lattice_resolution = 0
+    while True:
+        temp_lattice_resolution += 1
+        temp_number_of_vectors = comb(
+            temp_lattice_resolution + num_dims - 1,
+            num_dims - 1,
             exact=True,
         )
-        self.number_of_vectors = number_of_vectors
-        temp1 = range(1, self.number_of_objectives + self.lattice_resolution)
-        temp1 = np.array(list(combinations(temp1, self.number_of_objectives - 1)))
-        temp2 = np.array([range(self.number_of_objectives - 1)] * self.number_of_vectors)
-        temp = temp1 - temp2 - 1
-        weight = np.zeros((self.number_of_vectors, self.number_of_objectives), dtype=int)
-        weight[:, 0] = temp[:, 0]
-        for i in range(1, self.number_of_objectives - 1):
-            weight[:, i] = temp[:, i] - temp[:, i - 1]
-        weight[:, -1] = self.lattice_resolution - temp[:, -1]
-        self.values = weight / self.lattice_resolution
-        self.values_planar = np.copy(self.values)
-        self.normalize()
-
-    def normalize(self):
-        """Normalize the reference vectors to a unit hypersphere."""
-        self.number_of_vectors = self.values.shape[0]
-        norm_2 = np.linalg.norm(self.values, axis=1).reshape(-1, 1)
-        norm_1 = np.sum(self.values_planar, axis=1).reshape(-1, 1)
-        norm_2[norm_2 == 0] = np.finfo(float).eps
-        self.values = np.divide(self.values, norm_2)
-        self.values_planar = np.divide(self.values_planar, norm_1)
-
-    def neighbouring_angles(self) -> np.ndarray:
-        """Calculate neighbouring angles for normalization."""
-        cosvv = np.dot(self.values, self.values.transpose())
-        cosvv.sort(axis=1)
-        cosvv = np.flip(cosvv, 1)
-        cosvv[cosvv > 1] = 1
-        acosvv = np.arccos(cosvv[:, 1])
-        self.neighbouring_angles_current = acosvv
-        return acosvv
-
-    def adapt(self, fitness: np.ndarray):
-        """Adapt reference vectors. Then normalize.
-
-        Parameters
-        ----------
-        fitness : np.ndarray
-        """
-        max_val = np.amax(fitness, axis=0)
-        min_val = np.amin(fitness, axis=0)
-        self.values = self.initial_values * (max_val - min_val)
-
-        self.normalize()
-
-    def interactive_adapt_1(self, z: np.ndarray, translation_param: float = 0.2) -> None:
-        """Adapt reference vectors using the information about prefererred solution(s) selected by the Decision maker.
-
-        Args:
-            z (np.ndarray): Preferred solution(s).
-            translation_param (float): Parameter determining how close the reference vectors are to the central vector
-            **v** defined by using the selected solution(s) z.
-        """
-        if z.shape[0] == 1:
-            # single preferred solution
-            # calculate new reference vectors
-            self.values = translation_param * self.initial_values + ((1 - translation_param) * z)
-            self.values_planar = translation_param * self.initial_values_planar + ((1 - translation_param) * z)
-
-        else:
-            # multiple preferred solutions
-            # calculate new reference vectors for each preferred solution
-            values = [translation_param * self.initial_values + ((1 - translation_param) * z_i) for z_i in z]
-            values_planar = [
-                translation_param * self.initial_values_planar + ((1 - translation_param) * z_i) for z_i in z
-            ]
-
-            # combine arrays of reference vectors into a single array and update reference vectors
-            self.values = np.concatenate(values)
-            self.values_planar = np.concatenate(values_planar)
-
-        self.normalize()
-
-    def interactive_adapt_2(self, z: np.ndarray, predefined_distance: float = 0.2) -> None:
-        """Adapt reference vectors by using the information about non-preferred solution(s) selected by the Decision maker.
-
-        After the Decision maker has specified non-preferred solution(s), Euclidian distance between normalized solution
-        vector(s) and each of the reference vectors are calculated. Those reference vectors that are **closer** than a
-        predefined distance are either **removed** or **re-positioned** somewhere else.
-
-        Note:
-            At the moment, only the **removal** of reference vectors is supported. Repositioning of the reference
-            vectors is **not** supported.
-
-        Note:
-            In case the Decision maker specifies multiple non-preferred solutions, the reference vector(s) for which the
-            distance to **any** of the non-preferred solutions is less than predefined distance are removed.
-
-        Note:
-            Future developer should implement a way for a user to say: "Remove some percentage of
-            objecive space/reference vectors" rather than giving a predefined distance value.
-
-        Args:
-            z (np.ndarray): Non-preferred solution(s).
-            predefined_distance (float): The reference vectors that are closer than this distance are either removed or
-            re-positioned somewhere else.
-            Default value: 0.2
-        """
-        # calculate L1 norm of non-preferred solution(s)
-        z = np.atleast_2d(z)
-        norm = np.linalg.norm(z, ord=1, axis=1).reshape(np.shape(z)[0], 1)
-
-        # non-preferred solutions normalized
-        v_c = np.divide(z, norm)
-
-        # distances from non-preferred solution(s) to each reference vector
-        distances = np.array(
-            [
-                list(
-                    map(
-                        lambda solution: np.linalg.norm(solution - value, ord=2),
-                        v_c,
-                    )
-                )
-                for value in self.values_planar
-            ]
+        if temp_number_of_vectors > number_of_vectors:
+            break
+    return temp_lattice_resolution - 1
+
+
+def create_simplex(
+    number_of_objectives: int,
+    lattice_resolution: int = None,
+    number_of_vectors: int = None,
+) -> np.ndarray:
+    """
+    Create reference vectors using the simplex lattice design.
+
+    Args:
+        number_of_objectives (int): Number of objectives (dimensions).
+        lattice_resolution (int, optional): Lattice resolution to use. If None, will be determined from number_of_vectors.
+        number_of_vectors (int, optional): Desired number of reference vectors. Used if lattice_resolution is None.
+
+    Returns:
+        np.ndarray: Array of normalized reference vectors.
+
+    Raises:
+        ValueError: If both lattice_resolution and number_of_vectors are None.
+    """
+    if lattice_resolution is None and number_of_vectors is None:
+        raise ValueError(
+            "Either lattice resolution or number of vectors must be specified."
         )
 
-        # find out reference vectors that are not closer than threshold value to any non-preferred solution
-        mask = [all(d >= predefined_distance) for d in distances]
-
-        # set those reference vectors that met previous condition as new reference vectors, drop others
-        self.values = self.values[mask]
-        self.values_planar = self.values_planar[mask]
-
-    def iteractive_adapt_3(self, ref_point, translation_param=0.2):
-        """Adapt reference vectors linearly towards a reference point. Then normalize.
-
-        The details can be found in the following paper: Hakanen, Jussi &
-        Chugh, Tinkle & Sindhya, Karthik & Jin, Yaochu & Miettinen, Kaisa.
-        (2016). Connections of Reference Vectors and Different Types of
-        Preference Information in Interactive Multiobjective Evolutionary
-        Algorithms.
-
-        Parameters
-        ----------
-        ref_point :
-
-        translation_param :
-            (Default value = 0.2)
-
-        """
-        self.values = self.initial_values * translation_param + ((1 - translation_param) * ref_point)
-        self.values_planar = self.initial_values_planar * translation_param + ((1 - translation_param) * ref_point)
-        self.normalize()
-
-    def interactive_adapt_4(self, preferred_ranges: np.ndarray) -> None:
-        """Adapt reference vectors by using the information about the Decision maker's preferred range for each of the objective.
-
-        Using these ranges, Latin hypercube sampling is applied to generate m number of samples between
-        within these ranges, where m is the number of reference vectors. Normalized vectors constructed of these samples
-        are then set as new reference vectors.
-
-        Args:
-            preferred_ranges (np.ndarray): Preferred lower and upper bound for each of the objective function values.
-        """
-        # bounds
-        lower_limits = np.array([ranges[0] for ranges in preferred_ranges])
-        upper_limits = np.array([ranges[1] for ranges in preferred_ranges])
-
-        # generate samples using Latin hypercube sampling
-        lhs = LatinHypercube(d=self.number_of_objectives)
-        w = lhs.random(n=self.number_of_vectors)
-
-        # scale between bounds
-        w = w * (upper_limits - lower_limits) + lower_limits
-
-        # set new reference vectors and normalize them
-        self.values = w
-        self.values_planar = w
-        self.normalize()
-
-    def add_edge_vectors(self):
-        """Add edge vectors to the list of reference vectors.
-
-        Used to cover the entire orthant when preference information is
-        provided.
-
-        """
-        edge_vectors = np.eye(self.values.shape[1])
-        self.values = np.vstack([self.values, edge_vectors])
-        self.values_planar = np.vstack([self.values_planar, edge_vectors])
-        self.number_of_vectors = self.values.shape[0]
-        self.normalize()
-
-    def state(self) -> Sequence[Message]:
-        """Return the current state of the reference vectors."""
-        if self.verbosity == 0:
-            return []
-        if self.verbosity == 1:
-            return [
-                DictMessage(
-                    topic=ReferenceVectorMessageTopics.STATE,
-                    value={},
-                    source=self.__class__.__name__,
-                )
-            ]
-        if self.verbosity == 2:
-            return [
-                DictMessage(
-                    topic=ReferenceVectorMessageTopics.STATE,
-                    value={
-                        "number_of_vectors": self.number_of_vectors,
-                        "number_of_objectives": self.number_of_objectives,
-                        "lattice_resolution": self.lattice_resolution,
-                        "creation_type": self.creation_type,
-                    },
-                    source=self.__class__.__name__,
-                ),
-                PolarsDataFrameMessage(
-                    topic=ReferenceVectorMessageTopics.REFERENCE_VECTORS_SPHERICAL,
-                    value=self.values,
-                    source=self.__class__.__name__,
-                ),
-                PolarsDataFrameMessage(
-                    topic=ReferenceVectorMessageTopics.REFERENCE_VECTORS_PLANAR,
-                    value=self.values_planar,
-                    source=self.__class__.__name__,
-                ),
-            ]
-        raise ValueError(f"Verbosity level {self.verbosity} is not allowed.")
+    if lattice_resolution is None:
+        lattice_resolution = approx_lattice_resolution(
+            number_of_vectors, number_of_objectives
+        )
+
+    number_of_vectors = comb(
+        lattice_resolution + number_of_objectives - 1,
+        number_of_objectives - 1,
+        exact=True,
+    )
+
+    temp1 = range(1, number_of_objectives + lattice_resolution)
+    temp1 = np.array(list(combinations(temp1, number_of_objectives - 1)))
+    temp2 = np.array([range(number_of_objectives - 1)] * number_of_vectors)
+    temp = temp1 - temp2 - 1
+    weight = np.zeros((number_of_vectors, number_of_objectives), dtype=int)
+    weight[:, 0] = temp[:, 0]
+    for i in range(1, number_of_objectives - 1):
+        weight[:, i] = temp[:, i] - temp[:, i - 1]
+    weight[:, -1] = lattice_resolution - temp[:, -1]
+    values = weight / lattice_resolution
+    return normalize(values)
+
+
+def normalize(values: np.ndarray) -> np.ndarray:
+    """
+    Normalize a set of vectors to unit length (project onto the unit hypersphere).
+
+    Args:
+        values (np.ndarray): Array of vectors to normalize.
+
+    Returns:
+        np.ndarray: Normalized vectors.
+    """
+    norm_2 = np.linalg.norm(values, axis=1).reshape(-1, 1)
+    norm_2[norm_2 == 0] = np.finfo(float).eps
+    values = np.divide(values, norm_2)
+    return values
+
+
+def neighbouring_angles(values: np.ndarray) -> np.ndarray:
+    """
+    Calculate the angles to the nearest neighbor for each reference vector.
+
+    Args:
+        values (np.ndarray): Array of normalized reference vectors.
+
+    Returns:
+        np.ndarray: Array of angles (in radians) to the nearest neighbor for each vector.
+    """
+    cosvv = np.dot(values, values.transpose())
+    cosvv.sort(axis=1)
+    cosvv = np.flip(cosvv, 1)
+    cosvv[cosvv > 1] = 1
+    acosvv = np.arccos(cosvv[:, 1])
+    return acosvv
+
+
+def add_edge_vectors(values: np.ndarray) -> np.ndarray:
+    """
+    Add edge (axis-aligned) vectors to the set of reference vectors.
+
+    This ensures that each axis direction is represented in the set.
+
+    Args:
+        values (np.ndarray): Array of reference vectors.
+
+    Returns:
+        np.ndarray: Array of reference vectors with edge vectors added and normalized.
+    """
+    edge_vectors = np.eye(values.shape[1])
+    values = np.vstack([values, edge_vectors])
+    return normalize(values)