packingsolver3d

Pythonic bindings for the two three-dimensional solvers of PackingSolver, box and boxstacks. The upstream C++ is compiled together with a thin pybind11 bridge into one extension module, so a wheel install needs no compiler and every solve runs in-process.

Unofficial distribution. This project is maintained independently of PackingSolver and is not endorsed by its author. The solvers are built unmodified from the upstream commit recorded in packingsolver3d/config/meta.py; see NOTICE.md for the exact build configuration and licensing.

Installation

pip install packingsolver3d

Wheels are published for Linux (x86_64, aarch64), macOS (x86_64, arm64) and Windows (AMD64, ARM64), for every CPython the platform has an official build of: 3.7 through 3.14 on Linux x86_64 and Windows AMD64, 3.8 through 3.14 on Linux aarch64 and macOS, 3.11 through 3.14 on Windows ARM64. No compiler is needed for a wheel install. Other architectures (i686, ppc64le, s390x, armv7l, riscv64, loongarch64) are not built as wheels; pip falls back to the sdist there. Installing from the sdist compiles PackingSolver and the bridge from the vendored sources and needs a C++17 compiler, git, network access for upstream's FetchContent dependencies and CMake 3.28 or newer (installed into the build environment by pip where a cmake wheel exists). The optional plotting extra pulls in plotly:

pip install "packingsolver3d[plot]"

Quick start

A 55 x 40 x 23 cm carry-on, the things you would like to take and how much you want each of them. The solver picks the subset with the highest total value that really fits, places every piece, and the result draws itself:

from packingsolver3d import ALL_ROTATIONS, BinType, Instance, ItemType, Objective, box
from packingsolver3d.visual import plot_result       # needs the plot extra

luggage = {  # name: (x, y, z, value, copies)
    'laptop': (36, 25, 3, 10, 1), 'camera': (15, 10, 8, 9, 1), 'shoes': (30, 20, 12, 8, 1),
    'jacket': (35, 20, 15, 6, 1), 'sweater': (30, 25, 8, 5, 2), 'toiletry bag': (25, 12, 10, 4, 1),
    'hair dryer': (22, 9, 20, 3, 1), 'book': (24, 16, 4, 3, 4), 'souvenir': (10, 10, 10, 2, 6),
    'water bottle': (8, 8, 25, 1, 1),
}
names = list(luggage)
instance = Instance(
    bin_types=[BinType(x=55, y=40, z=23)],
    item_types=[ItemType(x=x, y=y, z=z, profit=value, copies=n, rotations=ALL_ROTATIONS)
                for x, y, z, value, n in luggage.values()],
    objective=Objective.KNAPSACK,                       # maximise the value of what fits
)
result = box.solve(instance, time_limit=3.0)

print(result.status, result.value, result.bound)         # Status.FEASIBLE 69.0 72.0
packed = [0] * len(names)
for placement in result.placements:
    packed[placement.item_type_id] += 1
for name, count in zip(names, packed):
    print(f'{name:13s} {count}/{luggage[name][4]}' + ('' if count == luggage[name][4] else '   <- left out'))

plot_result(result, title='What fits in the carry-on').show()   # rotate, zoom, hover a box for its item type

Status.FEASIBLE 69.0 72.0
laptop        1/1
camera        1/1
shoes         1/1
jacket        0/1   <- left out
sweater       2/2
toiletry bag  1/1
hair dryer    1/1
book          4/4
souvenir      6/6
water bottle  1/1

Everything but the jacket fits, for a value of 69 out of 75. result.bound is what the solver proved: no packing is worth more than 72, so the status stays FEASIBLE rather than OPTIMAL -- the package never relabels a good incumbent as a proven optimum. The figure is interactive in the documentation; on another machine the anytime search may leave a different low-value item out.

Stacking rules, weights, trucks and unloading order switch the engine to boxstacks:

from packingsolver3d import BinType, Instance, ItemType, Objective, boxstacks

pallets = Instance(
    bin_types=[BinType(x=100, y=100, z=100, cost=10, copies=5, maximum_weight=1000)],
    item_types=[ItemType(x=20, y=30, z=40, copies=6, weight=5,
                         stackability_id=0, maximum_stackability=3, maximum_weight_above=100)],
    objective=Objective.BIN_PACKING,
)
result = boxstacks.solve(pallets, time_limit=2.0)
print(result.status, result.number_of_bins, len(result.bins[0].stacks))   # Status.OPTIMAL 1 3

Passing that instance to box.solve raises UnsupportedFeatureError instead of silently dropping the stacking fields, which is what the upstream CSV reader would do. Every result can be drawn with plot_result(result, color_by='stack'); see the visualisation guide.

Long solves can be watched, and stopped, through progress_callback: it is called with a ProgressEvent (time, items, bins, profit, cost, upstream's label) on every improvement, and returning False ends the solve with the current incumbent (result.run.stop_reason == 'callback'). stop_when_unimproved_for=10.0 ends an anytime solve once ten seconds have passed without a new incumbent (stop_reason == 'unimproved'), which is the termination anytime search normally needs on top of a time limit. See the budgets guide.

Not sure how long to wait? recommend_time_budget(instance, solver='box') returns a TimeBudget -- a time_limit that is a loose upper bound plus matching stop_when_unimproved_* knobs -- from a model fitted on 3158 recorded improvement curves, one formula per upstream algorithm path (algorithm_path tells you which one your instance takes). alpha weighs quality against waiting (4 balanced, 8 thorough; the default is 4 for box and 8 for boxstacks); speed rescales for your machine. Pass **budget.as_options() to solve. The model, a replay of stopping policies (time limit only, stagnation only, both) and guidance for applications are in the docs under Explanations / How the time budget is estimated.

Scope

PackingSolver covers several problem families. This package deliberately exposes only the two 3D ones:

rectangle, rectangleguillotine, onedimensional and irregular are out of scope; use upstream directly for those.

box: ten items in one bin	boxstacks: two item types, coloured by stack
box: four item types over several bins	boxstacks: a semi-trailer truck, axle limits leave one item out

The figures are real solves drawn with packingsolver3d.visual (optional dependency plotly, pip install "packingsolver3d[plot]"), the same drawing upstream's scripts/visualize_box.py produces; in the documentation they are interactive.

Benchmarks

A reproducible capability study is part of the documentation: 97 cases from three public instance families with known or proven optima (all twenty 20-item Egeblad-Pisinger 3D knapsack instances, thirty Martello-Pisinger-Vigo generator class-9 instances of 30, 60 and 90 items cut from exactly three bins, and all 47 Ivancic-Mathur-Mohanty THPACK9 loading instances), run through box.solve with a 10 s time limit next to py3dbp, jerry800416/3D-bin-packing, gedex/bp3d, the five 3D strategies of U-Nesting, an exact CP-SAT model and the Martello-Pisinger-Vigo branch-and-bound as references. Every solution, ours and third-party, is re-validated by an independent geometry checker and every objective is recomputed from the placements. Totals over all cases; a smaller gap is better:

packingsolver3d: three bins, proven optimal	py3dbp: four bins, rotation relaxed

The pictures above are static previews because GitHub cannot run plotly; the gallery in the documentation has the same scenes as rotatable, zoomable figures for our solution and four or five other participants on one case of each benchmark. The instances are small and constraint-free, each number is a single run, and the greedy libraries were designed for speed rather than optimality, so this is a capability study, not a ranking of packing software. Sources, versions, the protocol, the complete per-case tables (roster, cases and bounds, leaderboards, items placed, times) and the gallery are in the benchmark section of the documentation; make benchmarks regenerates everything from tools/make_benchmarks.py.

Design

• Value in, value out. Public types are frozen dataclasses. There is no live solver handle, mutable session or callback; each solve call builds the upstream instance, runs optimize() and copies the best solution back into Python values.
• No Python object owns C++ memory. The bridge in packingsolver3d/_core.cpp takes plain dicts and returns plain dicts; no upstream object outlives the call.
• Auditable. Result.run records the problem type, the exact options handed to upstream, upstream's captured log and the wall time.
• Honest statuses. OPTIMAL requires a solver-reported bound for the requested objective and an achieved value meeting it; otherwise the result is FEASIBLE, however good it looks.
• Thread-friendly. The GIL is released while upstream runs and its log is collected through a per-call stream, not by redirecting std::cout, so several threads may solve at once (sixteen concurrent solves are in the test suite).
• In-process, by design. time_limit and memory_limit are upstream's own checks. There is no process boundary: a crash inside upstream takes the interpreter with it, so callers who need isolation run solve in a worker process of their own.

Behaviours inherited from upstream

packingsolver3d is a faithful binding: it does what PackingSolver does at the pinned commit and does not paper over it. These points were found while building the package; each is backed by an upstream source location or a reproducible observation, and the documentation page Upstream behaviours you should know carries the details.

• The LP backend is HiGHS and is always set. Upstream defaults the name to CLP and throws "no linear programming solver found" once column generation starts; the bundled build has HiGHS only.
• copies_min defaults to "all copies". Upstream's -1 means every copy is mandatory (none under knapsack); an explicit 0 makes an empty packing the correct bin-packing optimum. ItemType.copies_min is therefore None unless you mean a minimum.
• boxstacks groups stacks by (group_id, stackability_id) without checking footprints, and its solution builder then throws. boxstacks.validate refuses such instances up front with StackSemanticsError; give differently shaped items different stackability_id values.
• boxstacks keeps items upright. Only the XYZ and YXZ rotations are placed; item types allowing neither are refused with UnsupportedFeatureError. box places all six rotations.
• boxstacks accepts floor defects but places stacks over them at the pinned commit (observed with corner, interior and full-width defects). defects are forwarded faithfully; do not rely on them being avoided.
• Limits are upstream's own checks and the solver runs in-process. time_limit and memory_limit are checked at algorithm checkpoints; there is no hard memory limit and a crash inside upstream ends the interpreter. The budgets guide shows the worker-process pattern that restores both.
• Anytime mode runs until it is stopped. In ANYTIME mode (the default) the search ends only on the time limit, a stop signal or a proof of optimality; box widens its tree search without bound and, since the pinned commit (fontanf/packingsolver#578), so does the single-bin algorithm of boxstacks, which in exchange no longer reports a truncated pass when the limit is short. Always pass time_limit to anytime solves; without one they do not return on instances that do not pack fully (fontanf/packingsolver#580).
• Unset profit and cost default to geometry: item profit to x * y * z, bin cost to x * y (an area).
• The default objective produces no solution. It is upstream's unset placeholder, so Instance requires an explicit objective and Objective.DEFAULT is refused with InvalidInstanceError.
• OPTIMAL is only reported when the achieved value meets a bound upstream reported for that objective; otherwise the result is FEASIBLE, however good it looks. Keep value and bound as two columns when you publish numbers.

Supported platforms

Windows on ARM and older Pythons. CPython 3.7 and 3.8 never had a Windows ARM64 build at all. 3.9 and 3.10 exist for ARM64 only as python.org's pythonarm64 nuget package (marked experimental at the time, meant for embedding and CI): there was no installer and no Store package before 3.11, and the CI toolchain (actions/setup-python) provides ARM64 hosts from 3.11 on. Wheels for 3.9/3.10 on Windows ARM64 are deliberately not built: the scientific stack does not ship them either (numpy and scipy start at 3.12, pandas at 3.11), 3.9 is end-of-life and 3.10 reaches end-of-life in October 2026, and users of those interpreters on ARM hardware almost always run the x64 build under emulation, which the AMD64 wheels cover. On such a machine pip falls back to the sdist, which builds with the MSVC ARM64 toolchain.

Development

git clone --recursive https://github.com/HansBug/packingsolver3d.git
cd packingsolver3d
pip install -r requirements-build.txt -r requirements-test.txt -r requirements-cov.txt -r requirements-plot.txt
make build      # compile upstream + the pybind11 bridge into packingsolver3d/_core
make unittest   # pytest + docstring examples, with coverage
make doctest    # only the docstring examples (pytest --doctest-modules)
LINETRACE=1 make build && make unittest   # coverage.xml then also covers the C++ bridge
make rst_auto   # regenerate API reference pages
make docs       # sphinx html
make package    # sdist + wheel
make try_sdist  # install the sdist from source in a clean docker image and run the unit tests there

make help lists every target; RANGE_DIR=<subdir> narrows unittest and rst_auto to one directory.

License

This repository is released under the MIT License. PackingSolver is released under the MIT License, reproduced in LICENSE-packingsolver.