Built-in Features

VarNumberFeature

Bases: BaseFeature[VarNumberFeatureResult]

Fake feature class.

`run(model: Model) -> VarNumberFeatureResult`

Fake feature which will return a random number.

Parameters:

model (Model) –

The model for which the feature should be calculated

OptSolFeature

Bases: BaseFeature[OptSolFeatureResult]

Feature that computes the optimal (or best feasible) solution for optimization models.

This feature translates a Luna-Model to LP format and solves it using the SCIP mixed-integer programming solver. It can be configured with a maximum runtime to obtain upper bounds for computationally expensive problems.

Attributes:

max_runtime ((int | None, optional)) –

Maximum solver runtime in seconds. If None (default), the solver runs until optimality is proven or infeasibility is detected. If set, the solver may return a suboptimal solution marked with pre_terminated=True.

Raises:

InfeasibleModelError –

If the model has no feasible solution.

Requires

Install the 'pre-defined' extra: pip install luna-bench[pre-defined]

Examples:

>>> # Solve to optimality (no time limit)
>>> feature = OptSolFeature()
>>> result = feature.run(model)
>>> print(f"Optimal value: {result.global_best_sol}")

>>> # Get best solution within 60 seconds
>>> feature = OptSolFeature(max_runtime=60)
>>> result = feature.run(model)
>>> if result.pre_terminated:
...     print(f"Upper bound: {result.global_best_sol}")
... else:
...     print(f"Optimal value: {result.global_best_sol}")

`run(model: Model) -> OptSolFeatureResult`

Calculate the optimal solution for the given model, or at least get an upper bound.

This method performs the following steps: 1. Translates the Luna Quantum model to LP format via a temporary file 2. Reads the LP file into a SCIP solver instance 3. Configures the time limit (if specified) 4. Solves the optimization problem 5. Returns the best objective value and termination status

Parameters:

model (Model) –

The model for which the feature should be calculated

Returns:

OptSolFeatureResult –

Contains the best objective value found and whether the solver terminated early due to time limit.

Notes

For large or difficult problems, consider setting max_runtime to avoid excessive computation time
When pre_terminated is True, the returned best_sol is an upper bound (for minimization) or lower bound (for maximization) on the optimal value

MIP Features

ProblemSizeFeatures

Bases: BaseFeature[ProblemSizeFeaturesResult]

Feature extractor for problem size-related characteristics.

Extracts features related to the number and types of variables, constraints, and the sparsity of constraint matrices. Includes both absolute counts and fractional values, as well as statistical metrics related to variable support sizes.

`run(model: Model) -> ProblemSizeFeaturesResult`

Calculate problem size features for the given optimization model.

Computes various metrics including variable counts by type, constraint counts, matrix sparsity measures, and support size statistics for bounded variables.

Parameters:

model (Model) –

The optimization model for which the features should be calculated.

Returns:

ProblemSizeFeaturesResult –

Container with problem size metrics.

LinearConstraintMatrixFeatures

Bases: BaseFeature[LinearConstraintMatrixFeaturesResult]

Feature extractor for linear constraint matrix properties.

Extracts statistical features related to variable coefficients, constraint coefficients, and the distribution of constraint matrix entries. Includes both continuous and non-continuous features, as well as normalized and variation coefficient metrics.

`run(model: Model) -> LinearConstraintMatrixFeaturesResult`

Calculate linear constraint matrix features.

Computes various statistics for the constraint matrix including coefficient sums, normalized entries, and variation coefficients, grouped by variable type.

Parameters:

model (Model) –

The optimization model for which the features should be calculated.

Returns:

LinearConstraintMatrixFeaturesResult –

Container with constraint matrix statistical measures.

ObjectiveFunctionFeature

Bases: BaseFeature[ObjectiveFunctionFeatureResult]

Feature extractor for objective function coefficient statistics.

Extracts statistical features (mean, std) of objective function coefficients for continuous, non-continuous, and all variable types. Includes raw absolute values as well as normalized and square-root-normalized versions.

`run(model: Model) -> ObjectiveFunctionFeatureResult`

Calculate statistical features of objective function coefficients.

Computes mean and standard deviation of absolute objective function coefficients for continuous, non-continuous, and all variable types. Also calculates these statistics for normalized and square-root-normalized coefficient values.

Parameters:

model (Model) –

The optimization model for which the features should be calculated.

Returns:

ObjectiveFunctionFeatureResult –

Container with statistical measures of objective function coefficients.

RightHandSideFeatures

Bases: BaseFeature[RightHandSideFeaturesResult]

Feature extractor for right-hand side values of constraints.

Extracts statistical features (mean and standard deviation) for the RHS values of different constraint types: less-than-or-equal (<=), equality (==), and greater-than-or-equal (>=) constraints.

`run(model: Model) -> RightHandSideFeaturesResult`

Calculate right-hand side statistical features for constraints.

Computes mean and standard deviation of RHS values grouped by constraint sense (<=, ==, >=).

Parameters:

model (Model) –

The optimization model for which the features should be calculated.

Returns:

RightHandSideFeaturesResult –

Container with RHS statistical measures for each constraint type.

VariableConstraintGraphFeatures

Bases: BaseFeature[VariableConstraintGraphFeaturesResult]

Feature extractor for variable-constraint graph properties.

Calculates node degree statistics for variables and constraints in the bipartite graph representation of an optimization model. Computes statistics separately for continuous and non-continuous variables/constraints.

`run(model: Model) -> VariableConstraintGraphFeaturesResult`

Calculate variable-constraint graph features.

Computes node degree statistics (mean, median, variation coefficient, and quantiles) for variables and constraints, grouped by variable type.

Parameters:

model (Model) –

The optimization model for which the features should be calculated.

Returns:

VariableConstraintGraphFeaturesResult –

Container with graph-based statistical measures.

QUBO Features

QuboGraphFeature

Bases: BaseFeature[QuboGraphFeatureResult]

Extract graph-based features from QUBO models.

Compute graph-theoretic features from the QUBO matrix by constructing a weighted graph via networkx.from_numpy_array and analysing its topology.

Extracted features include:

Connectivity: Average degree distribution, average clustering coefficient, number of connected components, and average path length.
Robustness: Graph density, number of bridges, and number of articulation points.

Attributes:

include_self_loops (bool) –

Whether to include diagonal elements (self-loops) in the graph analysis. If False (default), diagonal entries are zeroed out before constructing the graph, analyzing only variable interactions. If True, linear terms are included as self-loops, which affects degree calculations and other metrics.

Requires

Install the 'pre-defined' extra: pip install luna-bench[pre-defined]

`run(model: Model) -> QuboGraphFeatureResult`

Compute graph-based features for the given model.

Parameters:

model (Model) –

The optimization model to extract features from.

Returns:

QuboGraphFeatureResult –

A result object containing the computed graph features.

QuboMatrixFeature

Bases: BaseFeature[QuboMatrixFeatureResult]

Extract statistical matrix features from QUBO models.

Compute descriptive statistics over all entries of the QUBO matrix.

Extracted features include:

Central tendency / dispersion: Mean, median, variance, standard deviation, minimum, and maximum.
Shape: Skewness and kurtosis of the flattened matrix.
Quantiles: 10th and 90th percentiles (q10, q90) and the variation coefficient (vc).

`run(model: Model) -> QuboMatrixFeatureResult`

Compute matrix statistical features for the given model.

Parameters:

model (Model) –

The optimization model to extract features from.

Returns:

QuboMatrixFeatureResult –

A result object containing the computed matrix statistics.

QuboSparsityDensityFeature

Bases: BaseFeature[QuboSparsityDensityFeatureResult]

Extract sparsity and density features from QUBO models.

Compute structural features describing the fill pattern of the QUBO matrix.

Extracted features include:

Ratios: Sparsity and density of the matrix.
Counts: Number of zero and non-zero entries.
Size: Number of variables (matrix dimension).

`run(model: Model) -> QuboSparsityDensityFeatureResult`

Compute sparsity and density features for the given model.

Parameters:

model (Model) –

The optimization model to extract features from.

Returns:

QuboSparsityDensityFeatureResult –

A result object containing the computed sparsity/density features.

QuboSpectralAnalysisFeature

Bases: BaseFeature[QuboSpectralAnalysisFeatureResult]

Extract spectral analysis features from QUBO models.

Decompose the QUBO matrix with numpy.linalg.eigh and compute descriptive statistics over eigenvalues and eigenvectors.

Extracted features include:

Eigenvalue statistics: Mean, median, std, variation coefficient, q10, q90, minimum, maximum, and dominant (largest absolute) eigenvalue.
Eigenvector statistics: Same set of statistics computed over all eigenvector components.
Condition number: Ratio of largest to smallest singular value, indicating numerical stability.

`run(model: Model) -> QuboSpectralAnalysisFeatureResult`

Compute spectral analysis features for the given model.

Parameters:

model (Model) –

The optimization model to extract features from.

Returns:

QuboSpectralAnalysisFeatureResult –

A result object containing the computed spectral features.