Skip to content

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.

 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 Luna Model 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.

 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, max_n_numbers: int, num_instances: int = 1, *, 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

Minimum number of integers per instance.

 required
max_n_numbers int

Maximum number of integers per instance.

 required
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

Returns:

Type Description
NumberPartitioningCollection

Collection containing generated instances.