Skip to content

Environment

Execution context for variable creation and expression scoping.

An Environment provides the symbolic scope in which Variable objects are defined. It is required for variable construction, and ensures consistency across expressions. The environment does not store constraints or expressions — it only facilitates their creation by acting as a context manager and anchor for Variable instances.

Environments are best used with with blocks, but can also be passed manually to models or variables.

Examples:

Create variables inside an environment:

>>> from luna_quantum import Environment, Variable
>>> with Environment() as env:
...     x = Variable("x")
...     y = Variable("y")

Serialize the environment state:

>>> data = env.encode()
>>> expr = Environment.decode(data)
Notes
  • The environment is required to create Variable instances.
  • It does not own constraints or expressions — they merely reference variables tied to an environment.
  • Environments cannot be nested. Only one can be active at a time.
  • Use encode() / decode() to persist and recover expression trees.

__init__

__init__() -> None

Initialize a new environment for variable construction.

It is recommended to use this in a with statement to ensure proper scoping.

decode classmethod

decode(data: bytes) -> Environment

Reconstruct an expression from a previously encoded binary blob.

Parameters:

Name Type Description Default
data bytes

The binary data returned from Environment.encode().

required

Returns:

Type Description
Expression

The reconstructed symbolic expression.

Raises:

Type Description
DecodeError

If decoding fails due to corruption or incompatibility.

deserialize classmethod

deserialize(data: bytes) -> Environment

Alias for decode().

See decode() for full usage details.

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 environment into a compact binary format.

This is the preferred method for persisting an environment's state.

Parameters:

Name Type Description Default
compress bool

Whether to compress the binary output. Default is True.

...
level int

Compression level (e.g., from 0 to 9). Default is 3.

...

Returns:

Type Description
bytes

Encoded binary representation of the environment.

Raises:

Type Description
IOError

If serialization fails.

get_variable

get_variable(name: str) -> Variable

Get a variable by its label (name).

Parameters:

Name Type Description Default
name str

The name/label of the variable

required

Returns:

Type Description
Variable

The variable with the specified label/name.

Raises:

Type Description
VariableNotExistingError

If no variable with the specified name is registered.

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 usage details.