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

desdeo/emo/operators/termination.py

@@ -0,0 +1,178 @@
+"""The base class for termination criteria.
+
+The termination criterion is used to determine when the optimization process should stop. In this implementation, it
+also includes a simple counter for the number of elapsed generations. This counter is increased by one each time the
+termination criterion is called. The simplest termination criterion is reaching the maximum number of generations.
+The implementation also contains a counter for the number of evaluations. This counter is updated by the Evaluator
+and Generator classes. The termination criterion can be based on the number of evaluations as well.
+
+Warning:
+    Each subclass of BaseTerminator must implement the do method. The do method should always call the
+    super().do method to increment the generation counter _before_ conducting the termination check.
+"""
+
+from collections.abc import Sequence
+
+from desdeo.tools.message import (
+    EvaluatorMessageTopics,
+    GeneratorMessageTopics,
+    IntMessage,
+    Message,
+    TerminatorMessageTopics,
+)
+from desdeo.tools.patterns import Subscriber
+
+
+class BaseTerminator(Subscriber):
+    """The base class for the termination criteria.
+
+    Also includes a simple counter for number of elapsed generations. This counter is increased by one each time the
+    termination criterion is called.
+    """
+
+    @property
+    def provided_topics(self) -> dict[int, Sequence[TerminatorMessageTopics]]:
+        """Return the topics provided by the terminator.
+
+        Returns:
+            dict[int, Sequence[TerminatorMessageTopics]]: The topics provided by the terminator.
+        """
+        return {
+            0: [],
+            1: [
+                TerminatorMessageTopics.GENERATION,
+                TerminatorMessageTopics.EVALUATION,
+                TerminatorMessageTopics.MAX_GENERATIONS,
+                TerminatorMessageTopics.MAX_EVALUATIONS,
+            ],
+        }
+
+    @property
+    def interested_topics(self):
+        """Return the message topics that the terminator is interested in."""
+        return [EvaluatorMessageTopics.NEW_EVALUATIONS, GeneratorMessageTopics.NEW_EVALUATIONS]
+
+    def __init__(self, **kwargs):
+        """Initialize a termination criterion."""
+        super().__init__(**kwargs)
+        self.current_generation: int = 1
+        self.current_evaluations: int = 0
+        self.max_generations: int = 0
+        self.max_evaluations: int = 0
+
+    def check(self) -> bool | None:
+        """Check if the termination criterion is reached.
+
+        Returns:
+            bool: True if the termination criterion is reached, False otherwise.
+        """
+        self.current_generation += 1
+
+    def state(self) -> Sequence[Message]:
+        """Return the state of the termination criterion."""
+        state = [
+            IntMessage(
+                topic=TerminatorMessageTopics.GENERATION,
+                value=self.current_generation,
+                source=self.__class__.__name__,
+            ),
+            IntMessage(
+                topic=TerminatorMessageTopics.EVALUATION, value=self.current_evaluations, source=self.__class__.__name__
+            ),
+        ]
+        if self.max_evaluations != 0:
+            state.append(
+                IntMessage(
+                    topic=TerminatorMessageTopics.MAX_EVALUATIONS,
+                    value=self.max_evaluations,
+                    source=self.__class__.__name__,
+                )
+            )
+        if self.max_generations != 0:
+            state.append(
+                IntMessage(
+                    topic=TerminatorMessageTopics.MAX_GENERATIONS,
+                    value=self.max_generations,
+                    source=self.__class__.__name__,
+                )
+            )
+        return state
+
+    def update(self, message: Message) -> None:
+        """Update the number of evaluations.
+
+        Note that for this method to work, this class must be registered as an observer of a subject that sends
+        messages with the key "num_evaluations". The Evaluator class does this.
+
+        Args:
+            message (dict): the message from the subject, must contain the key "num_evaluations".
+        """
+        if not isinstance(message, IntMessage):
+            return
+        if not isinstance(message.topic, EvaluatorMessageTopics) or isinstance(message.topic, GeneratorMessageTopics):
+            return
+        if (
+            message.topic == EvaluatorMessageTopics.NEW_EVALUATIONS  # NOQA: PLR1714
+            or message.topic == GeneratorMessageTopics.NEW_EVALUATIONS
+        ):
+            self.current_evaluations += message.value
+
+
+class MaxGenerationsTerminator(BaseTerminator):
+    """A class for a termination criterion based on the number of generations."""
+
+    def __init__(self, max_generations: int, **kwargs):
+        """Initialize a termination criterion based on the number of generations.
+
+        Args:
+            max_generations (int): the maximum number of generations.
+            kwargs: Additional keyword arguments. These are passed to the Subscriber class. At the very least, the
+                publisher must be passed. See the Subscriber class for more information.
+        """
+        super().__init__(**kwargs)
+        self.max_generations = max_generations
+
+    def check(self) -> bool:
+        """Check if the termination criterion based on the number of generations is reached.
+
+        Args:
+            new_generation (bool, optional): Increment the generation counter. Defaults to True.
+
+        Returns:
+            bool: True if the termination criterion is reached, False otherwise.
+        """
+        super().check()
+        self.notify()
+        return self.current_generation > self.max_generations
+
+
+# TODO (@light-weaver): This check is done _after_ the evaluations have taken place.
+# This means that the algorithm will run for one more generation than it should.
+class MaxEvaluationsTerminator(BaseTerminator):
+    """A class for a termination criterion based on the number of evaluations."""
+
+    def __init__(self, max_evaluations: int, **kwargs):
+        """Initialize a termination criterion based on the number of evaluations.
+
+        Looks for messages with key "num_evaluations" to update the number of evaluations.
+
+        Args:
+            max_evaluations (int): the maximum number of evaluations.
+            kwargs: Additional keyword arguments. These are passed to the Subscriber class. At the very least, the
+                publisher must be passed. See the Subscriber class for more information.
+        """
+        super().__init__(**kwargs)
+        if not isinstance(max_evaluations, int) or max_evaluations < 0:
+            raise ValueError("max_evaluations must be a non-negative integer")
+        self.max_evaluations = max_evaluations
+        self.current_evaluations = 0
+
+    def check(self) -> bool:
+        """Check if the termination criterion based on the number of evaluations is reached.
+
+        Returns:
+            bool: True if the termination criterion is reached, False otherwise.
+        """
+        super().check()
+        self.notify()
+        return self.current_evaluations >= self.max_evaluations

desdeo/explanations/__init__.py

@@ -0,0 +1,6 @@
+"""This module contains tools to generate and analyze explanations."""
+
+__all__ = ["ShapExplainer", "generate_biased_mean_data"]
+
+from .explainer import ShapExplainer
+from .utils import generate_biased_mean_data

desdeo/explanations/explainer.py

@@ -0,0 +1,100 @@
+"""Explainers are defined here."""
+
+import numpy as np
+import polars as pl
+import shap
+from scipy.spatial import cKDTree
+
+
+class ShapExplainer:
+    """Defines a SHAP explainer for reference point based methods."""
+
+    def __init__(self, problem_data: pl.DataFrame, input_symbols: list[str], output_symbols: list[str]):
+        """Initialize the explainer.
+
+        Initializes the explainer with given data, and input and output symbols.
+        The data should contain the columns listed in the input and output symbols.
+        This data is then used to simulate the inputs and outputs of an (interactive)
+        multiobjective optimization method, which is used to explain the relation of its
+        inputs and outputs using SHAP values.
+
+        Note:
+            The `data` can be generated by for a reference point based based by, e.g.,
+            randomly sampling the input space and then evaluating the methods with the
+            sampled inputs to generate outputs.
+
+        Args:
+            problem_data (pl.DataFrame): the data to simulate the input and
+                outputs of a multiobjective optimization method.
+            input_symbols (list[str]): the input symbols present in `data`.
+                These symbols represent the inputs to the method.
+            output_symbols (list[str]): the output symbols present in `data`.
+                These symbols represent the outputs of the method.
+        """
+        self.data = problem_data
+        self.input_symbols = input_symbols
+        self.output_symbols = output_symbols
+        self.input_array = self.data[self.input_symbols].to_numpy()
+        self.output_array = self.data[self.output_symbols].to_numpy()
+        self.to_output_tree = cKDTree(self.input_array)
+        self.explainer = None
+
+    def setup(self, background_data: pl.DataFrame):
+        """Setup the explainer.
+
+        Setups the SHAP explainer with  the given background data. The
+        background data should have the columns `self.input_symbols`. The
+        background data is used as the background (or missing data) when
+        computing SHAP values.  The mean (or expected values) of the background
+        data's output (`self.output_symbols`) will determine the baseline of the
+        SHAP values.
+
+        Note:
+            To generate a dataset with meaningful expected values, e.g., in case
+            the SHAP values are better understood by relating them to a specific baseline,
+            see `desdeo.explanations.generate_biased_mean_data`.
+
+        Args:
+            background_data (pl.DataFrame): the background data.
+        """
+        self.explainer = shap.Explainer(
+            self.evaluate,
+            masker=background_data[self.input_symbols].to_numpy(),
+        )
+
+    def evaluate(self, evaluate_array: np.ndarray) -> np.ndarray:
+        """Evaluates the multiobjective optimization method represented by the data.
+
+        Note:
+            Evaluation happens by finding the closest matching input array in the
+            `self.input_array` and then using that value's corresponding output
+            as the evaluation result. Closest means lowest Euclidean distance.
+
+        Args:
+            evaluate_array (np.ndarray): the inputs to the method represented by the data.
+                Can be either a single input, or an array of multiple inputs. Used mainly by
+                `self.explain_input`.
+
+        Returns:
+            np.ndarray: the evaluated output(s) corresponding to the input data.
+        """
+        _, indices = self.to_output_tree.query(evaluate_array)
+
+        return self.output_array[indices]
+
+    def explain_input(self, to_be_explained: pl.DataFrame) -> dict:
+        """Explain an input and produces SHAP values.
+
+        Args:
+            to_be_explained (pl.DataFrame): the input to be explained. The
+                dataframe must have the columns defined in `self.input_symbols`.
+
+        Returns:
+            dict: the key 'shaps' corresponds to the computed SHAP values for
+                the input, the key 'base_values' is the baseline the SHAP values
+                were computed against, and the key 'data' is the input the SHAP
+                values were computed for.
+        """
+        _to_be_explained = to_be_explained[self.input_symbols].to_numpy()
+
+        return self.explainer(_to_be_explained)

desdeo/explanations/utils.py

@@ -0,0 +1,90 @@
+"""Utilities specific to explainable multiobjective optimization."""
+
+import cvxpy as cp
+import numpy as np
+
+
+def generate_biased_mean_data(
+    data: np.ndarray, target_means: np.ndarray, min_size: int = 2, max_size: int | None = None, solver: str = "SCIP"
+) -> list | None:
+    r"""Finds a subset of the provided data that has a mean value close to provided target values.
+
+    Finds a subset of the provided data that has a mean value close to the
+    provided target values.  Formulates a mixed-integer quadratic programming problem to
+    find a subset of `data` with a mean as close as possible to `target_values`
+    and a size between `min_size` and `max_size`. In other words, the following problems is solved:
+
+    \begin{align}
+        &\min_{\mathbf{x}} & f(\mathbf{x}) & = \sum_{i=1}^m \left[ \left(\frac{1}{k}
+            \sum_{j=1}^n x_j \times \text{data}_j\right)_i - \text{target}_i \right]^2 \\
+        &\text{s.t.,}   & k & = \sum_{i=1}^n x_i,\\
+        &               & k & \leq \text{max_size},\\
+        &               & k & \geq \text{min_size},\\
+    \end{align},
+    where $n$ is the number of rows in `data`, $m$ is the number of columns in
+    `data`, and $k$ is the size of the subset. Notice that the closeness to the
+    target means is based on the Euclidean distance.
+
+    Note:
+        Be mindful that this functions can take a long time with a very large
+            data set and large upper bound for the desired subset.
+
+    Args:
+        data (np.ndarray): the data from which to generate the subset with a
+            biased mean. Should be a 2D array with each row representing a sample
+            and each column the value of the variables in the sample.
+        target_means (np.ndarray): the target mean values for each column the
+            generated subset should have values close to.
+        min_size (int, optional): the minimum size of the generated subset. Defaults to 2.
+        max_size (int | None, optional): the maximum size of the generated
+            subset. If None, then the maximum size is bound by the numbers of rows
+            in `data`. Defaults to None.
+        solver (str, optional): the selected solver to be used by cvxpy. The
+            solver should support mixed-integer quadratic programming. Defaults to
+            "SCIP".
+
+    Returns:
+        list | None: the indices of the samples of the generated subset respect to
+            `data`, i.e., the generated subset is `data[indices]`. If optimization is not successful,
+            returns None instead.
+    """
+    # Number of rows and columns
+    n_rows, n_cols = data.shape
+    max_size = n_rows if max_size is None else max_size
+
+    # Big M used to penalize the auxiliary variable z
+    big_m = data.max(axis=0)
+
+    # Binary variables to select rows from the data
+    x = cp.Variable(n_rows, boolean=True)
+
+    # Auxiliary variables, z represents the mean. phi is the weighted sum of the data (weighted by x)
+    z = cp.Variable(n_cols)
+    phi = cp.Variable((n_rows, n_cols))
+
+    # The objective function, squared values of the difference between the mean
+    # of the currently selected subset and the target values.
+    objective = cp.sum_squares(z - target_means)
+
+    # Define the constraints
+    constraints = [
+        # Sets the value of phi
+        *[cp.sum(phi[:, col]) == cp.sum(cp.multiply(x, data[:, col])) for col in range(n_cols)],
+        # Constraints the values of phi using big M, in practice setting z to be the mean values
+        *[phi[:, col] <= cp.multiply(big_m[col], x) for col in range(n_cols)],
+        *[phi[:, col] <= z[col] for col in range(n_cols)],
+        *[phi[:, col] >= z[col] - cp.multiply(big_m[col], 1 - x) for col in range(n_cols)],
+        phi >= 0,
+        # Bounds the size of the set: min_size <= k <= max_size
+        cp.sum(x) >= min_size,
+        cp.sum(x) <= max_size,
+    ]
+
+    # Create the problem model
+    problem = cp.Problem(cp.Minimize(objective), constraints)
+
+    # Solve the problem
+    problem.solve(solver=solver)
+
+    # Return the indices of the found subset
+    return [i for i in range(n_rows) if x.value[i] == 1]

desdeo/mcdm/__init__.py

@@ -0,0 +1,19 @@
+"""Imports available from the desdeo-mcdm package."""
+
+__all__ = [
+    "NimbusError",
+    "generate_starting_point",
+    "infer_classifications",
+    "solve_intermediate_solutions",
+    "solve_sub_problems",
+    "rpm_solve_solutions",
+]
+
+from .nimbus import (
+    NimbusError,
+    generate_starting_point,
+    infer_classifications,
+    solve_intermediate_solutions,
+    solve_sub_problems,
+)
+from .reference_point_method import rpm_solve_solutions