Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,40 @@ What changed in `packvium/packvium` on Packagist, release by release. The format
[Keep a Changelog](https://keepachangelog.com/1.1.0/) and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.5.0]

No API changes. The beam search is faster with identical placements, a block answer reports
its real support, and a misspelt configuration key is now refused (see *Fixed*).

### Changed

- **Beam search 18–24% faster, same results.** The bound that ranks beam nodes reads prefix
sums built once per step, one binary search per node instead of a `BigInt` addition per
future item, and expansions that cannot beat the best plan so far are skipped early.

### Fixed

- **A block answer reports the support each item really has.** `HomogeneousBlockSolver` wrote
`supportRatio` 1.0 for every item, including those of a block set on a smaller one, which
overhang it. The bottom layer of each block now reports the share of its base that rests on
something. With `minimumSupportRatio` above zero the block solver is no longer tried at all;
its answer was built and then discarded by validation.
- **A misspelt `configuration` key is refused.** A key the request schema does not declare in
`configuration` or its `effort_budget` (`profile` for `solver_profile`, `top_k` for
`alternatives`) was silently ignored, so the request ran on defaults. `ArrayCodec::pack` now
throws `InvalidRequestException` with reason `not_allowed` and the key's pointer, for example
`/configuration/profile`.
- **A number past PHP's integer range is refused instead of changed.** A length or weight of
`9223372036854775808` became `9223372036854775807`, and a decimal whose scaled value overflowed
became a float, so the request was solved for a different size than the one sent. Both now
throw `InvalidArgumentException` ("Scaled unit value exceeds integer range").
- **An unknown `objective` or access direction is refused with its pointer.** It was
`invalid_value` with an empty field; it is now `not_allowed` with, for example,
`/configuration/objective`.
- **Compressible items are no longer laid out as rigid blocks** by `HomogeneousBlockSolver`.
- **Refusal messages match the documentation**, e.g. a fixed placement with unknown keys says it
`cannot carry` them.

## [1.4.0]

Replanning a job that has already started, and container ids that match the other engines.
Expand Down
25 changes: 25 additions & 0 deletions CITATION.cff
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
cff-version: 1.2.0
message: "If you use Packvium in your research, please cite it as below."
title: "Packvium for PHP"
type: software
authors:
- name: "Packvium contributors"
website: "https://packvium.com"
version: "1.5.0"
license: MIT
url: "https://packvium.com"
repository-code: "https://github.com/toxakara/packvium-php"
repository-artifact: "https://packagist.org/packages/packvium/packvium"
abstract: >-
Deterministic 3D bin-packing and cartonization engine for pallets, containers, trucks and shipping cartons. Exact integer geometry, reproducible results.
keywords:
- 3d-bin-packing
- bin-packing
- 3d-packing
- cartonization
- container-loading
- pallet-packing
- truck-loading
- packing-algorithm
- logistics
- deterministic
227 changes: 189 additions & 38 deletions README.md

Large diffs are not rendered by default.

31 changes: 31 additions & 0 deletions codemeta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
{
"@context": "https://w3id.org/codemeta/3.0",
"@type": "SoftwareSourceCode",
"name": "Packvium for PHP",
"description": "Deterministic 3D bin-packing and cartonization engine for pallets, containers, trucks and shipping cartons. Exact integer geometry, reproducible results.",
"version": "1.5.0",
"license": "https://spdx.org/licenses/MIT",
"author": [
{
"@type": "Organization",
"name": "Packvium contributors",
"url": "https://packvium.com"
}
],
"url": "https://packvium.com",
"codeRepository": "https://github.com/toxakara/packvium-php",
"issueTracker": "https://github.com/toxakara/packvium-php/issues",
"programmingLanguage": "PHP",
"keywords": [
"3d-bin-packing",
"bin-packing",
"3d-packing",
"cartonization",
"container-loading",
"pallet-packing",
"truck-loading",
"packing-algorithm",
"logistics",
"deterministic"
]
}
12 changes: 9 additions & 3 deletions composer.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "packvium/packvium",
"description": "Deterministic, extensible 3D cartonization and container packing library with exact metric and imperial units.",
"description": "Deterministic 3D bin-packing and cartonization engine for pallets, containers, trucks and shipping cartons. Exact integer geometry, reproducible results.",
"type": "library",
"suggest": {
"packvium/native-bridge": "Routes solves through the Rust core over FFI when a shared library is available, with identical results."
Expand All @@ -14,13 +14,19 @@
],
"keywords": [
"3d-bin-packing",
"bin-packing",
"3d-packing",
"cartonization",
"container-loading",
"packing",
"logistics"
"pallet-packing",
"truck-loading",
"packing-algorithm",
"logistics",
"deterministic"
],
"homepage": "https://packvium.com",
"support": {
"docs": "https://packvium.com/docs",
"issues": "https://github.com/toxakara/packvium-php/issues",
"source": "https://github.com/toxakara/packvium-php",
"security": "https://github.com/toxakara/packvium-php/blob/main/SECURITY.md"
Expand Down
20 changes: 12 additions & 8 deletions docs/GUARANTEES.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,9 @@ After a result reports `feasible` or `optimal` and passes independent validation
1/8 µg for weight. No coordinate is ever a binary floating-point number, so no
placement decision depends on rounding;
- **determinism** — identical input and identical seed produce an identical result, on
any platform and in any of the implementations;
any platform, when the search completes or stops on `configuration.effort_budget`. A
search stopped by `time_limit_ms` stops where the host's speed let it, so it may differ
between runs; the result says which limit stopped it;
- **complete accounting** — every requested item instance appears exactly once, either
placed or listed as unpacked with a reason code.

Expand All @@ -31,24 +33,26 @@ After a result reports `feasible` or `optimal` and passes independent validation
- **That your inputs are right.** Dimensions, weights and clearances are taken as given.
Round item exteriors outward, container interiors inward, and clearance outward before
you build the request.
- **Support for non-rectangular shapes.** Items and containers are rigid axis-aligned
cuboids; obstacles are rectangular. No cylinders, deformable bags, meshes or
irregular geometry.
- **Arbitrary shapes.** Containers are axis-aligned cuboids. An item is a cuboid, a convex
hull of vertices, or a cuboid that compresses by a declared ratio; obstacles are cuboids
or unions of them. Concave meshes, curved surfaces and free-form deformable bags are not
modelled — approximate them with a convex hull or a bounding cuboid.
- **A result before the deadline.** With a time limit set, the search may return
`time_limit` with a partial packing, or nothing placed at all.
- **Full load propagation.** Top-load limits are enforced against what rests *directly*
on an item, not against the accumulated mass of an entire stack above it.

## Not modelled at all

Deformable goods, dynamic shipping physics, contact-load propagation through arbitrary
support graphs, pallet-overhang standards, axle loads, unloading-route optimization, and
carrier tariff or rating catalogs. None of these are built in, and none are approximated
Dynamic shipping physics, contact-load propagation through arbitrary support graphs,
pallet-overhang standards, and route optimization. Axle loads, the unloading order of a
given stop sequence (`stop_index`, `access_directions`) and carrier rate tables are
modelled; choosing the route itself is not. None of the unmodelled items is approximated
silently — if you need them, they belong in your own layer above this library.

## Status of this release

Version `1.4.0` freezes the public API. Field names, status codes, the objective
Version `1.5.0` freezes the public API. Field names, status codes, the objective
vector, the numeric policy and the validation rules do not change without a major
version, so any `1.x` is a safe upgrade from any earlier `1.x`. A caret or tilde
constraint on `1.0` is enough; an exact pin is no longer required.
Expand Down
2 changes: 1 addition & 1 deletion docs/UNITS-AND-NUMERICS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ One internal length tick is `1/16000 mm`.
- `1 international inch = 25.4 mm = 406,400 ticks`
- common fractional inches through at least `1/128 in` are exact integers

Accepted inputs include integers, decimal strings, fractions (`3/16`) and mixed fractions (`12 3/8`), with `mm`, `cm`, `m`, `in`, `ft`, and ticks. Binary floating-point input is intentionally rejected by the Python API; PHP type declarations accept only integer/string/structured values.
Accepted inputs include integers, decimal strings, fractions (`3/16`) and mixed fractions (`12 3/8`), with `mm`, `cm`, `m`, `in`, `ft`, and ticks. A binary float with a fractional part is intentionally rejected by the Python API, by `Length` and `Weight` alike (`TypeError`); an integral float such as `100.0` is exact, and is what JavaScript sends for `100`, so it is accepted as that integer. PHP type declarations accept only integer/string/structured values.

## Weight

Expand Down
Loading
Loading