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 (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:

  • ax (Axes | None, default: None ) –

    Matplotlib axes to draw on. Creates a new figure if None.

Returns:

  • Axes –

    The axes with the plot.

to_string() -> str

Return a string describing the data.

Returns:

  • str –

    String representation of the data.

from_values(numbers: list[int]) -> NumberPartitioningData staticmethod

Create a NumberPartitioningData instance from explicit values.

Parameters:

  • numbers (list[int]) –

    1D array of integers to partition.

Returns:

generate_random(n_numbers: int = 8, max_value: int | None = None, seed: int | None = None) -> NumberPartitioningData staticmethod

Generate a random number partitioning instance.

Parameters:

  • n_numbers (int, default: 8 ) –

    Number of integers, by default 8.

  • max_value (int | None, default: None ) –

    Maximum value for each integer, by default None, will be set to 2 * n_numbers.

  • seed (int | None, default: None ) –

    Random seed for reproducibility, by default None.

Returns:

Raises:

  • 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:

Returns:

  • 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:

Returns:

  • Model –

    A LunaModel ready to be solved.

interpret(solution: Solution, data: NumberPartitioningData) -> NumberPartitioningSolution staticmethod

Extract solution from quantum result.

Parameters:

Returns:

Solution

Solution model for NumberPartitioning use case.

NumberPartitioningSolution

Bases: UcSolution

Solution for the Number Partitioning Problem.

Attributes:

  • 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:

  • data (NumberPartitioningData | None, default: None ) –

    Problem data for context.

  • ax (Axes | None, default: None ) –

    Matplotlib axes to draw on. Creates a new figure if None.

Returns:

  • Axes –

    The axes with the plot.

to_string() -> str

Return a string describing the solution.

Returns:

  • 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:

  • min_n_numbers (int | None, default: None ) –

    Minimum number of integers per instance.

  • max_n_numbers (int | None, default: None ) –

    Maximum number of integers per instance.

  • num_instances (int, default: 1 ) –

    Number of instances per size, by default 1.

  • max_value (int | None, default: None ) –

    Maximum value for each integer, by default 2 * n_numbers.

  • seed (int | None, default: None ) –

    Random seed for reproducibility, by default None.

  • sizes (Sequence[int] | None, default: None ) –

    Explicit sizes to generate, e.g. [10, 50, 100], instead of a range. Mutually exclusive with min_n_numbers/max_n_numbers, by default None.

Returns:

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:

  • max_runtime (float, default: 3600 ) –

    SCIP time limit per instance in seconds. Must be positive. Defaults to 3600 seconds.

  • quiet (bool, default: True ) –

    Suppress the SCIP solver output.

Returns:

  • list[bool] –

    Feasibility mask over the instances as they were before filtering, in that order: True where the instance was kept, False where it was removed.

Raises: