Skip to content

Expression

Polynomial expression supporting symbolic arithmetic, constraint creation, and encoding.

An Expression represents a real-valued mathematical function composed of variables, scalars, and coefficients. Expressions may include constant, linear, quadratic, and higher-order terms (cubic and beyond). They are used to build objective functions and constraints in symbolic optimization models.

Expressions support both regular and in-place arithmetic, including addition and multiplication with integers, floats, Variable instances, and other Expressions.

Parameters:

Name Type Description Default
env Environment

Environment used to scope the expression when explicitly instantiating it. Typically, expressions are constructed implicitly via arithmetic on variables.

...

Examples:

Constructing expressions from variables:

>>> from luna_quantum import Environment, Variable
>>> with Environment():
...     x = Variable("x")
...     y = Variable("y")
...     expr = 1 + 2 * x + 3 * x * y + x * y * y

Inspecting terms:

>>> expr.get_offset()
1.0
>>> expr.get_linear(x)
2.0
>>> expr.get_quadratic(x, y)
3.0
>>> expr.get_higher_order((x, y, y))
1.0

In-place arithmetic:

>>> expr += x
>>> expr *= 2

Creating constraints:

>>> constraint = expr == 10.0
>>> constraint2 = expr <= 15

Serialization:

>>> blob = expr.encode()
>>> restored = Expression.decode(blob)
Supported Arithmetic

The following operations are supported:

  • Addition:

    • expr + exprExpression
    • expr + variableExpression
    • expr + int | floatExpression
    • int | float + exprExpression
  • In-place addition:

    • expr += expr
    • expr += variable
    • expr += int | float
  • Multiplication:

    • expr * expr
    • expr * variable
    • expr * int | float
    • int | float * expr
  • In-place multiplication:

    • expr *= expr
    • expr *= variable
    • expr *= int | float
  • Constraint creation:

    • expr == constantConstraint
    • expr <= constantConstraint
    • expr >= constantConstraint
Notes
  • Expressions are mutable: in-place operations (+=, *=) modify the instance.
  • Expressions are scoped to an environment via the variables they reference.
  • Comparisons like expr == expr return bool, not constraints.
  • Use ==, <=, >= with numeric constants to create constraints.

num_variables property

num_variables: int

Return the number of distinct variables in the expression.

Returns:

Type Description
int

Number of variables with non-zero coefficients.

__init__

__init__() -> None
__init__(env: Environment) -> None
__init__(env: Environment | None = ...) -> None

Create a new empty expression scoped to an environment.

Parameters

env : Environment The environment to which this expression is bound.

Raises:

Type Description
NoActiveEnvironmentFoundError

If no environment is provided and none is active in the context.

decode classmethod

decode(data: bytes) -> Expression

Reconstruct an expression from encoded bytes.

Parameters:

Name Type Description Default
data bytes

Binary blob returned by encode().

required

Returns:

Type Description
Expression

Deserialized expression object.

Raises:

Type Description
DecodeError

If decoding fails due to corruption or incompatibility.

deserialize classmethod

deserialize(data: bytes) -> Expression

Alias for decode().

See decode() for full documentation.

encode

encode() -> bytes
encode(*, compress: bool) -> bytes
encode(*, level: int) -> bytes
encode(compress: bool, level: int) -> bytes
encode(compress: bool | None = ..., level: int | None = ...) -> bytes

Serialize the expression into a compact binary format.

Parameters:

Name Type Description Default
compress bool

Whether to compress the data. Default is True.

...
level int

Compression level (0–9). Default is 3.

...

Returns:

Type Description
bytes

Encoded representation of the expression.

Raises:

Type Description
IOError

If serialization fails.

get_higher_order

get_higher_order(variables: tuple[Variable, ...]) -> float

Get the coefficient for a higher-order term (degree ≥ 3).

Parameters:

Name Type Description Default
variables tuple of Variable

A tuple of variables specifying the term.

required

Returns:

Type Description
float

The coefficient, or 0.0 if not present.

Raises:

Type Description
VariableOutOfRangeError

If any variable is out of bounds for the environment.

get_linear

get_linear(variable: Variable) -> float

Get the coefficient of a linear term for a given variable.

Parameters:

Name Type Description Default
variable Variable

The variable whose linear coefficient is being queried.

required

Returns:

Type Description
float

The coefficient, or 0.0 if the variable is not present.

Raises:

Type Description
VariableOutOfRangeError

If the variable index is not valid in this expression's environment.

get_offset

get_offset() -> float

Get the constant (offset) term in the expression.

Returns:

Type Description
float

The constant term.

get_quadratic

get_quadratic(u: Variable, v: Variable) -> float

Get the coefficient for a quadratic term (u * v).

Parameters:

Name Type Description Default
u Variable
required
v Variable
required

Returns:

Type Description
float

The coefficient, or 0.0 if not present.

Raises:

Type Description
VariableOutOfRangeError

If either variable is out of bounds for the expression's environment.

is_equal

is_equal(other: Expression) -> bool

Compare two expressions for equality.

Parameters:

Name Type Description Default
other Expression

The expression to which self is compared to.

required

Returns:

Type Description
bool

If the two expressions are equal.

serialize

serialize() -> bytes
serialize(*, compress: bool) -> bytes
serialize(*, level: int) -> bytes
serialize(compress: bool, level: int) -> bytes
serialize(compress: bool | None = ..., level: int | None = ...) -> bytes

Alias for encode().

See encode() for full documentation.