packvium

package module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 0 Imported by: 0

README

Packvium for Go

Deterministic 3D cartonization and container packing in Go, with exact integer geometry and no dependencies beyond the standard library.

Packvium for Go is a full reimplementation of the Packvium reference engine, not a binding over another one. It accepts the same requests and returns the same results as the Python, PHP, Java and .NET engines. Its tests run the shared conformance corpus, and every result matches the reference result byte for byte.

Version 1.0.0. This release corresponds to Packvium 1.0.0 in the other languages, and its tests run the 1.0.0 conformance corpus: every packing fixture and every commerce case. Field names, status codes and the objective vector stay the same for all of 1.x.

Install

go get github.com/packvium/packvium-go@v1.0.1

Go 1.13 or newer. The module is checked on a real Go 1.13 toolchain, so projects that cannot upgrade their compiler can still use it.

Quick start

package main

import (
	"fmt"
	"log"

	"github.com/packvium/packvium-go/algorithm"
	"github.com/packvium/packvium-go/config"
	"github.com/packvium/packvium-go/domain"
	"github.com/packvium/packvium-go/packer"
)

func main() {
	bookSize, _ := domain.DimensionsOf("210", "140", "30", "mm")
	boxSize, _ := domain.DimensionsOf("400", "300", "250", "mm")
	spec := domain.NewItemSpec("book", bookSize)
	spec.Quantity = 4
	book, err := domain.NewItem(spec)
	if err != nil {
		log.Fatal(err)
	}
	box, err := domain.NewContainer(domain.ContainerSpec{ID: "box", InnerDimensions: boxSize})
	if err != nil {
		log.Fatal(err)
	}
	balanced, _ := config.New(config.Default(config.Balanced))
	result, err := packer.New(balanced, algorithm.NoExtensions()).Pack([]*domain.Item{book}, []*domain.Container{box})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(result.Status) // feasible
	for _, container := range result.Containers {
		for _, placement := range container.Placements() {
			// Coordinates are exact ticks: 1/16000 mm.
			fmt.Println(placement.Instance().ID(), placement.Position().X(), placement.Rotation())
		}
	}
}

Fractional inches are stored exactly, without rounding to millimetres:

domain.DimensionsOf("12 3/8", "8 1/2", "3/4", "in")

Every value object is immutable: a *Spec struct describes an item or container, the New... constructor validates it, and the result exposes only accessors.

To get the result in the JSON format every other engine produces, use serialization.EncodeResult(result, "mm", "g") with jsonvalue-style sorted output, or skip the domain types entirely and call serialization.Pack on a decoded request.

Examples

examples/ has one runnable program per directory. Each prints exactly what its Python counterpart prints; go test ./examples/ checks that, line by line.

Example What it shows
basic The smallest useful call: items go in and placements come out.
objectives All six objectives, on scenes where they choose differently.
constraints Upright-only, floor-only, top-load limits and tags, and how to read why an item was refused.
units Why there are no floats: fractional inches, exact ticks, and a refusal caused by a single tick.
serialization The JSON contract, and which mistakes are refused and which are ignored.
shapes Items that do not fill their box: wedges sharing a crate as convex_hull, and a cushion that compresses until the crush limit refuses it.
nested Units go into cartons and cartons go onto a pallet, in one call.
extensions Custom placement rules, item orders and candidate scorers plugged into the solver.
commerce Rate a shipment, apply an eligibility rule and pin a catalog version.
go run ./examples/objectives

Command line

cmd/packvium reads a JSON packing request (a file argument, or standard input) and writes the result JSON to standard output, or to -o FILE. The formats are the ones every other Packvium engine uses.

go build -o packvium ./cmd/packvium
echo '{"items":[{"id":"box","quantity":8,"dimensions":{"length":"50","width":"50","height":"50"}}],"containers":[{"id":"carton","inner_dimensions":{"length":"100","width":"100","height":"100"}}]}' | ./packvium

A refused request exits with status 1 and prints the reason on standard error, in the same wording as the other engines; a usage error exits with status 2. cmd/packvium-commerce is the same for the commerce API.

What it does

  • Exact arithmetic. Length is counted in ticks of 1/16000 mm and weight in ticks of 1/8 µg. Coordinates are never floating-point numbers, so rounding cannot change where an item is placed.
  • Real constraints. Weight and payload limits, allowed rotations, keep-upright, floor-only, non-stackable, top-load limits, minimum support ratio, incompatible tags, clearance, obstacles, axle loads and multi-stop routes.
  • Several solvers, not one. Grid, layer, extreme-point, maximal-space, homogeneous-block and exact search for small problems.
  • Checked answers. An independent validator checks every solution again, and every item left out is listed with a reason code.
  • Deterministic. The same input always gives the same result. The only effect of the clock is the time limit you set; set an effort budget when you need bit-identical truncation too.
  • Commerce. Package commerce prices a shipment, evaluates an eligibility policy and resolves catalog versions, as deterministic functions of the document you pass in.

Differences from the reference engine

Valid requests get identical results. The Go port differs in a few places, none of which shows up in the conformance corpus:

  • Lengths and weights are 64-bit ticks, as in PHP and Java. A value that would overflow is refused, where Python would keep calculating with larger integers. Volumes are exact arbitrary-precision integers.
  • The parallel portfolio cannot be enabled from a request, so it is not included; every start runs one after another, as the reference runs them.
  • JSON NaN/Infinity literals, which the reference's parser accepts, are refused.

Testing

go test ./...   # unit tests, and every example against its recorded output

The full conformance corpus runs in the Packvium suite repository, where all the engines are checked against the same fixtures.

License

MIT.

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.
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-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
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.
extensions command
Extension points: rules the schema does not have a field for.
Extension points: rules the schema does not have a field for.
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 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.
internal
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL