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 Expression
s.
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:
Creating constraints:
Serialization:
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
returnbool
, not constraints. - Use
==
,<=
,>=
with numeric constants to create constraints.
num_variables
property
¶
Return the number of distinct variables in the expression.
Returns:
Type | Description |
---|---|
int
|
Number of variables with non-zero coefficients. |
__init__ ¶
__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 |
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 ¶
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 the constant (offset) term in the expression.
Returns:
Type | Description |
---|---|
float
|
The constant term. |
get_quadratic ¶
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 |
required |
Returns:
Type | Description |
---|---|
bool
|
If the two expressions are equal. |