Skip to content

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: