qilisdk.core.expression

A symbolic expression tree (AST) for qilisdk.

The public entry point is Expression, the abstract base of every node:

• leaves – Constant and the variable family (Parameter, Variable, BinaryVariable, SpinVariable) defined in qilisdk.core.variables;

• operator nodes – Add, Mul, Pow;

• unary maths functions – Function and its concrete subclasses (Sin, Cos, Exp, Log, Tan, Sqrt).

Construction canonicalizes (a cheap, total normalization: flattening, combining like terms/powers, folding constants, eliminating identities, ordering operands deterministically). Canonical form is the sole definition of ==/hash – equal expressions are structurally identical and equality is order-independent for + and * (x + y == y + x). Semantic rewrites – expand() and derivative() – are explicit and never participate in equality.

Classes

Expression	Abstract base of every node in the expression tree.
Constant	A numeric literal leaf. Replaces the old Term.CONST sentinel.
Add	A canonical n-ary sum. Operands are deterministically ordered and combine like terms.
Mul	A canonical n-ary product. Collects like powers and folds the numeric coefficient.
Pow	A power base ** exp. The exponent may be a numeric or symbolic Expression.
Function	Abstract base for unary maths functions (sin, cos, exp, ...).
Sin	Sine of an expression.
Cos	Cosine of an expression.
Exp	Exponential of an expression.
Log	Natural logarithm of an expression.
Tan	Tangent of an expression.
Sqrt	Square root of an expression.
Abs	Absolute value of an expression.

Functions

Inv(→ Expression)

Build the reciprocal 1 / arg.

Module Contents

class Expression

Bases: abc.ABC

Abstract base of every node in the expression tree.

property is_idempotent_under_mul: bool

Whether self * self == self (true only for BinaryVariable).

property is_parameter: bool

Whether this expression is a Parameter leaf.

abstractmethod evaluate(env: collections.abc.Mapping[qilisdk.core.variables.BaseVariable, qilisdk.core.types.Number | list[int]] | None = None) → qilisdk.core.types.Number

Numerically evaluate the expression given an assignment of symbols to values.

abstractmethod free_symbols() → set[qilisdk.core.variables.BaseVariable]

The set of named leaves (variables/parameters) occurring in the expression.

property degree: int

Abstractmethod:

Polynomial degree. Raises NonPolynomialError for non-polynomial expressions.

abstractmethod derivative(symbol: qilisdk.core.variables.BaseVariable) → Expression

Symbolic derivative with respect to symbol.

expand() → Expression

Distribute products over sums.

Returns:

a canonical sum-of-monomials equal to this expression.

Return type:

Expression

substitute(mapping: collections.abc.Mapping[Expression, Expression | qilisdk.core.types.Number]) → Expression

Structurally replace sub-expressions according to mapping.

Returns:

the expression with substitutions applied.

Return type:

Expression

to_binary() → Expression

Encode every continuous Variable into binary variables (no-op for most nodes).

Returns:

an equivalent expression over binary variables.

Return type:

Expression

free_parameters() → set[qilisdk.core.variables.Parameter]

Collect the parameters occurring in the expression.

Returns:

the free parameters.

Return type:

set[Parameter]

variables() → list[qilisdk.core.variables.BaseVariable]

Collect the named leaves of the expression.

Returns:

the variables and parameters, sorted by label.

Return type:

list[BaseVariable]

is_parameterized() → bool

Whether every named leaf is a Parameter.

Returns:

True if the expression contains only parameters (or no variables).

Return type:

bool

get_constant() → qilisdk.core.types.Number

Return the additive constant of the expression.

Returns:

the constant term (0 unless the expression is a sum or a constant).

Return type:

Number

as_coefficients_dict() → dict[Expression, qilisdk.core.types.Number]

Map each (non-constant) monomial to its numeric coefficient.

Returns:

a mapping from monomial to coefficient.

Return type:

dict[Expression, Number]

monomial_factors() → list[tuple[Expression, int]]

Decompose a single monomial into its factors.

Returns:

the (base, integer_power) factors.

Return type:

list[tuple[Expression, int]]

to_list() → list[Expression]

The node’s operands as a list: the summands of a sum, the factors of a product.

A leaf has no operands, so it yields itself. This is the readable spelling of .args.

Returns:

the operands of this node.

Return type:

list[Expression]

class Constant(value: qilisdk.core.types.Number)

Bases: Expression

A numeric literal leaf. Replaces the old Term.CONST sentinel.

property value: qilisdk.core.types.Number

nodes are immutable so the cached hash stays valid.

Type:

The numeric literal. Read-only

evaluate(env: collections.abc.Mapping[qilisdk.core.variables.BaseVariable, qilisdk.core.types.Number | list[int]] | None = None) → qilisdk.core.types.Number

Numerically evaluate the expression given an assignment of symbols to values.

free_symbols() → set[qilisdk.core.variables.BaseVariable]

The set of named leaves (variables/parameters) occurring in the expression.

property degree: int

Polynomial degree. Raises NonPolynomialError for non-polynomial expressions.

derivative(symbol: qilisdk.core.variables.BaseVariable) → Expression

Symbolic derivative with respect to symbol.

get_constant() → qilisdk.core.types.Number

Return the additive constant of the expression.

Returns:

the constant term (0 unless the expression is a sum or a constant).

Return type:

Number

as_coefficients_dict() → dict[Expression, qilisdk.core.types.Number]

Map each (non-constant) monomial to its numeric coefficient.

Returns:

a mapping from monomial to coefficient.

Return type:

dict[Expression, Number]

monomial_factors() → list[tuple[Expression, int]]

Decompose a single monomial into its factors.

Returns:

the (base, integer_power) factors.

Return type:

list[tuple[Expression, int]]

class Add(args: tuple[Expression, ...])

Bases: Expression

A canonical n-ary sum. Operands are deterministically ordered and combine like terms.

property args: tuple[Expression, ...]

nodes are immutable so the cached hash stays valid.

Type:

The summands. Read-only

classmethod build(raw: tuple[Expression, ...]) → Expression

evaluate(env: collections.abc.Mapping[qilisdk.core.variables.BaseVariable, qilisdk.core.types.Number | list[int]] | None = None) → qilisdk.core.types.Number

Numerically evaluate the expression given an assignment of symbols to values.

free_symbols() → set[qilisdk.core.variables.BaseVariable]

The set of named leaves (variables/parameters) occurring in the expression.

property degree: int

Polynomial degree. Raises NonPolynomialError for non-polynomial expressions.

derivative(symbol: qilisdk.core.variables.BaseVariable) → Expression

Symbolic derivative with respect to symbol.

expand() → Expression

Distribute products over sums.

Returns:

a canonical sum-of-monomials equal to this expression.

Return type:

Expression

substitute(mapping: collections.abc.Mapping[Expression, Expression | qilisdk.core.types.Number]) → Expression

Structurally replace sub-expressions according to mapping.

Returns:

the expression with substitutions applied.

Return type:

Expression

to_binary() → Expression

Encode every continuous Variable into binary variables (no-op for most nodes).

Returns:

an equivalent expression over binary variables.

Return type:

Expression

get_constant() → qilisdk.core.types.Number

Return the additive constant of the expression.

Returns:

the constant term (0 unless the expression is a sum or a constant).

Return type:

Number

to_list() → list[Expression]

The node’s operands as a list: the summands of a sum, the factors of a product.

A leaf has no operands, so it yields itself. This is the readable spelling of .args.

Returns:

the operands of this node.

Return type:

list[Expression]

as_coefficients_dict() → dict[Expression, qilisdk.core.types.Number]

Map each (non-constant) monomial to its numeric coefficient.

Returns:

a mapping from monomial to coefficient.

Return type:

dict[Expression, Number]

class Mul(args: tuple[Expression, ...])

Bases: Expression

A canonical n-ary product. Collects like powers and folds the numeric coefficient.

Mul does not distribute over sums; use expand() for that.

property args: tuple[Expression, ...]

nodes are immutable so the cached hash stays valid.

Type:

The factors. Read-only

classmethod build(raw: tuple[Expression, ...]) → Expression

coefficient() → qilisdk.core.types.Number

monomial() → Expression

evaluate(env: collections.abc.Mapping[qilisdk.core.variables.BaseVariable, qilisdk.core.types.Number | list[int]] | None = None) → qilisdk.core.types.Number

Numerically evaluate the expression given an assignment of symbols to values.

free_symbols() → set[qilisdk.core.variables.BaseVariable]

The set of named leaves (variables/parameters) occurring in the expression.

property degree: int

Polynomial degree. Raises NonPolynomialError for non-polynomial expressions.

derivative(symbol: qilisdk.core.variables.BaseVariable) → Expression

Symbolic derivative with respect to symbol.

expand() → Expression

Distribute products over sums.

Returns:

a canonical sum-of-monomials equal to this expression.

Return type:

Expression

substitute(mapping: collections.abc.Mapping[Expression, Expression | qilisdk.core.types.Number]) → Expression

Structurally replace sub-expressions according to mapping.

Returns:

the expression with substitutions applied.

Return type:

Expression

to_binary() → Expression

Encode every continuous Variable into binary variables (no-op for most nodes).

Returns:

an equivalent expression over binary variables.

Return type:

Expression

to_list() → list[Expression]

The node’s operands as a list: the summands of a sum, the factors of a product.

A leaf has no operands, so it yields itself. This is the readable spelling of .args.

Returns:

the operands of this node.

Return type:

list[Expression]

as_coefficients_dict() → dict[Expression, qilisdk.core.types.Number]

Map each (non-constant) monomial to its numeric coefficient.

Returns:

a mapping from monomial to coefficient.

Return type:

dict[Expression, Number]

monomial_factors() → list[tuple[Expression, int]]

Decompose a single monomial into its factors.

Returns:

the (base, integer_power) factors.

Return type:

list[tuple[Expression, int]]

class Pow(base: Expression, exp: Expression)

Bases: Expression

A power base ** exp. The exponent may be a numeric or symbolic Expression.

property base: Expression

nodes are immutable so the cached hash stays valid.

Type:

The base. Read-only

property exp: Expression

nodes are immutable so the cached hash stays valid.

Type:

The exponent. Read-only

classmethod build(base: Expression, exp: Expression) → Expression

evaluate(env: collections.abc.Mapping[qilisdk.core.variables.BaseVariable, qilisdk.core.types.Number | list[int]] | None = None) → qilisdk.core.types.Number

Numerically evaluate the expression given an assignment of symbols to values.

free_symbols() → set[qilisdk.core.variables.BaseVariable]

The set of named leaves (variables/parameters) occurring in the expression.

property degree: int

Polynomial degree. Raises NonPolynomialError for non-polynomial expressions.

derivative(symbol: qilisdk.core.variables.BaseVariable) → Expression

Symbolic derivative with respect to symbol.

expand() → Expression

Distribute products over sums.

Returns:

a canonical sum-of-monomials equal to this expression.

Return type:

Expression

substitute(mapping: collections.abc.Mapping[Expression, Expression | qilisdk.core.types.Number]) → Expression

Structurally replace sub-expressions according to mapping.

Returns:

the expression with substitutions applied.

Return type:

Expression

to_binary() → Expression

Encode every continuous Variable into binary variables (no-op for most nodes).

Returns:

an equivalent expression over binary variables.

Return type:

Expression

monomial_factors() → list[tuple[Expression, int]]

Decompose a single monomial into its factors.

Returns:

the (base, integer_power) factors.

Return type:

list[tuple[Expression, int]]

class Function(arg: object)

Bases: Expression, abc.ABC

Abstract base for unary maths functions (sin, cos, exp, …).

A concrete function declares – all at the class level so serialization carries only the operand – a stable NAME, a numpy numeric kernel _numeric(), and the local outer derivative _outer_derivative() (the chain rule is applied by derivative()).

NAME: ClassVar[str] = ''

property arg: Expression

nodes are immutable so the cached hash stays valid.

Type:

The operand. Read-only

evaluate(env: collections.abc.Mapping[qilisdk.core.variables.BaseVariable, qilisdk.core.types.Number | list[int]] | None = None) → qilisdk.core.types.Number

Numerically evaluate the expression given an assignment of symbols to values.

free_symbols() → set[qilisdk.core.variables.BaseVariable]

The set of named leaves (variables/parameters) occurring in the expression.

property degree: int

Polynomial degree. Raises NonPolynomialError for non-polynomial expressions.

derivative(symbol: qilisdk.core.variables.BaseVariable) → Expression

Symbolic derivative with respect to symbol.

expand() → Expression

Distribute products over sums.

Returns:

a canonical sum-of-monomials equal to this expression.

Return type:

Expression

substitute(mapping: collections.abc.Mapping[Expression, Expression | qilisdk.core.types.Number]) → Expression

Structurally replace sub-expressions according to mapping.

Returns:

the expression with substitutions applied.

Return type:

Expression

to_binary() → Expression

Encode every continuous Variable into binary variables (no-op for most nodes).

Returns:

an equivalent expression over binary variables.

Return type:

Expression

classmethod to_yaml(representer, node)

classmethod from_yaml(constructor, node)

class Sin(arg: object)

Bases: Function

Sine of an expression.

NAME = 'sin'

class Cos(arg: object)

Bases: Function

Cosine of an expression.

NAME = 'cos'

class Exp(arg: object)

Bases: Function

Exponential of an expression.

NAME = 'exp'

class Log(arg: object)

Bases: Function

Natural logarithm of an expression.

NAME = 'log'

class Tan(arg: object)

Bases: Function

Tangent of an expression.

NAME = 'tan'

class Sqrt(arg: object)

Bases: Function

Square root of an expression.

NAME = 'sqrt'

class Abs(arg: object)

Bases: Function

Absolute value of an expression.

Abs is not differentiable at zero and there is no sign node to express its derivative away from zero, so Expression.derivative() raises on it.

NAME = 'abs'

Inv(arg: object) → Expression

Build the reciprocal 1 / arg.

This is a thin wrapper over Pow rather than a node of its own, so Inv(x) and x ** -1 are the same expression.

Returns:

the reciprocal of arg.

Return type:

Expression

Raises:

TypeError – if arg is neither an Expression nor a number.