Skip to content
lunaᴹᴼᴰᴱᴸ

Welcome to LunaModel

High-performance symbolic modeling for optimization problems

LunaModel is a powerful Python library for defining, translating, and transforming optimization problems. Built with Rust for exceptional performance, it provides an intuitive Python API for creating symbolic mathematical models that can be solved using various optimization backends.

Why LunaModel?

  • High Performance: Rust-powered core for lightning-fast model operations
  • Expressive Syntax: Natural Python syntax for defining optimization models
  • Universal Translation: Convert between LP, QUBO, BQM, CQM, and other formats
  • Flexible Modeling: Support for expressions of arbitrary degree (linear, quadratic, and higher-order)
  • Extensible: Transform models between different representations
  • Portable: Built-in serialization for seamless model sharing

Quick Start

Installation

LunaModel can be installed with:

terminal
uv add luna-model
terminal
pip install luna-model
terminal
poetry add luna-model

Your First Model

Here's a simple example that demonstrates the core concepts:

Python
from luna_model import Model, Sense, Vtype
from luna_model.utils import quicksum

# Create a model
model = Model(name="Knapsack", sense=Sense.MAX)

# Define problem data
n_items = 5
max_weight = 25
weights = [1.5, 10.0, 5.2, 3.5, 8.32]
values = [10.0, 22.0, 3.2, 1.99, 6.25]

# Add binary variables (1 = take item, 0 = don't take)
items = [
    model.add_variable(f"item_{i}", vtype=Vtype.BINARY)
    for i in range(n_items)
]

# Set objective: maximize total value
model.objective = quicksum(values[i] * items[i] for i in range(n_items))

# Add constraint: don't exceed weight limit
model.constraints += quicksum(weights[i] * items[i] for i in range(n_items)) <= max_weight

print(model)

That's it! You've created your first optimization model.

Core Concepts

LunaModel is built around four fundamental concepts:

Variables

Decision variables represent unknowns that the optimizer will determine.

Python
# Binary variable (0 or 1)
x = model.add_variable("x", vtype=Vtype.BINARY)

# Integer variable with bounds
y = model.add_variable("y", vtype=Vtype.INTEGER, lower=0, upper=10)

# Continuous variable
z = model.add_variable("z", vtype=Vtype.REAL, lower=-1.5, upper=1.5)

# Spin variable (-1 or +1)
s = model.add_variable("s", vtype=Vtype.SPIN)

Expressions

Mathematical combinations of variables and constants.

Python
# Linear: 3x + 2y + 5
linear = 3 * x + 2 * y + 5

# Quadratic: x*y + 2x²
quadratic = x * y + 2 * x * x

# Higher-order: x*y*z (LunaModel supports arbitrary degree!)
higher_order = x * y * z

Constraints

Restrictions that valid solutions must satisfy.

Python
# Inequality constraints
model.constraints += x + y <= 5
model.constraints += 2 * x - y >= 1

# Equality constraint
model.constraints += x + y == 3

Objectives

The goal of your optimization (what to minimize or maximize).

Python
# Minimize (default)
model.set_objective(x + y, sense=Sense.MIN)

# Maximize
model.set_objective(3 * x + 2 * y, sense=Sense.MAX)

Documentation Structure

Getting Started

Everything you need to get up and running with LunaModel:

  • Installation instructions
  • Your first optimization model
  • Quick reference guide

User Guide

Comprehensive guides for building optimization models:

Translators

Convert models between different optimization formats:

Transformations

Transform models between different representations:

API Reference

Complete API documentation for all classes and functions:

Key Features

Multiple Variable Types

LunaModel supports four variable types to match your problem domain:

Type Values Use Case
Vtype.BINARY 0 or 1 Yes/no decisions, selection problems
Vtype.SPIN -1 or +1 Ising models, quantum optimization
Vtype.INTEGER ..., -1, 0, 1, ... Counting, discrete quantities
Vtype.REAL Real numbers Continuous optimization

Universal Model Translation

Seamlessly convert between different optimization formats:

Python
from pathlib import Path
from luna_model.translator import LpTranslator

lp_filepath = Path("path/to/your/model.lp")
model = LpTranslator.to_lm(lp_filepath)
Python
from luna_model.translator import LpTranslator

lp_filestr = "..."
model = LpTranslator.to_lm(lp_filestr)
Python
from luna_model.translator import QuboTranslator
import numpy as np

qubo = np.array([[-2, 1], [0, -1]])
model = QuboTranslator.to_lm(qubo)
Python
from luna_model.translator import BqmTranslator
from dimod import BinaryQuadraticModel

bqm = BinaryQuadraticModel({"x": -1, "y": 2}, {("x", "y"): 1}, 0.5, "BINARY")
model = BqmTranslator.to_lm(bqm, name="example")

This translator requires luna-model to be installed with the dimod extra.

Python
from luna_model.translator import CqmTranslator
from dimod import ConstrainedQuadraticModel, Binary, Integer

cqm = ConstrainedQuadraticModel()
x = Binary("x")
y = Integer("y", lower_bound=0, upper_bound=10)
cqm.set_objective(x + 2 * y)
cqm.add_constraint(x + y >= 3, label="min_sum")

model = CqmTranslator.to_lm(cqm, name="example")

This translator requires luna-model to be installed with the dimod extra.

Solution Handling

Work with optimization results from any solver:

Python
from luna_model import Solution, Environment, Variable

env = Environment()
with env:
    _ = Variable("x")
    _ = Variable("y")

# Create solution from solver results
solution = Solution(
    samples=[{"x": 1, "y": 0}],
    obj_values=[3.0],
    feasible=[True],
    env=env,
)

# Access solution data
print(f"Best solution: {solution.best()}")
print(f"Objective value: {solution.obj_values[0]}")

Integration with Luna Platform

LunaModel integrates seamlessly with the Luna Platform through luna-quantum:

terminal
pip install luna-quantum

This gives you access to powerful optimization solvers and quantum computing resources to solve your models.

Common Use Cases

Optimize item selection with constraints:

Python
# Maximize value subject to weight constraints
model.objective = quicksum(values[i] * items[i] for i in range(n))
model.constraints += quicksum(weights[i] * items[i] for i in range(n)) <= max_weight

Assign tasks to resources optimally:

Python
# Each task to exactly one worker
for i in range(n_tasks):
    model.constraints += quicksum(assignment[i][j] for j in range(n_workers)) == 1

Optimize manufacturing schedules:

Python
# Maximize profit subject to resource constraints
model.objective = quicksum(profit[p] * production[p] for p in products)
model.constraints += quicksum(labor[p] * production[p] for p in products) <= labor_available

Plan optimal routes for deliveries:

Python
# Minimize distance while visiting all locations
model.objective = quicksum(distance[i][j] * route[i][j] for i, j in edges)

Performance Tips

  • Use quicksum() instead of Python's sum() for large expressions
  • Set appropriate bounds on INTEGER and REAL variables
  • Use the right variable type - BINARY is more efficient than INTEGER with bounds [0, 1]
  • Build expressions incrementally for large models
  • Leverage transformations to convert to solver-native formats

Getting Help

License

LunaModel is licensed under the Apache License 2.0. See LICENSE for details.

What's Next?

Ready to dive deeper? Here are some suggested paths:

  1. New to optimization modeling? Start with Getting Started
  2. Want to understand the fundamentals? Read Core Concepts
  3. Ready to build models? Try Modeling Basics
  4. Need to convert models? Check out Model Translators
  5. Looking for reference docs? Browse the API Reference