DOCS / REFERENCE

The objective vector

How results are ranked, why every key is an exact integer, and what an equal score does not imply: what was left over comes first.

Docs for Packvium 1.11.x · contract stable since 1.0

01Five keys, compared lexicographically#

Units left over, containers opened, container cost, unused volume and stack height, compared ascending, so lower is better. The reference table below pairs each one with the key it arrives under. Ratios are carried as parts per million so the whole vector stays integral.

02What was left over comes first#

No objective may hide an incomplete answer. Six of the seven rank the units left over first, so an arrangement that leaves an item behind ranks worse than one that does not. maximum_volume, added in 1.6.0, ranks the volume left over first, in parts per million of the volume requested, and the units second: it will leave three small items out to pack one large one.

03A lower bound, and the gap to it#

Under default and lowest_cost from 1.8.0, maximum_value, open_dimension_height and maximum_volume from 1.10.0, and shipping_cost and lowest_landed_cost from 1.11.0, a result carries optimality.lower_bound: a vector no arrangement can score below, computed from the request alone. Where the answer is above it, gap_key names the first key that differs, absolute_gap says by how much and relative_gap gives that as a fraction of the bound. A result is optimal only when it reaches the bound - which proves no better arrangement exists - and validate checks both the bound and the gap. The Playground prints them under every run.

04The formula is universal, the value is not#

Every engine computes the vector the same way and none may misreport the score of the packing it returned. Engines that return different but equally valid arrangements score differently, which is a stated non-guarantee rather than a defect.

Reference tables

Read from the same constants the engine, the playground and the validator use, so this page cannot drift from the code.

Score vector by objective

Score vector by objective
ObjectiveKeys in ranking order
defaultFewest containers
  1. unpacked_count
  2. container_count
  3. total_cost_minor
  4. unused_volume_ppm
  5. stack_height_ppm
lowest_costLowest container cost
  1. unpacked_count
  2. total_cost_minor
  3. container_count
  4. unused_volume_ppm
  5. stack_height_ppm
shipping_costLowest billable weight
  1. unpacked_count
  2. billable weight
  3. container_count
  4. unused_volume_ppm
  5. stack_height_ppm
lowest_landed_costLowest carrier charge
  1. unpacked_count
  2. carrier charge
  3. container_count
  4. unused_volume_ppm
  5. stack_height_ppm
open_dimension_heightLowest stack height
  1. unpacked_count
  2. achieved height in ticks
  3. container_count
  4. total_cost_minor
  5. unused_volume_ppm
maximum_valueMost value packed
  1. unpacked_count
  2. value forgone
  3. container_count
  4. total_cost_minor
  5. unused_volume_ppm
maximum_volumeMost volume packed
  1. volume left over
  2. unpacked_count
  3. container_count
  4. total_cost_minor
  5. unused_volume_ppm
  • unpacked_countUnits left over
  • container_countContainers opened
  • total_cost_minorContainer costin minor currency units
  • unused_volume_ppmUnused volumeparts per million, added up over the containers
  • stack_height_ppmStack heightparts per million of container height, added up
  • billable weightBillable weightin weight ticks of 1/8 µg, the larger of gross and dimensional weight
  • carrier chargeCarrier chargein minor currency units, from each container's rate table
  • achieved height in ticksHeight achievedin ticks of 1/16000 mm
  • value forgoneValue forgonein the caller's own scale, summed over the items left over
  • volume left overVolume left overparts per million of the total volume of the items requested