LunaUseCases

A collection of optimization use cases targeting the luna-quantum model/solver stack and built on the luna-usecase-template interface.

Each use case ships a standardized, well-tested implementation – the problem data model, a constraint-based formulation, benchmark generators, and tests – so researchers and practitioners can prototype and benchmark solvers in minutes instead of days.

Documentation: docs.aqarios.com

Overview

The library ships 45+ fully-implemented use cases spanning combinatorial, graph, finance, scheduling, machine-learning, and applied problems. Every use case is a self-contained subpackage that follows the same five-class contract:

All classes register themselves via luna_usecase_template.Registry, which powers serialization, discovery, and auto-generated documentation.

Available Use Cases

Combinatorial

Graph

Finance

Scheduling

Machine Learning

Other

For data formats, formulations, and runnable tutorials see docs.aqarios.com.

Package Structure

The installed luna_usecases package contains the importable use case subpackages only. Tutorial notebooks and the full API reference are published at docs.aqarios.com.

luna_usecases/
├── __init__.py     # Re-exports every use case subpackage
├── abstract/       # Re-exports of UcData / UcFormulation / … from luna_usecase_template
├── utils/          # Shared helpers: errors, plotting, hashing, numpy-pydantic
└── <usecase>/      # One subpackage per use case (see layout below)

Each use case subpackage follows the same six-file layout:

<usecase>/
├── __init__.py     # Public exports: <Name>{Data, Formulation, Instance, Solution, Collection}
├── data.py         # UcData subclass — pydantic-validated inputs
├── formulation.py  # UcFormulation — builds a luna_quantum Model
├── instance.py     # UcInstance — data + formulation bundle
├── solution.py     # UcSolution — interprets a luna_quantum Solution
└── collection.py   # UcInstanceCollection — benchmark generators

Quick Start

Requires Python >= 3.12

Install

pip install luna-usecases
# or, with uv
uv add luna-usecases

Solve your first instance

from luna_usecases.integer_knapsack_problem import IkpData, IkpFormulation, IkpInstance
from luna_quantum import algorithms

data = IkpData.generate_random(n_items=20, capacity=50, seed=42)
instance = IkpInstance(data=data, formulation=IkpFormulation())

model = instance.formulate()
result = algorithms.SCIP().run(model).result()
solution = instance.interpret(result)
print(solution.print())

Executable tutorials for every use case are available at docs.aqarios.com.

Built with ❤️ by the Aqarios Team