Fast, symbolic modeling for optimization — a high-performance Rust core with a Python-first API.
Build, translate, and transform optimization models.

About · Installation · Example · Documentation · Contributing

About

LunaModel is a high-performance symbolic modeling library for describing, translating, and transforming optimization problems. It provides Rust crates for model representation, translation, serialization, and transformation, with a Python-first API exposed through the luna-model package.

Use LunaModel when you need to build optimization models programmatically, convert between common model formats, or prepare models for solver- or platform-specific workflows. You can use it standalone, or through luna-quantum to solve your problems on the Luna Platform.

• Symbolic modeling — define algebraic expressions of arbitrary degree, constraints, and optimization models (in the spirit of dimod, Gurobi, or CPLEX).
• Translators — convert to and from LunaModel for many common formats, including LP, MPS, QUBO, BQM, CQM, and several solution result formats.
• Transformations — a compilation/transpilation stack to map a model into a target representation, e.g. CQM → BQM or integer → binary.
• Serialization — built-in, portable serialization for models and solutions.
• Python-first — an ergonomic Python API backed by a fast Rust core.
• Rust crates — use the workspace crates directly when embedding LunaModel in Rust.

Installation

Install the package from PyPI with uv:

uv add luna-model

or with pip:

pip install luna-model

The package is imported as luna_model:

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

Quick Example

The Multi-Dimensional Knapsack Problem: given $n$ items, each with a weight $w_{ij}$ and value $v_i$, dimension $J$ and a capacity $W_j$, select items to maximize total value without exceeding the capacity.

$$\begin{align*} &\text{maximize} \sum_{i=1}^{n} v_i x_i \\\ &\text{s.t.} \sum_{i=1}^{n} w_{ij} x_i \leq W_j \quad \forall j \in J \quad \text{and} \quad x_i \in \{ 0, 1 \} \end{align*}$$

from luna_model import Model, Sense, Vtype
from luna_model.utils import quicksum
import numpy as np

weights = np.array(
    [
        [1.5, 1],
        [10, 3],
        [5.2, 9],
        [3.5, 12],
        [8.32, 4],
    ]
)
values = np.array([10.0, 22.0, 3.2, 1.99, 6.25])
capacity = np.array([25, 19])

model = Model(sense=Sense.MAX, name="Knapsack")
items = [model.add_variable(f"x{i}", vtype=Vtype.BINARY) for i in range(len(weights))]

model.set_objective(quicksum(values[i] * items[i] for i in range(len(items))))
model.add_constraint(
    quicksum(weights[i, 0] * items[i] for i in range(len(items))) <= capacity[0],
    name="capacity_1",
)
model.add_constraint(
    quicksum(weights[i, 1] * items[i] for i in range(len(items))) <= capacity[1],
    name="capacity_2",
)

print(model)

The same model can be expressed far more concisely by leaning on NumPy: using add_variables and vectorized operations (weights.T @ items) lets you define the objective and all constraints in a few lines, without the explicit Python loops and per-element indexing of the first example.

model = Model(sense=Sense.MAX, name="Knapsack")
items = model.add_variables(name="x", shape=values.shape, vtype=Vtype.BINARY)
model.set_objective(quicksum(values * items))
model.add_constraints(weights.T @ items <= capacity, name="capacity")

print(model)

Variables are BINARY by default and can also be SPIN, INTEGER, or REAL. See the documentation for bounded variants, integer models, and more.

Components

Component	Description
LunaModel	A symbolic modeling library for arbitrary optimization models.
LunaModel.translator	A translation library that supports many common model formats.
LunaModel.transformation	A compilation and transpilation stack to transform a model (source) into a target representation (target).
LunaModel.utils	Utility functions for expression and model creation.
LunaModel.errors	All error types that can be raised within LunaModel.

Development

This repository is a Rust workspace with the Python package in py-lunamodel.

Prerequisites: Rust and Cargo, uv, and Python 3.11 or newer.

git clone https://github.com/aqarios/luna-model.git
cd luna-model

# set up the Python development environment
cd py-lunamodel
uv sync

Useful local checks:

# Python tests, linting, and formatting (from py-lunamodel)
uv run pytest
uv run ruff check .
uv run ruff format .

# Rust checks (from the repository root)
cargo test --workspace
cargo fmt --all

# build the Python wheel (from py-lunamodel)
uv build

To build the Rust API documentation locally:

cargo doc --workspace --no-deps

Documentation

The full documentation is published at docs.aqarios.com.

Communication

• Start in GitHub Discussions for bug reports, feature ideas, questions, and usage help. Maintainers triage discussions and turn confirmed, actionable items into issues — see CONTRIBUTING.md.
• Open a pull request when a change is ready for review. For anything beyond a small, obvious fix, make sure there is an accepted issue or an agreed direction in a discussion first.

Contributing

Bug fixes, documentation improvements, examples, and focused feature work are welcome. See CONTRIBUTING.md for branch naming, local checks, pull request expectations, and release notes.

License

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