luna-usecase-template 0.0.2a2__py3-none-any.whl

luna_usecase_template/__init__.py

@@ -0,0 +1,15 @@
+from .collection import UcInstanceCollection
+from .data import UcData
+from .formulation import UcFormulation
+from .instance import UcInstance
+from .registry import Registry
+from .solution import UcSolution
+
+__all__ = [
+    "Registry",
+    "UcData",
+    "UcFormulation",
+    "UcInstance",
+    "UcInstanceCollection",
+    "UcSolution",
+]

luna_usecase_template/base.py

@@ -0,0 +1,50 @@
+from pathlib import Path
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict
+
+
+class UcBaseModel(BaseModel):
+    """Use case base model with config."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    def store(self, path: Path | str) -> None:
+        """Store model to file.
+
+        Supported file types are `json` and `pkl`
+        """
+        if isinstance(path, str):
+            path = Path(path)
+
+        match path.suffix:
+            case ".json":
+                with open(path, "w") as f:
+                    f.write(self.model_dump_json())
+            case _:
+                msg = (
+                    f"Unsupported suffix '{path.suffix}'. "
+                    f"Only .json is supported as of now."
+                )
+                raise ValueError(msg)
+
+    @classmethod
+    def load(cls, path: Path | str) -> Self:
+        """Load model from file.
+
+        Supported file types are `json` and `pkl`
+        """
+        if isinstance(path, str):
+            path = Path(path)
+
+        match path.suffix:
+            case ".json":
+                with open(path) as f:
+                    return cls.model_validate_json(f.read())
+
+            case _:
+                msg = (
+                    f"Unsupported suffix '{path.suffix}'. "
+                    f"Only .json is supported as of now."
+                )
+                raise ValueError(msg)

luna_usecase_template/collection.py

@@ -0,0 +1,29 @@
+from typing import Self
+
+from pydantic import ModelWrapValidatorHandler, model_validator
+
+from .base import UcBaseModel
+from .instance import UcInstance
+
+
+class UcInstanceCollection[I: UcInstance](UcBaseModel):
+    """Instance collection base class."""
+
+    instances: list[I]
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def validate_instance(
+        cls, data: ..., handler: ModelWrapValidatorHandler[Self]
+    ) -> Self:
+        """Validate pydantic model."""
+        if cls.__name__ != "UcInstanceCollection":
+            return handler(data)
+
+        from .registry import Registry  # noqa: PLC0415
+
+        return Registry.collection_adapter(base_class=cls).validate_python(data)
+
+    @classmethod
+    def generate_predefined(cls) -> Self:
+        """Generate a predefined instance collection of the use case."""

luna_usecase_template/data.py

@@ -0,0 +1,31 @@
+from abc import abstractmethod
+from inspect import isabstract
+from typing import Self
+
+from pydantic import ModelWrapValidatorHandler, model_validator
+
+from .base import UcBaseModel
+from .named import Named
+
+
+class UcData(UcBaseModel, Named):
+    """Use Case data base class."""
+
+    data_name: str
+
+    @abstractmethod
+    def to_string(self) -> str:
+        """Return the model data definition."""
+        ...
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def validate_instance(
+        cls, data: ..., handler: ModelWrapValidatorHandler[Self]
+    ) -> Self:
+        """Validate pydantic model."""
+        if isabstract(cls):
+            from .registry import Registry  # noqa: PLC0415
+
+            return Registry.data_adapter(base_class=cls).validate_python(data)
+        return handler(data)

luna_usecase_template/formulation.py

@@ -0,0 +1,45 @@
+from abc import abstractmethod
+from inspect import isabstract
+from typing import Self
+
+from luna_model import Model, Solution
+from pydantic import ModelWrapValidatorHandler, model_validator
+
+from .base import UcBaseModel
+from .data import UcData
+from .named import Named
+from .solution import UcSolution
+
+
+class UcFormulation[D: UcData, S: UcSolution](UcBaseModel, Named):
+    """Use case formulation base class."""
+
+    @staticmethod
+    @abstractmethod
+    def to_string(data: D) -> str:
+        """Print the formulation."""
+        ...
+
+    @staticmethod
+    @abstractmethod
+    def formulate(data: D) -> Model:
+        """Formulate the use case as a concrete AqModel."""
+        ...
+
+    @staticmethod
+    @abstractmethod
+    def interpret(solution: Solution, data: D) -> S:
+        """Interpret the solution to the AqModel."""
+        ...
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def validate_instance(
+        cls, data: ..., handler: ModelWrapValidatorHandler[Self]
+    ) -> Self:
+        """Validate the pydantic model."""
+        if isabstract(cls):
+            from .registry import Registry  # noqa: PLC0415
+
+            return Registry.formulation_adapter(base_class=cls).validate_python(data)
+        return handler(data)

luna_usecase_template/instance.py

@@ -0,0 +1,52 @@
+from typing import Self
+
+from luna_model import Model, Solution
+from pydantic import ModelWrapValidatorHandler, model_validator
+
+from .base import UcBaseModel
+from .data import UcData
+from .formulation import UcFormulation
+from .solution import UcSolution
+
+
+class UcInstance[D: UcData, F: UcFormulation, S: UcSolution](UcBaseModel):
+    """Use case instance is the collection of the data and formulation."""
+
+    data: D
+    formulation: F
+
+    def to_string(self) -> str:
+        """Get a string representation of the instance."""
+        data_descr = "Data:"
+        data_descr += self.data.to_string()
+        form_descr = "Formulation:"
+        form_descr += self.formulation.to_string(self.data)
+        return f"{data_descr}\n{form_descr}"
+
+    @property
+    def name(self) -> str:
+        """Get name of the instance."""
+        return self.formulation.name + "<" + self.data.data_name + ">"
+
+    def formulate(self) -> Model:
+        """Formulate the instance as AqModel."""
+        model = self.formulation.formulate(self.data)
+        model.name = self.name
+        return model
+
+    def interpret(self, solution: Solution) -> S:
+        """Interpret the solution to the AqModel."""
+        return self.formulation.interpret(solution=solution, data=self.data)
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def validate_instance(
+        cls, data: ..., handler: ModelWrapValidatorHandler[Self]
+    ) -> Self:
+        """Validate the pydantic model."""
+        if cls.__name__ != "UcInstance":
+            return handler(data)
+
+        from .registry import Registry  # noqa: PLC0415
+
+        return Registry.instance_adapter(base_class=cls).validate_python(data)

luna_usecase_template/named.py

@@ -0,0 +1,19 @@
+from typing import Literal, get_args, get_origin
+
+
+class Named[N: str]:
+    """Named pydantic class mixin."""
+
+    name: N
+
+    @classmethod
+    def get_name(cls) -> str:
+        """Return the name of the class."""
+        name_type = cls.__dict__["__annotations__"]["name"]
+        if not (get_origin(name_type) is Literal and len(get_args(name_type)) == 1):
+            msg = (
+                f"Invalid `name` field in '{cls.__name__}'. "
+                "Required to be a Literal of a single string."
+            )
+            raise RuntimeError(msg)
+        return get_args(name_type)[0]

luna_usecase_template/registry.py

@@ -0,0 +1,219 @@
+import functools
+import importlib
+import inspect
+import pkgutil
+from collections.abc import Callable, Iterable
+from types import ModuleType
+from typing import ClassVar, Union
+
+from pydantic import TypeAdapter
+
+from .collection import UcInstanceCollection
+from .data import UcData
+from .formulation import UcFormulation
+from .instance import UcInstance
+from .solution import UcSolution
+
+
+def _check_concrete[T: type](f: Callable[[T], T]) -> Callable[[T], T]:
+    @functools.wraps(f)
+    def _inner(t: T) -> T:
+        if inspect.isabstract(t):
+            msg = (
+                f"Abstract class '{t.__name__}' detected. "
+                "Registry can only hold concrete models."
+            )
+
+            raise ValueError(msg)
+        return f(t)
+
+    return _inner
+
+
+def _generic_adapter(
+    types: Iterable[type], base_class: type | None = None
+) -> TypeAdapter:
+    if base_class is not None:
+        types = [t for t in types if issubclass(t, base_class)]
+    else:
+        types = list(types)
+    if len(types) == 0:
+        msg = "No suitable types registered."
+        raise ValueError(msg)
+    return TypeAdapter(Union[*types])
+
+
+class Registry:
+    """Registry of all use case classes."""
+
+    _instances: ClassVar[list[type[UcInstance]]] = []
+    _datas: ClassVar[list[type[UcData]]] = []
+    _formulations: ClassVar[list[type[UcFormulation]]] = []
+    _solutions: ClassVar[list[type[UcSolution]]] = []
+    _collections: ClassVar[list[type[UcInstanceCollection]]] = []
+    _registered: ClassVar[set[type]] = set()
+
+    @staticmethod
+    def adapter() -> TypeAdapter:
+        """Get the type adapter of all registered classes."""
+        types = (
+            Registry._instances
+            + Registry._datas
+            + Registry._formulations
+            + Registry._solutions
+            + Registry._collections
+        )
+        return TypeAdapter(Union[*types])
+
+    @staticmethod
+    def _check_registered[T: type](f: Callable[[T], T]) -> Callable[[T], T]:
+        @functools.wraps(f)
+        def _inner(t: T) -> T:
+            if t not in Registry._registered:
+                Registry._registered.add(t)
+                return f(t)
+            return t
+
+        return _inner
+
+    @staticmethod
+    def instance_adapter(base_class: None | type[UcInstance] = None) -> TypeAdapter:
+        """Get the type adapter of all registered instance classes."""
+        return _generic_adapter(Registry._instances, base_class)
+
+    @staticmethod
+    def data_adapter(base_class: None | type[UcData] = None) -> TypeAdapter:
+        """Get the type adapter of all registered data classes."""
+        return _generic_adapter(Registry._datas, base_class)
+
+    @staticmethod
+    def formulation_adapter(
+        base_class: None | type[UcFormulation] = None,
+    ) -> TypeAdapter:
+        """Get the type adapter of all registered formulation classes."""
+        return _generic_adapter(Registry._formulations, base_class)
+
+    @staticmethod
+    def solution_adapter(base_class: None | type[UcSolution] = None) -> TypeAdapter:
+        """Get the type adapter of all registered solution classes."""
+        return _generic_adapter(Registry._solutions, base_class)
+
+    @staticmethod
+    def collection_adapter(
+        base_class: None | type[UcInstanceCollection] = None,
+    ) -> TypeAdapter:
+        """Get the type adapter of all registered collection classes."""
+        return _generic_adapter(Registry._collections, base_class)
+
+    @staticmethod
+    @_check_registered
+    @_check_concrete
+    def add_instance[T: type[UcInstance]](instance: T) -> T:
+        """Register an instance class."""
+        Registry._instances.append(instance)
+        return instance
+
+    @staticmethod
+    @_check_registered
+    @_check_concrete
+    def add_data[T: type[UcData]](data: T) -> T:
+        """Register a data class."""
+        Registry._datas.append(data)
+        return data
+
+    @staticmethod
+    @_check_registered
+    @_check_concrete
+    def add_formulation[T: type[UcFormulation]](formulation: T) -> T:
+        """Register a formulation class."""
+        Registry._formulations.append(formulation)
+        return formulation
+
+    @staticmethod
+    @_check_registered
+    @_check_concrete
+    def add_solution[T: type[UcSolution]](solution: T) -> T:
+        """Register a solution class."""
+        Registry._solutions.append(solution)
+        return solution
+
+    @staticmethod
+    @_check_registered
+    @_check_concrete
+    def add_collection[T: type[UcInstanceCollection]](collection: T) -> T:
+        """Register a collection class."""
+        Registry._collections.append(collection)
+        return collection
+
+    @staticmethod
+    def add[T: type](input_class: T) -> T:
+        """Register any class."""
+        if issubclass(input_class, UcInstance):
+            Registry.add_instance(input_class)
+        elif issubclass(input_class, UcData):
+            Registry.add_data(input_class)
+        elif issubclass(input_class, UcFormulation):
+            Registry.add_formulation(input_class)
+        elif issubclass(input_class, UcSolution):
+            Registry.add_solution(input_class)
+        elif issubclass(input_class, UcInstanceCollection):
+            Registry.add_collection(input_class)
+        else:
+            msg = f"Attempted to register unknown type {input_class}."
+            raise TypeError(msg)
+        return input_class
+
+    @staticmethod
+    def can_register(input_class: type) -> bool:
+        """Check if a class can be registered."""
+        if input_class in Registry._registered or inspect.isabstract(input_class):
+            return False
+        if input_class.__name__ in ("UcInstance", "UcInstanceCollection"):
+            return False
+
+        return bool(
+            issubclass(input_class, UcInstance)
+            or issubclass(input_class, UcData)
+            or issubclass(input_class, UcFormulation)
+            or issubclass(input_class, UcSolution)
+            or issubclass(input_class, UcInstanceCollection)
+        )
+
+    @staticmethod
+    def add_module(mod: ModuleType) -> None:
+        """Add a whole module."""
+        for info in pkgutil.walk_packages(mod.__path__, prefix=f"{mod.__name__}."):
+            submod = importlib.import_module(info.name)  # nosemgrep: non-literal-import
+
+            for _, obj in inspect.getmembers(submod, inspect.isclass):
+                if Registry.can_register(obj):
+                    Registry.add(obj)
+
+    @staticmethod
+    def validate(s: ...) -> ...:
+        """Validate a python object."""
+        return Registry.adapter().validate_python(s)
+
+    @staticmethod
+    def validate_json(s: str | bytes | bytearray) -> ...:
+        """Validate a json string."""
+        return Registry.adapter().validate_json(s)
+
+    @staticmethod
+    def to_string() -> str:
+        """Return a string representation of the registry and contents."""
+        lines = [
+            "UcData: " + ", ".join(f"{t.__name__}" for t in Registry._datas),
+            "UcSolution: " + ", ".join(f"{t.__name__}" for t in Registry._solutions),
+            "UcInstance: " + ", ".join(f"{t.__name__}" for t in Registry._instances),
+            "UcFormulation: "
+            + ", ".join(f"{t.__name__}" for t in Registry._formulations),
+            "UcInstanceCollection: "
+            + ", ".join(f"{t.__name__}" for t in Registry._collections),
+        ]
+        return "\n".join(lines)
+
+    @staticmethod
+    def print() -> None:
+        """Print the registry and contents."""
+        print(Registry.to_string())  # noqa: T201

luna_usecase_template/solution.py

@@ -0,0 +1,38 @@
+from abc import abstractmethod
+from inspect import isabstract
+from typing import Protocol, Self, runtime_checkable
+
+from pydantic import ModelWrapValidatorHandler, model_validator
+
+from .base import UcBaseModel
+from .data import UcData
+from .named import Named
+
+
+class UcSolution(UcBaseModel, Named):
+    """Use case solution base class."""
+
+    @abstractmethod
+    def to_string(self) -> str:
+        """Print the solution."""
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def validate_solution(
+        cls, data: ..., handler: ModelWrapValidatorHandler[Self]
+    ) -> Self:
+        """Validate the pydantic model."""
+        if isabstract(cls):
+            from .registry import Registry  # noqa: PLC0415
+
+            return Registry.solution_adapter(base_class=cls).validate_python(data)
+        return handler(data)
+
+
+@runtime_checkable
+class Visulaizable[T: UcData](Protocol):
+    """Visualizable protocol."""
+
+    def visualize(self, data: T | None = None) -> None:
+        """Visualize the solution."""
+        ...

luna_usecase_template-0.0.2a2.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: luna-usecase-template
+Version: 0.0.2a2
+Summary: Template for optimization use cases.
+Keywords: aqarios,luna,quantum computing,quantum optimization,optimization,sdk
+Author: Aqarios GmbH
+Author-email: Aqarios GmbH <info@aqarios.com>
+License-Expression: Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: luna-model>=0.5.3
+Requires-Dist: pydantic>=2.12.5
+Maintainer: Maximilian Janetschek, David Bucher, Jonas Blenninger
+Maintainer-email: Maximilian Janetschek <maximilian.janetschek@aqarios.com>, David Bucher <david.bucher@aqarios.com>, Jonas Blenninger <jonas.blenninger@aqarios.com>
+Requires-Python: >=3.11.0
+Description-Content-Type: text/markdown
+
+# Use Case Library
+
+A Python SDK for defining optimization use cases in the [Luna](https://aqarios.com) quantum optimization framework.
+
+## Overview
+
+`usecase-lib` provides a structured template for defining optimization problems with:
+
+- **Data** — Problem input data (`UcData`)
+- **Formulation** — How the problem maps to a mathematical model (`UcFormulation`)
+- **Solution** — Interpretation of solver output (`UcSolution`)
+- **Instance** — A concrete pairing of data + formulation (`UcInstance`)
+- **Collection** — Groups of instances (`UcInstanceCollection`)
+
+All types support JSON serialization and polymorphic deserialization via a central `Registry`.
+
+## Requirements
+
+- Python >= 3.13.0
+
+## Quick Start
+
+### Define a use case
+
+```python
+from typing import Literal, override
+
+from luna_model import Model, Solution
+from usecase_lib import Registry, UcData, UcFormulation, UcInstance, UcSolution
+
+
+class MyData(UcData):
+    name: Literal["my_data"] = "my_data"
+    values: list[float]
+
+    @override
+    def to_string(self) -> str:
+        return str(self.values)
+
+
+class MySolution(UcSolution):
+    name: Literal["my_solution"] = "my_solution"
+    result: float
+
+    @override
+    def to_string(self) -> str:
+        return str(self.result)
+
+
+class MyFormulation(UcFormulation[MyData, MySolution]):
+    name: Literal["my_formulation"] = "my_formulation"
+
+    @override
+    @staticmethod
+    def to_string(data: MyData) -> str:
+        return "minimize sum(values)"
+
+    @override
+    @staticmethod
+    def formulate(data: MyData) -> Model:
+        m = Model("MyProblem")
+        # ... build your model ...
+        return m
+
+    @override
+    @staticmethod
+    def interpret(solution: Solution, data: MyData) -> MySolution:
+        return MySolution(result=0.0)
+
+
+class MyInstance(UcInstance):
+    data: MyData
+    formulation: MyFormulation
+```
+
+### Register and serialize
+
+```python
+# Register classes (also works as @Registry.add decorator)
+Registry.add(MyData)
+Registry.add(MySolution)
+Registry.add(MyFormulation)
+Registry.add(MyInstance)
+
+# Create and serialize
+data = MyData(data_name="example", values=[1.0, 2.0, 3.0])
+instance = MyInstance(data=data, formulation=MyFormulation())
+instance.store("instance.json")
+
+# Deserialize with polymorphic type dispatch
+loaded = MyInstance.load("instance.json")
+```
+
+## Architecture
+
+Every concrete `UcData`, `UcFormulation`, and `UcSolution` subclass must define a `name` field as a `Literal["unique_string"]`. This enables the `Registry` to distinguish types during deserialization.
+
+Abstract base classes use Pydantic wrap validators to automatically dispatch validation to the correct registered subclass, so you can deserialize from a base type without knowing the concrete type ahead of time.
+
+## Development
+
+```bash
+uv sync                # Install dependencies
+ruff check . --fix     # Lint with auto-fix
+ruff format .          # Format code
+uv build               # Build package
+```
+
+## License
+
+Apache-2.0

luna_usecase_template-0.0.2a2.dist-info/RECORD

@@ -0,0 +1,12 @@
+luna_usecase_template/__init__.py,sha256=FlETY5PXi0M255ShJn2oz76bns9rKu9G7a2beEulpsI,336
+luna_usecase_template/base.py,sha256=1IC08mmpBcAq-ANl1ggfoSoTQqSmSIZTaBqLFHscRu0,1397
+luna_usecase_template/collection.py,sha256=paC6cs6tg545_T3InPG1y73lxQl96azW55h4BLMcugw,831
+luna_usecase_template/data.py,sha256=tu1vUXO0HN9s695Hc29ZukND0wYGmIZDgnFQzA4WwQo,807
+luna_usecase_template/formulation.py,sha256=BZzPLcoOKgplkWD3fw8MD03_dXx5QH4KYZxL-oIIpA0,1250
+luna_usecase_template/instance.py,sha256=R3NYiFsirdq5wKK02W-tnQQWV9v3q-_JwImrQRYDypw,1683
+luna_usecase_template/named.py,sha256=qtQJD5tdNmILKCmc7sNneZKu-aIGRlndM5AWt5LAEkA,593
+luna_usecase_template/registry.py,sha256=cIHKhZaTHhGErmmw7ngvLZmBl2xihwY6tK21zUnmZy4,7506
+luna_usecase_template/solution.py,sha256=XI9pGB46sLaecMBFdpJTx6b4zOV0imls6nFYXBDRJ94,1033
+luna_usecase_template-0.0.2a2.dist-info/WHEEL,sha256=mydTeHxOpFHo-DnYhAd_3ATePms-g4rrYvM7wJK8P-U,80
+luna_usecase_template-0.0.2a2.dist-info/METADATA,sha256=9xfwux_zaArnxlet6EKugpPUhZ4T93JIwadHB72UKS0,3775
+luna_usecase_template-0.0.2a2.dist-info/RECORD,,

luna_usecase_template-0.0.2a2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.9
+Root-Is-Purelib: true
+Tag: py3-none-any