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

desdeo/gdm/score_bands.py

@@ -0,0 +1,114 @@
+"""Implements a interactive SCORE bands based GDM."""
+
+from typing import Literal
+
+import polars as pl
+from pydantic import BaseModel, ConfigDict, Field
+
+from desdeo.gdm.voting_rules import consensus_rule
+from desdeo.tools.score_bands import SCOREBandsConfig, SCOREBandsResult, score_json
+
+
+class SCOREBandsGDMConfig(BaseModel):
+    """Configuration for the SCORE bands based GDM."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    score_bands_config: SCOREBandsConfig = Field(default_factory=lambda: SCOREBandsConfig())
+    """Configuration for the SCORE bands method."""
+    minimum_votes: int = Field(default=1, gt=0)
+    """Minimum number of votes required to select a cluster."""
+    from_iteration: int | None
+    """The iteration number from which to consider the clusters. Set to None if method is initializing."""
+
+
+class SCOREBandsGDMResult(BaseModel):
+    """Result of the SCORE bands based GDM."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    votes: dict[str, int] | None = Field(default=None)
+    """The votes given by the decision makers."""
+    score_bands_result: SCOREBandsResult
+    """Result of the SCORE bands method."""
+    relevant_ids: list[int]
+    """IDs of the relevant solutions in the current iteration. Assumes that data is not modified between iterations."""
+    # If the data keeps changing, we need to store the actual data instead of just the IDs.
+    iteration: int
+    previous_iteration: int | None
+    """The previous iteration number, if any."""
+
+
+def score_bands_gdm(
+    data: pl.DataFrame,
+    config: SCOREBandsGDMConfig,
+    state: list[SCOREBandsGDMResult],
+    votes: dict[str, int] | None = None,
+) -> list[SCOREBandsGDMResult]:
+    """Run the SCORE bands based interactive GDM.
+
+    Args:
+        data (pl.DataFrame): The data to run the GDM on.
+        config (SCOREBandsGDMConfig): Configuration for the GDM.
+        state (list[SCOREBandsGDMResult]): List of previous state of the GDM. Empty list if first iteration.
+        votes (dict[str, int] | None, optional): Votes from the decision makers. Defaults to None.
+
+    Raises:
+        ValueError: Both state and votes must be provided or neither.
+
+    Returns:
+        list[SCOREBandsGDMResult]: The updated state of the GDM.
+    """
+    if bool(state) != bool(votes):
+        raise ValueError("Both state and votes must be provided or neither.")
+    if votes is None:
+        # First iteration. No votes yet.
+        score_bands_result = score_json(data, config.score_bands_config)
+        return [
+            SCOREBandsGDMResult(
+                score_bands_result=score_bands_result,
+                relevant_ids=list(range(len(data))),
+                iteration=1,
+                previous_iteration=None,
+            )
+        ]
+    if not state:
+        raise ValueError("State must be provided if votes are provided.")
+    elif config.from_iteration is None:
+        raise ValueError("from_iteration must be set in the config for subsequent iterations.")
+
+    winning_clusters = consensus_rule(votes, config.minimum_votes)
+
+    index_column_name = "index"
+    if index_column_name in data.columns:
+        index_column_name = "index_"
+    cluster_column_name = "cluster"
+    if cluster_column_name in data.columns:
+        cluster_column_name = "cluster_"
+
+    current_iteration = state[-1].iteration + 1
+
+    clusters = state[config.from_iteration - 1].score_bands_result.clusters
+    relevant_data = (
+        data.with_row_index(name=index_column_name)  # Add index column
+        .filter(
+            pl.col(index_column_name).is_in(state[config.from_iteration - 1].relevant_ids)
+        )  # Get the solutions from previous iteration
+        .with_columns(pl.Series(cluster_column_name, clusters))  # Add clustering information from last iteration
+        .filter(pl.col(cluster_column_name).is_in(winning_clusters))  # Keep only winning clusters
+        .drop(cluster_column_name)  # Drop cluster column
+    )
+
+    relevant_ids = relevant_data[index_column_name].to_list()
+    relevant_data = relevant_data.drop(index_column_name)  # Drop index column
+
+    return [
+        *state,
+        SCOREBandsGDMResult(
+            votes=votes,
+            score_bands_result=score_json(relevant_data, config.score_bands_config),
+            relevant_ids=relevant_ids,
+            iteration=current_iteration,
+            previous_iteration=config.from_iteration,
+        ),
+    ]

desdeo/gdm/voting_rules.py

@@ -0,0 +1,50 @@
+"""This module contains voting rules for group decision making such as majority rule."""
+
+from collections import Counter
+
+
+def majority_rule(votes: dict[str, int]) -> int | None:
+    """Choose the option that has more than half of the votes.
+
+    Args:
+        votes (dict[str, int]): A dictionary mapping voter IDs to their votes.
+
+    Returns:
+        int | None: The option that has more than half of the votes, or None if no such option exists.
+    """
+    counts = Counter(votes.values())
+    all_votes = sum(counts.values())
+    for vote, c in counts.items():
+        if c > all_votes // 2:
+            return vote
+    return None
+
+
+def plurality_rule(votes: dict[str, int]) -> list[int]:
+    """Choose the option that has the most votes.
+
+    Args:
+        votes (dict[str, int]): A dictionary mapping voter IDs to their votes.
+
+    Returns:
+        list[int]: A list of options that have the most votes (in case of a tie).
+    """
+    counts = Counter(votes.values())
+    max_votes = max(counts.values())
+    return [vote for vote, c in counts.items() if c == max_votes]
+
+
+def consensus_rule(votes: dict[str, int], min_votes: int) -> list[int]:
+    """Choose all options that have at least min_votes votes.
+
+    Args:
+        votes (dict[str, int]): A dictionary mapping voter IDs to their votes.
+        min_votes (int): The minimum number of votes required for an option to be selected.
+
+    """
+    if min_votes <= 0:
+        raise ValueError("min_votes must be greater than 0.")
+    if min_votes > len(votes):
+        raise ValueError("min_votes cannot be greater than the number of voters.")
+    counts = Counter(votes.values())
+    return [vote for vote, c in counts.items() if c >= min_votes]

desdeo/mcdm/__init__.py

@@ -1,14 +1,35 @@
 """Imports available from the desdeo-mcdm package."""
 
 __all__ = [
+    "ENautilusResult",
     "NimbusError",
+    "enautilus_get_representative_solutions",
+    "enautilus_step",
+    "calculate_closeness",
+    "calculate_intermediate_points",
+    "calculate_lower_bounds",
+    "calculate_reachable_subset",
     "generate_starting_point",
     "infer_classifications",
+    "prune_by_average_linkage",
     "solve_intermediate_solutions",
     "solve_sub_problems",
+    "solve_group_sub_problems",
+    "voting_procedure",
     "rpm_solve_solutions",
+    "rpm_intermediate_solutions",
 ]
 
+from .enautilus import (
+    ENautilusResult,
+    calculate_closeness,
+    calculate_intermediate_points,
+    calculate_lower_bounds,
+    calculate_reachable_subset,
+    enautilus_get_representative_solutions,
+    enautilus_step,
+    prune_by_average_linkage,
+)
 from .nimbus import (
     NimbusError,
     generate_starting_point,
@@ -16,4 +37,5 @@ from .nimbus import (
     solve_intermediate_solutions,
     solve_sub_problems,
 )
-from .reference_point_method import rpm_solve_solutions
+from .gnimbus import solve_group_sub_problems, voting_procedure
+from .reference_point_method import rpm_solve_solutions, rpm_intermediate_solutions

desdeo/mcdm/enautilus.py

@@ -0,0 +1,338 @@
+"""Functions related to the E-NAUTILUS method are defined here.
+
+Reference of the method:
+
+Ruiz, A. B., Sindhya, K., Miettinen, K., Ruiz, F., & Luque, M. (2015).
+E-NAUTILUS: A decision support system for complex multiobjective optimization
+problems based on the NAUTILUS method. European Journal of Operational Research,
+246(1), 218-231.
+"""
+
+import numpy as np
+import polars as pl
+from pydantic import BaseModel, Field
+from scipy.cluster.hierarchy import fcluster, linkage
+from scipy.spatial.distance import pdist
+
+from desdeo.problem import (
+    Problem,
+    numpy_array_to_objective_dict,
+    objective_dict_to_numpy_array,
+)
+from desdeo.tools import SolverResults, flip_maximized_objective_values
+
+
+class ENautilusResult(BaseModel):
+    """The result of an iteration of the E-NAUTILUS method."""
+
+    current_iteration: int = Field(description="Number of the current iteration.")
+    iterations_left: int = Field(description="Number of iterations left.")
+    intermediate_points: list[dict[str, float]] = Field(description="New intermediate points")
+    reachable_best_bounds: list[dict[str, float]] = Field(
+        description="Best bounds of the objective function values reachable from each intermediate point."
+    )
+    reachable_worst_bounds: list[dict[str, float]] = Field(
+        description="Worst bounds of the objective function values reachable from each intermediate point."
+    )
+    closeness_measures: list[float] = Field(description="Closeness measures of each intermediate point.")
+    reachable_point_indices: list[list[int]] = Field(
+        description="Indices of the reachable points from each intermediate point."
+    )
+
+
+def enautilus_get_representative_solutions(
+    problem: Problem, result: ENautilusResult, non_dominated_points: pl.DataFrame
+) -> list[SolverResults]:
+    """Returns the solution corresponding to the intermediate points.
+
+    The representative points are selected based on the current intermediate points.
+    If the number of iterations left is 0, then the intermediate and representative points
+    are equal.
+
+    Args:
+        problem (Problem): the problem being solved.
+        result (ENautilusResult): an ENautilusResponse returned by `enautilus_step`.
+        non_dominated_points (pl.DataFrame): a dataframe from which the
+            representative solutions are taken.
+
+    Returns:
+        SolverResults: full information about the solutions. If information
+            other than just objective function values are expected, then the
+            supplied `non_dominated_points` should contain this information.
+    """
+    obj_syms = [obj.symbol for obj in problem.objectives]
+    var_syms = [var.symbol for var in problem.variables]
+    const_syms = [con.symbol for con in problem.constraints] if problem.constraints else None
+    extra_syms = [extra.symbol for extra in problem.extra_funcs] if problem.extra_funcs else None
+    scal_syms = [scal.symbol for scal in problem.scalarization_funcs] if problem.scalarization_funcs else None
+
+    # Objective matrix (rows = ND points, cols = objectives, original senses)
+    obj_matrix = non_dominated_points.select(obj_syms).to_numpy()
+
+    solver_results: list[SolverResults] = []
+
+    for interm in result.intermediate_points:
+        interm_vec = np.array([interm[sym] for sym in obj_syms], dtype=float)
+
+        # Find index of closest ND point (Euclidean distance)
+        idx = int(np.argmin(np.linalg.norm(obj_matrix - interm_vec, axis=1)))
+
+        row = non_dominated_points[idx]
+
+        var_dict = {sym: row[sym] for sym in var_syms if sym in row}
+        obj_dict = {sym: row[sym] for sym in obj_syms}
+        const_dict = {sym: row[sym] for sym in const_syms if sym in row} if const_syms is not None else None
+        extra_dict = {sym: row[sym] for sym in extra_syms if sym in row} if extra_syms is not None else None
+        scal_dict = {sym: row[sym] for sym in scal_syms if sym in row} if scal_syms is not None else None
+
+        solver_results.append(
+            SolverResults(
+                optimal_variables=var_dict,
+                optimal_objectives=obj_dict,
+                constraint_values=const_dict,
+                extra_func_values=extra_dict,
+                scalarization_values=scal_dict,
+                success=True,
+                message="E-NAUTILUS: nearest non-dominated point selected for intermediate point.",
+            )
+        )
+
+    return solver_results
+
+
+def enautilus_step(  # noqa: PLR0913
+    problem: Problem,
+    non_dominated_points: pl.DataFrame | dict[str, float],
+    current_iteration: int,
+    iterations_left: int,
+    selected_point: dict[str, float],
+    reachable_point_indices: list[int],
+    number_of_intermediate_points: int,
+) -> ENautilusResult:
+    """Compute one iteration of the E-NAUTILUS method.
+
+    It is assumed that information from a previous iteration (selected point,
+    etc.) is available either from a previous iteration of E-NAUTILUS, or if
+    this is the first iteration, then the selected (intermediate) point
+    `selected_point` should be the approximated nadir point from
+    `non_dominated_points`. In this case, the `reachable_point_indices` should
+    cover the whole of `non_dominated_points`. After the first iteration, all
+    the information for computing the next iteration is always available from
+    the previous iteration's result of this function (plus the `selected_point`
+    provided by e.g., a decision maker).
+
+    Args:
+        problem (Problem): the problem being solved. Used mainly for manipulating the other arguments.
+        non_dominated_points (pl.DataFrame): a set of non-dominated points
+            approximating the Pareto front of `Problem`. This should be a Polars
+            dataframe with at least columns that match the objective function
+            symbols in `Problem` and the corresponding minimization value column.
+            I.e., for an objective with symbol 'f1' the dataframe should have the
+            symbols 'f1' and 'f1_min', where the column 'f1_min has the
+            corresponding values of 'f1', but assuming minimization (N.B. if 'f1' is
+            minimized, then 'f1_min' would have identical values as 'f1'). If provided
+            as a `dict`, this will be converted to a polars dataframe.
+        current_iteration (int): the number of the current iteration. For the first iteration, this should be zero.
+        iterations_left (int): how many iteration are left (counting the current one).
+        selected_point (dict[str, float]): the selected intermediate point in
+            the previous iteration. If this is the first iteration, then this should
+            be the nadir point approximated from `non_dominated_points`.
+        reachable_point_indices (list[int]): the indices of the points in
+            `non_dominated_points` that are reachable from
+            `current_iteration_point`.
+        number_of_intermediate_points (int): how many intermediate points are generated.
+
+    Returns:
+        ENautilusResult: the result of the iteration.
+    """
+    # treat everything as minimized
+    # selected point as numpy array, correct for minimization
+    z_h = objective_dict_to_numpy_array(problem, flip_maximized_objective_values(problem, selected_point))
+
+    # subset of reachable solutions, take _min column
+    if isinstance(non_dominated_points, dict):
+        # dict converted to Polars dataframe
+        _non_dominated_points = pl.DataFrame(non_dominated_points)
+    else:
+        # already Polars dataframe
+        _non_dominated_points = non_dominated_points
+
+    non_dom_objectives = _non_dominated_points[[f"{obj.symbol}_min" for obj in problem.objectives]].to_numpy()
+    p_h = non_dom_objectives[reachable_point_indices]
+
+    # estimate nadir from non-dominated points, treating as minimized problem
+    z_nadir = non_dom_objectives.max(axis=0)
+
+    # compute representative points
+    representative_points = prune_by_average_linkage(p_h, number_of_intermediate_points)
+
+    # calculate intermediate points
+    intermediate_points = calculate_intermediate_points(z_h, representative_points, iterations_left)
+
+    # calculate lower bounds
+    intermediate_lower_bounds = [
+        calculate_lower_bounds(p_h, intermediate_point) for intermediate_point in intermediate_points
+    ]
+
+    # calculate closeness measures
+    closeness_measures = [
+        calculate_closeness(intermediate_point, z_nadir, representative_point)
+        for (intermediate_point, representative_point) in zip(intermediate_points, representative_points, strict=True)
+    ]
+
+    # calculate the indices of the reachable points for each intermediate point
+    reachable_from_intermediate = [
+        calculate_reachable_subset(non_dom_objectives, reachable_point_indices, lower_bounds, interm)
+        for lower_bounds, interm in zip(intermediate_lower_bounds, intermediate_points, strict=True)
+    ]
+
+    best_bounds = [
+        flip_maximized_objective_values(problem, numpy_array_to_objective_dict(problem, bounds))
+        for bounds in intermediate_lower_bounds
+    ]
+    worst_bounds = [
+        flip_maximized_objective_values(problem, numpy_array_to_objective_dict(problem, point))
+        for point in intermediate_points
+    ]
+
+    corrected_intermediate_points = [
+        flip_maximized_objective_values(problem, numpy_array_to_objective_dict(problem, point))
+        for point in intermediate_points
+    ]
+
+    return ENautilusResult(
+        current_iteration=current_iteration + 1,
+        iterations_left=iterations_left - 1,
+        intermediate_points=corrected_intermediate_points,
+        reachable_best_bounds=best_bounds,
+        reachable_worst_bounds=worst_bounds,
+        closeness_measures=closeness_measures,
+        reachable_point_indices=reachable_from_intermediate,
+    )
+
+
+def prune_by_average_linkage(non_dominated_points: np.ndarray, k: int) -> np.ndarray:
+    """Prune a set of non-dominated points using average linkage clustering (Morse, 1980).
+
+    This is used to calculate the representative solutions in E-NAUTILUS.
+
+    Args:
+        non_dominated_points (np.ndarray): an array of non-dominated points in objective space.
+        k (int): Number of representative points to retain.
+
+    Returns:
+        np.ndarray: an array of representative points.
+    """
+    if len(non_dominated_points) <= k:
+        # no need to prune
+        return non_dominated_points
+
+    # Compute pairwise distances
+    distances = pdist(non_dominated_points, metric="euclidean")
+
+    # Hierarchical clustering using average linkage
+    z = linkage(distances, method="average")
+
+    # Cut tree to form k clusters
+    cluster_labels = fcluster(z, k, criterion="maxclust")
+
+    # For each cluster, choose the point closest to the centroid
+    representatives = []
+    for cluster_id in range(1, k + 1):
+        cluster_points = non_dominated_points[cluster_labels == cluster_id]
+        centroid = cluster_points.mean(axis=0)
+        closest_idx = np.argmin(np.linalg.norm(cluster_points - centroid, axis=1))
+        representatives.append(cluster_points[closest_idx])
+
+    return np.array(representatives)
+
+
+def calculate_intermediate_points(
+    z_previous: np.ndarray, zs_representatives: np.ndarray, iterations_left: int
+) -> np.ndarray:
+    """Calculates the intermediate points to be shown to the decision maker at each iteration.
+
+    The number of returned points depends on how many `zs_representative points` are supplied.
+
+    Args:
+        z_previous (np.ndarray): the point selected by the decision maker in the previous iteration.
+        zs_representatives (np.ndarray): the representative solutions at the current iteration.
+        iterations_left (int): the number of iterations left (including the current one).
+
+    Returns:
+        np.ndarray: an array of intermediate points.
+    """
+    return ((iterations_left - 1) / iterations_left) * z_previous + (1 / iterations_left) * zs_representatives
+
+
+def calculate_reachable_subset(
+    non_dominated_points: np.ndarray, reachable_indices: np.ndarray, lower_bounds: np.ndarray, z_preferred: np.ndarray
+) -> list[int]:
+    """Calculates the reachable subset on a non-dominated set from a selected intermediate point.
+
+    Args:
+        non_dominated_points (np.ndarray): the original set of non-dominated points.
+        reachable_indices (np.ndarray): the currently reachable indices, which
+            will be used to select the new reachable points.
+        lower_bounds (np.ndarray): the lower bounds of the reachable subset of non-dominates points.
+        z_preferred (np.ndarray): the selected intermediate point subject to the reachable subset is calculated.
+
+    Returns:
+        list[int]: the indices of the reachable solutions
+    """
+    return [
+        i
+        for i, z in enumerate(non_dominated_points)
+        if np.all(lower_bounds <= z) and np.all(z <= z_preferred) and i in reachable_indices
+    ]
+
+
+def calculate_lower_bounds(non_dominated_points: np.ndarray, z_intermediate: np.ndarray) -> np.ndarray:
+    """Calculates the lower bounds of reachable solutions from an intermediate point.
+
+    The lower bounds are calculated by solving an epsilon-constraint problem
+    with the epsilon values taken from the intermediate point.
+
+    Args:
+        non_dominated_points (np.ndarray): a set of non-dominated points
+            according to which the reachable values are computed.
+        z_intermediate (np.ndarray): the intermediate point according to which
+            the lower bounds are calculated.
+
+    Returns:
+        np.ndarray: the lower bounds of reachable solutions on the non-dominated
+            set based from the intermediate point.
+    """
+    k = non_dominated_points.shape[1]
+    bounds = []
+
+    for r in range(k):
+        # Indices of objectives other than r
+        other = np.delete(np.arange(k), r)
+
+        # Find points that are no worse than z_intermediate in all objectives except r
+        mask = np.all(non_dominated_points[:, other] <= z_intermediate[other], axis=1)
+        feasible = non_dominated_points[mask]
+
+        if feasible.size > 0:
+            bounds.append(np.min(feasible[:, r]))
+        else:
+            bounds.append(np.inf)  # No feasible point in this projection
+
+    return np.array(bounds)
+
+
+def calculate_closeness(z_intermediate: np.ndarray, z_nadir: np.ndarray, z_representative: np.ndarray) -> float:
+    """Calculate the closeness of an intermediate point to the non-dominated set.
+
+    The greater the closeness is, the close intermediate point is to the non-dominated set.
+
+    Args:
+        z_intermediate (np.ndarray): the intermediate point.
+        z_nadir (np.ndarray): the nadir point of the non-dominated set.
+        z_representative (np.ndarray): the representative solution of `z_intermediate`.
+
+    Returns:
+        float: the closeness measure.
+    """
+    return np.linalg.norm(z_intermediate - z_nadir) / np.linalg.norm(z_representative - z_nadir) * 100