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

desdeo/api/models/emo.py

@@ -0,0 +1,128 @@
+"""Models specific to the nimbus method."""
+
+from pydantic import ConfigDict
+from sqlmodel import JSON, Column, Field, SQLModel
+
+from desdeo.emo.options.templates import PreferenceOptions, TemplateOptions
+from desdeo.tools.score_bands import SCOREBandsConfig, SCOREBandsResult
+
+
+class EMOIterateRequest(SQLModel):
+    """Model of the request to iterate an EMO method."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    problem_id: int
+    """Database ID of the problem to solve."""
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+    """State ID of the parent state, if any. Should be None if this is the first state in a session."""
+
+    template_options: list[TemplateOptions] | None = Field(default=None)
+    """Options for the template to use. A list of options can be given if multiple templates are used in parallel."""
+    preference_options: PreferenceOptions | None = Field(default=None)
+    """Options for the preference handling."""
+
+
+class EMOFetchRequest(SQLModel):
+    """Model of the request to fetch solutions from an EMO method."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    problem_id: int
+    """Database ID of the problem to solve."""
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+    """State ID of the parent state, if any. Should be None if this is the first state in a session."""
+
+    num_solutions: int = Field(default=0)
+    """Number of solutions to fetch. If 0, fetch all solutions."""
+
+
+class EMOSaveRequest(SQLModel):
+    """Request model for saving solutions from any method's state."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    problem_id: int
+    """Database ID of the problem to solve."""
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+    """State ID of the parent state, if any. Should be None if this is the first state in a session."""
+
+    solution_ids: list[int] = Field()
+    """List of solution IDs to save."""
+    solution_names: list[str | None] | None = Field(default=None)
+    """List of names for the solutions to save. If None, no names are given."""
+
+
+class EMOScoreRequest(SQLModel):
+    """Request model for getting SCORE bands visualization data from state."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    problem_id: int
+    """Database ID of the problem to solve."""
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+    """State ID of the parent state, if any."""
+
+    config: SCOREBandsConfig | None = Field(default=None)
+    """Configuration for the SCORE bands visualization."""
+
+    solution_ids: list[int] = Field()
+    """List of solution IDs to score."""
+
+
+class EMOIterateResponse(SQLModel):
+    """Model of the response to an EMO iterate request."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    method_ids: list[str]
+    """IDs of the EMO methods using websockets to get/send updates."""
+    client_id: str
+    """Client ID to use when connecting to the websockets."""
+    state_id: int
+    """The state ID of the newly created state."""
+
+
+class Solution(SQLModel):
+    solution_id: int
+    """ID of the solution"""
+    objective_values: dict[str, list[float]]
+    """Values of the objectives. Each inner list corresponds to a solution."""
+    constraint_values: dict[str, list[float]] | None = None
+    """Values of the constraints. Each inner list corresponds to a solution."""
+    variable_values: dict[str, list[float | int | bool]]
+    """Values of the decision variables. Each inner list corresponds to a solution."""
+    extra_func_values: dict[str, list[float]] | None = None
+    """Values of the extra functions. Each inner list corresponds to a solution."""
+
+
+class EMOFetchResponse(SQLModel):
+    """Model of the response to an EMO fetch request."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    state_id: int
+    """The state ID of the newly created state."""
+    objective_values: dict[str, list[float]]
+    """Values of the objectives. Each inner list corresponds to a solution."""
+    constraint_values: dict[str, list[float]] | None = None
+    """Values of the constraints. Each inner list corresponds to a solution."""
+    variable_values: dict[str, list[float | int | bool]]
+    """Values of the decision variables. Each inner list corresponds to a solution."""
+    extra_func_values: dict[str, list[float]] | None = None
+    """Values of the extra functions. Each inner list corresponds to a solution."""
+
+
+class EMOScoreResponse(SQLModel):
+    """Model of the response to an EMO score request."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+    state_id: int | None = Field(default=None)
+    """The state ID of the newly created state."""
+
+    result: SCOREBandsResult

desdeo/api/models/enautilus.py

@@ -0,0 +1,69 @@
+"""Models specific to the E-NAUTILUS point method."""
+
+from sqlmodel import JSON, Column, Field, SQLModel
+
+from desdeo.tools import SolverResults
+
+
+class ENautilusStepRequest(SQLModel):
+    """Model of the request to the E-NAUTILUS method."""
+
+    problem_id: int
+    session_id: int | None = Field(default=None)
+    parent_state_id: int | None = Field(default=None)
+    # non_dominated points fetched from problem metadata in endpoints
+    representative_solutions_id: int = Field(description="The id of the representative solutions to be used.")
+
+    current_iteration: int = Field(description="The number of the current iteration.")
+    iterations_left: int = Field(description="The number of iterations left.")
+    selected_point: dict[str, float] | None = Field(
+        sa_column=Column(JSON),
+        description=(
+            "The selected intermediate point. If first iteration, set this to be the (approximated) nadir point. "
+            "If not set, then the point is assumed to be the nadir point of the current approximating set."
+        ),
+    )
+    reachable_point_indices: list[int] = Field(
+        description=(
+            "The indices indicating the point on the non-dominated set that are "
+            "reachable from the currently selected point."
+        )
+    )
+    number_of_intermediate_points: int = Field(description="The number of intermediate points to be generated.")
+
+
+class ENautilusStepResponse(SQLModel):
+    """The response from E-NAUTILUS step endpoint."""
+
+    state_id: int | None = Field(description="The id of the state created by the request that generated this response")
+
+    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(sa_column=Column(JSON), description="New intermediate points")
+    reachable_best_bounds: list[dict[str, float]] = Field(
+        sa_column=Column(JSON),
+        description="Best bounds of the objective function values reachable from each intermediate point.",
+    )
+    reachable_worst_bounds: list[dict[str, float]] = Field(
+        sa_column=Column(JSON),
+        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."
+    )
+
+
+class ENautilusStateResponse(SQLModel):
+    """The response model when requesting a state in E-NAUTILUS."""
+
+    request: ENautilusStepRequest = Field(description="The original request for generating the state.")
+    response: ENautilusStepResponse = Field(description="The state generated by the request.")
+
+
+class ENautilusRepresentativeSolutionsResponse(SQLModel):
+    """Model of the response when requesting representative solutions from E-NAUTILUS."""
+
+    solutions: list[SolverResults] = Field(
+        description="The solutions on the non-dominated front closest to the intermediate points."
+    )

desdeo/api/models/gdm/gdm_aggregate.py

@@ -0,0 +1,139 @@
+"""Classes for group decision making, aggregating all different types of data classes."""
+
+import json
+
+from sqlalchemy.types import TypeDecorator
+from sqlmodel import JSON, Column, Field, Relationship, SQLModel
+
+from desdeo.api.models.gdm.gdm_base import BaseGroupInfoContainer
+from desdeo.api.models.gdm.gdm_score_bands import GDMSCOREBandFinalSelection, GDMSCOREBandInformation
+from desdeo.api.models.gdm.gnimbus import EndProcessPreference, OptimizationPreference, VotingPreference
+from desdeo.tools import SolverResults
+
+
+class PreferenceType(TypeDecorator):
+    """A converter of Preference types."""
+
+    impl = JSON
+
+    # Serialize
+    def process_bind_param(self, value, dialect):
+        """Turns a preference item into json."""
+        if isinstance(value, BaseGroupInfoContainer):
+            return value.model_dump_json()
+        return None
+
+    # Deserialize
+    def process_result_value(self, value, dialect):
+        """And the other way around."""
+        jsoned = json.loads(value)
+        if jsoned is not None:
+            match jsoned["method"]:
+                case "voting":
+                    return VotingPreference.model_validate(jsoned)
+                case "optimization":
+                    return OptimizationPreference.model_validate(jsoned)
+                # As the different methods are implemented, add new types
+                case "end":
+                    return EndProcessPreference.model_validate(jsoned)
+                case "gdm-score-bands":
+                    return GDMSCOREBandInformation.model_validate(jsoned)
+                case "gdm-score-bands-final":
+                    return GDMSCOREBandFinalSelection.model_validate(jsoned)
+                case _:
+                    print(f"Unable to deserialize Preference with method {jsoned['method']}.")
+                    return None
+        return None
+
+
+class GroupBase(SQLModel):
+    """Base class for group table model and group response model."""
+
+
+class Group(GroupBase, table=True):
+    """Table model for Group."""
+
+    id: int | None = Field(primary_key=True, default=None)
+    name: str | None = Field(default=None)
+
+    owner_id: int | None = Field(foreign_key="user.id", default=None)
+    user_ids: list[int] | None = Field(sa_column=Column(JSON))
+
+    problem_id: int = Field(default=None)
+
+    """The id of the head GroupIteration."""
+    head_iteration_id: int | None
+
+
+class GroupPublic(GroupBase):
+    """Response model for Group."""
+
+    id: int
+    name: str
+    owner_id: int
+    user_ids: list[int]
+    problem_id: int
+
+
+class GroupIteration(SQLModel, table=True):
+    """Table model for Group Iteration (we could extend this in various ways)."""
+
+    id: int | None = Field(primary_key=True, default=None)
+    problem_id: int | None = Field(default=None)
+
+    """ID of the associated Group."""
+    group_id: int
+
+    """The preferences are stored in this item while the iteration is in progress."""
+    info_container: BaseGroupInfoContainer = Field(sa_column=Column(PreferenceType))
+    # NOTE: This used to be called "preferences" and the class used to be called "BasePreference"
+
+    notified: dict[int, bool] = Field(sa_column=Column(JSON))
+
+    """State for storing post optimization/voting related data (dec vars, objectives, etc.)"""
+    state_id: int | None = Field()
+
+    """Linked list emerges."""
+    parent_id: int | None = Field(foreign_key="groupiteration.id", default=None)
+    parent: "GroupIteration" = Relationship(
+        back_populates="children", sa_relationship_kwargs={"remote_side": "GroupIteration.id"}
+    )
+    # If parent is removed, remove the child too
+    children: list["GroupIteration"] = Relationship(
+        back_populates="parent", sa_relationship_kwargs={"cascade": "all, delete-orphan"}
+    )
+
+
+class GroupInfoRequest(SQLModel):
+    """Class for requesting group information."""
+
+    group_id: int
+
+class GroupRevertRequest(SQLModel):
+    """Class for requesting reverting to certain iteration."""
+
+    group_id: int = Field(description="The ID of the group we wish to revert.")
+    state_id: int = Field(
+        description="The state's ID to which we want to revert to. "\
+            "Corresponds to state_id in GroupIteration."
+    )
+
+
+class GroupResult(SQLModel):
+    """Class for group's result."""
+
+    solver_results: list[SolverResults]
+
+
+class GroupModifyRequest(SQLModel):
+    """Used for adding a user into group and removing a user from group."""
+
+    group_id: int
+    user_id: int
+
+
+class GroupCreateRequest(SQLModel):
+    """Used for requesting a group to be created."""
+
+    group_name: str
+    problem_id: int

desdeo/api/models/gdm/gdm_base.py

@@ -0,0 +1,69 @@
+"""Base classes for Group Decision Making. Here one can add some common data types for serialization."""
+
+import json
+
+from pydantic import ValidationError
+from sqlalchemy.types import TypeDecorator
+from sqlmodel import JSON, SQLModel
+
+from desdeo.api.models.preference import ReferencePoint
+
+
+class ReferencePointDictType(TypeDecorator):
+    """A converter for dict of int and preferences."""
+
+    impl = JSON
+
+    def process_bind_param(self, value, dialect):
+        """Turns a reference point dict into json."""
+        if isinstance(value, dict):
+            for key, item in value.items():
+                if isinstance(item, ReferencePoint):
+                    value[key] = item.model_dump_json()
+            return json.dumps(value)
+        return None
+
+    def process_result_value(self, value, dialect):
+        """And the other way around."""
+        dictionary = json.loads(value)
+        for key, item in dictionary.items():
+            if item is None:
+                print("Something's wrong... Database has a NoneType entry.")
+            try:
+                dictionary[key] = ReferencePoint.model_validate(json.loads(item))
+            except ValidationError as e:
+                print(f"Validation error when deserializing PreferencePoint: {e}")
+        return dictionary
+
+
+class BooleanDictTypeDecorator(TypeDecorator):
+    """A converter of bool into json, surprising that this needs to exists."""
+
+    impl = JSON
+
+    def process_bind_param(self, value, dialect):
+        """Turns boolean dict to json."""
+        if isinstance(value, dict):
+            for key, item in value.items():
+                if isinstance(item, bool):
+                    value[key] = json.dumps(item)
+            return json.dumps(value)
+        return None
+
+    def process_result_value(self, value, dialect):
+        """And the other way around."""
+        dictionary = json.loads(value)
+        for key, item in dictionary.items():
+            if item is None:
+                print("Something's wrong... Database has a NoneType entry.")
+            try:
+                dictionary[key] = bool(item)
+            except Exception as e:
+                print(f"Validation error when deserializing boolean: {e}")
+        return dictionary
+
+
+class BaseGroupInfoContainer(SQLModel):
+    """A base class for a method specific iteration information."""
+
+    method: str = "unset"

desdeo/api/models/gdm/gdm_score_bands.py

@@ -0,0 +1,114 @@
+"""Models for GDM Score Bands.
+
+Idea is that in the very first iteration, the filtered indices contains the clustering
+information on the entire data. Since on each iteration, the clustering is different,
+we need to include the indices over and over again. Of course with time the amount of
+indices will get smaller and smaller, and eventually be only ~10 solutions.
+
+The names of the classes can be renamed to fit the purpose better, currently they are
+more or less just the first thing that came to my mind.
+"""
+
+from sqlmodel import JSON, Column, Field, SQLModel
+
+from desdeo.api.models.gdm.gdm_base import BaseGroupInfoContainer
+from desdeo.gdm.score_bands import SCOREBandsGDMConfig, SCOREBandsGDMResult
+from desdeo.problem.schema import VariableType
+from desdeo.tools.score_bands import SCOREBandsResult
+
+
+class GDMSCOREBandInformation(BaseGroupInfoContainer):
+    """Class for containing info on which band was voted for."""
+    method: str = "gdm-score-bands"
+    user_votes: dict[str, int] = Field(
+        description="Dictionary of votes."
+    )
+    user_confirms: list[int] = Field(
+        description="List of users who want to move on."
+    )
+    score_bands_config: SCOREBandsGDMConfig = Field(
+        description="The configuration that led to this classification."
+    )
+    score_bands_result: SCOREBandsGDMResult = Field(
+        description="The results of the score bands."
+    )
+
+
+class GDMSCOREBandFinalSelection(BaseGroupInfoContainer):
+    """Class for containing the final 10 or less solutions, the final solution and the votes that led to it."""
+    method: str = "gdm-score-bands-final"
+    user_votes: dict[str, int] = Field(
+        description="Dictionary of votes."
+    )
+    user_confirms: list[int] = Field(
+        description="List of users who want to move on."
+    )
+
+    """The 10 or less solutions to choose from"""
+    solution_variables: dict[str, list[VariableType]] = Field(sa_column=Column(JSON))
+    solution_objectives: dict[str, list[float]] = Field(sa_column=Column(JSON))
+
+    """The selected (or generated??) of those 10 or less."""
+    winner_solution_variables: dict[str, VariableType] = Field(sa_column=Column(JSON))
+    winner_solution_objectives: dict[str, float] = Field(sa_column=Column(JSON))
+
+
+class GDMScoreBandsInitializationRequest(SQLModel):
+    """Request class for initialization of score bands."""
+    group_id: int = Field(
+        description="The group to be initialized."
+    )
+    score_bands_config: SCOREBandsGDMConfig = Field(
+        description="The configuration for the initial score banding."
+    )
+
+class GDMScoreBandsVoteRequest(SQLModel):
+    """Request for voting for a band."""
+    group_id: int = Field(
+        description="ID of the group in question"
+    )
+    vote: int = Field(
+        description="The vote. Vaalisalaisuus."
+    )
+
+class GDMSCOREBandsRevertRequest(SQLModel):
+    """Request for reverting to a previous setup."""
+    group_id: int = Field(
+        description="Group ID."
+    )
+    iteration_number: int = Field(
+        description="The number of the iteration that we want to revert to."
+    )
+
+class GDMSCOREBandsResponse(SQLModel):
+    """Response class for GDMSCOREBands, whether it is initialization or not."""
+    method: str = "gdm-score-bands"
+    group_id: int = Field(
+        description="The group in question."
+    )
+    group_iter_id: int = Field(
+        description="ID of the latest group iteration."
+    )
+    latest_iteration: int = Field(
+        description="The latest GDM iteration number. Different from Group Iteration id."
+    )
+    result: SCOREBandsResult = Field(
+        description="The results of the score bands procedure."
+    )
+
+class GDMSCOREBandsDecisionResponse(SQLModel):
+    """Response class for gdm score bands that includes the last 10 or less solutions."""
+    method: str = "gdm-score-bands-final"
+    group_id: int = Field(
+        description="The group in question."
+    )
+    group_iter_id: int = Field(
+        description="ID of the latest group iteration."
+    )
+    result: GDMSCOREBandFinalSelection = Field(
+        description="The container for the solutions and the winner solution."
+    )
+
+class GDMSCOREBandsHistoryResponse(SQLModel):
+    """Response class for all history. Allows for going to a previous iteration."""
+    history: list[GDMSCOREBandsResponse | GDMSCOREBandsDecisionResponse]

desdeo/api/models/gdm/gnimbus.py

@@ -0,0 +1,138 @@
+"""GNIMBUS specific data classes; REMEMBER to add SER/DES into aggregator!"""
+
+import json
+
+from pydantic import ValidationError
+from sqlmodel import JSON, Column, Field, SQLModel, TypeDecorator
+
+from desdeo.api.models.gdm.gdm_base import (
+    BaseGroupInfoContainer,
+    BooleanDictTypeDecorator,
+    ReferencePoint,
+    ReferencePointDictType,
+)
+from desdeo.api.models.generic_states import SolutionReference, SolutionReferenceLite
+from desdeo.tools import SolverResults
+
+
+class SolverResultType(TypeDecorator):
+    """Not sure why the solver results wouldn't serialize but this should do the trick."""
+
+    impl = JSON
+
+    def process_bind_param(self, value, dialect):
+        """Turns solver results into json."""
+        if isinstance(value, list):
+            solver_list = []
+            for item in value:
+                if isinstance(item, SolverResults):
+                    solver_list.append(item.model_dump_json())
+            return json.dumps(solver_list)
+        return None
+
+    def process_result_value(self, value, dialect):
+        """And back."""
+        if value is not None:
+            value_list = json.loads(value)
+            solver_list: SolverResults = []
+            for item in value_list:
+                item_dict = json.loads(item)
+                try:
+                    solver_list.append(SolverResults.model_validate(item_dict))
+                except ValidationError as e:
+                    print(f"Validation error when deserializing SolverResults: {e}")
+                    continue
+            return solver_list
+        return None
+
+
+class GNIMBUSSwitchPhaseRequest(SQLModel):
+    """A request for a certain phase. Comes from the group owner/analyst."""
+
+    group_id: int
+    new_phase: str
+
+
+class GNIMBUSSwitchPhaseResponse(SQLModel):
+    """A response for the above request."""
+
+    old_phase: str
+    new_phase: str
+
+
+class OptimizationPreference(BaseGroupInfoContainer):
+    """A structure for storing optimization preferences. See GNIMBUS for details."""
+
+    method: str = "optimization"
+    phase: str = Field(default="learning")
+    set_preferences: dict[int, ReferencePoint] = Field(sa_column=Column(ReferencePointDictType))
+
+
+class VotingPreference(BaseGroupInfoContainer):
+    """A structure for storing voting preferences."""
+
+    method: str = "voting"
+    set_preferences: dict[int, int] = Field(
+        sa_column=Column(JSON)
+    )  # A user votes for an index from the results (or something)
+
+
+class EndProcessPreference(BaseGroupInfoContainer):
+    """A structure for storing info on whether everyone is happy to end the gnimbus process."""
+
+    method: str = "end"
+    success: bool | None = Field()
+
+    # We check if everyone agrees to stop.
+    set_preferences: dict[int, bool] = Field(sa_column=Column(BooleanDictTypeDecorator))
+
+
+class GNIMBUSResultResponse(SQLModel):
+    """The response for getting GNIMBUS results. NOTE: OBSOLETE!"""
+
+    method: str
+    phase: str
+    preferences: VotingPreference | OptimizationPreference
+    common_results: list[SolutionReference]
+    user_results: list[SolutionReference]
+    personal_result_index: int | None
+
+
+class FullIteration(SQLModel):
+    """A full iteration item containing results from a complete or incomplete iteration.
+
+    This is a format to send information to the user interface.
+    """
+
+    phase: str = Field(
+        description="The phase of the iteration."
+    )
+    optimization_preferences: OptimizationPreference | None = Field(
+        description="The preferences related to the optimization stage of the full iteration."
+    )
+    voting_preferences: VotingPreference | EndProcessPreference | None = Field(
+        description="The preferences related to the voting phase of the iteration. \
+            either actual votes or a vote to see whether to just continue."
+    )
+    starting_result: SolutionReferenceLite | None = Field(
+        description="The starting result of the optimization process. Fetched from the previous \
+            iteration's final result."
+    )
+    common_results: list[SolutionReferenceLite] = Field(
+        description="The common results (1 to 4) generated by gnimbus."
+    )
+    user_results: list[SolutionReferenceLite] = Field(
+        description="The user specific results generated by gnimbus in phases learning and crp."
+    )
+    personal_result_index: int | None = Field(
+        description="The user result index of requester."
+    )
+    final_result: SolutionReferenceLite | None = Field(
+        description="The final result after voting."
+    )
+
+
+class GNIMBUSAllIterationsResponse(SQLModel):
+    """The response model for getting all found solutions among others."""
+
+    all_full_iterations: list[FullIteration]