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

desdeo/tools/message.py

@@ -0,0 +1,234 @@
+"""Defines the messaging protocol used by the various EMO operators."""
+
+from enum import Enum
+from typing import Any, Literal
+
+from polars import DataFrame
+from pydantic import BaseModel, ConfigDict, Field, field_serializer
+
+
+class CrossoverMessageTopics(Enum):
+    """Topics for messages related to crossover operators."""
+
+    TEST = "TEST"
+    """ A message topic used only for testing the crossover operators. """
+    XOVER_PROBABILITY = "XOVER_PROBABILITY"
+    """ The current crossover probability. """
+    XOVER_DISTRIBUTION = "XOVER_DISTRIBUTION"
+    """ The current crossover distribution index. Primary used in the SBX crossover. """
+    PARENTS = "PARENTS"
+    """ The parents selected for crossover. """
+    OFFSPRINGS = "OFFSPRINGS"
+    """ The offsprings generated from the crossover. """
+    ALPHA = "ALPHA"
+    """ Alpha parameter used in crossover. """
+
+
+class MutationMessageTopics(Enum):
+    """Topics for messages related to mutation operators."""
+
+    TEST = "TEST"
+    """ A message topic used only for testing the mutation operators. """
+    MUTATION_PROBABILITY = "MUTATION_PROBABILITY"
+    """ The current mutation probability. """
+    MUTATION_DISTRIBUTION = "MUTATION_DISTRIBUTION"
+    """ The current mutation distribution index. Primary used in the polynomial mutation. """
+    OFFSPRING_ORIGINAL = "OFFSPRING_ORIGINAL"
+    """ The original offsprings before mutation. """
+    OFFSPRINGS = "OFFSPRINGS"
+    """ The offsprings after mutation. """
+    PARENTS = "PARENTS"
+    """ The parents of the offsprings. """
+
+
+class EvaluatorMessageTopics(Enum):
+    """Topics for messages related to evaluator operators."""
+
+    TEST = "TEST"
+    """ A message topic used only for testing the evaluator operators. """
+    POPULATION = "POPULATION"
+    """ The population to evaluate. """
+    OUTPUTS = "OUTPUTS"
+    """ The outputs of the population. Contains objectives, targets, constraints. """
+    OBJECTIVES = "OBJECTIVES"
+    """ The true objective values of the population. """
+    TARGETS = "TARGETS"
+    """ The targets, i.e., objective values seen by the evolutionary operators."""
+    CONSTRAINTS = "CONSTRAINTS"
+    """ The constraints of the population. """
+    VERBOSE_OUTPUTS = "VERBOSE_OUTPUTS"
+    """ Same as POPULATION + OUTPUTS."""
+    NEW_EVALUATIONS = "NEW_EVALUATIONS"
+    """ The number of new evaluations. """
+
+
+class GeneratorMessageTopics(Enum):
+    """Topics for messages related to population generator operators."""
+
+    TEST = "TEST"
+    """ A message topic used only for testing the evaluator operators. """
+    POPULATION = "POPULATION"
+    """ The population to evaluate. """
+    OUTPUTS = "OUTPUTS"
+    """ The outputs of the population generation. Contains objectives, targets, and constraints. """
+    OBJECTIVES = "OBJECTIVES"
+    """ The true objective values of the population. """
+    TARGETS = "TARGETS"
+    """ The targets, i.e., objective values seen by the evolutionary operators."""
+    CONSTRAINTS = "CONSTRAINTS"
+    """ The constraints of the population. """
+    VERBOSE_OUTPUTS = "VERBOSE_OUTPUTS"
+    """ Same as POPULATION + OUTPUTS. """
+    NEW_EVALUATIONS = "NEW_EVALUATIONS"
+    """ The number of new evaluations. """
+
+
+class SelectorMessageTopics(Enum):
+    """Topics for messages related to selector operators."""
+
+    TEST = "TEST"
+    """ A message topic used only for testing the selector operators. """
+    STATE = "STATE"
+    """ The state of the parameters of the selector. """
+    INDIVIDUALS = "INDIVIDUALS"
+    """ The individuals to select from. """
+    OUTPUTS = "OUTPUTS"
+    """ The outputs of the individuals. """
+    CONSTRAINTS = "CONSTRAINTS"
+    """ The constraints of the individuals. """
+    SELECTED_INDIVIDUALS = "SELECTED_INDIVIDUALS"
+    """ The individuals selected by the selector. """
+    SELECTED_OUTPUTS = "SELECTED_OUTPUTS"
+    """ The targets of the selected individuals. """
+    SELECTED_VERBOSE_OUTPUTS = "SELECTED_VERBOSE_OUTPUTS"
+    """ Same as SELECTED_OUTPUTS + SELECTED_INDIVIDUALS"""
+    REFERENCE_VECTORS = "REFERENCE_VECTORS"
+    """ The reference vectors used in the selection in decomposition-based EMO algorithms. """
+
+
+class TerminatorMessageTopics(Enum):
+    """Topics for messages related to terminator operators."""
+
+    TEST = "TEST"
+    """ A message topic used only for testing the terminator operators. """
+    STATE = "STATE"
+    """ The state of the parameters of the terminator. """
+    TERMINATION = "TERMINATION"
+    """ The value of the termination condition. """
+    GENERATION = "GENERATION"
+    """ The current generation number. """
+    EVALUATION = "EVALUATION"
+    """ The current number of evaluations. """
+    MAX_GENERATIONS = "MAX_GENERATIONS"
+    """ The maximum number of generations. """
+    MAX_EVALUATIONS = "MAX_EVALUATIONS"
+    """ The maximum number of evaluations. """
+
+
+MessageTopics = (
+    CrossoverMessageTopics
+    | MutationMessageTopics
+    | EvaluatorMessageTopics
+    | GeneratorMessageTopics
+    | SelectorMessageTopics
+    | TerminatorMessageTopics
+    | Literal["ALL"]  # Used to indicate that all topics are of interest to a subscriber.
+)
+
+
+class BaseMessage(BaseModel):
+    """A message containing an integer value."""
+
+    topic: MessageTopics = Field(..., description="The topic of the message.")
+    """ The topic of the message. """
+    source: str = Field(..., description="The source of the message.")
+    """ The source of the message. """
+
+
+class IntMessage(BaseMessage):
+    """A message containing an integer value."""
+
+    value: int = Field(..., description="The integer value of the message.")
+    """ The integer value of the message. """
+
+
+class FloatMessage(BaseMessage):
+    """A message containing a float value."""
+
+    value: float = Field(..., description="The float value of the message.")
+    """ The float value of the message. """
+
+
+class StringMessage(BaseMessage):
+    """A message containing a string value."""
+
+    value: str = Field(..., description="The string value of the message.")
+    """ The string value of the message. """
+
+
+class BoolMessage(BaseMessage):
+    """A message containing a boolean value."""
+
+    value: bool = Field(..., description="The boolean value of the message.")
+    """ The boolean value of the message. """
+
+
+class DictMessage(BaseMessage):
+    """A message containing a dictionary value."""
+
+    value: dict[str, Any] = Field(..., description="The dictionary value of the message.")
+    """ The dictionary value of the message. """
+
+
+class Array2DMessage(BaseMessage):
+    """A message containing a 2D array value, such as a population or a set of objectives."""
+
+    value: list[list[float]] = Field(..., description="The array value of the message.")
+    """ The array value of the message. """
+
+
+class PolarsDataFrameMessage(BaseMessage):
+    """A message containing a 2D array value, such as a population or a set of objectives."""
+
+    value: DataFrame = Field(..., description="The array value of the message.")
+    """ The array value of the message. """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    @field_serializer("value")
+    def _serialize_value(self, value: DataFrame) -> dict[str, list[int | float]]:
+        return value.to_dict(as_series=False)
+
+
+class GenericMessage(BaseMessage):
+    """A message containing a generic value."""
+
+    value: Any = Field(..., description="The generic value of the message.")
+    """ The generic value of the message. """
+
+
+Message = (
+    IntMessage
+    | FloatMessage
+    | DictMessage
+    | Array2DMessage
+    | GenericMessage
+    | StringMessage
+    | BoolMessage
+    | PolarsDataFrameMessage
+)
+
+AllowedMessagesAtVerbosity: dict[int, tuple[type[Message], ...]] = {
+    0: (),
+    1: (IntMessage, FloatMessage, StringMessage, BoolMessage),
+    2: (
+        IntMessage,
+        FloatMessage,
+        StringMessage,
+        BoolMessage,
+        DictMessage,
+        Array2DMessage,
+        GenericMessage,
+        PolarsDataFrameMessage,
+    ),
+}

desdeo/tools/ng_solver_interfaces.py

@@ -0,0 +1,199 @@
+"""Solver interfaces to the optimization routines found in nevergrad.
+
+For more info, see https://facebookresearch.github.io/nevergrad/index.html
+"""
+
+from concurrent.futures import ThreadPoolExecutor
+from typing import Literal
+
+import nevergrad as ng
+from pydantic import BaseModel, Field
+
+from desdeo.problem import Problem, SympyEvaluator
+from desdeo.tools.generics import BaseSolver, SolverResults
+
+available_nevergrad_optimizers = [
+    "NGOpt",
+    "TwoPointsDE",
+    "PortfolioDiscreteOnePlusOne",
+    "OnePlusOne",
+    "CMA",
+    "TBPSA",
+    "PSO",
+    "ScrHammersleySearchPlusMiddlePoint",
+    "RandomSearch",
+]
+
+
+class NevergradGenericOptions(BaseModel):
+    """Defines options to be passed to nevergrad's optimization routines."""
+
+    budget: int = Field(description="The maximum number of allowed function evaluations.", default=100)
+    """The maximum number of allowed function evaluations. Defaults to 100."""
+
+    num_workers: int = Field(description="The maximum number of allowed parallel evaluations.", default=1)
+    """The maximum number of allowed parallel evaluations. This is currently
+    used to define the batch size when evaluating problems. Defaults to 1."""
+
+    optimizer: Literal[*available_nevergrad_optimizers] = Field(
+        description=(
+            "The optimizer to be used. Must be one of `NGOpt`, `TwoPointDE`, `PortfolioDiscreteOnePlusOne`, "
+            "`OnePlusOne`, `CMA`, `TBPSA`, `PSO`, `ScrHammersleySearchPlusMiddlePoint`, or `RandomSearch`. "
+            "Defaults to `NGOpt`."
+        ),
+        default="NGOpt",
+    )
+    """The optimizer to be used. Must be one of `NGOpt`, `TwoPointsDE`, `PortfolioDiscreteOnePlusOne`,
+    `OnePlusOne`, `CMA`, `TBPSA`, `PSO`, `ScrHammersleySearchPlusMiddlePoint`, or `RandomSearch`.
+    Defaults to `NGOpt`."""
+
+
+_default_nevergrad_generic_options = NevergradGenericOptions()
+"""The set of default options for nevergrad's NgOpt optimizer."""
+
+
+def parse_ng_results(results: dict, problem: Problem, evaluator: SympyEvaluator) -> SolverResults:
+    """Parses the optimization results returned by nevergrad solvers.
+
+    Args:
+        results (dict): the results. A dict with at least the keys
+            `recommendation`, which points to a parametrization returned by
+            nevergrad solvers, `message` with information about the optimization,
+            and `success` indicating whther a recommendation was found successfully
+        or not.
+        problem (Problem): the problem the results belong to.
+        evaluator (GenericEvaluator): the evaluator used to evaluate the problem.
+
+    Returns:
+        SolverResults: a pydantic dataclass withthe relevant optimization results.
+    """
+    optimal_variables = results["recommendation"].value
+    success = results["success"]
+    msg = results["message"]
+
+    results = evaluator.evaluate(optimal_variables)
+
+    optimal_objectives = {obj.symbol: results[obj.symbol] for obj in problem.objectives}
+
+    constraint_values = (
+        {con.symbol: results[con.symbol] for con in problem.constraints} if problem.constraints is not None else None
+    )
+    extra_func_values = (
+        {extra.symbol: results[extra.symbol] for extra in problem.extra_funcs}
+        if problem.extra_funcs is not None
+        else None
+    )
+    scalarization_values = (
+        {scal.symbol: results[scal.symbol] for scal in problem.scalarization_funcs}
+        if problem.scalarization_funcs is not None
+        else None
+    )
+
+    return SolverResults(
+        optimal_variables=optimal_variables,
+        optimal_objectives=optimal_objectives,
+        constraint_values=constraint_values,
+        extra_func_values=extra_func_values,
+        scalarization_values=scalarization_values,
+        success=success,
+        message=msg,
+    )
+
+
+class NevergradGenericSolver(BaseSolver):
+    """Creates a solver that utilizes optimizations routines found in the nevergrad library."""
+
+    def __init__(self, problem: Problem, options: NevergradGenericOptions | None = _default_nevergrad_generic_options):
+        """Creates a solver that utilizes optimizations routines found in the nevergrad library.
+
+        These solvers are best utilized for black-box, gradient free optimization with
+        computationally expensive function calls. Utilizing multiple workers is recommended
+        (see `NevergradGenericOptions`) when function calls are heavily I/O bound.
+
+        See https://facebookresearch.github.io/nevergrad/getting_started.html for further information
+        on nevergrad and its solvers.
+
+        References:
+            Rapin, J., & Teytaud, O. (2018). Nevergrad - A gradient-free
+                optimization platform. GitHub.
+                https://GitHub.com/FacebookResearch/Nevergrad
+
+        Args:
+            problem (Problem): the problem to be solved.
+            options (NgOptOptions | None): options to be passes to the solver.
+                If none, `_default_ng_ngopt_options` are used. Defaults to None.
+
+        Returns:
+            Callable[[str], SolverResults]: returns a callable function that takes
+                as its argument one of the symbols defined for a function expression in
+                problem.
+        """
+        self.problem = problem
+        self.options = options if options is not None else _default_nevergrad_generic_options
+        self.evaluator = SympyEvaluator(problem)
+
+    def solve(self, target: str) -> SolverResults:
+        """Solve the problem for the given target.
+
+        Args:
+            target (str): the symbol of the objective function to be optimized.
+
+        Returns:
+            SolverResults: the results of the optimization.
+        """
+        parametrization = ng.p.Dict(
+            **{
+                var.symbol: ng.p.Scalar(
+                    # sets the initial value of the variables, if None, then the
+                    # mid-point of the lower and upper bounds is chosen as the
+                    # initial value.
+                    init=var.initial_value if var.initial_value is not None else (var.lowerbound + var.upperbound) / 2
+                ).set_bounds(var.lowerbound, var.upperbound)
+                for var in self.problem.variables
+            }
+        )
+
+        optimizer = ng.optimizers.registry[self.options.optimizer](
+            parametrization=parametrization, **self.options.model_dump(exclude="optimizer")
+        )
+
+        constraint_symbols = (
+            None if self.problem.constraints is None else [con.symbol for con in self.problem.constraints]
+        )
+
+        try:
+            if optimizer.num_workers == 1:
+                # single thread
+                recommendation = optimizer.minimize(
+                    lambda xs, t=target: self.evaluator.evaluate_target(xs, t),
+                    constraint_violation=[
+                        lambda xs, t=con_t: self.evaluator.evaluate_target(xs, t) for con_t in constraint_symbols
+                    ]
+                    if constraint_symbols is not None
+                    else None,
+                )
+
+            elif optimizer.num_workers > 1:
+                # multiple processors
+                with ThreadPoolExecutor(max_workers=optimizer.num_workers) as executor:
+                    recommendation = optimizer.minimize(
+                        lambda xs, t=target: self.evaluator.evaluate_target(xs, t),
+                        constraint_violation=[
+                            lambda xs, t=con_t: self.evaluator.evaluate_target(xs, t) for con_t in constraint_symbols
+                        ]
+                        if constraint_symbols is not None
+                        else None,
+                        executor=executor,
+                        batch_mode=False,
+                    )
+
+            msg = f"Recommendation found by {self.options.optimizer}."
+            success = True
+
+        except Exception as e:
+            msg = f"{self.options.optimizer} failed. Possible reason: {e}"
+            success = False
+
+        result = {"recommendation": recommendation, "message": msg, "success": success}
+
+        return parse_ng_results(result, self.problem, self.evaluator)

desdeo/tools/non_dominated_sorting.py

@@ -0,0 +1,133 @@
+"""This module contains functions for non-dominated sorting of solutions."""
+
+import numpy as np
+from numba import njit  # type: ignore
+
+
+@njit()
+def dominates(x: np.ndarray, y: np.ndarray) -> bool:
+    """Returns true if x dominates y.
+
+    Args:
+        x (np.ndarray): First solution. Should be a 1-D array of numerics.
+        y (np.ndarray): Second solution. Should be the same shape as x.
+
+    Returns:
+        bool: True if x dominates y, false otherwise.
+    """
+    dom = False
+    for i in range(len(x)):
+        if x[i] > y[i]:
+            return False
+        elif x[i] < y[i]:
+            dom = True
+    return dom
+
+
+@njit()
+def non_dominated(data: np.ndarray) -> np.ndarray:
+    """Finds the non-dominated front from a population of solutions.
+
+    Args:
+        data (np.ndarray): 2-D array of solutions, with each row being a single solution.
+
+    Returns:
+        np.ndarray: Boolean array of same length as number of solutions (rows). The value is
+            true if corresponding solution is non-dominated. False otherwise
+    """
+    num_solutions = len(data)
+    index = np.zeros(num_solutions, dtype=np.bool_)
+    index[0] = True
+    for i in range(1, num_solutions):
+        index[i] = True
+        for j in range(i):
+            if not index[j]:
+                continue
+            if dominates(data[i], data[j]):
+                index[j] = False
+            elif dominates(data[j], data[i]):
+                index[i] = False
+                break
+    return index
+
+
+@njit()
+def fast_non_dominated_sort(data: np.ndarray) -> np.ndarray:
+    """Conduct fast non-dominated sorting on a population of solutions.
+
+    Args:
+        data (np.ndarray): 2-D array of solutions, with each row being a single solution.
+
+    Returns:
+        np.ndarray: n x f boolean array. n is the number of solutions, f is the number of fronts.
+            The value of an array element is true if the corresponding solution id (column) belongs in
+            the corresponding front (row).
+    """
+    num_solutions = len(data)
+    indices = np.arange(num_solutions)
+    taken = np.zeros(num_solutions, dtype=np.bool_)
+    fronts = np.zeros((num_solutions, num_solutions), dtype=np.bool_)
+
+    for i in indices:
+        current_front = non_dominated(data[~taken])
+
+        current_front_all = np.zeros(num_solutions, dtype=np.bool_)
+        current_front_all[~taken] = current_front
+        fronts[i] = current_front_all
+
+        taken = taken + fronts[i]
+        if not fronts[i].any():
+            # if the current front is empty or if all the solutions have been sorted, stop
+            break
+    return fronts[:i]
+
+
+def fast_non_dominated_sort_indices(data: np.ndarray) -> list[np.ndarray]:
+    """Conduct fast non-dominated sorting on a population of solutions.
+
+    This function returns identical results as `fast_non_dominated_sort`, but in a different format.
+    This function returns an array of solution indices for each front, packed in a list.
+
+    Args:
+        data (np.ndarray): 2-D array of solutions, with each row being a single solution.
+
+    Returns:
+        list[np.ndarray]: A list with f elements where f is the number of fronts in the data,
+            arranged in ascending order. Each element is a numpy array of the indices of solutions
+            belonging to the corresponding front.
+    """
+    fronts = fast_non_dominated_sort(data)
+    return [np.where(fronts[i])[0] for i in range(len(fronts))]
+
+
+@njit()
+def non_dominated_merge(set1: np.ndarray, set2: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Merge two sets of non-dominated solutions.
+
+    This is a slightly more efficient way to merge two sets of solutions such that the resulting
+    set only contains non-dominated solutions from the two sets. This function assumes that the
+    two sets already only contain non-dominated solutions. I.e., each solution in each set is non-dominated
+    with respect to all other solutions in the same set. However, the solutions in the two sets may not be
+    non-dominated with respect to each other.
+
+    Args:
+        set1 (np.ndarray): 2-D array of solutions, with each row being a single solution.
+        set2 (np.ndarray): 2-D array of solutions, with each row being a single solution.
+
+    Returns:
+        tuple[np.ndarray, np.ndarray]: A tuple of two mask arrays. The first mask array is for set1 and the
+            second mask array is for set2. The value of an element in the mask array is True if the corresponding
+            solution is non-dominated in the merged set. False otherwise.
+    """
+    # Masks to keep track of which solutions are non-dominated. Default is all True.
+    set1_mask = np.ones(len(set1), dtype=np.bool_)
+    set2_mask = np.ones(len(set2), dtype=np.bool_)
+
+    for i in range(len(set1)):
+        for j in range(len(set2)):
+            if dominates(set1[i], set2[j]):
+                set2_mask[j] = False
+            elif dominates(set2[j], set1[i]):
+                set1_mask[i] = False
+
+    return set1_mask, set2_mask