Skip to content

Archived LunaModel 0.5.9 documentation

You are reading the old LunaModel 0.5.9 documentation. The regular documentation describes LunaModel >=0.6.0; use the latest documentation unless you explicitly need the old release.

Core Concepts

This guide introduces the fundamental concepts you need to understand when working with LunaModel.

Overview

LunaModel is built around five core concepts:

  1. Models - Container for optimization problems
  2. Variables - Decision variables in your problem
  3. Expressions - Mathematical combinations of variables
  4. Constraints - Restrictions on valid solutions
  5. Objectives - What you're trying to optimize

Models

A Model is the central object in LunaModel. It represents a complete optimization problem and contains all variables, constraints, and the objective function.

Creating a Model

Python
from luna_model import Model

model = Model()

Model Properties

  • Variables: Collection of decision variables
  • Constraints: List of constraint expressions
  • Objective: The expression to minimize or maximize
  • Sense: Optimization direction (minimize or maximize)

Key Methods

Python
# Add variables
x = model.add_variable("x", vtype=Vtype.BINARY)

# Add constraints
model.add_constraint(x + y <= 5)

# Set objective
model.objective = 3*x + 2*y

# Query model
print(model.num_variables())
print(model.variables())

Variables

Variables represent the decision points in your optimization problem. Each variable has a name, type, and optional bounds.

Variable Types

LunaModel supports four variable types:

  • BINARY: Boolean variables (0 or 1)
  • INTEGER: Whole number variables
  • SPIN: Ising model variables (-1 or +1)
  • REAL: Continuous real-valued variables

Creating Variables

Python
from luna_model import Model, Vtype

model = Model()

# Binary variable
x = model.add_variable("x", vtype=Vtype.BINARY)

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

# Spin variable
s = model.add_variable("s", vtype=Vtype.SPIN)

# Real variable
r = model.add_variable("r", vtype=Vtype.REAL, lower=0.0, upper=1.0)

Variable Properties

Python
# Access variable properties
print(x.name)      # Variable name
print(x.vtype)     # Variable type
lower, upper = y.bounds  # Bounds as tuple
print(lower, upper)

Expressions

Expressions are mathematical combinations of variables and constants. They form the building blocks for objectives and constraints.

Expression Types

  • Linear: Sum of variables with coefficients
  • Quadratic: Products of two variables
  • Polynomial: Higher-order products

Creating Expressions

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

# Quadratic expression
quadratic = x*y + 2*x*x + y*y

# Mixed expression
mixed = 3*x + x*y + 2*y

# Complex polynomial
poly = x*y*z + x*x*y + 2*z

Expression Operations

Python
# Addition
expr1 = x + y
expr2 = 2*x + 3*y
combined = expr1 + expr2  # 3*x + 4*y

# Multiplication
scaled = 2 * expr1  # 2*x + 2*y

# Negation
negated = -expr1  # -x - y

# Evaluation
sample = {x.name: 1, y.name: 2}
value = expr1.evaluate(sample)  # Returns 3

Constraints

Constraints define feasibility conditions that valid solutions must satisfy.

Constraint Types

LunaModel supports three comparison operators:

  • Equality (==): Variable/expression must equal a value
  • Less than or equal (<=): Upper bound constraint
  • Greater than or equal (>=): Lower bound constraint

Creating Constraints

Python
# Equality constraint
model.add_constraint(x + y == 5)

# Inequality constraints
model.add_constraint(2*x + 3*y <= 10)
model.add_constraint(x - y >= 1)

# Quadratic constraint
model.add_constraint(x*x + y*y <= 25)

Constraint Properties

Python
# Access constraint components
for constraint in model.constraints():
    print(constraint.expression)  # Left-hand side
    print(constraint.sense)       # ==, <=, or >=
    print(constraint.rhs)         # Right-hand side value

Objectives

The objective defines what you're trying to optimize - minimize or maximize.

Setting Objectives

Python
# Minimize (default)
model.objective = x + y

# Or explicitly set sense
from luna_model import Sense
model.set_objective(x + y, sense=Sense.MIN)

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

Objective Types

  • Linear objective: 3*x + 2*y + 5
  • Quadratic objective: x*x + 2*x*y + y*y
  • Higher-order objective: x*y*z + x*x*y

Evaluating Objectives

Python
# Set objective
model.objective = 3*x + 2*y

# Evaluate for specific variable values
sample = {x.name: 1, y.name: 2}
value = model.objective.evaluate(sample)
print(value)  # 7

Model Structure

A complete model combines all these elements:

Python
from luna_model import Model, Vtype, Sense

# Create model
model = Model()

# Add variables
x = model.add_variable("x", vtype=Vtype.BINARY)
y = model.add_variable("y", vtype=Vtype.BINARY)
z = model.add_variable("z", vtype=Vtype.BINARY)

# Add constraints
model.add_constraint(x + y + z <= 2)
model.add_constraint(x + y >= 1)

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

# Inspect model
print(f"Variables: {model.num_variables()}")
print(f"Constraints: {model.num_constraints()}")
print(f"Objective sense: {model.sense}")

Type Conversions

LunaModel provides transformations to convert between variable types:

Python
from luna_model.transformation import PassManager
from luna_model.transformation.passes import BinarySpinPass

# Create model with mixed variable types
model = Model()
x = model.add_variable("x", vtype=Vtype.BINARY)
s = model.add_variable("s", vtype=Vtype.SPIN)

# Convert all to SPIN
pm = PassManager([BinarySpinPass(Vtype.SPIN, None)])
result = pm.run(model)
transformed_model = result.model

Performance Tips

  • Build expressions incrementally for large models
  • Reuse expressions when possible
  • Use appropriate variable types (BINARY vs INTEGER)

Next Steps

Now that you understand the core concepts, continue to: