Expression

Polynomial expression supporting symbolic arithmetic, constraint creation.

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 + expr → Expression
  • expr + variable → Expression
  • expr + int | float → Expression
  • int | float + expr → Expression

• 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 == constant → Constraint
  • expr <= constant → Constraint
  • expr >= constant → Constraint

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:

Name	Type	Description	Default
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 = True, level: int | None = 3) -> bytes

Serialize the expression into a compact binary format.

Parameters:

Name	Type	Description	Default
compress	bool	Whether to compress the data. Default is True.	True
level	int	Compression level (0-9). Default is 3.	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.

items

items() -> ExpressionIterator

Iterate over the single components of an expression.

An component refers to a single constant, linear, quadratic, or higher-order term of an expression.

Returns:

Type	Description
ExpressionIterator	The iterator over the expression's components.

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.