Converter specification

Packrift source-to-packingsolver format map.

This page documents how the public Packrift carton and generated scenario-order fixture records are converted into `packingsolver` box-problem input files. It is intended for converter review, reproducible parser tests, and benchmark publication prep.

Scope and source-of-truth boundaries

The fixture pack is input data only. It does not assert known optimal or quasi-optimal solutions, third-party endorsement, live Packrift inventory, freight approval, or customer-order truth.

Packrift source records Public carton SKU dimensions and generated ecommerce scenario orders from the Packrift benchmark ledger.

Packingsolver target Box-problem CSV files: `bins.csv`, `items.csv`, and optional `parameters.csv` per scenario.

Official parser reference `InstanceBuilder` box CSV parser, plus the upstream `convert_box.py` pattern.

Machine-readable map `packingsolver-format-map.json` contains the same mapping in JSON form.

Reference converter `convert_box_packrift.py` converts the public Packrift fixture CSV files into the generated packingsolver folder layout.

Generated file set

File	Purpose	Packrift source	Generated count
`bins.csv`	Candidate bin/carton types for one scenario	`fixture_cartons_v2026.05.31.csv`	One file per scenario
`items.csv`	Item types to pack for one scenario order	`fixture_orders_v2026.05.31.csv`	One file per scenario
`parameters.csv`	Solver objective selection	Scenario-level policy	One file per scenario

Column contract

`bins.csv`

Required parser columns: X, Y, Z.
Optional parser columns used by Packrift: COST, COPIES.
Optional parser columns not populated unless evidence exists: COPIES_MIN, MAXIMUM_WEIGHT.
Packrift dimensions are converted from inches to integer thousandths of an inch.

`items.csv`

Required parser columns: X, Y, Z.
Optional parser columns used by Packrift: COPIES, PROFIT, and six rotation flags.
COPIES maps to the generated scenario item count.
All six rotations are enabled for screening unless a scenario explicitly documents an orientation restriction.

Packrift transform rules

Target field	Rule	Reason
`X`, `Y`, `Z`	`round(length_in * 1000)`, `round(width_in * 1000)`, `round(height_in * 1000)`	Packingsolver expects integer lengths; thousandths preserve fractional inch source dimensions.
`COST`	For bin candidates, `round(volume_cuin * 1000)`.	Gives smaller cartons a lower cost proxy without using live Packrift price or margin data.
`COPIES` in `bins.csv`	`1` per candidate carton in generated scenarios.	Each instance asks whether one of the candidate carton types can carry the scenario items.
`COPIES` in `items.csv`	Scenario `item_count`.	Preserves repeated item lines without expanding every physical item into a separate row.
`PROFIT`	`X * Y * Z` after dimension scaling.	Keeps parser behavior deterministic and avoids unsupported commercial-value claims.
`ROTATION_*`	Set to `1` for all six rotations unless a source row states a physical orientation constraint.	Useful default for parser and converter tests; downstream users can tighten rotations when they model real handling constraints.
`objective`	`variable-sized-bin-packing` in `parameters.csv`.	Matches the ecommerce carton-selection use case: choose a carton type from candidates rather than solve a fixed-container benchmark.

Example instance

The first generated scenario demonstrates the scaling and cost proxy. The source carton is 4.75 x 3.5 x 2 inches, represented as 4750 x 3500 x 2000 integer units.

# bins.csv
ID,X,Y,Z,COST,COPIES
0,4750,3500,2000,33250,1
1,4000,4000,3000,48000,1

# items.csv
ID,X,Y,Z,COPIES,PROFIT,ROTATION_XYZ,ROTATION_YXZ,ROTATION_ZYX,ROTATION_YZX,ROTATION_XZY,ROTATION_ZXY
0,4750,3500,2000,4,33250000000,1,1,1,1,1,1

# parameters.csv
NAME,VALUE
objective,variable-sized-bin-packing

Converter checklist

Read Packrift carton candidates from the carton CSV.
Read scenario item rows from the order CSV and group by order_id.
Scale all inch dimensions to integer thousandths before writing parser files.
Write one scenario folder containing bins.csv, items.csv, and parameters.csv.
Validate that every row has positive X, Y, Z, positive item copies, and no blank required fields.
Keep public claims limited to input-data usefulness until an external maintainer or dataset venue publishes its own record.

A public reference implementation is now available as convert_box_packrift.py. It mirrors the upstream converter style while keeping Packrift-specific source parsing isolated.

Downloads

Format Map JSONMachine-readable converter field map and transform rules Converter ScriptPython standard-library reference converter Fixture ManifestVersion, counts, source files, and boundaries Cartons CSVPackrift public carton candidates Orders CSVGenerated ecommerce scenario item lines Publication ZIPVenue-ready package pending human auth and license decision