Model

A symbolic optimization model consisting of an objective and constraints.

The Model class represents a structured symbolic optimization problem. It combines a scalar objective Expression, a collection of Constraints, and a shared Environment that scopes all variables used in the model.

Models can be constructed explicitly by passing an environment, or implicitly by allowing the model to create its own private environment. If constructed inside an active Environment context (via with Environment()), that context is used automatically.

Parameters:

Name	Type	Description	Default
env	Environment	The environment in which variables and expressions are created. If not provided, the model will either use the current context (if active), or create a new private environment.	...
name	str	An optional name assigned to the model.	...

Examples:

Basic usage:

>>> from luna_quantum import Model, Variable
>>> model = Model("MyModel")
>>> with model.environment:
...     x = Variable("x")
...     y = Variable("y")
>>> model.objective = x * y + x
>>> model.constraints += x >= 0
>>> model.constraints += y <= 5

With explicit environment:

>>> from luna_quantum import Environment
>>> env = Environment()
>>> model = Model("ScopedModel", env)
>>> with env:
...     x = Variable("x")
...     model.objective = x * x

Serialization:

>>> blob = model.encode()
>>> restored = Model.decode(blob)
>>> restored.name
'MyModel'

Notes

• The Model class does not solve the optimization problem.
• Use .objective, .constraints, and .environment to access the symbolic content.
• Use encode() and decode() to serialize and recover models.

constraints property

constraints: Constraints

Access the set of constraints associated with the model.

environment property

environment: Environment

Get the environment in which this model is defined.

metadata property

metadata: ModelMetadata | None

Return metadata for the current Model instance.

If metadata is cached and corresponds to the current hash, returns the cached metadata. Otherwise, retrieves metadata via a client and updates the cache.

Parameters:

Name	Type	Description	Default
self		Instance of Model.	required

Returns:

Type	Description
Optional[ModelMetadata]	Metadata for the current Model instance, or None if an error occurs or metadata cannot be retrieved.

name property

name: str

Return the name of the model.

num_constraints property

num_constraints: int

Return the number of constraints defined in the model.

Returns:

Type	Description
int	Total number of constraints.

objective property

objective: Expression

Get the objective expression of the model.

sense property

sense: Sense

Get the sense of the model

Returns:

Type	Description
Sense	The sense of the model (Min or Max).

__eq__ method descriptor

__eq__(value) -> bool

Return self==value.

__ge__ method descriptor

__ge__(value)

Return self>=value.

__hash__ method descriptor

__hash__() -> int

Return hash(self).

__init__

__init__() -> None

__init__(name: str) -> None

__init__(name: str, *, sense: Sense) -> None

__init__(name: str, *, env: Environment) -> None

__init__(*, sense: Sense) -> None

__init__(*, env: Environment) -> None

__init__(*, sense: Sense, env: Environment) -> None

__init__(name: str, *, sense: Sense, env: Environment) -> None

__init__(
    name: str | None = ...,
    *,
    sense: Sense | None = ...,
    env: Environment | None = ...,
) -> None

Initialize a new symbolic model.

Parameters:

Name	Type	Description	Default
name	str	An optional name for the model.	...
env	Environment	The environment in which the model operates. If not provided, a new environment will be created or inferred from context.	...

__le__ method descriptor

__le__(value)

Return self<=value.

__repr__ method descriptor

__repr__() -> str

Return repr(self).

__str__ method descriptor

__str__() -> str

Return str(self).

add_constraint method descriptor

add_constraint(constraint: Constraint, name: str | None = None) -> None

Add a constraint to the model's constraint collection.

Parameters:

Name	Type	Description	Default
constraint	Constraint	The constraint to be added.	required
name	str	The name of the constraint to be added.	None

add_objective method descriptor

add_objective(expression)

add_variable method descriptor

add_variable(
    name: str,
    vtype: Vtype | None = None,
    lower: float | type[Unbounded] | None = Ellipsis,
    upper: float | type[Unbounded] | None = Ellipsis,
) -> Variable

Add a new variable to the model.

Parameters:

Name	Type	Description	Default
name	str	The name of the variable.	required
vtype	Vtype	The variable type (e.g., Vtype.Real, Vtype.Integer, etc.). Defaults to Vtype.Binary.	None
lower	float | type[Unbounded] | None	The lower bound restricts the range of the variable. Only applicable for Real and Integer variables.	Ellipsis
upper	float | type[Unbounded] | None	The upper bound restricts the range of the variable. Only applicable for Real and Integer variables.	Ellipsis

Returns:

Type	Description
Variable	The variable added to the model.

decode builtin

decode(data: bytes) -> Model

Reconstruct an expression from encoded bytes.

Parameters:

Name	Type	Description	Default
data	bytes	Binary blob returned by encode().	required

Returns:

Type	Description
Expression	Deserialized expression object.

Raises:

Type	Description
DecodeError	If decoding fails due to corruption or incompatibility.

delete_luna

delete_luna(client: ILunaSolve | str | None = None) -> None

Delete the Luna instance of the Model.

Ensure the Model instance is removed properly using the provided client or the default client.

Parameters:

Name	Type	Description	Default
self	Model	The instance of the model to be deleted.	required
client	Optional[Union[ILunaSolve, str]]	The client used to connect to the service. If not provided, the default client is used.	None

Returns:

Type	Description
None

deserialize builtin

deserialize(data: bytes) -> Model

Alias for decode().

See decode() for full documentation.

encode method descriptor

encode(compress: bool | None = True, level: int | None = 3) -> bytes

Serialize the model into a compact binary format.

Parameters:

Name	Type	Description	Default
compress	bool	Whether to compress the binary output. Default is True.	True
level	int	Compression level (0–9). Default is 3.	3

Returns:

Type	Description
bytes	Encoded model representation.

Raises:

Type	Description
IOError	If serialization fails.

equal_contents method descriptor

equal_contents(other)

evaluate method descriptor

evaluate(solution: Solution) -> Solution

Evaluate the model given a solution.

Parameters:

Name	Type	Description	Default
solution	Solution	The solution used to evaluate the model with.	required

Returns:

Type	Description
Solution	A new solution object with filled-out information.

evaluate_sample method descriptor

evaluate_sample(sample: Sample) -> Result

Evaluate the model given a single sample.

Parameters:

Name	Type	Description	Default
sample	Sample	The sample used to evaluate the model with.	required

Returns:

Type	Description
Result	A result object containing the information from the evaluation process.

get_variable method descriptor

get_variable(name: str) -> Variable

Get a variable by its label (name).

Parameters:

Name	Type	Description	Default
label	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.

load_luna

load_luna(model_id: str, client: ILunaSolve | str | None = None) -> Model

Load an AQ model using a specific model ID.

This function retrieves an AQ model from a client obj. The client can either be provided directly or created dynamically if not specified.

Parameters:

Name	Type	Description	Default
model_id	str	The identifier of the model that needs to be loaded.	required
client	Optional[Union[ILunaSolve, str]]	The client to use for loading the model. If not provided, a client will be created automatically.	None

Returns:

Type	Description
Model	The AQ model that was successfully loaded.

load_solutions

load_solutions(client: ILunaSolve | str | None = None) -> list[Solution]

Load solutions for an Model.

Fetch and return the list of all solutions for the patched Model using the provided client or the default client.

Parameters:

Name	Type	Description	Default
self	Model	The Model for which solutions are to be loaded.	required
client	Optional[Union[ILunaSolve, str]]	The client used to interact and retrieve model solutions. If not provided, a default client will be created using the ClientFactory.	None

Returns:

Type	Description
List[IAqSolution]	A list of IAqSolution instances containing the solutions.

load_solve_jobs

load_solve_jobs(client: ILunaSolve | str | None = None) -> list[SolveJob]

Load and return a list of SolveJob objects for the Model instance.

Parameters:

Name	Type	Description	Default
self	Model	The instance of the Model for which solve jobs need to be loaded.	required
client	Optional[Union[ILunaSolve, str]]	The client object or client type for fetching solve jobs, by default None.	None

Returns:

Type	Description
List[SolveJob]	A list of SolveJob objects related to the Model instance.

save_luna

save_luna(client: ILunaSolve | str | None = None) -> None

Save the model and update its metadata and hash.

This function saves the current state of the model using the provided client or default client obtained from ClientFactory. It also updates the local metadata attributes of the model after saving.

Parameters:

Name	Type	Description	Default
self	Model	The instance of the Model class.	required
client	Optional[Union[ILunaSolve, str]]	The client to facilitate saving the model. Can be an instance of ILunaSolve, a string representing the client, or left as None to use the default client.	None

Returns:

Type	Description
None	This function does not return any values.

serialize method descriptor

serialize(compress: bool | None = True, level: int | None = 3) -> bytes

Alias for encode().

See encode() for full documentation.

set_objective method descriptor

set_objective(expression: Expression, sense: Sense | None = None) -> None

Set the model's objective to this expression.

Parameters:

Name	Type	Description	Default
expression	Expression	The expression assigned to the model's objective.	required
sense	Sense	The sense of the model for this objective, by default Sense.Min.	None

set_sense method descriptor

set_sense(sense: Sense) -> None

Set the optimization sense of a model.

Parameters:

Name	Type	Description	Default
sense	Sense	The sense of the model (minimization, maximization)	required

substitute method descriptor

substitute(target: Variable, replacement: Expression | Variable) -> None

Substitute every occurrence of a variable in the model’s objective and constraint expressions with another expression.

Given a Model instance self, this method replaces all occurrences of target with replacement for the objective and each constraint. If any substitution would cross differing environments (e.g. captures from two different scopes), it raises a DifferentEnvsError.

Parameters:

Name	Type	Description	Default
target	VarRef	The variable reference to replace.	required
replacement	Expression	The expression to insert in place of target.	required

Returns:

Type	Description
None	Performs substitution in place; no return value.

Raises:

Type	Description
DifferentEnvsError	If the environments of self, target, and replacement are not compatible.

variables method descriptor

variables(active: bool | None = None) -> list[Variable]

Get all variables that are part of this model.

Parameters:

Name	Type	Description	Default
active	bool	Instead of all variables from the environment, return only those that are actually present in the model's objective.	None

Returns:

Type	Description
The model's variables as a list.

violated_constraints method descriptor

violated_constraints(sample: Sample) -> Constraints

Get all model constraints that are violated by the given sample.

Parameters:

Name	Type	Description	Default
sample	Sample	The sample to check constraint feasibility for.	required

Returns:

Type	Description
Constraints	The constraints violated by the given sample.