luna-quantum 1.0.8rc2__cp311-cp311-macosx_11_0_arm64.whl → 1.0.8rc4__cp311-cp311-macosx_11_0_arm64.whl

luna_quantum/__init__.py

@@ -21,6 +21,9 @@ from luna_quantum.solve.usecases import (
     SolveJobFetchUpdatesUseCase,
     SolveJobGetResultUseCase,
 )
+from luna_quantum.solve.usecases.solve_job_get_by_id_usecase import (
+    SolveJobGetByIdUseCase,
+)
 from luna_quantum.util.debug_info import debug_info
 from luna_quantum.util.log_utils import Logging
 
@@ -29,12 +32,14 @@ from ._core import (
     Comparator,
     Constant,
     Constraint,
-    Constraints,
+    ConstraintCollection,
+    ConstraintType,
     Environment,
     Expression,
     ExpressionIterator,
     HigherOrder,
     Linear,
+    ModelSpecs,
     Quadratic,
     Result,
     ResultIterator,
@@ -56,8 +61,17 @@ from ._core import (
     translator,
     utils,
 )
+from ._utility import deprecated
 from .utils import quicksum
 
+
+@deprecated(
+    "`Constraints` class name is deprecated and will be removed, "
+    "use `ConstraintCollection` instead."
+)
+class Constraints(ConstraintCollection): ...  # noqa: D101 # comes from aq-models
+
+
 __version__ = __luna_quantum_version__
 UseCaseFactory.set_model_fetch_class(ModelFetchMetadataUseCase)
 UseCaseFactory.set_model_delete_class(ModelDeleteUseCase)
@@ -72,12 +86,15 @@ UseCaseFactory.set_solve_job_create_class(SolveJobCreateUseCase)
 UseCaseFactory.set_solve_job_delete_class(SolveJobDeleteUseCase)
 UseCaseFactory.set_solve_job_get_result_class(SolveJobGetResultUseCase)
 UseCaseFactory.set_solve_job_fetch_updates_class(SolveJobFetchUpdatesUseCase)
+UseCaseFactory.set_solve_job_get_id_class(SolveJobGetByIdUseCase)
 LunaSolveClientFactory.set_client_class(client_class=LunaSolve)
 __all__ = [
     "Bounds",
     "Comparator",
     "Constant",
     "Constraint",
+    "ConstraintCollection",
+    "ConstraintType",
     "Constraints",
     "DefaultToken",
     "Environment",
@@ -90,6 +107,7 @@ __all__ = [
     "LunaSolve",
     "LunaSolveClientFactory",
     "Model",
+    "ModelSpecs",
     "Quadratic",
     "Result",
     "ResultIterator",

luna_quantum/__init__.pyi

@@ -1,14 +1,17 @@
+from warnings import deprecated
 from ._core import (
     Bounds,
     Comparator,
     Constant,
     Constraint,
-    Constraints,
+    ConstraintCollection,
+    ConstraintType,
     Environment,
     Expression,
     ExpressionIterator,
     HigherOrder,
     Linear,
+    ModelSpecs,
     Quadratic,
     Result,
     ResultIterator,
@@ -23,6 +26,7 @@ from ._core import (
     Timing,
     Unbounded,
     Variable,
+    ValueSource,
     Vtype,
     errors,
     transformations,
@@ -39,12 +43,19 @@ from luna_quantum.solve.parameters import algorithms, backends, constants
 from luna_quantum.util.debug_info import debug_info
 from luna_quantum.util.log_utils import Logging
 
+@deprecated(
+    "`Constraints` class name is deprecated and will be removed, use `ConstraintCollection` instead."
+)
+class Constraints(ConstraintCollection): ...
+
 __version__ = __luna_quantum_version__
 __all__ = [
     "Bounds",
     "Comparator",
     "Constant",
     "Constraint",
+    "ConstraintCollection",
+    "ConstraintType",
     "Constraints",
     "DefaultToken",
     "Environment",
@@ -56,6 +67,7 @@ __all__ = [
     "LunaQ",
     "LunaSolve",
     "Model",
+    "ModelSpecs",
     "Quadratic",
     "Result",
     "ResultIterator",
@@ -69,6 +81,7 @@ __all__ = [
     "Timer",
     "Timing",
     "Unbounded",
+    "ValueSource",
     "Variable",
     "Vtype",
     "__version__",

luna_quantum/_core.pyi

@@ -5,10 +5,13 @@ from types import TracebackType
 from typing import Literal, Self, overload
 from numpy.typing import NDArray
 from . import errors, transformations, translator, utils
+from ._utility import deprecated
 from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
 from luna_quantum.solve.domain.model_metadata import ModelMetadata
 from luna_quantum.solve.domain.solve_job import SolveJob
 
+__version__ = ...
+
 class Vtype(Enum):
     """
     Enumeration of variable types supported by the optimization system.
@@ -963,6 +966,11 @@ class Solution:
         """Get the solver / algorithm runtime."""
         ...
 
+    @runtime.setter
+    def runtime(self, /, timing: Timing) -> None:
+        """Get the solver / algorithm runtime."""
+        ...
+
     @property
     def sense(self, /) -> Sense:
         """Get the optimization sense."""
@@ -1245,39 +1253,6 @@ class Solution:
         counts: int = ...,
         sense: Sense = ...,
     ) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dict(
-        data: dict[Variable, int | float],
-        *,
-        env: Environment = ...,
-        model: Model = ...,
-        timing: Timing = ...,
-        counts: int = ...,
-        sense: Sense = ...,
-    ) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dict(
-        data: dict[str, int | float],
-        *,
-        env: Environment = ...,
-        model: Model = ...,
-        timing: Timing = ...,
-        counts: int = ...,
-        sense: Sense = ...,
-    ) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dict(
-        data: dict[Variable | str, int | float],
-        *,
-        env: Environment = ...,
-        model: Model = ...,
-        timing: Timing = ...,
-        counts: int = ...,
-        sense: Sense = ...,
-    ) -> Solution: ...
     @staticmethod
     def from_dict(
         data: dict[Variable | str, int | float],
@@ -1400,39 +1375,6 @@ class Solution:
         counts: list[int] = ...,
         sense: Sense = ...,
     ) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dicts(
-        data: list[dict[Variable, int | float]],
-        *,
-        env: Environment = ...,
-        model: Model = ...,
-        timing: Timing = ...,
-        counts: list[int] = ...,
-        sense: Sense = ...,
-    ) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dicts(
-        data: list[dict[str, int | float]],
-        *,
-        env: Environment = ...,
-        model: Model = ...,
-        timing: Timing = ...,
-        counts: list[int] = ...,
-        sense: Sense = ...,
-    ) -> Solution: ...
-    @overload
-    @staticmethod
-    def from_dicts(
-        data: list[dict[Variable | str, int | float]],
-        *,
-        env: Environment = ...,
-        model: Model = ...,
-        timing: Timing = ...,
-        counts: list[int] = ...,
-        sense: Sense = ...,
-    ) -> Solution: ...
     @staticmethod
     def from_dicts(
         data: list[dict[Variable | str, int | float]],
@@ -2066,13 +2008,124 @@ class Sense(Enum):
     Max = ...
     """Indicate the objective function to be maximized."""
 
+class ConstraintType(Enum):
+    """
+    Enumeration of constraint types supported by the optimization system.
+
+    This enum defines the type of constraint used within a model.
+    """
+
+    Unconstrained = ...
+    """The model contains no constraints, i.e., is unconstrained."""
+    Equality = ...
+    """The model contains equality constraints (`Comparator.Eq`)."""
+    Inequality = ...
+    """The model contains inequality constraints (`Comparator.Le`, `Comparator.Ge`).
+
+    implicitly includes the `ConstraintType.LessEqual` and `ConstraintType.GreaterEqual`
+    options.
+    """
+    LessEqual = ...
+    """The model contains less-equal-inequality constraints (`Comparator.Le`)."""
+    GreaterEqual = ...
+    """The model contains greater-equal-inequality constraints (`Comparator.Ge`)."""
+
+class ModelSpecs:
+    """A class containing sepcifications of a model."""
+
+    def __init__(
+        self,
+        /,
+        *,
+        sense: (Sense | None) = ...,
+        vtypes: (list[Vtype] | None) = ...,
+        constraints: (list[ConstraintType] | None) = ...,
+        max_degree: (int | None) = ...,
+        max_constraint_degree: (int | None) = ...,
+        max_num_variables: (int | None) = ...,
+    ) -> None:
+        """Create a ModelSpec instance.
+
+        Parameters
+        ----------
+        sense: Sense | None
+            The exepected Sense of a model, default None.
+        vtypes: list[Vtype] | None
+            The exepected vtypes in a model, default None.
+        constraints: list[ConstraintType] | None = ...,
+            The exepected constraint types in a model, default None.
+        max_degree: int | None
+            The exepected maximum degree of the model's objective function,
+            default None.
+        max_constraint_degree: int | None
+            The exepected maximum degree of the model's constraints, default None.
+        max_num_variables: int | None
+            The exepected maximum number of the variables in the model, default None.
+        """
+        ...
+
+    @property
+    def sense(self) -> Sense | None:
+        """The sense specification, can be `None` if no sense spec is available."""
+        ...
+
+    @property
+    def max_degree(self) -> int | None:
+        """The specification for the max degree of the objective function.
+
+        Can be `None` if no max_degree spec is available.
+        """
+        ...
+
+    @property
+    def max_constraint_degree(self) -> int | None:
+        """The specification for the max degree of all constraints.
+
+        Can be `None` if no max_constraint_degree spec is available.
+        """
+        ...
+
+    @property
+    def max_num_variables(self) -> int | None:
+        """The specification for the max number of variables in the model.
+
+        Can be `None` if no max_num_variables spec is available.
+        """
+        ...
+
+    @property
+    def vtypes(self) -> list[Vtype] | None:
+        """The vtypes specification, can be `None` if no vtypes spec is available."""
+        ...
+
+    @property
+    def constraints(self) -> list[ConstraintType] | None:
+        """
+        The constraints specification.
+
+        Can be `None` if no constraints spec is available.
+        """
+        ...
+
+    def satisfies(self, other: ModelSpecs) -> bool:
+        """Check if `self` satisfies the model specs given in `other`.
+
+        Parameters
+        ----------
+        other : ModelSpecs
+            The model specifications `self` should satisfy.
+        """
+        ...
+
+    def __str__(self, /) -> str: ...
+
 class Model:
     """
     A symbolic optimization model consisting of an objective and constraints.
 
     The `Model` class represents a structured symbolic optimization problem. It
-    combines a scalar objective `Expression`, a collection of `Constraints`, and
-    a shared `Environment` that scopes all variables used in the model.
+    combines a scalar objective `Expression`, a collection of `ConstraintCollection`,
+    and a shared `Environment` that scopes all variables used in the model.
 
     Models can be constructed explicitly by passing an environment, or implicitly
     by allowing the model to create its own private environment. If constructed
@@ -2338,12 +2391,12 @@ class Model:
         ...
 
     @property
-    def constraints(self, /) -> Constraints:
+    def constraints(self, /) -> ConstraintCollection:
         """Access the set of constraints associated with the model."""
         ...
 
     @constraints.setter
-    def constraints(self, value: Constraints, /) -> None:
+    def constraints(self, value: ConstraintCollection, /) -> None:
         """Replace the model's constraints with a new set."""
         ...
 
@@ -2466,7 +2519,7 @@ class Model:
         """
         ...
 
-    def violated_constraints(self, /, sample: Sample) -> Constraints:
+    def violated_constraints(self, /, sample: Sample) -> ConstraintCollection:
         """
         Get all model constraints that are violated by the given sample.
 
@@ -2477,7 +2530,7 @@ class Model:
 
         Returns
         -------
-        Constraints
+        ConstraintCollection
             The constraints violated by the given sample.
         """
         ...
@@ -2513,6 +2566,21 @@ class Model:
             If the environments of `self`, `target`, and `replacement`
             are not compatible.
         """
+        ...
+
+    def get_specs(self) -> ModelSpecs:
+        """Get this model's specs."""
+        ...
+
+    def satisfies(self, specs: ModelSpecs) -> bool:
+        """Check if the model satisfies the given specs.
+
+        Parameters
+        ----------
+        specs : ModelSpecs
+            The sepcs this model's specs are compared to.
+        """
+        ...
 
     @overload
     def encode(self, /) -> bytes: ...
@@ -3934,30 +4002,46 @@ class Constraint:
     def __str__(self, /) -> str: ...
     def __repr__(self, /) -> str: ...
 
-class Constraints:
+class ConstraintCollectionIterator:
+    """
+    Iterate over the name, constraint tuples of a constraint collection.
+
+    Examples
+    --------
+    >>> from luna_quantum import ConstraintCollection
+    >>> coll: ConstraintCollection = ...
+    for (name, constraint) in coll.items():
+        ...
+    """
+
+    def __next__(self) -> tuple[str, Constraint]: ...
+    def __iter__(self) -> ConstraintCollectionIterator: ...
+
+class ConstraintCollection:
     """
     A collection of symbolic constraints used to define a model.
 
-    The `Constraints` object serves as a container for individual `Constraint`
+    The `ConstraintCollection` object serves as a container for individual `Constraint`
     instances. It supports adding constraints programmatically and exporting
     them for serialization.
 
-    Constraints are typically added using `add_constraint()` or the `+=` operator.
+    ConstraintCollection are typically added using `add_constraint()`
+    or the `+=` operator.
 
     Examples
     --------
-    >>> from luna_quantum import Constraints, Constraint, Environment, Variable
+    >>> from luna_quantum import ConstraintCollection, Constraint, Environment, Variable
     >>> with Environment():
     ...     x = Variable("x")
     ...     c = Constraint(x + 1, 0.0, Comparator.Le)
 
-    >>> cs = Constraints()
+    >>> cs = ConstraintCollection()
     >>> cs += x >= 1.0
 
     Serialization:
 
     >>> blob = cs.encode()
-    >>> expr = Constraints.decode(blob)
+    >>> expr = ConstraintCollection.decode(blob)
 
     Notes
     -----
@@ -3985,6 +4069,10 @@ class Constraints:
         """
         ...
 
+    def items(self, /) -> ConstraintCollectionIterator:
+        """Iterate over all items (`(name, constraint)`) in the collection."""
+        ...
+
     @overload
     def encode(self, /) -> bytes: ...
     @overload
@@ -4082,7 +4170,7 @@ class Constraints:
 
         Returns
         -------
-        Constraints
+        ConstraintCollection
             The updated collection.
 
         Raises
@@ -4094,6 +4182,9 @@ class Constraints:
 
     @overload
     def get(self, item: str, /) -> Constraint: ...
+    @deprecated(
+        "Constraint access using int will be removed, use name (str) based indexing instead."
+    )
     @overload
     def get(self, item: int, /) -> Constraint: ...
     def get(self, item: (int | str), /) -> Constraint:
@@ -4102,22 +4193,31 @@ class Constraints:
 
     @overload
     def remove(self, item: str, /) -> Constraint: ...
+    @deprecated(
+        "Constraint access using int will be removed, use name (str) based indexing instead."
+    )
     @overload
     def remove(self, item: int, /) -> Constraint: ...
     def remove(self, item: (int | str), /) -> Constraint:
         """Remove a constraint for its name or index."""
         ...
 
-    def __eq__(self, other: Constraints, /) -> bool: ...
+    def __eq__(self, other: ConstraintCollection, /) -> bool: ...
     def __str__(self, /) -> str: ...
     def __repr__(self, /) -> str: ...
     @overload
     def __getitem__(self, item: str, /) -> Constraint: ...
+    @deprecated(
+        "Constraint access using int will be removed, use name (str) based indexing instead."
+    )
     @overload
     def __getitem__(self, item: int, /) -> Constraint: ...
     def __getitem__(self, item: (int | str), /) -> Constraint: ...
     @overload
     def __setitem__(self, item: str, content: Constraint, /) -> None: ...
+    @deprecated(
+        "Constraint access using int will be removed, use name (str) based indexing instead."
+    )
     @overload
     def __setitem__(self, item: int, content: Constraint, /) -> None: ...
     def __setitem__(self, item: (int | str), content: Constraint, /) -> None: ...
@@ -4128,18 +4228,19 @@ class Constraints:
         Returns
         -------
         int
-            The number of constraints associated with this `Constraints` object.
+            The number of constraints associated with this `ConstraintCollection`
+            object.
         """
         ...
 
     def __iter__(self, /) -> Iterator[Constraint]: ...
-    def equal_contents(self, other: Constraints, /) -> bool:
+    def equal_contents(self, other: ConstraintCollection, /) -> bool:
         """
         Check whether this constraints has equal contents as `other`.
 
         Parameters
         ----------
-        other : Constraints
+        other : ConstraintCollection
 
         Returns
         -------
@@ -4158,7 +4259,7 @@ __all__ = [
     "Bounds",
     "Comparator",
     "Constraint",
-    "Constraints",
+    "ConstraintCollection",
     "Environment",
     "Expression",
     "Model",