Upstream behaviours you should know
packingsolver3d is a faithful binding: it does what upstream PackingSolver does at the pinned commit, and it does not paper over upstream’s choices. The behaviours below were found while building the package, each is backed by the upstream source location or a reproducible observation, and each says what the package does about it. If you rely on one of them, check this page again after the submodule moves.
The LP backend is fixed to HiGHS
Upstream. OptimizeParameters::linear_programming_solver_name defaults to CLP; the factory that resolves the name is a chain of #if <backend>_FOUND guards ending in a bare throw (“no linear programming solver found”). The bundled build compiles HiGHS only. Small instances never reach column generation and hide the problem.
Package. Every call sets the solver name to HiGHS; linear_programming_solver exists as an override only for custom builds.
copies_min defaults to “all copies”
Upstream. InstanceBuilder::build resolves an item type’s copies_min == -1 to copies for every objective except knapsack, where it becomes 0. An explicit copies_min = 0 therefore makes bin packing return zero bins as the true optimum.
Package. ItemType.copies_min is None by default and then left to upstream. Set it only when you mean “at least this many copies”.
boxstacks groups stacks without comparing footprints
Upstream. tree_search.cpp buckets item types by (group_id, stackability_id) alone; SolutionBuilder::add_item later throws when an item’s footprint does not match the stack it was put in. Both ids default to 0, so two item shapes in a plain instance already trigger it.
Package. packingsolver3d.boxstacks.validate() raises StackSemanticsError when two item types share a bucket but have no footprint in common over their allowed rotations. Give differently shaped items different stackability_id values.
boxstacks keeps items upright
Upstream. The sequential one-dimensional / rectangle phase only ever picks XYZ or YXZ (sequential_onedimensional_rectangle.cpp), and the tree search takes heights from z(Rotation::XYZ). An item type allowing only side rotations ends in SolutionBuilder::add_item throwing “forbidden rotation”.
Package. packingsolver3d.boxstacks.validate() raises UnsupportedFeatureError for item types whose rotations include neither XYZ nor YXZ. The box solver places all six rotations.
boxstacks accepts defects but places stacks over them
Observation. At the pinned commit, instances with a floor Defect in a corner, in the interior, or spanning the full bin width all produced stacks overlapping the defect; upstream’s certificate lists the defect, its search treats it as an insertion anchor, and no overlap check rejects the placement. This is upstream behaviour, not a translation error: the package’s tests only assert that such instances are accepted.
Package. defects are forwarded faithfully. Do not rely on them being avoided until upstream changes; the docstring of packingsolver3d.boxstacks.solve() repeats this.
The box model has no stacking, defects or unloading
Upstream. The box solver knows bins, items, rotations and weight capacity. Its readers ignore unknown columns without a diagnostic.
Package. packingsolver3d.box.validate() raises UnsupportedFeatureError when an instance carries stacking fields, defects or an unloading constraint, instead of solving a different problem in silence. Use packingsolver3d.boxstacks.solve() for those.
Limits are upstream’s, and the solver runs in-process
Upstream. time_limit feeds upstream’s timer, checked at algorithm checkpoints; memory_limit feeds memory_limit_megabytes, compared against the resident size at checkpoints.
Package. Both are forwarded as-is. There is no wall-clock kill and no hard address-space limit, and a crash inside upstream ends the interpreter. Budgets, algorithm switches and batch runs shows the worker-process pattern that restores hard limits and crash containment when you need them.
Item profit and bin cost default to geometry
Upstream. An unset item profit becomes x * y * z; an unset bin cost becomes x * y – an area, not a volume.
Package. Both fields are None by default and left to upstream. Pass an explicit cost whenever bin types differ in height and you optimise VARIABLE_SIZED_BIN_PACKING.
Anytime runs are not reproducible run to run
Upstream. The default ANYTIME mode uses threads and wall-clock checkpoints; the incumbent at the time limit can differ between runs. The reported bound does not depend on timing.
Package. Use OptimizationMode.NOT_ANYTIME_DETERMINISTIC (or NOT_ANYTIME_SEQUENTIAL, which upstream’s own tests use) when two runs must agree, and always record result.run.options.
Anytime mode runs until it is stopped
Upstream. In ANYTIME mode the search only ends on the time limit, on a stop signal, or once it has proved that no better solution exists (every item packed, or the bound reached). Otherwise it keeps widening its search: box’s tree search doubles its queue without an upper size, and since the pinned commit (2a598481, fontanf/packingsolver#578) the single-bin algorithm of boxstacks does the same, growing the queues of its rectangle subproblem and of its 3D fallback level by level and reporting every improvement. Before that commit boxstacks ran one fixed pass and returned by itself, but a time limit shorter than that pass (about 12 s for 130 stacks) cut the pass in the middle and reported the truncated prefix as the result; now any time limit yields the best complete pass found so far. The maintainer confirmed in fontanf/packingsolver#580 that running until stopped is the intended semantics.
Package. Always pass time_limit to ANYTIME solves (the default mode): on an instance that does not pack fully and whose search tree is not exhausted, box.solve and boxstacks.solve never return without one. The NOT_ANYTIME_* modes still run a single fixed pass and return on their own, at the cost of the truncation above when the limit is shorter than the pass. stop_when_unimproved_for (see Budgets, algorithm switches and batch runs) supplies the stop signal upstream expects from its caller: the solve ends once no new incumbent has appeared for that many seconds.
Multi-bin boxstacks fills bins one at a time
Upstream. With several bins, boxstacks has no tree search: bin packing runs sequential single knapsack (SSK: fill one bin with the growing single-bin search, remove what it placed, continue) when the bin holds more than 16 mean items of a copy-heavy cargo or more than 64 otherwise, and sequential value correction (SVC: pack every bin with a fixed pass, adjust item profits, repeat) below those thresholds and always for knapsack and variable-sized bin packing. SVC reports its first solution only after a whole iteration over all bins, tens of seconds on a thousand items, and it returns as soon as a bin-packing solution uses at most two bins. SSK reports within a second on the 40’ container loads of the examples. Neither falls back to the other: a bin count the greedy pass cannot close ends with no solution at the time limit, which on container loads of 1.2 to 2 bin volumes with three or four bins is mostly the sign of an infeasible bin count. Before 9bfb9431 the multi-bin path was SVC only; 63ed7915 (fontanf/packingsolver#584) forwards the timer to the pricing subproblem that made SSK overrun its time limit by up to 25 s. Two crashes of this path are fixed upstream at 9ae71316 (0.0.5): the bin-weight check used a multiplicative PSTOL slack in the search but a strict comparison in Solution::build, so an insertion accepted inside the slack could abort the run with solution doesn’t satisfy bin weight capacity (fontanf/packingsolver#582, fixed by #586 with one absolute tolerance precomputed from the highest bin weight of the instance), and SVC on a multi-bin knapsack divided by the packed copies of an item type its pass had left out entirely, so the next pass aborted with Items must have strictly positive profits. (#587, fixed by #588: such an item type now keeps its profit).
Here. algorithm_path() replicates the selection and recommend_time_budget() budgets the two paths separately. Give bin packing one more bin than the volume bound suggests when stacking limits or upright-only items are involved, and read a NO_SOLUTION on such a load as “these bins do not suffice” before reading it as “not enough time”. Measured on 43 container loads with a 60 s limit: first solution median 30 s and 31 loads without a solution at 2a598481; 0.5 s and 15 loads at the pinned commit, all 15 of them without a solution on every earlier commit too (fontanf/packingsolver#583).
The default objective produces no solution
Upstream. Objective::Default is the placeholder an Instance carries before an objective is set; upstream’s command line has no default for --objective and its optimisers only run their algorithms for an explicit objective. An instance solved with default returns no packing at all when bins have several copies, and an undefined one otherwise.
Package. Instance requires objective, and Objective.DEFAULT – kept because it is upstream’s token – is refused with InvalidInstanceError before the solver is called.