logistics.container-fit

def container_fit(container: str, length_mm: int, width_mm: int, height_mm: int, carton_grams: int, keep_upright: bool, max_payload_kg: Optional[int]) -> ContainerFit

FitLimit = Literal["space", "weight"]

@dataclass(frozen=True)
class ContainerFit:
    """The load, how it is stacked, and what stopped it growing."""

    container: str
    #: how many to load: the smaller of the two limits
    cartons: int
    #: how many fit by dimensions alone
    space_limit: int
    #: how many the payload allows
    weight_limit: int
    #: weight only when it is strictly the smaller
    limited_by: FitLimit
    #: cartons in a row along the container
    along_length: int
    #: rows side by side
    across_width: int
    #: tiers stacked
    layers: int
    #: the carton dimension lying along the container's length
    placed_length_mm: int
    #: ...across its width
    placed_width_mm: int
    #: ...upright
    placed_height_mm: int
    #: cartons x cartonGrams
    cargo_grams: int
    #: carton volume loaded over the space's volume, rounded down; 10000 = full
    volume_used_basis_points: int

from fune.logistics.container_fit import container_fit  # logistics.container-fit@^1

from typing import Optional, Tuple

from .logistics_container_fit_data import CONTAINERS  ← this capability’s own data, compiled from data/containers.json into the same file by fune build
from .logistics_container_fit_types import ContainerFit


def _whole(value: object) -> bool:
    return isinstance(value, int) and not isinstance(value, bool)


def container_fit(
    container: str,
    length_mm: int,
    width_mm: int,
    height_mm: int,
    carton_grams: int,
    keep_upright: bool,
    max_payload_kg: Optional[int],
) -> ContainerFit:
    """How many identical cartons fit in a container or trailer: the best block
    stow over the allowed orientations that pass the door, capped by payload."""
    for d in (length_mm, width_mm, height_mm):
        if not _whole(d) or d < 1:
            raise ValueError("carton dimensions must be 1 mm or more, received %r" % (d,))
    if not _whole(carton_grams) or carton_grams < 1:
        raise ValueError("cartonGrams must be 1 or more, received %r" % (carton_grams,))
    spec = next((c for c in CONTAINERS if c.code == container), None)
    if spec is None:
        raise ValueError(
            'unknown container "%s": expected %s' % (container, ", ".join(c.code for c in CONTAINERS))
        )
    payload_kg = spec.max_payload_kg
    if max_payload_kg is not None:
        if not _whole(max_payload_kg) or max_payload_kg < 1:
            raise ValueError("maxPayloadKg must be 1 or more, received %r" % (max_payload_kg,))
        if max_payload_kg > spec.max_payload_kg:
            raise ValueError(
                "maxPayloadKg must not exceed %d kg for %s, received %d"
                % (spec.max_payload_kg, container, max_payload_kg)
            )
        payload_kg = max_payload_kg

    l, w, h = length_mm, width_mm, height_mm
    # Upright first (as given, then turned on the floor), then the four tipped ones.
    orientations = (
        [(l, w, h), (w, l, h)]
        if keep_upright
        else [(l, w, h), (w, l, h), (l, h, w), (h, l, w), (w, h, l), (h, w, l)]
    )

    best: Optional[Tuple[int, int, int, Tuple[int, int, int]]] = None
    best_count = 0
    for o in orientations:
        a, b, c = o
        if a > spec.length_mm or b > spec.width_mm or c > spec.height_mm:
            continue
        # End-loaded containers: the carton's cross-section has to pass the door.
        if spec.door_width_mm is not None and b > spec.door_width_mm:
            continue
        if spec.door_height_mm is not None and c > spec.door_height_mm:
            continue
        along = spec.length_mm // a
        across = spec.width_mm // b
        layers = spec.height_mm // c
        count = along * across * layers
        if best is None or count > best_count:
            best = (along, across, layers, o)
            best_count = count
    if best is None:
        raise ValueError("carton does not fit in %s in any allowed orientation" % container)

    weight_limit = payload_kg * 1000 // carton_grams
    cartons = min(best_count, weight_limit)
    space = spec.length_mm * spec.width_mm * spec.height_mm
    along, across, layers, placed = best
    return ContainerFit(
        container=container,
        cartons=cartons,
        space_limit=best_count,
        weight_limit=weight_limit,
        limited_by="weight" if weight_limit < best_count else "space",
        along_length=along,
        across_width=across,
        layers=layers,
        placed_length_mm=placed[0],
        placed_width_mm=placed[1],
        placed_height_mm=placed[2],
        cargo_grams=cartons * carton_grams,
        volume_used_basis_points=cartons * l * w * h * 10000 // space,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add logistics.container-fit

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./logistics.container-fit-1.0.0-python.fune, or fetch it from a terminal with fune pull logistics.container-fit@1.0.0:python.

The whole function, every language, is one file too: logistics.container-fit-1.0.0.fune, 27,549 bytes, sha256 0724243703a57d2a7546dcf573145a83d6aab928f399362008abab1ef93294b6. It installs into a project of any language.

# fune: before logistics.container-fit

# fune: after logistics.container-fit

# fune: step logistics.container-fit after <n|label>

More from the author

A carton can lie six ways. With `keepUpright` ("this way up" cartons) only the two that keep `heightMm` vertical are tried; otherwise all six. Each orientation's count is `floor(L / a) x floor(W / b) x floor(H / c)`, and the largest wins, ties going to the first in this order: as given, turned on the floor, then the four tipped ones (length-height-width, height-length-width, width-height-length, height-width-length).

Turning a carton on the floor often matters more than people expect: 580 x 380 x 300 mm cartons in a 40ft high cube give 1,080 as given and 1,116 turned (31 rows of 380 mm beat 20 rows of 580 mm). Dividing the volumes instead (`container volume / carton volume`) overstates the answer every time, since the gaps at the walls and roof are real.

It is a block stow, not an optimiser: filling the leftover strip along a wall with cartons turned the other way can add a few more, and load-planning software does that. The answer here is a safe, reproducible lower bound.

## Doors

A carton has to get in. Containers are loaded through the end doors, which are smaller than the inside (a 20ft box is 2,393 mm high inside but 2,292 mm at the door), so an orientation whose width or height does not pass the door is not used. The trailer is a curtainsider, loaded from the side, so it has no door limit. No usable orientation at all is an error.

## Weight

`weightLimit = floor(maxPayloadKg x 1000 / cartonGrams)`, using the container's rated payload or the caller's lower `maxPayloadKg` (road weight limits on the vehicle carrying the box are often the real constraint: ask the haulier). A figure above the container's rating is an error. `cartons` is the smaller limit, and `limitedBy` says which one it was. The payload is assumed spread evenly; concentrated loads have their own limits.

## Container data

Inside and door dimensions are the carrier's nominal figures, not the ISO minimums: an ISO 668 / ISO 1496-1 container is only guaranteed 5,898 x 2,350 x 2,350 mm inside (20ft), so a plan that needs the last few millimetres may not fit every box. Payloads vary with the tare of the individual box; the figures are one carrier's.

| code | inside (mm) | door (mm) | payload | source | |---|---|---|---|---| | 20gp | 5,900 x 2,352 x 2,393 | 2,340 x 2,292 | 30,200 kg | Hapag-Lloyd | | 40gp | 12,032 x 2,352 x 2,395 | 2,340 x 2,292 | 28,800 kg | Hapag-Lloyd | | 40hc | 12,032 x 2,352 x 2,700 | 2,340 x 2,597 | 28,650 kg | Hapag-Lloyd | | trailer-13.6 | 13,600 x 2,440 x 2,650 | side loaded | 24,000 kg | haulier reference values |

Trailers are not standardised the way containers are; the figures are the cautious end of the published range, and your haulier's own figures should be preferred.

## Sources

- Hapag-Lloyd, Container Specification (general purpose and high cube tables; it also reproduces the ISO 668 external and minimum internal dimensions), https://www.hapag-lloyd.com/content/dam/website/downloads/press_and_media/publications/15211_Container_Specification_engl_Gesamt_web.pdf - ISO 668:2020, Series 1 freight containers: classification, dimensions and ratings; ISO 1496-1, general cargo containers. - PLS Transport, "Trailer dimensions: technical guide", https://pls-transport.be/en/articles/trailer-dimensions ; Calcargo, "Trailer dimensions: what fits inside", https://calcargo.eu/en/blog/trailer-dimensions-what-fits-inside

Files