Welcome to packingsolver3d
Overview
packingsolver3d is an unofficial Python distribution of 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; every solve runs in-process and copies its result back into plain Python values, so no Python object ever owns solver memory. The package is maintained independently of PackingSolver and is not endorsed by its author; the solvers themselves are built unmodified from a pinned upstream commit.
Key Features
Value-in / value-out API built on frozen dataclasses:
Instancegoes in,Resultcomes outTwo solvers, one model:
packingsolver3d.boxfor plain 3D packing,packingsolver3d.boxstacksfor stacks, weights, trucks, unloading order and defectsHonest statuses: a solver-reported bound is never relabelled as a proven optimum;
OPTIMALmeans the achieved value met the reported boundAuditable runs: every result carries the exact options handed to upstream, upstream’s captured log and the wall time
Upstream’s own limits:
time_limitandmemory_limitgo to the solver’s timer and memory checkPrebuilt wheels for Linux, macOS and Windows on x86_64 and arm64, CPython 3.7 through 3.14 where the platform has one
Quick Start
pip install packingsolver3d
from packingsolver3d import ALL_ROTATIONS, BinType, Instance, ItemType, Objective, box
from packingsolver3d.visual import plot_result # pip install "packingsolver3d[plot]"
luggage = { # name: (x, y, z, value, copies) -- a 55 x 40 x 23 cm carry-on and what you would like to take
'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),
}
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 -- everything but the jacket
plot_result(result, title='What fits in the carry-on').show()
The full walkthrough is Quick start: what fits in the carry-on; the behaviours inherited from upstream that you should know before trusting a number are collected in Upstream behaviours you should know.
Architecture
Package root (
packingsolver3d): re-exports the model, result and error types plus the two solver modulesSolver modules (
packingsolver3d.box,packingsolver3d.boxstacks): onesolvefunction each, mirroring upstream’s parametersNative bridge (
packingsolver3d._core): upstreamboxandboxstacksplus the pybind11 glue, one extension moduleMetadata (
packingsolver3d.config): package version, pinned upstream commit and build options
Upstream and Source
GitHub Repository: https://github.com/HansBug/packingsolver3d
PackingSolver Upstream: https://github.com/fontanf/packingsolver
Tutorials
Tutorials are learning paths with one observable success each. The roadmap explains the reading order; the pages follow it.
How-to Guides
How-to guides are task pages for readers who already know what they want to do.
Explanations
Explanations give the reasoning behind the design and the upstream behaviours that shape results.
Benchmarks
A small, reproducible capability study on three public instance families, next to the open-source 3D packing libraries commonly used from Python, Go and Rust and two exact reference codes, with every solution re-validated and drawn.
Reference
Reference pages state facts: fields, options, errors, and the generated API map.
API Documentation
This page is the generated Python API map for packingsolver3d. It belongs to the Reference section: use it when you already know which module, class, function, or data object you need to inspect.
If you are choosing a workflow, or looking up how a model field, a solver option or an error maps to upstream PackingSolver, start from Reference map; it points to the focused reference pages before this complete API map.
Modules whose name starts with an underscore are internals and
documented for contributors; the public surface is re-exported
from packingsolver3d itself.
The toctree below is generated from packingsolver3d/ by
make rst_auto and should remain the infrastructure-backed
module tree.