qilisdk.core.variables

Decision variables, parameters, encodings, and comparison relations.

The arithmetic core (Expression and the operator/function nodes) lives in qilisdk.core.expression; this module defines the leaves of that tree – the named BaseVariable family (Parameter, Variable, BinaryVariable, SpinVariable) – together with the Encoding strategies that lower continuous variables to binary, and Comparison, the (non-Expression) relation type produced by the LT()/LEQ()/EQ()/NEQ()/GT()/GEQ() helpers.

Classes

`Domain`	str(object='') -> str
`Encoding`	Abstract variable encoding: how a continuous variable is represented in binary variables.
`Bitwise`	Bitwise (binary) variable encoding.
`OneHot`	One-Hot variable encoding.
`DomainWall`	Domain-wall variable encoding.
`BaseVariable`	Abstract base class for symbolic named leaves (decision variables and parameters).
`BinaryVariable`	Binary decision variable restricted to `{0, 1}`.
`SpinVariable`	Spin decision variable restricted to `{-1, 1}`.
`Variable`	Generic (possibly continuous) optimization variable with a configurable binary encoding.
`Parameter`	Symbolic scalar used to parametrize expressions while remaining differentiable.

Module Contents

class Domain[fuente]

Bases: qilisdk.core.types.QiliEnum

str(object=””) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to “utf-8”. errors defaults to “strict”.

Initialize self. See help(type(self)) for accurate signature.

INTEGER = 'Integer Domain'[fuente]

POSITIVE_INTEGER = 'Positive Integer Domain'[fuente]

REAL = 'Real Domain'[fuente]

BINARY = 'Binary Domain'[fuente]

SPIN = 'Spin Domain'[fuente]

check_value(value: qilisdk.core.types.Number) → bool[fuente]

Whether value is valid for this domain.

Parámetros:: value (Number) – the value to be evaluated.
Devuelve:: True if the value provided is valid, False otherwise.
Tipo del valor devuelto:: bool

min() → float[fuente]

Return the smallest value allowed by this domain.

Devuelve:: the minimum value allowed of a given domain.
Tipo del valor devuelto:: float

max() → float[fuente]

Return the largest value allowed by this domain.

Devuelve:: the maximum value allowed for a given domain.
Tipo del valor devuelto:: float

class Encoding[fuente]

Bases: abc.ABC

Abstract variable encoding: how a continuous variable is represented in binary variables.

property name: str[fuente]

Abstractmethod:

The encoding’s name.

static encode(var: Variable, precision: float = 0.01) → qilisdk.core.expression.Expression[fuente]

Abstractmethod:

Return an expression of binary variables representing var in this encoding.

static encoding_constraint(var: Variable, precision: float = 0.01) → qilisdk.core.comparison.Comparison | None[fuente]

Abstractmethod:

Return a constraint that ensures the encoding is respected, or None if the encoding needs none.

static evaluate(var: Variable, value: list[int] | int, precision: float = 0.01) → float[fuente]

Abstractmethod:

Decode a binary assignment into the value of the continuous variable.

static num_binary_equivalent(var: Variable, precision: float = 0.01) → int[fuente]

Abstractmethod:

Number of binary variables needed to encode var.

static check_valid(value: list[int] | int) → tuple[bool, int][fuente]

Abstractmethod:

Whether value is a valid sample in this encoding (and the encoding error).

class Bitwise[fuente]

Bases: Encoding

Bitwise (binary) variable encoding.

name = 'Bitwise'[fuente]: The encoding’s name.

static encode(var: Variable, precision: float = 0.01) → qilisdk.core.expression.Expression[fuente]: Return an expression of binary variables representing var in this encoding.

static evaluate(var: Variable, value: list[int] | int, precision: float = 0.01) → float[fuente]: Decode a binary assignment into the value of the continuous variable.

static encoding_constraint(var: Variable, precision: float = 0.01) → qilisdk.core.comparison.Comparison | None[fuente]: Return a constraint that ensures the encoding is respected, or None if the encoding needs none.

static num_binary_equivalent(var: Variable, precision: float = 0.01) → int[fuente]: Number of binary variables needed to encode var.

static check_valid(value: list[int] | int) → tuple[bool, int][fuente]: Whether value is a valid sample in this encoding (and the encoding error).

class OneHot[fuente]

Bases: Encoding

One-Hot variable encoding.

name = 'One-Hot'[fuente]: The encoding’s name.

static encode(var: Variable, precision: float = 0.01) → qilisdk.core.expression.Expression[fuente]: Return an expression of binary variables representing var in this encoding.

static evaluate(var: Variable, value: list[int] | int, precision: float = 0.01) → float[fuente]: Decode a binary assignment into the value of the continuous variable.

static encoding_constraint(var: Variable, precision: float = 0.01) → qilisdk.core.comparison.Comparison[fuente]: Return a constraint that ensures the encoding is respected, or None if the encoding needs none.

static num_binary_equivalent(var: Variable, precision: float = 0.01) → int[fuente]: Number of binary variables needed to encode var.

static check_valid(value: list[int] | int) → tuple[bool, int][fuente]: Whether value is a valid sample in this encoding (and the encoding error).

class DomainWall[fuente]

Bases: Encoding

Domain-wall variable encoding.

name = 'Domain Wall'[fuente]: The encoding’s name.

static encode(var: Variable, precision: float = 0.01) → qilisdk.core.expression.Expression[fuente]: Return an expression of binary variables representing var in this encoding.

static evaluate(var: Variable, value: list[int] | int, precision: float = 0.01) → float[fuente]: Decode a binary assignment into the value of the continuous variable.

static encoding_constraint(var: Variable, precision: float = 0.01) → qilisdk.core.comparison.Comparison[fuente]: Return a constraint that ensures the encoding is respected, or None if the encoding needs none.

static num_binary_equivalent(var: Variable, precision: float = 0.01) → int[fuente]: Number of binary variables needed to encode var.

static check_valid(value: list[int] | int) → tuple[bool, int][fuente]: Whether value is a valid sample in this encoding (and the encoding error).

class BaseVariable(label: str, domain: Domain, bounds: tuple[float | None, float | None] = (None, None))[fuente]

Bases: qilisdk.core.expression.Expression, abc.ABC

Abstract base class for symbolic named leaves (decision variables and parameters).

Initialize a new variable.

Parámetros:

label (str) – The name of the variable.
domain (Domain) – The domain of the values this variable can take.
bounds (tuple[float | None, float | None], optional) – the (lower, upper) bounds, both included. None selects the domain’s extreme. Defaults to (None, None).

Muestra:

OutOfBoundsException – a bound does not respect the variable’s domain.
InvalidBoundsError – the lower bound is greater than the upper bound.

property bounds: tuple[float, float][fuente]: The (lower, upper) bounds of the variable.

property lower_bound: float[fuente]: The lower bound of the variable.

property upper_bound: float[fuente]: The upper bound of the variable.

property label: str[fuente]: The label (name) of the variable.

property domain: Domain[fuente]: The domain of values the variable can take.

set_bounds(lower_bound: float | None, upper_bound: float | None) → None[fuente]

Set the bounds of the variable.

Parámetros:

lower_bound (float | None) – The lower bound (None -> domain minimum).
upper_bound (float | None) – The upper bound (None -> domain maximum).

Muestra:

OutOfBoundsException – a bound does not respect the variable’s domain.
InvalidBoundsError – the lower bound is greater than the upper bound.

abstractmethod num_binary_equivalent() → int[fuente]: Number of binary variables needed to represent this variable in its encoding.

update_variable(domain: Domain, bounds: tuple[float | None, float | None] = (None, None)) → None[fuente]

Replace this variable’s domain and bounds.

Parámetros:

domain (Domain) – The updated domain of the variable.
bounds (tuple[float | None, float | None]) – The updated bounds. Defaults to (None, None).

free_symbols() → set[BaseVariable][fuente]: The set of named leaves (variables/parameters) occurring in the expression.

property degree: int[fuente]: Polynomial degree. Raises NonPolynomialError for non-polynomial expressions.

derivative(symbol: BaseVariable) → qilisdk.core.expression.Expression[fuente]: Symbolic derivative with respect to symbol.

class BinaryVariable(label: str)[fuente]

Bases: BaseVariable

Binary decision variable restricted to {0, 1}.

Ejemplo

from qilisdk.core.variables import BinaryVariable

x = BinaryVariable("x")

Initialize a new variable.

Parámetros:

label (str) – The name of the variable.
domain (Domain) – The domain of the values this variable can take.
bounds (tuple[float | None, float | None], optional) – the (lower, upper) bounds, both included. None selects the domain’s extreme. Defaults to (None, None).

Muestra:

OutOfBoundsException – a bound does not respect the variable’s domain.
InvalidBoundsError – the lower bound is greater than the upper bound.

property is_idempotent_under_mul: bool[fuente]: Whether self * self == self (true only for BinaryVariable).

num_binary_equivalent() → int[fuente]: Number of binary variables needed to represent this variable in its encoding.

evaluate(env: collections.abc.Mapping[BaseVariable, qilisdk.core.types.Number | list[int]] | None = None) → qilisdk.core.types.RealNumber[fuente]: Numerically evaluate the expression given an assignment of symbols to values.

abstractmethod update_variable(domain: Domain, bounds: tuple[float | None, float | None] = (None, None)) → None[fuente]

Replace this variable’s domain and bounds.

Parámetros:

domain (Domain) – The updated domain of the variable.
bounds (tuple[float | None, float | None]) – The updated bounds. Defaults to (None, None).

class SpinVariable(label: str)[fuente]

Bases: BaseVariable

Spin decision variable restricted to {-1, 1}.

Initialize a new variable.

Parámetros:

label (str) – The name of the variable.
domain (Domain) – The domain of the values this variable can take.
bounds (tuple[float | None, float | None], optional) – the (lower, upper) bounds, both included. None selects the domain’s extreme. Defaults to (None, None).

Muestra:

OutOfBoundsException – a bound does not respect the variable’s domain.
InvalidBoundsError – the lower bound is greater than the upper bound.

num_binary_equivalent() → int[fuente]: Number of binary variables needed to represent this variable in its encoding.

abstractmethod update_variable(domain: Domain, bounds: tuple[float | None, float | None] = (None, None)) → None[fuente]

Replace this variable’s domain and bounds.

Parámetros:

domain (Domain) – The updated domain of the variable.
bounds (tuple[float | None, float | None]) – The updated bounds. Defaults to (None, None).

evaluate(env: collections.abc.Mapping[BaseVariable, qilisdk.core.types.Number | list[int]] | None = None) → qilisdk.core.types.RealNumber[fuente]: Numerically evaluate the expression given an assignment of symbols to values.

class Variable(label: str, domain: Domain = Domain.INTEGER, bounds: tuple[float | None, float | None] = (None, None), encoding: type[Encoding] = Bitwise, precision: float = 0.01)[fuente]

Bases: BaseVariable

Generic (possibly continuous) optimization variable with a configurable binary encoding.

Ejemplo

from qilisdk.core.variables import Domain, Variable

price = Variable("price", domain=Domain.REAL, bounds=(0, 10))
binary_term = price.to_binary()

Initialize a new generic variable.

Parámetros:

label (str) – The name of the variable.
domain (Domain, optional) – The domain of the values this variable can take. Defaults to Domain.INTEGER, which is much cheaper to binarize than Domain.REAL.
bounds (tuple[float | None, float | None], optional) – the (lower, upper) bounds, both included. None selects the domain’s extreme. Defaults to (None, None).
encoding (type[Encoding], optional) – the binary encoding. Defaults to Bitwise.
precision (float, optional) – the floating point precision for REAL variables. Defaults to 1e-2.

property encoding: type[Encoding][fuente]

property precision: float[fuente]

property expression: qilisdk.core.expression.Expression[fuente]: The binary-encoded expression for this variable, computed once and cached.

property bin_vars: list[BaseVariable][fuente]

set_precision(precision: float) → None[fuente]

set_bounds(lower_bound: float | None, upper_bound: float | None) → None[fuente]

Set the bounds of the variable.

Parámetros:

lower_bound (float | None) – The lower bound (None -> domain minimum).
upper_bound (float | None) – The upper bound (None -> domain maximum).

Muestra:

OutOfBoundsException – a bound does not respect the variable’s domain.
InvalidBoundsError – the lower bound is greater than the upper bound.

update_variable(domain: Domain, bounds: tuple[float | None, float | None] = (None, None), encoding: type[Encoding] | None = None) → None[fuente]

Replace this variable’s domain and bounds.

Parámetros:

domain (Domain) – The updated domain of the variable.
bounds (tuple[float | None, float | None]) – The updated bounds. Defaults to (None, None).

evaluate(env: collections.abc.Mapping[BaseVariable, qilisdk.core.types.Number | list[int]] | None = None) → qilisdk.core.types.RealNumber[fuente]: Numerically evaluate the expression given an assignment of symbols to values.

to_binary() → qilisdk.core.expression.Expression[fuente]

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

Devuelve:: an equivalent expression over binary variables.
Tipo del valor devuelto:: Expression

num_binary_equivalent() → int[fuente]

Number of binary variables needed to encode the continuous variable.

Cached; _invalidate_encoding() drops it when the domain, bounds, encoding or precision change.

Devuelve:: the number of binary variables in the variable’s encoding.
Tipo del valor devuelto:: int

check_valid(binary_list: list[int]) → tuple[bool, int][fuente]

Check whether binary_list is a valid sample in the variable’s encoding.

Devuelve:: whether the sample is valid, and the encoding error.
Tipo del valor devuelto:: tuple[bool, int]

encoding_constraint() → qilisdk.core.comparison.Comparison | None[fuente]: Return a constraint that ensures the variable’s encoding is respected, or None if it needs none.

class Parameter(label: str, value: qilisdk.core.types.RealNumber, domain: Domain = Domain.REAL, bounds: tuple[float | None, float | None] = (None, None), trainable: bool = True)[fuente]

Bases: BaseVariable

Symbolic scalar used to parametrize expressions while remaining differentiable.

Ejemplo

from qilisdk.core.variables import Parameter

theta = Parameter("theta", value=0.5)
theta.set_value(0.75)

Initialize a new variable.

Parámetros:

label (str) – The name of the variable.
domain (Domain) – The domain of the values this variable can take.
bounds (tuple[float | None, float | None], optional) – the (lower, upper) bounds, both included. None selects the domain’s extreme. Defaults to (None, None).

Muestra:

OutOfBoundsException – a bound does not respect the variable’s domain.
InvalidBoundsError – the lower bound is greater than the upper bound.

property is_parameter: bool[fuente]: Whether this expression is a Parameter leaf.

property value: qilisdk.core.types.RealNumber[fuente]

property is_trainable: bool[fuente]

check_value(value: qilisdk.core.types.RealNumber) → None[fuente]

set_value(value: qilisdk.core.types.RealNumber) → None[fuente]

num_binary_equivalent() → int[fuente]

A parameter has no binary representation.

Devuelve:: always 0; parameters are not encoded into binary variables.
Tipo del valor devuelto:: int

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

Evaluate the parameter, using the value from env if present else its stored value.

Parámetros:: env (Mapping[BaseVariable, Number | list[int]] | None) – an optional assignment.
Devuelve:: the parameter’s value.
Tipo del valor devuelto:: RealNumber

to_binary() → qilisdk.core.expression.Expression[fuente]: Return the constant representation of the parameter.

set_bounds(lower_bound: float | None, upper_bound: float | None) → None[fuente]

Set the bounds of the variable.

Parámetros:

lower_bound (float | None) – The lower bound (None -> domain minimum).
upper_bound (float | None) – The upper bound (None -> domain maximum).

Muestra:

OutOfBoundsException – a bound does not respect the variable’s domain.
InvalidBoundsError – the lower bound is greater than the upper bound.

update_variable(domain: Domain, bounds: tuple[float | None, float | None] = (None, None)) → None[fuente]

Replace this variable’s domain and bounds.

Parámetros:

domain (Domain) – The updated domain of the variable.
bounds (tuple[float | None, float | None]) – The updated bounds. Defaults to (None, None).