Documentation
¶
Overview ¶
Package packvium is the Go port of the Packvium deterministic 3D bin-packing library.
The port replays the reference engine's release history milestone by milestone; see PORTING-STATUS.md for which milestone this tree implements. Layers follow the reference architecture and depend in one direction only:
units -> domain -> constraints/algorithms/validation -> packer -> serialization
Directories
¶
| Path | Synopsis |
|---|---|
|
Package algorithm holds the solver layer: the single-container solvers, the container planner, the portfolio orchestrator, the objective scorers and the extension points a caller can plug in.
|
Package algorithm holds the solver layer: the single-container solvers, the container planner, the portfolio orchestrator, the objective scorers and the extension points a caller can plug in. |
|
Package artifacts builds the portable operational artifact and exports it as JSON, CSV and a printable HTML work order (docs/OPERATIONAL-ARTIFACTS.md in the suite repository).
|
Package artifacts builds the portable operational artifact and exports it as JSON, CSV and a printable HTML work order (docs/OPERATIONAL-ARTIFACTS.md in the suite repository). |
|
cmd
|
|
|
packvium
command
Command packvium packs one request: packing JSON in (a file argument, or stdin), result JSON out (stdout, or -o FILE).
|
Command packvium packs one request: packing JSON in (a file argument, or stdin), result JSON out (stdout, or -o FILE). |
|
packvium-artifact-probe
command
Command packvium-artifact-probe is the batch probe the suite's artifact conformance (conformance/artifacts/run.py) drives, answering the protocol of its probe.php.
|
Command packvium-artifact-probe is the batch probe the suite's artifact conformance (conformance/artifacts/run.py) drives, answering the protocol of its probe.php. |
|
packvium-commerce
command
Command packvium-commerce drives the exported commerce API from stdin to stdout: one case object ({"operation", "document", "request"}) in, one canonical result document out.
|
Command packvium-commerce drives the exported commerce API from stdin to stdout: one case object ({"operation", "document", "request"}) in, one canonical result document out. |
|
Package commerce is Packvium's exported commercial and control-plane API: three deterministic functions -- Quote, EvaluatePolicy and CatalogVersionInfo -- over one canonical JSON commerce document.
|
Package commerce is Packvium's exported commercial and control-plane API: three deterministic functions -- Quote, EvaluatePolicy and CatalogVersionInfo -- over one canonical JSON commerce document. |
|
Package compression is the occupied height of a compressible item under the load resting on it.
|
Package compression is the occupied height of a compressible item under the load resting on it. |
|
Package config holds the immutable solver configuration of one packing call.
|
Package config holds the immutable solver configuration of one packing call. |
|
Package constraint holds the placement rules every solver runs and the whole-scene load analysis they share: contact and support graphs, bearing, crushing, stacking, density, route order, stop accessibility and axle loads.
|
Package constraint holds the placement rules every solver runs and the whole-scene load analysis they share: contact and support graphs, bearing, crushing, stacking, density, route order, stop accessibility and axle loads. |
|
Package domain holds the immutable value objects a packing request and result are made of: items, containers, obstacles, rotations, placements and outcomes.
|
Package domain holds the immutable value objects a packing request and result are made of: items, containers, obstacles, rotations, placements and outcomes. |
|
examples
|
|
|
artifacts
command
Hand a packing result to a warehouse system that has no engine.
|
Hand a packing result to a warehouse system that has no engine. |
|
basic
command
The smallest useful call: some items, some boxes, one answer.
|
The smallest useful call: some items, some boxes, one answer. |
|
commerce
command
Commerce: quote a shipment, apply a policy rule, and inspect a catalog version.
|
Commerce: quote a shipment, apply a policy rule, and inspect a catalog version. |
|
constraints
command
Constraints: how to say "this may not go there" and get told why.
|
Constraints: how to say "this may not go there" and get told why. |
|
execution
command
Turn a packing result into instructions someone can follow on a dock.
|
Turn a packing result into instructions someone can follow on a dock. |
|
extensions
command
Extension points: rules the schema does not have a field for.
|
Extension points: rules the schema does not have a field for. |
|
intelligence
command
Prove a carton change is better before you publish it.
|
Prove a carton change is better before you publish it. |
|
nested
command
Nested packing: cartons into a pallet, in one call.
|
Nested packing: cartons into a pallet, in one call. |
|
objectives
command
Objectives: six ways to be "best", and the scenes where they disagree.
|
Objectives: six ways to be "best", and the scenes where they disagree. |
|
serialization
command
Serialization: the JSON contract every engine shares, and what it does with mistakes.
|
Serialization: the JSON contract every engine shares, and what it does with mistakes. |
|
shapes
command
Shapes: items that do not fill their box.
|
Shapes: items that do not fill their box. |
|
units
command
Units: why there are no floats anywhere, and what you can type.
|
Units: why there are no floats anywhere, and what you can type. |
|
Package execution derives an execution plan from an already validated packing result.
|
Package execution derives an execution plan from an already validated packing result. |
|
locks
Package locks is operator locks, expressed as request-derived constraints: an operator saying "this item stays in this box, in this place" (docs/EXECUTION-PLAN.md).
|
Package locks is operator locks, expressed as request-derived constraints: an operator saying "this item stays in this box, in this place" (docs/EXECUTION-PLAN.md). |
|
Package explain renders deterministic, localization-ready sentences for why an item was not packed.
|
Package explain renders deterministic, localization-ready sentences for why an item was not packed. |
|
Package hull is exact separating-axis collision for convex_hull items.
|
Package hull is exact separating-axis collision for convex_hull items. |
|
Package intelligence groups the decision layer that sits above the packer: deciding whether a change is an improvement before it is published.
|
Package intelligence groups the decision layer that sits above the packer: deciding whether a change is an improvement before it is published. |
|
holdout
Package holdout replays a recommendation against history it was not derived from: would it have improved past decisions, scored on a slice it never saw? The contract is docs/INTELLIGENCE-API.md in the reference.
|
Package holdout replays a recommendation against history it was not derived from: would it have improved past decisions, scored on a slice it never saw? The contract is docs/INTELLIGENCE-API.md in the reference. |
|
outcomes
Package outcomes is an append-only ledger of first-party shipment outcomes and packing exceptions: which alternative was chosen, which carton was really used, measured dimensions and weight, a repack, damage, a return, an operator override.
|
Package outcomes is an append-only ledger of first-party shipment outcomes and packing exceptions: which alternative was chosen, which carton was really used, measured dimensions and weight, a repack, damage, a return, an operator override. |
|
pareto
Package pareto is a Pareto report over benchmark or scenario results, one per profile.
|
Package pareto is a Pareto report over benchmark or scenario results, one per profile. |
|
recommendations
Package recommendations proposes carton-catalog and rule changes, backed by evidence, and is the one route from a proposal to a published change.
|
Package recommendations proposes carton-catalog and rule changes, backed by evidence, and is the one route from a proposal to a published change. |
|
simulation
Package simulation runs scenarios and compares them: what-if analysis over a fixed order corpus.
|
Package simulation runs scenarios and compares them: what-if analysis over a fixed order corpus. |
|
internal
|
|
|
canonicaljson
Package canonicaljson writes RFC 8785 canonical JSON: the one spelling every Packvium engine agrees on byte for byte.
|
Package canonicaljson writes RFC 8785 canonical JSON: the one spelling every Packvium engine agrees on byte for byte. |
|
ints
Package ints holds the int64 helpers the language only gained as builtins after the module's minimum Go version.
|
Package ints holds the int64 helpers the language only gained as builtins after the module's minimum Go version. |
|
jsonvalue
Package jsonvalue decodes and encodes JSON with the reference engine's rules: integers stay exact (int64, or *big.Int past that range), floats are distinct from integers, and output is byte-identical to the reference's json.dumps with sorted keys.
|
Package jsonvalue decodes and encodes JSON with the reference engine's rules: integers stay exact (int64, or *big.Int past that range), floats are distinct from integers, and output is byte-identical to the reference's json.dumps with sorted keys. |
|
pyrepr
Package pyrepr renders a string the way the reference engine's repr() does.
|
Package pyrepr renders a string the way the reference engine's repr() does. |
|
wide
Package wide is a signed 128-bit integer for exact products of two int64 values.
|
Package wide is a signed 128-bit integer for exact products of two int64 values. |
|
Package nested packs level by level: what one level packs becomes the items of the next, so units go into cartons and cartons go onto pallets in one call.
|
Package nested packs level by level: what one level packs becomes the items of the next, so units go into cartons and cartons go onto pallets in one call. |
|
Package packer solves a packing request: it runs the solver portfolio, validates and scores every answer, and returns the best with its ranked alternatives.
|
Package packer solves a packing request: it runs the solver portfolio, validates and scores every answer, and returns the best with its ranked alternatives. |
|
Package policy holds versioned eligibility rules carried in the request and compiles them into the engine's own constraint pipeline.
|
Package policy holds versioned eligibility rules carried in the request and compiles them into the engine's own constraint pipeline. |
|
Package result holds the immutable outcome of one packing call.
|
Package result holds the immutable outcome of one packing call. |
|
Package sequence holds the loading and unloading dependency graphs over one container's placements, the safe orders derived from them, and an independent replay that checks any order step by step.
|
Package sequence holds the loading and unloading dependency graphs over one container's placements, the safe orders derived from them, and an independent replay that checks any order step by step. |
|
Package serialization is the JSON adapter: a wire request in, a wire result out.
|
Package serialization is the JSON adapter: a wire request in, a wire result out. |
|
Package validation re-derives every guarantee of a packing result from the placements alone.
|
Package validation re-derives every guarantee of a packing result from the placements alone. |
Click to show internal directories.
Click to hide internal directories.