Number Partitioning API Reference
Data
Data model for NumberPartitioning use case.
NumberPartitioningData
Bases: UcData
Data for the Number Partitioning Problem.
Given a set of integers, the Number Partitioning problem asks to divide them into two subsets such that the difference of their sums is minimized.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
Literal['number_partitioning']
|
Identifier for this data type. |
numbers |
NumPyArray
|
1D array of integers to partition. |
plot(*, ax: Axes | None = None) -> Axes
Plot the numbers as a bar chart.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ax
|
Axes | None
|
Matplotlib axes to draw on. Creates a new figure if |
None
|
Returns:
| Type | Description |
|---|---|
Axes
|
The axes with the plot. |
to_string() -> str
Return a string describing the data.
Returns:
| Type | Description |
|---|---|
str
|
String representation of the data. |
from_values(numbers: list[int]) -> NumberPartitioningData
staticmethod
Create a NumberPartitioningData instance from explicit values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
numbers
|
list[int]
|
1D array of integers to partition. |
required |
Returns:
| Type | Description |
|---|---|
NumberPartitioningData
|
A NumberPartitioningData instance with the given values. |
generate_random(n_numbers: int = 8, max_value: int | None = None, seed: int | None = None) -> NumberPartitioningData
staticmethod
Generate a random number partitioning instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_numbers
|
int
|
Number of integers, by default 8. |
8
|
max_value
|
int | None
|
Maximum value for each integer, by default None, will be set to 2 * n_numbers. |
None
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
Returns:
| Type | Description |
|---|---|
NumberPartitioningData
|
A randomly generated number partitioning instance. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If n_numbers > max_value, which makes distinct sampling impossible. |
Formulation
Formulation for NumberPartitioning use case.
NumberPartitioningFormulation
Bases: UcFormulation[NumberPartitioningData, NumberPartitioningSolution]
Quadratic formulation for the Number Partitioning Problem.
Mathematical Formulation
Decision Variables:
x_i in {0,1} for each number i: 1 if number i is in partition 1
Objective:
minimize (2 * sum_i numbers[i]*x[i] - S)^2
where S = sum(numbers)
Expanded: sum_{i,j} numbers[i]*numbers[j]*x[i]*x[j]
- S * sum_i numbers[i]*x[i]
(constant S^2 omitted)
Constraints:
None (unconstrained quadratic optimization)
to_string(data: NumberPartitioningData) -> str
staticmethod
Return a string describing the formulation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
NumberPartitioningData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
str
|
String representation of the formulation. |
formulate(data: NumberPartitioningData) -> Model
staticmethod
Formulate the Number Partitioning Problem.
Uses a quadratic objective to minimize the squared difference between partition sums. No constraints are needed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
NumberPartitioningData
|
The Number Partitioning instance data. |
required |
Returns:
| Type | Description |
|---|---|
Model
|
A LunaModel ready to be solved. |
interpret(solution: Solution, data: NumberPartitioningData) -> NumberPartitioningSolution
staticmethod
Extract solution from quantum result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solution
|
Solution
|
The quantum solution. |
required |
data
|
NumberPartitioningData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
NumberPartitioningSolution
|
Structured solution with metrics. |
Solution
Solution model for NumberPartitioning use case.
NumberPartitioningSolution
Bases: UcSolution
Solution for the Number Partitioning Problem.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
Literal['number_partitioning']
|
Identifier for this solution type. |
partition_0 |
list[int]
|
Numbers assigned to partition 0. |
partition_1 |
list[int]
|
Numbers assigned to partition 1. |
sum_0 |
int
|
Sum of numbers in partition 0. |
sum_1 |
int
|
Sum of numbers in partition 1. |
difference |
int
|
Absolute difference between partition sums. |
is_valid |
bool
|
Whether the difference is 0 (perfect partition). |
plot(data: NumberPartitioningData | None = None, *, ax: Axes | None = None) -> Axes
Plot the number partitioning solution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
NumberPartitioningData | None
|
Problem data for context. |
None
|
ax
|
Axes | None
|
Matplotlib axes to draw on. Creates a new figure if |
None
|
Returns:
| Type | Description |
|---|---|
Axes
|
The axes with the plot. |
to_string() -> str
Return a string describing the solution.
Returns:
| Type | Description |
|---|---|
str
|
String representation of the solution. |
Instance
Instance model for NumberPartitioning use case.
NumberPartitioningInstance
Bases: UcInstance[NumberPartitioningData, NumberPartitioningFormulation, NumberPartitioningSolution]
Instance combining data and formulation for NumberPartitioning.
Collection
Collection of NumberPartitioning instances.
NumberPartitioningCollection
Bases: UcInstanceCollection[NumberPartitioningInstance]
Collection of Number Partitioning instances.
This collection provides methods to generate benchmark instances with various characteristics for testing and evaluation.
from_random(min_n_numbers: int | None = None, max_n_numbers: int | None = None, num_instances: int = 1, *, sizes: Sequence[int] | None = None, max_value: int | None = None, seed: int | None = None) -> NumberPartitioningCollection
classmethod
Generate random number partitioning instances.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
min_n_numbers
|
int | None
|
Minimum number of integers per instance. |
None
|
max_n_numbers
|
int | None
|
Maximum number of integers per instance. |
None
|
num_instances
|
int
|
Number of instances per size, by default 1. |
1
|
max_value
|
int | None
|
Maximum value for each integer, by default 2 * n_numbers. |
None
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
sizes
|
Sequence[int] | None
|
Explicit sizes to generate, e.g. |
None
|
Returns:
| Type | Description |
|---|---|
NumberPartitioningCollection
|
Collection containing generated instances. |
filter_infeasible(max_runtime: float = 3600, *, quiet: bool = True) -> list[bool]
Drop the instances of this collection that have no feasible solution.
Every instance is formulated and handed to SCIP, which stops as soon as
it finds the first feasible solution. An instance is removed from the
collection when SCIP proves the model infeasible, when no solution turns
up within max_runtime, or when formulating it fails altogether. This
keeps randomly generated instances from breaking a downstream pipeline.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_runtime
|
float
|
SCIP time limit per instance in seconds. Must be positive. Defaults to 3600 seconds. |
3600
|
quiet
|
bool
|
Suppress the SCIP solver output. |
True
|
Returns:
| Type | Description |
|---|---|
list[bool]
|
Feasibility mask over the instances as they were before filtering,
in that order: |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |