Environment

Execution context for variable creation and expression scoping.

An Environment provides the symbolic scope in which Variables are defined. It is required for constructing variables ensuring 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 = True, level: int | None = 3) -> 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.	True
level	int	Compression level (e.g., from 0 to 9). Default is 3.	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.