Skip to content

Variable API Reference

Variable

A decision variable.

Variables represent unknowns in an optimization problem that are determined by the optimization process. Each variable has a name, type, optional bounds, and belongs to an environment.

Variables can be combined using arithmetic operations (+, -, *, **) to create Expression objects, and compared using relational operators (==, <=, >=) to create Constraint objects.

Parameters:

  • name (str) –

    The unique name identifying this variable within its environment.

  • vtype (Vtype, default: Vtype.BINARY ) –

    The type of the variable. Must be one of:

    • Vtype.BINARY: Variable can be 0 or 1
    • Vtype.SPIN: Variable can be -1 or +1
    • Vtype.INTEGER: Variable can be any integer
    • Vtype.REAL: Variable can be any real number

    If Vtype.INVERTED_BINARY is used an error is raised.

  • bounds (Bounds, default: None ) –

    The bounds constraining the variable's value.

  • env (Environment, default: None ) –

    The environment managing this variable. If None, requires an active environment context.

Attributes:

  • id (int) –

    Unique integer identifier for this variable within its environment.

  • name (str) –

    The name of the variable.

  • bounds (Bounds) –

    The lower and upper bounds of the variable.

  • vtype (Vtype) –

    The type of the variable.

  • environment (Environment) –

    The environment containing this variable.

Examples:

Create binary variables:

>>> from luna_model import Environment, Variable, Vtype
>>> with Environment():
...     x1 = Variable("x1")  # Binary by default
...     x2 = Variable("x2", vtype=Vtype.BINARY)

Create integer variables with bounds:

>>> from luna_model import Variable, Vtype, Bounds
>>> env = Environment()
>>> y = Variable("y", vtype=Vtype.INTEGER, bounds=Bounds(0, 10), env=env)

Create expressions using arithmetic:

>>> with Environment():
...     x = Variable("x")
...     y = Variable("y")
>>> expr = 3 * x + 2 * y - 5  # Creates an Expression

Create constraints using comparisons:

>>> with Environment():
...     x = Variable("x")
...     y = Variable("y")
>>> constraint = x + y <= 1  # Creates a Constraint

id: int property

Get the unique identifier of the variable.

Returns:

  • int –

    Unique integer identifier within the variable's environment.

Notes

Variable IDs are assigned sequentially within an environment.

name: str property

Get the name of the variable.

Returns:

  • str –

    The variable's name as specified at creation.

bounds: VBounds property

Get the bounds of the variable.

Returns:

  • VBounds –

    The variable's bounds with a guaranteed lower and upper value.

vtype: Vtype property

Get the type of the variable.

Returns:

  • Vtype –

    The variable type (BINARY, SPIN, INTEGER, or REAL).

environment: Environment property

Get the environment containing this variable.

Returns:

  • Environment –

    The environment containing this variable's metadata.

is_equal(other: Variable) -> bool

Check if this variable is the same as another variable.

Parameters:

  • other (Variable) –

    The variable to compare with.

Returns:

  • bool –

    True if both variables refer to the same underlying variable (same ID and environment), False otherwise.

Notes

This compares variable identity, not just name equality. Two variables with the same name in different environments are not equal.

inv() -> Variable

Get an inverted version of this variable.

Only a binary variable (Vtype.BINARY) can be inverted. Inverting a variable of any other vtype will raise an UnsupportedOperationError. If the inverted variable already exists it is not re-created but returned directly.

Returns:

Raises:

  • UnsupportedOperationError –

    If any variable is inverted that is not of type Vtype.BINARY

Notes

Inverted variables maintain a relationship with their original variable in the environment.

__add__(other: Expression | Variable | float) -> Expression

Add this variable to another term.

Parameters:

Returns:

  • Expression –

    A new expression representing the sum.

__sub__(other: Expression | Variable | float) -> Expression

Subtract another term from this variable.

Parameters:

Returns:

  • Expression –

    A new expression representing the difference.

__mul__(other: Expression | Variable | float) -> Expression

Multiply this variable by another term.

Parameters:

Returns:

  • Expression –

    A new expression representing the product.

__radd__(other: Expression | Variable | float) -> Expression

Add this variable to another term (right operand).

Parameters:

Returns:

  • Expression –

    A new expression representing the sum.

__rsub__(other: Expression | Variable | float) -> Expression

Subtract this variable from another term (right operand).

Parameters:

Returns:

  • Expression –

    A new expression representing the difference.

__rmul__(other: Expression | Variable | float) -> Expression

Multiply another term by this variable (right operand).

Parameters:

Returns:

  • Expression –

    A new expression representing the product.

__pow__(val: int) -> Expression

Raise this variable to a power.

Parameters:

  • val (int) –

    The exponent (must be a positive integer).

Returns:

  • Expression –

    A new expression representing this variable raised to the power.

__neg__() -> Expression

Negate this variable.

Returns:

  • Expression –

    A new expression representing the negation of this variable.

__invert__() -> Variable

Get an inverted version of this variable.

Only a binary variable (Vtype.BINARY) can be inverted. Inverting a variable of any other vtype will raise an UnsupportedOperationError. If the inverted variable already exists it is not re-created but returned directly.

Returns:

Raises:

  • UnsupportedOperationError –

    If any variable is inverted that is not of type Vtype.BINARY

Notes

Inverted variables maintain a relationship with their original variable in the environment.

__eq__(other: Expression | Variable | float) -> Constraint | bool 

__eq__(other: Variable) -> bool

__eq__(other: Expression | float) -> Constraint

Check equality or create an equality constraint.

When comparing with another Variable, performs identity comparison. When comparing with an Expression or float, creates an equality constraint.

Parameters:

Returns:

  • Constraint or bool –
    • bool if comparing with another Variable (identity check)
    • Constraint if comparing with Expression or float (constraint creation)

__le__(other: Expression | Variable | float) -> Constraint

Create a less-than-or-equal-to constraint.

Parameters:

Returns:

  • Constraint –

    A constraint representing self <= other.

__ge__(other: Expression | Variable | float) -> Constraint

Create a greater-than-or-equal-to constraint.

Parameters:

Returns:

  • Constraint –

    A constraint representing self >= other.

__hash__() -> int

Compute hash.

__str__() -> str

Get human-readable string representation.

__repr__() -> str

Get debug string representation.

Vtype

Bases: Enum

Enumeration of variable types.

The variable type determines the domain of values a variable can take during optimization.

Attributes:

  • BINARY (str) –

    Binary variable that can be 0 or 1. Used for yes/no decisions.

  • INVERTED_BINARY (str) –

    Inverted binary variable. Created by inverting a BINARY variable. Creating a variable with vtype=Vtype.INVERTED_BINARY will raise an error.

  • SPIN (str) –

    Spin variable that can be -1 or +1. Common in quantum computing formulations.

  • INTEGER (str) –

    Integer variable that can be any integer value within bounds.

  • REAL (str) –

    Real-valued (continuous) variable that can be any floating-point value within bounds.

Bounds

Bounds for constraining variable values.

Bounds specify the lower and upper limits on the values a variable can take during optimization. Bounds can be finite values or unbounded (infinite).

Parameters:

  • lower (float or type[Unbounded], default: None ) –

    The lower bound. Use Unbounded for negative infinity. Use None for the default value based on a variable's vtype.

  • upper (float or type[Unbounded], default: None ) –

    The upper bound. Use Unbounded for positive infinity. Use None for the default value based on a variable's vtype.

Attributes:

  • lower (float or type[Unbounded] or None) –

    The lower bound value. If set to None the lower bound will be determined based on the variable's vtype this bounds object is be associated with during variable creation.

  • upper (float or type[Unbounded] or None) –

    The upper bound value. If set to None the upper bound will be determined based on the variable's vtype this bounds object is be associated with during variable creation.

lower: float | type[Unbounded] | None property

Get the lower bound.

Returns:

  • (float or type[Unbounded], optional) –

    The lower bound value if set (Unbounded for negative infinity).

upper: float | type[Unbounded] | None property

Get the upper bound.

Returns:

  • (float or type[Unbounded], optional) –

    The upper bound value if set (Unbounded for positive infinity).

default(vtype: Vtype) -> Bounds classmethod

Get the default bounds for a variable type.

Parameters:

  • vtype (Vtype) –

    The variable type.

Returns:

  • Bounds –

    Default bounds for the specified vtype.

binary() -> Bounds classmethod

Get the bounds for binary variables.

Returns:

  • Bounds –

    Bounds with lower=0, upper=1.

spin() -> Bounds classmethod

Get the bounds for spin variables.

Returns:

  • Bounds –

    Bounds with lower=-1, upper=1.

integer() -> Bounds classmethod

Get the bounds for integer variables.

Returns:

  • Bounds –

    Bounds with typical integer range limits.

real() -> Bounds classmethod

Get the bounds for real variables.

Returns:

  • Bounds –

    Bounds for real-valued variables.

__str__() -> str

Return human-readable string representation.

Returns:

  • str –

    String representation of the bounds.

__repr__() -> str

Return detailed string representation.

Returns:

  • str –

    Detailed representation of the bounds.

__eq__(other: Bounds) -> bool

Check equality with another Bounds object.

Parameters:

  • other (Bounds) –

    The bounds to compare with.

Returns:

  • bool –

    True if bounds are equal, False otherwise.

__hash__() -> int

Compute hash for use in sets and dictionaries.

Returns:

  • int –

    Hash value of the bounds.

Unbounded

Indicating the lower (-inf) or upper bound (+inf).