Transformations API Reference

Manage and execute a sequence of passes on a model.

The PassManager implements a compiler-style pass pattern, enabling both general-purpose and algorithm-specific manipulations of optimization models. Each pass is an atomic operation that transforms the model or extracts information from the model. The PassManager runs each pass in order and produces an IR that records the transformations applied and supports back-transformations.

Parameters:

• passes (Sequence[BasePass], default: None ) –

  An ordered sequence of Pass instances to apply, default None.

Intermediate representation of a transformed model.

The IR contains the resulting model after transformation along with the analysis cache and execution log generated during execution of the PassManager.

Bases: PyPipeline, PipelineProto, BasePass

A pipeline for executing multiple transformation passes in sequence.

Pipelines organize and execute multiple passes, managing dependencies and ensuring they run in the correct order.

Parameters:

• passes (list[BasePass]) –

  The transformation passes to include in the pipeline.

• name (str, default: None ) –

  A custom name for the pipeline. If not provided, a default name will be generated.

Bases: PyTransformationPass, BasePass

Base class for transformation passes that modify models.

Transformation passes apply changes to models and can also convert solutions backwards to match the input representation.

Bases: PyAnalysisPass, BasePass, Generic[T]

Base class for analysis passes that compute information about models.

Analysis passes inspect models and compute results without modifying them. They can depend on other analysis passes and cache their results for efficient access in subsequent passes.

Convert a model to an unconstrained binary model.

This pipeline transforms any model with constraints to an unconstrained binary model. It allows the input model to contain binary, spin or integer variables. Spin and integer variables are automatically converted to a binary representation. If the input model has linear constraints they are added to the model's objective as quadratic penalties scaled by the the maximum bias of the input model's objective times the penalty_scaling paramter.

Raises:

• AnalysisPassError –

  If the model's constraints are not all linear.

Bases: ConcreteTransformationPass

Convert between Binary and Spin variable types.

Transform the variables of type binary to spin typed variables or vice versa. Target vtype is set by the vtype parameter.

Parameters:

• vtype (Literal[BINARY, SPIN]) –

  The target vtype to convert the variables to. If set to Vtype.SPIN all binary variables in the model are converted to spin variables. If set to Vtype.BINARY all spin variables are converted to binary variables.

• prefix (str, default: None ) –

  An optional prefix to prepend to the name of the new variables created. If none specified a default prefix is used.

Examples:

>>> from luna_model import Model, Vtype
>>> from luna_model.transformation import PassManager
>>> from luna_model.transformation.passes import BinarySpinPass
>>> model = Model()
>>> x = model.add_variable("x", vtype=Vtype.BINARY)
>>> y = model.add_variable("y", vtype=Vtype.BINARY)
>>> model.objective = x * y + x - 2 * y
>>> pm = PassManager([BinarySpinPass(vtype=Vtype.SPIN)])
>>> ir = pm.run(model)
>>> spin_model = ir.model

Bases: ConcreteTransformationPass

Change the optimization sense between minimization and maximization.

Converts the optimization sense by negating the objective function.

Parameters:

• sense (Sense) –

  The target sense to convert the optimization sense to.

Examples:

>>> from luna_model import Model, Vtype, Sense
>>> from luna_model.transformation import PassManager
>>> from luna_model.transformation.passes import ChangeSensePass
>>> model = Model(sense=Sense.MAX)
>>> x = model.add_variable("x", vtype=Vtype.BINARY)
>>> y = model.add_variable("y", vtype=Vtype.BINARY)
>>> model.objective = x * y + x - 2 * y
>>> pm = PassManager([ChangeSensePass(Sense.MIN)])
>>> ir = pm.run(model)
>>> min_model = ir.model

Bases: ConcreteAnalysisPass

Analysis pass that computes the maximum absolute coefficient value in the objective.

Examples:

>>> from luna_model import Model, Vtype
>>> from luna_model.transformation import PassManager
>>> from luna_model.transformation.passes import MaxBiasAnalysis
>>> model = Model()
>>> x = model.add_variable("x", vtype=Vtype.BINARY)
>>> y = model.add_variable("y", vtype=Vtype.BINARY)
>>> model.objective = x * y + x - 2 * y
>>> pm = PassManager([MaxBiasAnalysis()])
>>> ir = pm.run(model)
>>> ir.cache["max-bias"].val
2.0

Bases: ConcreteAnalysisPass

Analysis pass that checks the model's specs for correctness.

This analysis pass checks if the input model satisfies the specifications (ModelSpecs) this pass is initilized with. If the specs are not satified by the model it raises an error during runtime.

Examples:

>>> from luna_model import Model, Vtype
>>> from luna_model.transformation import PassManager
>>> from luna_model.transformation.passes import CheckModelSpecsAnalysis
>>> model = Model()
>>> x = model.add_variable("x", vtype=Vtype.BINARY)
>>> y = model.add_variable("y", vtype=Vtype.BINARY)
>>> model.objective = x * y + x - 2 * y
>>> specs = ModelSpecs(max_degree=2)
>>> pm = PassManager([CheckModelSpecsAnalysis(specs)])
>>> ir = pm.run(model)
>>> # no errors raised

Bases: ConcreteAnalysisPass

Analysis pass that computes the min value possible for all constraints.

This analysis pass computes the minimal value possible for all constraints of the input model.

Examples:

>>> from luna_model import Model, Vtype
>>> from luna_model.transformation import PassManager
>>> from luna_model.transformation.passes import CheckModelSpecsAnalysis
>>> model = Model()
>>> x = model.add_variable("x", vtype=Vtype.BINARY)
>>> y = model.add_variable("y", vtype=Vtype.BINARY)
>>> model.objective = x * y + x - 2 * y
>>> model.constraints += -5 * x + y <= 2, "my-constraint"
>>> pm = PassManager([MinValueForConstraintAnalysis()])
>>> ir = pm.run(model)
>>> ir.cache["min-value-for-constraint"].vals
{'my-constraint': -5.0}

Bases: ConcreteAnalysisPass

Analysis pass that computes the model's specs and stores them in the cache.

This analysis pass computes the ModelSpecs of the input model and writes it to the AnalysisCache to be used by transformation passes following it during the PassManager execution. This analysis pass can, for example, be used in combination with the IfElsePass to guide the transformation depending on the specifications (ModelSpecs) of a model.

Examples:

>>> from luna_model import Model, Vtype
>>> from luna_model.transformation import PassManager
>>> from luna_model.transformation.passes import SpecsAnalysis
>>> model = Model()
>>> x = model.add_variable("x", vtype=Vtype.BINARY)
>>> y = model.add_variable("y", vtype=Vtype.BINARY)
>>> model.objective = x * y + x - 2 * y
>>> pm = PassManager([SpecsAnalysis()])
>>> ir = pm.run(model)
>>> ir.cache["specs"]
ModelSpecs(sense=Minimize, vtype=Binary, constraints=, max_degree=2, max_constraint_degree=0, max_num_variables=2)

Bases: ConcreteTransformationPass

Move all equality constraints to the model's objective as a quadratic penalties.

Converts the model by moving all equality constraints to the objective as quadratic penalties. Requires the MaxBiasAnalysis pass to be executed before this pass.

Less-equal (<=) or greater-equal (>=) constraints are not respected by this transformation and have to be handled before this pass using, e.g., the GeToLeConstraintsPass and the LeToEqConstraintsPass.

Parameters:

• penalty_scaling (float, default: 10.0 ) –

  The factor used to scale the penalties with, default 10.0.

Examples:

>>> from luna_model import Model, Vtype, Sense
>>> from luna_model.transformation import PassManager
>>> from luna_model.transformation.passes import MaxBiasAnalysis
>>> from luna_model.transformation.passes import EqualityConstraintsToQuadraticPenaltyPass
>>> model = Model(sense=Sense.MAX)
>>> x = model.add_variable("x", vtype=Vtype.BINARY)
>>> y = model.add_variable("y", vtype=Vtype.BINARY)
>>> model.objective = x * y + x - 2 * y
>>> model.constraints += x + y == 0
>>> pm = PassManager(
...     [
...         MaxBiasAnalysis(),
...         EqualityConstraintsToQuadraticPenaltyPass(),
...     ]
... )
>>> ir = pm.run(model)
>>> print(ir.model.objective)
41 x y + 21 x + 18 y

Bases: ConcreteTransformationPass

Convert the model's constraints by chaning all greater-equal (>=) constraints to less-equal (<=) constraints.

Examples:

>>> from luna_model import Model, Vtype, Sense
>>> from luna_model.transformation import PassManager
>>> from luna_model.transformation.passes import GeToLeConstraintsPass
>>> model = Model(sense=Sense.MAX)
>>> x = model.add_variable("x", vtype=Vtype.BINARY)
>>> y = model.add_variable("y", vtype=Vtype.BINARY)
>>> model.objective = x * y + x - 2 * y
>>> model.constraints += x + y >= 0, "ge_constr"
>>> pm = PassManager([GeToLeConstraintsPass()])
>>> ir = pm.run(model)
>>> ir.model.constraints["ge_constr"]
-x - y <= 0

Bases: ConcreteTransformationPass

Convert integer variables to a binary representation.

Transform the variables of type integer to be represented by binary typed variables.

Examples:

>>> from luna_model import Model, Vtype
>>> from luna_model.transformation import PassManager
>>> from luna_model.transformation.passes import BinarySpinPass
>>> model = Model()
>>> x = model.add_variable("x", vtype=Vtype.INTEGER, lower=0, upper=3)
>>> y = model.add_variable("y", vtype=Vtype.BINARY)
>>> model.objective = x * y + x - 2 * y
>>> pm = PassManager([IntegerToBinaryPass()])
>>> ir = pm.run(model)
>>> print(ir.model.objective)
y x_b0 + 2 y x_b1 - 2 y + x_b0 + 2 x_b1

Bases: ConcreteTransformationPass

Convert the model's constraints by chaning all less-equal (<=) constraints to equality (==) constraints.

Examples:

>>> from luna_model import Model, Vtype, Sense
>>> from luna_model.transformation import PassManager
>>> from luna_model.transformation.passes import MinValueForConstraintAnalysis
>>> from luna_model.transformation.passes import LeToEqConstraintsPass
>>> model = Model(sense=Sense.MAX)
>>> x = model.add_variable("x", vtype=Vtype.BINARY)
>>> y = model.add_variable("y", vtype=Vtype.BINARY)
>>> model.objective = x * y + x - 2 * y
>>> model.constraints += x + y <= 3, "le_constr"
>>> pm = PassManager([MinValueForConstraintAnalysis(), LeToEqConstraintsPass()])
>>> ir = pm.run(model)
>>> ir.model.constraints["le_constr"]
x + y + slack_le_constr == 0
>>> print(ir.model.get_variable("slack_le_constr"))
slack_le_constr: Integer(lower=0, upper=3)

Bases: PyTransformationPass, BasePass

Base class for transformation passes that modify models.

Transformation passes apply changes to models and can also convert solutions backwards to match the input representation.

Bases: PyAnalysisPass, BasePass, Generic[T]

Base class for analysis passes that compute information about models.

Analysis passes inspect models and compute results without modifying them. They can depend on other analysis passes and cache their results for efficient access in subsequent passes.

Bases: PyIfElsePass, BasePass

Conditional pass that executes different pipelines based on a runtime condition.

The IfElsePass evaluates a condition function against the analysis cache at runtime and executes either the then pipeline or the otherwise pipeline based on the result. This enables branching logic in transformation workflows, allowing different transformation strategies based on model properties discovered during analysis.

Parameters:

• requires (list[str]) –

  List of pass names that must be run before this pass. These passes provide the data used by the condition function.

• condition (Callable[[AnalysisCache], bool]) –

  A function that takes an AnalysisCache and returns a boolean. If True, the then pipeline is executed; otherwise, the otherwise pipeline runs.

• then (Pipeline) –

  The pipeline to execute when the condition evaluates to True.

• otherwise (Pipeline) –

  The pipeline to execute when the condition evaluates to False.

• name (str, default: None ) –

  Optional name for this pass. If not provided, a default name is generated.

Examples:

Execute different transformations based on the maximum bias:

>>> from luna_model import Model, Vtype
>>> from luna_model.transformation import PassManager, Pipeline, IfElsePass
>>> from luna_model.transformation.passes import MaxBiasAnalysis, BinarySpinPass
>>> # Create conditional pass
>>> conditional = IfElsePass(
...     requires=["max-bias"],
...     condition=lambda cache: cache["max-bias"].val > 10.0,
...     then=Pipeline([BinarySpinPass(vtype=Vtype.BINARY)]),
...     otherwise=Pipeline([]),
...     name="conditional-spin-conversion",
... )

Let's create a model that satisfies the condition:

>>> model = Model("example")
>>> x = model.add_variable("x", vtype=Vtype.SPIN)
>>> y = model.add_variable("y")
>>> z = model.add_variable("z")
>>> model.objective = 2 * x + 12 * y * z

And use it in the pass manager:

>>> pm = PassManager([MaxBiasAnalysis(), conditional])
>>> result = pm.run(model)
>>> print(result.model)
Model: example
Minimize
  12 * y * z - 4 * x_x + 2
Binary
  y z x_x

And now a model that does not satisfy the condition:

>>> model = Model("example")
>>> x = model.add_variable("x", vtype=Vtype.SPIN)
>>> y = model.add_variable("y")
>>> z = model.add_variable("z")
>>> model.objective = 2 * x + 8 * y * z

And use it in the pass manager:

>>> pm = PassManager([MaxBiasAnalysis(), conditional])
>>> result = pm.run(model)
>>> print(result.model)
Model: example
Minimize
  8 * y * z + 2 * x
Binary
  y z
Spin
  x

An element of the execution log of an intermediate representation (IR).

Log elements record information about transformation passes, including the pass name, timing information, and the type of action performed.