to_constant_volume_bins

torch_sim.autobatching.to_constant_volume_bins(items, max_volume, *, weight_pos=None, key=None, lower_bound=None, upper_bound=None)[source]

Distribute items into bins of fixed maximum volume.

Groups items into the minimum number of bins possible while ensuring each bin’s total weight does not exceed max_volume. Items are sorted by weight in descending order before binning to improve packing efficiency.

Upstreamed from binpacking by @benmaier. https://pypi.org/project/binpacking/.

Parameters:

  • items (dict[int, float] | list[float] | list[tuple]) – Items to distribute, provided as either: - Dictionary with numeric weights as values - List of numeric weights - List of tuples containing weights (requires weight_pos or key)

  • max_volume (float) – Maximum allowed weight sum per bin.

  • weight_pos (int | None) – For tuple lists, index of weight in each tuple. Defaults to None.

  • key (callable | None) – Function to extract weight from list items. Defaults to None.

  • lower_bound (float | None) – Exclude items with weights below this value. Defaults to None.

  • upper_bound (float | None) – Exclude items with weights above this value. Defaults to None.

Returns:

List of bins, where each bin contains items of the same type as input: - List of dictionaries if input was a dictionary - List of lists if input was a list of numbers - List of lists of tuples if input was a list of tuples

Return type:

list[dict[int, float]] | list[list[float]] | list[list[tuple]]

Raises:

  • TypeError – If input is not iterable.

  • ValueError – If weight_pos or key is not provided for tuple list input, or if lower_bound >= upper_bound.