luna-usecases 0.1.0

A collection of optimization use cases for quantum and classical optimization

Luna Use Cases

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:

Class	Role
UcData	Pydantic-validated problem data (arrays, graphs, metadata).
UcFormulation	Builds a luna_quantum.Model from UcData.
UcInstance	Pairs data + formulation; exposes formulate() / interpret().
UcSolution	Interprets a luna_quantum.Solution into a problem-native view.
UcInstanceCollection	Benchmark generators that produce batches of UcInstance objects.

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

---

Available Use Cases

Combinatorial

Use Case	Module
Bin Packing Problem (BPP)	bin_packing_problem
Integer Knapsack Problem (IKP)	integer_knapsack_problem
Quadratic Knapsack	quadratic_knapsack
Set Cover	set_cover
Set Packing	set_packing
Set Partitioning	set_partitioning
Exact Cover	exact_cover
Subset Sum	subset_sum
Number Partitioning	number_partitioning
Cutting Stock	cutting_stock
Travelling Salesman Problem (TSP)	traveling_salesman_problem
Binary Paint Shop	binary_paint_shop
Binary Integer Linear Programming (BILP)	binary_integer_linear_programming
Uncapacitated Facility Location Problem (UFLP)	uncapacitated_facility_location_problem

Graph

Use Case	Module
MaxCut	maxcut
Max 2-SAT	max2sat
Max 3-SAT	max3sat
Graph Coloring	graph_coloring
Graph Partitioning	graph_partitioning
Graph Isomorphism	graph_isomorphism
Max Clique	max_clique
Max Independent Set	max_independent_set
Minimum Vertex Cover	minimum_vertex_cover
Hamiltonian Cycle	hamiltonian_cycle
Longest Path	longest_path
Minimal Spanning Tree	minimal_spanning_tree
Minimal Maximal Matching	minimal_maximal_matching
Subgraph Isomorphism	subgraph_isomorphism
Induced Subgraph Isomorphism	induced_subgraph_isomorphism
Largest Mapping of Weighted Common Subgraph (LMWCS)	largest_mapping_of_weighted_common_subgraph

Finance

Use Case	Module
Portfolio Optimization Problem (POP)	portfolio_optimization
Portfolio Optimization with Investment Bands	portfolio_optimization_with_investment_bands
Dynamic Portfolio Optimization	dynamic_portfolio_optimization
Arbitrage (Node-Based)	arbitrage_node_based
Arbitrage (Edge-Based)	arbitrage_edge_based

Scheduling

Use Case	Module
Production Assignment and Scheduling (PAS)	production_assignment_and_scheduling
Job Shop Scheduling Problem (JSSP)	job_shop_scheduling
Nurse Scheduling	nurse_scheduling
Flight Gate Assignment	flight_gate_assignment
Satellite Scheduling	satellite_scheduling
Container Assignment	container_assignment
Traffic Flow	traffic_flow

Machine Learning

Use Case	Module
K-Medoids Clustering	k_medoids_clustering
Market Graph Clustering	market_graph_clustering
Credit Scoring Feature Selection	credit_scoring_feature_selection

Other

Use Case	Module
Quadratic Assignment Problem (QAP)	quadratic_assignment_problem
Garden Optimization	garden_optimization
Sensor Position Problem (SPP)	sensor_position_problem
Sensor Placement	sensor_placement

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