Metadata-Version: 2.4
Name: luna_usecases
Version: 0.1.0
Summary: A collection of optimization use cases for quantum and classical optimization
Keywords: optimization,quantum,qubo,ising,operations-research,combinatorial-optimization,benchmarks,luna,luna-quantum,scip
Author: Aqarios GmbH
Author-email: Aqarios GmbH <info@aqarios.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: ipykernel>=7.0.1
Requires-Dist: luna-model>=0.6.0
Requires-Dist: luna-quantum>=1.2.0
Requires-Dist: luna-usecase-template>=0.1.0
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: networkx>=3.6
Requires-Dist: notebook>=7.4.7
Requires-Dist: numpy>=2.4.6
Requires-Dist: pyscipopt>=6.2.1
Requires-Dist: yfinance>=1.3.0
Maintainer: Maximilian Janetschek, David Bucher, Daniel Porawski
Maintainer-email: Maximilian Janetschek <maximilian.janetschek@aqarios.com>, David Bucher <david.bucher@aqarios.com>, Daniel Porawski <daniel.porawski@aqarios.com>
Requires-Python: >=3.12.0, <3.15
Project-URL: Homepage, https://github.com/aqarios/luna-usecases
Project-URL: Repository, https://github.com/aqarios/luna-usecases
Project-URL: Documentation, https://aqarios.github.io/luna-usecases/
Project-URL: Issues, https://github.com/aqarios/luna-usecases/issues
Description-Content-Type: text/markdown

# 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](https://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](https://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](https://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

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

### Solve your first instance

```python
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](https://docs.aqarios.com).

---

**Built with ❤️ by the Aqarios Team**
