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

desdeo/api/models/__init__.py

@@ -0,0 +1,266 @@
+"""Model exports."""
+
+__all__ = [  # noqa: RUF022
+    "Bounds",
+    "ConstantDB",
+    "ConstraintDB",
+    "CreateSessionRequest",
+    "DiscreteRepresentationDB",
+    "EMOSaveState",
+    "EMOSolveRequest",
+    "EMOIterateState",
+    "ENautilusRepresentativeSolutionsResponse",
+    "ENautilusState",
+    "ENautilusStateResponse",
+    "ENautilusStepRequest",
+    "ENautilusStepResponse",
+    "ExtraFunctionDB",
+    "ForestProblemMetaData",
+    "GenericIntermediateSolutionResponse",
+    "GetSessionRequest",
+    "GNIMBUSOptimizationState",
+    "GNIMBUSVotingState",
+    "GNIMBUSEndState",
+    "InteractiveSessionBase",
+    "InteractiveSessionDB",
+    "InteractiveSessionInfo",
+    "IntermediateSolutionRequest",
+    "IntermediateSolutionResponse",
+    "IntermediateSolutionState",
+    "NIMBUSClassificationRequest",
+    "NIMBUSClassificationState",
+    "NIMBUSDeleteSaveRequest",
+    "NIMBUSDeleteSaveResponse",
+    "NIMBUSInitializationRequest",
+    "NIMBUSInitializationState",
+    "NIMBUSIntermediateSolutionResponse",
+    "NIMBUSSaveRequest",
+    "NIMBUSClassificationResponse",
+    "NIMBUSInitializationResponse",
+    "NIMBUSSaveResponse",
+    "NIMBUSFinalizeRequest",
+    "NIMBUSFinalizeResponse",
+    "NIMBUSFinalState",
+    "NIMBUSSaveState",
+    "NonPreferredSolutions",
+    "ObjectiveDB",
+    "PreferenceBase",
+    "PreferenceDB",
+    "PreferredSolutions",
+    "PreferredRanges",
+    "ProblemDB",
+    "ProblemAddFromJSONRequest",
+    "ProblemGetRequest",
+    "ProblemInfo",
+    "ProblemInfoSmall",
+    "ProblemMetaDataDB",
+    "ProblemMetaDataGetRequest",
+    "ProblemSelectSolverRequest",
+    "ReferencePoint",
+    "RepresentativeNonDominatedSolutions",
+    "RPMSolveRequest",
+    "RPMState",
+    "SavedSolutionReference",
+    "ScalarizationFunctionDB",
+    "SimulatorDB",
+    "State",
+    "StateDB",
+    "SolutionInfo",
+    "TensorConstantDB",
+    "TensorVariableDB",
+    "User",
+    "UserBase",
+    "UserPublic",
+    "UserRole",
+    "VariableDB",
+    "ProblemMetaDataDB",
+    "BaseProblemMetaData",
+    "ForestProblemMetaData",
+    "Group",
+    "GroupModifyRequest",
+    "GroupCreateRequest",
+    "GroupRevertRequest",
+    "GroupIteration",
+    "GroupPublic",
+    "GroupInfoRequest",
+    "BaseGroupInfoContainer",
+    "ReferencePointDictType",
+    "BooleanDictTypeDecorator",
+    "EMOSolveRequest",
+    "PreferredRanges",
+    "PreferedSolutions",
+    "NonPreferredSolutions",
+    "EMOFetchRequest",
+    "EMOFetchResponse",
+    "EMOIterateRequest",
+    "EMOIterateResponse",
+    "EMOSaveRequest",
+    "EMOScoreRequest",
+    "EMOScoreResponse",
+    "Solution",
+    "SolutionReference",
+    "SolutionReferenceLite",
+    "SolutionReferenceResponse",
+    "SolverSelectionMetadata",
+    "UserSavedEMOResults",
+    "UserSavedSolutionDB",
+    "UtopiaRequest",
+    "UtopiaResponse",
+    "VariableDB",
+    "ScoreBandsRequest",
+    "ScoreBandsResponse",
+    "OptimizationPreference",
+    "VotingPreference",
+    "EndProcessPreference",
+    "GNIMBUSResultResponse",
+    "FullIteration",
+    "GNIMBUSAllIterationsResponse",
+    "GNIMBUSSwitchPhaseRequest",
+    "GNIMBUSSwitchPhaseResponse",
+    "GDMScoreBandsInitializationRequest",
+    "GDMSCOREBandInformation",
+    "GDMSCOREBandsResponse",
+    "GDMScoreBandsVoteRequest",
+    "GDMSCOREBandFinalSelection",
+    "GDMSCOREBandsDecisionResponse",
+    "GDMSCOREBandsRevertRequest",
+    "GDMSCOREBandsHistoryResponse",
+]
+
+
+from .archive import UserSavedEMOResults
+from .emo import (
+    EMOFetchRequest,
+    EMOFetchResponse,
+    EMOIterateRequest,
+    EMOIterateResponse,
+    EMOSaveRequest,
+    EMOScoreRequest,
+    EMOScoreResponse,
+    Solution,
+)
+from .enautilus import (
+    ENautilusRepresentativeSolutionsResponse,
+    ENautilusStateResponse,
+    ENautilusStepRequest,
+    ENautilusStepResponse,
+)
+from .gdm.gdm_aggregate import (
+    Group,
+    GroupCreateRequest,
+    GroupInfoRequest,
+    GroupIteration,
+    GroupModifyRequest,
+    GroupPublic,
+    GroupRevertRequest,
+)
+from .gdm.gdm_base import (
+    BaseGroupInfoContainer,
+    BooleanDictTypeDecorator,
+    ReferencePointDictType,
+)
+from .gdm.gdm_score_bands import (
+    GDMSCOREBandFinalSelection,
+    GDMSCOREBandInformation,
+    GDMSCOREBandsDecisionResponse,
+    GDMSCOREBandsHistoryResponse,
+    GDMScoreBandsInitializationRequest,
+    GDMSCOREBandsResponse,
+    GDMSCOREBandsRevertRequest,
+    GDMScoreBandsVoteRequest,
+)
+from .gdm.gnimbus import (
+    EndProcessPreference,
+    FullIteration,
+    GNIMBUSAllIterationsResponse,
+    GNIMBUSResultResponse,
+    GNIMBUSSwitchPhaseRequest,
+    GNIMBUSSwitchPhaseResponse,
+    OptimizationPreference,
+    VotingPreference,
+)
+from .generic import (
+    GenericIntermediateSolutionResponse,
+    IntermediateSolutionRequest,
+    ScoreBandsRequest,
+    ScoreBandsResponse,
+    SolutionInfo,
+)
+from .generic_states import (
+    SavedSolutionReference,
+    SolutionReference,
+    SolutionReferenceLite,
+    SolutionReferenceResponse,
+    State,
+    StateDB,
+    UserSavedSolutionDB,
+)
+from .nimbus import (
+    NIMBUSClassificationRequest,
+    NIMBUSClassificationResponse,
+    NIMBUSDeleteSaveRequest,
+    NIMBUSDeleteSaveResponse,
+    NIMBUSFinalizeRequest,
+    NIMBUSFinalizeResponse,
+    NIMBUSInitializationRequest,
+    NIMBUSInitializationResponse,
+    NIMBUSIntermediateSolutionResponse,
+    NIMBUSSaveRequest,
+    NIMBUSSaveResponse,
+)
+from .preference import (
+    Bounds,
+    NonPreferredSolutions,
+    PreferenceBase,
+    PreferenceDB,
+    PreferredRanges,
+    PreferredSolutions,
+    ReferencePoint,
+)
+from .problem import (
+    ConstantDB,
+    ConstraintDB,
+    DiscreteRepresentationDB,
+    ExtraFunctionDB,
+    ForestProblemMetaData,
+    ObjectiveDB,
+    ProblemAddFromJSONRequest,
+    ProblemDB,
+    ProblemGetRequest,
+    ProblemInfo,
+    ProblemInfoSmall,
+    ProblemMetaDataDB,
+    ProblemMetaDataGetRequest,
+    ProblemSelectSolverRequest,
+    RepresentativeNonDominatedSolutions,
+    ScalarizationFunctionDB,
+    SimulatorDB,
+    SolverSelectionMetadata,
+    TensorConstantDB,
+    TensorVariableDB,
+    VariableDB,
+)
+from .reference_point_method import RPMSolveRequest
+from .session import (
+    CreateSessionRequest,
+    GetSessionRequest,
+    InteractiveSessionBase,
+    InteractiveSessionDB,
+    InteractiveSessionInfo,
+)
+from .state import (
+    EMOIterateState,
+    EMOSaveState,
+    ENautilusState,
+    GNIMBUSEndState,
+    GNIMBUSOptimizationState,
+    GNIMBUSVotingState,
+    IntermediateSolutionState,
+    NIMBUSClassificationState,
+    NIMBUSFinalState,
+    NIMBUSInitializationState,
+    NIMBUSSaveState,
+    RPMState,
+)
+from .user import User, UserBase, UserPublic, UserRole
+from .utopia import UtopiaRequest, UtopiaResponse

desdeo/api/models/archive.py

@@ -0,0 +1,23 @@
+"""Defines models for archiving solutions."""
+
+from sqlmodel import Field
+
+from desdeo.tools.generics import EMOResult
+
+
+class UserSavedEMOResults(EMOResult):
+    """Defines a schema for storing emo solutions."""
+
+    name: str | None = Field(
+        description="An optional name for the solution, useful for archiving purposes.",
+        default=None,
+    )
+
+    def to_emo_results(self) -> EMOResult:
+        """Convert to SolverResults without the name field."""
+        return EMOResult(
+            optimal_variables=self.optimal_variables,
+            optimal_objectives=self.optimal_objectives,
+            constraint_values=self.constraint_values,
+            extra_func_values=self.extra_func_values,
+        )

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"