Luna UseCase Template

A Python SDK for defining optimization use cases in the Luna quantum optimization framework.

⚠️ Under Active Development This project is under active development and has not yet reached a stable release (< 1.0.0). The API may change at any time. Minor version bumps (e.g. 0.1.0 → 0.2.0) may include breaking changes.

Overview

luna-usecase-template 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.11.0

Quick Start

Define a use case

from typing import Literal, override

from luna_model import Model, Solution
from luna_usecase_template 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

# 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

uv sync                # Install dependencies
uv run ruff check . --fix     # Lint with auto-fix
uv run ruff format .          # Format code
uv build               # Build package

License

Apache-2.0