Model Sets

Overview

A ModelSet is a named collection of luna-quantum Model objects, persisted to SQLite. Model sets allow you to group related models together, store them across sessions, and reuse them in benchmarking workflows.

The primary class is ModelSet, imported from luna_bench. Each model set has a unique name and contains zero or more models, each tracked via ModelMetadata.

Attribute	Type	Description
`id`	`int`	Auto-assigned database identifier
`name`	`ModelSetName`	Unique name for the model set
`models`	`list[ModelMetadata]`	Collection of models in the set

Creating a Model Set

Use the ModelSet.create class method to create a new, empty model set. The name must be unique across all persisted model sets.

Python

from luna_bench import ModelSet

model_set = ModelSet.create("my-benchmark-set")

Persistence

The model set is immediately persisted to SQLite upon creation. You can close your session and load it later by name.

Adding Models

Models come from the luna-quantum package. You can build them programmatically with its API, restore a serialized one with Model.deserialize, or import them from a common format with one of the built-in translators. Then add them to a model set with model_set.add().

Python

from luna_quantum import Model, Variable, Vtype, Bounds, Unbounded

# Build a model programmatically
model = Model("problem")
with model.environment:
    x = Variable("x", vtype=Vtype.REAL, bounds=Bounds(lower=0, upper=Unbounded))
    y = Variable("y", vtype=Vtype.REAL, bounds=Bounds(lower=0, upper=Unbounded))
model.objective = 3 * x + 2 * y
model.constraints += x + y <= 10

# Add it to the set
model_set.add(model)

Importing from files and other formats

luna-quantum ships translators that turn common optimization formats into a Model. Each translator's to_lm method ("to Luna model") returns a Model you can add directly. LP and MPS come from files; CQM and BQM come from dimod objects.

Python

from luna_quantum.translator import LpTranslator, MpsTranslator, CqmTranslator, BqmTranslator

# From LP / MPS files
model_set.add(LpTranslator.to_lm("problem.lp"))
model_set.add(MpsTranslator.to_lm("problem.mps"))

# From dimod CQM / BQM objects
model_set.add(CqmTranslator.to_lm(cqm))   # dimod ConstrainedQuadraticModel
model_set.add(BqmTranslator.to_lm(bqm))   # dimod BinaryQuadraticModel

You can add multiple models in sequence:

Python

for model in (model_a, model_b, model_c):
    model_set.add(model)

Deduplication by Hash

Models are deduplicated by their hash value. Adding the same model twice to a model set is a no-op: the second call will not create a duplicate entry.

Loading and Reusing Model Sets

Model sets persist in SQLite and can be loaded in any later session.

Load a single model set by name

Python

model_set = ModelSet.load("my-benchmark-set")

List all available model sets

Python

all_sets = ModelSet.load_all()

for ms in all_sets:
    print(f"{ms.name}: {len(ms.models)} model(s)")

List all models across every model set

Python

all_models = ModelSet.load_all_models()

for meta in all_models:
    print(f"Model '{meta.model_name}' (hash: {meta.model_hash})")

Cross-Session Workflows

Because model sets are stored in SQLite, you can create a model set in one script or notebook, then load and use it in a completely separate benchmarking run.

ModelMetadata and Lazy Loading

Each model inside a model set is represented by a ModelMetadata object rather than the full Model instance. This keeps loading lightweight: the actual Model is only constructed when you explicitly request it.

Attribute	Type	Description
`id`	`int`	Database identifier for this entry
`model_name`	`str`	Human-readable name of the model
`model_hash`	`int`	Hash used for deduplication

Accessing the underlying Model

Use the .model property on a ModelMetadata instance to get the full Model object. This triggers a lazy load from the database.

Python

model_set = ModelSet.load("my-benchmark-set")

for meta in model_set.models:
    print(meta.model_name, meta.model_hash)

    # Lazy-load the actual Model object when needed
    full_model = meta.model

Lazy Loading

The .model property performs a database lookup on first access. If you are iterating over a large model set and only need metadata (name, hash), avoid calling .model to keep things fast.

Managing Models

Removing a model from a set

To remove a specific model from a model set, pass the Model object to remove_model():

Python

# pass the Model instance you added earlier
model_set.remove_model(model)

Deleting an entire model set

To permanently delete a model set and all of its associations from the database:

Python

model_set.delete()

Irreversible Operation

Calling delete() permanently removes the model set from SQLite. This action cannot be undone. The underlying Model objects themselves are not destroyed: only the model set and its membership records are removed.