Skip to content

Installation

Requirements

  • Python 3.13 or higher
  • A Luna API key (set as LUNA_API_KEY environment variable)

Setup uv

We recommend using uv as a fast Python package manager. Install it for your platform:

terminal
brew install uv
terminal
curl -LsSf https://astral.sh/uv/install.sh | sh
terminal
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, verify it works:

uv --version

Install luna_usecases

terminal
uv add luna-usecases
terminal
pip install luna-usecases

The Use Case Library

The purpose of this library is to provide a collection of different optimization problems and use cases that can be used in a standardized way. Each use case is programmed against an abstract interface with consistent usage, making it easy to switch between problems.

Core Components

Every use case follows a consistent pattern with these components:

Component Description
Data Defines the problem instance (e.g., graph structure, weights, constraints). Includes factory methods like from_random() for generating test instances.
Formulation Translates the problem data into a mathematical optimization model. Builds constraints and objective functions using luna_quantum.
Solution A validated result structure containing the optimized decision to the problem.
Instance Combines Data + Formulation into a single object. Provides formulate() to build the model and interpret() to extract solutions.
Collection Generates sets of benchmark instances for testing and comparison across different problem sizes.

Pluggable Formulations

Different formulations can express the same optimization problem in different ways. This allows you to:

  • Compare formulation efficiency across solvers
  • Test alternative mathematical representations
  • Extend existing use cases with custom formulations

Tutorial Notebooks

Each pre-implemented use case includes a tutorial notebook that walks you through:

  1. Creating different data instances
  2. Building and inspecting the formulation
  3. Solving with various luna_quantum algorithms
  4. Interpreting and analyzing results
  5. Using collections for batch benchmarking

Next Steps