packvium 0.1.0__tar.gz

packvium-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Packvium contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packvium-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: packvium
+Version: 0.1.0
+Summary: Deterministic, extensible 3D cartonization and rectangular bin-packing library
+Author: Packvium contributors
+License-Expression: MIT
+Keywords: 3d-bin-packing,cartonization,packaging,container-loading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Packvium for Python
+
+Deterministic 3D cartonization and rectangular bin packing. Pure Python, **no runtime
+dependencies**, exact integer geometry.
+
+> **Version 0.1.0 — early release.** The public API is not frozen; pin an exact version.
+> Read [docs/GUARANTEES.md](docs/GUARANTEES.md) before relying on a result.
+
+```bash
+pip install packvium
+```
+
+## Quick start
+
+```python
+from packvium import Container, Dimensions, Item, Packer, PackingConfig
+
+result = Packer(PackingConfig.balanced()).pack(
+    items=[Item.create("book", Dimensions.mm("210", "140", "30"), quantity=4)],
+    containers=[Container.create("box", Dimensions.mm("400", "300", "250"))],
+)
+
+print(result.status)                      # feasible
+for container in result.containers:
+    for placement in container.placements:
+        print(placement.item_id, placement.position, placement.orientation)
+```
+
+Fractional inches are exact, not approximated:
+
+```python
+Dimensions.inches("12 3/8", "8 1/2", "3/4")
+```
+
+There is also a CLI that reads a JSON request on standard input:
+
+```bash
+echo '{"items":[{"id":"box","quantity":8,"dimensions":{"length":"50","width":"50","height":"50"}}],
+       "containers":[{"id":"carton","inner_dimensions":{"length":"100","width":"100","height":"100"}}]}' \
+  | python -m packvium
+```
+
+## What it does
+
+- **Exact arithmetic.** Length is measured in ticks of 1/16000 mm and weight in 1/8 µg.
+  No coordinate is ever a float, so no placement decision depends on rounding.
+- **Real constraints.** Weight and payload limits, permitted rotations, keep-upright,
+  floor-only, non-stackable, top-load limits, minimum support ratio, tag incompatibility,
+  clearance and rectangular obstacles.
+- **A solver portfolio, not one algorithm.** Regular-grid, layer, extreme-point,
+  maximal-space and bounded exact search, selected by problem shape and profile.
+- **Answers you can check.** Every solution is re-validated by logic independent of the
+  search. Unplaced items come back with a reason code, not silently missing.
+- **Deterministic.** The same input and seed produce the same result, always.
+- **Multi-container and nested.** Split across containers, or pack containers into
+  containers.
+- **Extensible.** Register your own constraints, item orderings, candidate scorers,
+  container selectors or complete solvers.
+
+## Documentation
+
+| Document | Covers |
+| --- | --- |
+| [docs/GUARANTEES.md](docs/GUARANTEES.md) | What is promised and what is not. Start here. |
+| [docs/PUBLIC-API.md](docs/PUBLIC-API.md) | Inputs, outputs and status semantics. |
+| [docs/UNITS-AND-NUMERICS.md](docs/UNITS-AND-NUMERICS.md) | Units, accepted input forms, rounding policy. |
+
+## Requirements
+
+Python 3.10 or newer. No dependencies.
+
+## Other ports exist
+
+The same request and result contract is implemented independently in PHP and Rust, and
+all three are held to producing identical placements on a shared fixture set. If your
+stack spans languages, you can compute a packing on any of them and get the same answer.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports go through the process in
+[SECURITY.md](SECURITY.md), not public issues.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

packvium-0.1.0/README.md

@@ -0,0 +1,85 @@
+# Packvium for Python
+
+Deterministic 3D cartonization and rectangular bin packing. Pure Python, **no runtime
+dependencies**, exact integer geometry.
+
+> **Version 0.1.0 — early release.** The public API is not frozen; pin an exact version.
+> Read [docs/GUARANTEES.md](docs/GUARANTEES.md) before relying on a result.
+
+```bash
+pip install packvium
+```
+
+## Quick start
+
+```python
+from packvium import Container, Dimensions, Item, Packer, PackingConfig
+
+result = Packer(PackingConfig.balanced()).pack(
+    items=[Item.create("book", Dimensions.mm("210", "140", "30"), quantity=4)],
+    containers=[Container.create("box", Dimensions.mm("400", "300", "250"))],
+)
+
+print(result.status)                      # feasible
+for container in result.containers:
+    for placement in container.placements:
+        print(placement.item_id, placement.position, placement.orientation)
+```
+
+Fractional inches are exact, not approximated:
+
+```python
+Dimensions.inches("12 3/8", "8 1/2", "3/4")
+```
+
+There is also a CLI that reads a JSON request on standard input:
+
+```bash
+echo '{"items":[{"id":"box","quantity":8,"dimensions":{"length":"50","width":"50","height":"50"}}],
+       "containers":[{"id":"carton","inner_dimensions":{"length":"100","width":"100","height":"100"}}]}' \
+  | python -m packvium
+```
+
+## What it does
+
+- **Exact arithmetic.** Length is measured in ticks of 1/16000 mm and weight in 1/8 µg.
+  No coordinate is ever a float, so no placement decision depends on rounding.
+- **Real constraints.** Weight and payload limits, permitted rotations, keep-upright,
+  floor-only, non-stackable, top-load limits, minimum support ratio, tag incompatibility,
+  clearance and rectangular obstacles.
+- **A solver portfolio, not one algorithm.** Regular-grid, layer, extreme-point,
+  maximal-space and bounded exact search, selected by problem shape and profile.
+- **Answers you can check.** Every solution is re-validated by logic independent of the
+  search. Unplaced items come back with a reason code, not silently missing.
+- **Deterministic.** The same input and seed produce the same result, always.
+- **Multi-container and nested.** Split across containers, or pack containers into
+  containers.
+- **Extensible.** Register your own constraints, item orderings, candidate scorers,
+  container selectors or complete solvers.
+
+## Documentation
+
+| Document | Covers |
+| --- | --- |
+| [docs/GUARANTEES.md](docs/GUARANTEES.md) | What is promised and what is not. Start here. |
+| [docs/PUBLIC-API.md](docs/PUBLIC-API.md) | Inputs, outputs and status semantics. |
+| [docs/UNITS-AND-NUMERICS.md](docs/UNITS-AND-NUMERICS.md) | Units, accepted input forms, rounding policy. |
+
+## Requirements
+
+Python 3.10 or newer. No dependencies.
+
+## Other ports exist
+
+The same request and result contract is implemented independently in PHP and Rust, and
+all three are held to producing identical placements on a shared fixture set. If your
+stack spans languages, you can compute a packing on any of them and get the same answer.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports go through the process in
+[SECURITY.md](SECURITY.md), not public issues.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

packvium-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "packvium"
+version = "0.1.0"
+description = "Deterministic, extensible 3D cartonization and rectangular bin-packing library"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{name = "Packvium contributors"}]
+keywords = ["3d-bin-packing", "cartonization", "packaging", "container-loading"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+
+[project.scripts]
+packvium = "packvium.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+pythonpath = ["src"]

packvium-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

packvium-0.1.0/src/packvium/__init__.py

@@ -0,0 +1,70 @@
+from .config import PackingConfig, SolverProfile
+from .effort import EffortBudget
+from .explain import (
+    LEVEL_PREFIXES,
+    REASON_MESSAGES,
+    UnknownReasonError,
+    explain_reason,
+    explain_unpacked_item,
+    explain_unpacked_items,
+)
+from .extensions import ContainerSelector, DefaultSolutionScorer, ExtensionRegistry, ItemOrderStrategy, SolutionScorer
+from .geometry import AxisAlignedBox, Dimensions, Point, Rotation, dimensional_weight
+from .models import (Axle, Container, Item, ItemInstance, Obstacle, PackedContainer, PackingRequest,
+                     Placement, ReasonProof, RejectionObservation, UnpackedItem)
+from .nested import NestedPacker, NestedPackingResult, PackingLevel
+from .packer import Packer
+from .packing_sequence import (
+    ALL_DIRECTIONS,
+    InvalidDirectionError,
+    LoadingDependencyGraph,
+    Reachability,
+    RouteSequenceError,
+    SequenceError,
+    SequenceReplayError,
+    SequenceStep,
+    SequenceWarning,
+    UnloadingDependencyGraph,
+    placement_reachability,
+    replay_loading_order,
+    replay_removal_order,
+    safe_loading_order,
+    safe_loading_order_with_evidence,
+    safe_removal_order,
+    safe_removal_order_with_evidence,
+    safe_route_removal_order,
+)
+from .rebalance import RebalanceResult, WeightMove, rebalance_weight
+from .result import (
+    AlgorithmReport,
+    PackingResult,
+    PackingStatus,
+    ResultFact,
+    SolverMetrics,
+    StartRecord,
+    aggregate_termination,
+)
+from .serialization import pack_from_dict
+from .trace import TraceSink, use_trace
+from .units import Length, Rounding, Weight
+from .validation import IndependentSolutionValidator, ValidationIssue, ValidationReport
+
+__all__ = [
+    "ALL_DIRECTIONS", "AlgorithmReport", "Axle", "AxisAlignedBox", "Container", "DefaultSolutionScorer", "Dimensions",
+    "EffortBudget", "ExtensionRegistry",
+    "IndependentSolutionValidator", "InvalidDirectionError", "Item", "ItemInstance", "LEVEL_PREFIXES", "Length",
+    "LoadingDependencyGraph", "NestedPacker",
+    "NestedPackingResult", "Obstacle", "PackedContainer", "Packer", "PackingConfig",
+    "PackingLevel", "PackingRequest", "PackingResult", "PackingStatus", "Placement", "Point",
+    "REASON_MESSAGES", "Reachability", "ReasonProof", "RebalanceResult", "RejectionObservation", "ResultFact", "Rotation",
+    "Rounding", "RouteSequenceError",
+    "SequenceError",
+    "SequenceReplayError", "SequenceStep", "SequenceWarning", "SolutionScorer",
+    "SolverMetrics", "StartRecord", "TraceSink", "UnknownReasonError", "UnloadingDependencyGraph",
+    "aggregate_termination",
+    "SolverProfile", "UnpackedItem", "ValidationIssue", "ValidationReport", "WeightMove",
+    "Weight", "dimensional_weight", "explain_reason", "explain_unpacked_item", "explain_unpacked_items",
+    "pack_from_dict", "placement_reachability", "rebalance_weight", "replay_loading_order",
+    "replay_removal_order", "safe_loading_order", "safe_loading_order_with_evidence", "safe_removal_order",
+    "safe_removal_order_with_evidence", "safe_route_removal_order", "use_trace",
+]

packvium-0.1.0/src/packvium/__main__.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+import argparse, json, sys
+from .serialization import pack_from_dict
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Pack rigid cuboids into rectangular containers")
+    parser.add_argument("input", nargs="?", help="JSON input file; stdin when omitted")
+    parser.add_argument("-o", "--output")
+    args = parser.parse_args()
+    with (open(args.input, encoding="utf-8") if args.input else sys.stdin) as source:
+        result = pack_from_dict(json.load(source))
+    encoded = json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as target: target.write(encoded + "\n")
+    else: print(encoded)
+    return 0
+
+if __name__ == "__main__": raise SystemExit(main())

packvium-0.1.0/src/packvium/_compat.py

@@ -0,0 +1,42 @@
+"""Small runtime compatibility helpers for the public Python package.
+
+The canonical models use ``dataclass(slots=True)`` on Python 3.10+ to reduce
+per-instance memory.  Python 3.9 has the same dataclass semantics but does not
+accept the ``slots`` keyword.  Keeping the version branch in one lower-layer
+module lets every model retain one definition and one public API.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass as _stdlib_dataclass
+from typing import Any, Callable, TypeVar, overload
+
+
+_T = TypeVar("_T")
+
+
+def _dataclass_options(options: dict[str, Any], version: tuple[int, int]) -> dict[str, Any]:
+    compatible = dict(options)
+    if version < (3, 10):
+        compatible.pop("slots", None)
+    return compatible
+
+
+@overload
+def dataclass(cls: type[_T]) -> type[_T]: ...
+
+
+@overload
+def dataclass(**options: Any) -> Callable[[type[_T]], type[_T]]: ...
+
+
+def dataclass(cls: type[_T] | None = None, **options: Any) -> Any:
+    """Delegate to stdlib dataclass, omitting only unsupported 3.10 keywords."""
+
+    compatible = _dataclass_options(options, sys.version_info[:2])
+
+    def decorate(target: type[_T]) -> type[_T]:
+        return _stdlib_dataclass(target, **compatible)
+
+    return decorate if cls is None else decorate(cls)

packvium-0.1.0/src/packvium/axle_load.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+if TYPE_CHECKING:
+    from .constraints import LoadUnit
+    from .models import Axle
+
+
+def axle_reactions(
+    axles: tuple["Axle", "Axle"],
+    units: Sequence["LoadUnit"],
+    tare_weight_ticks: int = 0,
+    tare_doubled_center_x: int = 0,
+) -> tuple[int, int, int]:
+    """Return ``(denominator, front_numerator, rear_numerator)`` exactly.
+
+    Axle limits are gross-load limits. Payload contributes at each item's physical
+    centre; tare contributes at the container's geometric longitudinal centre (the
+    caller passes its doubled coordinate, preserving an odd half-tick).
+    """
+    front, rear = axles
+    total_weight = tare_weight_ticks + sum(unit.weight_ticks for unit in units)
+    doubled_weighted_x = tare_weight_ticks * tare_doubled_center_x + sum(
+        unit.weight_ticks * (2 * unit.box.origin.x + unit.box.dimensions.length.ticks)
+        for unit in units
+    )
+    denominator = 2 * (rear.position.ticks - front.position.ticks)
+    return (
+        denominator,
+        2 * total_weight * rear.position.ticks - doubled_weighted_x,
+        doubled_weighted_x - 2 * total_weight * front.position.ticks,
+    )
+
+
+def axle_load_exceeded(
+    axles: tuple["Axle", "Axle"],
+    units: Sequence["LoadUnit"],
+    tare_weight_ticks: int = 0,
+    tare_doubled_center_x: int = 0,
+) -> tuple[str, str] | None:
+    """Whether either axle bears more than its own limit, as (code, detail).
+
+    Two-point beam statics: taking moments about each axle in turn gives an exact
+    fraction for what the other axle carries, with no assumption weaker than "the
+    container behaves like a rigid beam resting on exactly two supports" -- true by
+    construction since `Container.axles` only ever has two entries.
+
+    Takes `LoadUnit`s, the same "box + weight, real or hypothetical" abstraction
+    `top_loads`/`stack_density_exceeded` already share, rather than requiring a real
+    `Placement` -- a placement-time candidate does not have one yet. A unit's own box
+    is already its envelope; the envelope's centre coincides exactly with the
+    physical item's centre because clearance pads both sides of every axis equally,
+    so no separate physical/envelope distinction is needed here.
+
+    Never rounds an intermediate axle load. Both loads are compared to their limits
+    by cross-multiplying the same exact fraction (numerator over `2 * (rear - front)`
+    as the shared denominator), the same discipline `stack_density_exceeded` and
+    `SupportConstraint` already use -- a rounded intermediate could hide a real
+    overload or manufacture one that was not there.
+    """
+    front, rear = axles
+    denominator, numerator_front, numerator_rear = axle_reactions(
+        axles, units, tare_weight_ticks, tare_doubled_center_x
+    )
+
+    if front.max_load is not None and numerator_front > front.max_load.ticks * denominator:
+        return ("axle_overloaded", "front")
+    if rear.max_load is not None and numerator_rear > rear.max_load.ticks * denominator:
+        return ("axle_overloaded", "rear")
+    return None
+
+
+def axle_balanced_origins(
+    axles: tuple["Axle", "Axle"],
+    other_units: Sequence["LoadUnit"],
+    tare_weight_ticks: int,
+    tare_doubled_center_x: int,
+    item_weight_ticks: int,
+    item_length_ticks: int,
+) -> list[int]:
+    """The tightest x-origins that seat this item exactly on either axle's limit.
+
+    Candidate-point generation (`find_candidates`) only ever proposes positions
+    flush against the container wall or another placed box's own corner -- correct
+    for plain volume packing, where nothing is ever gained by leaving a gap, but
+    incomplete once axle limits are in play: sometimes the only feasible spot for
+    an item is floating away from every wall and every other box, specifically to
+    keep this item's own moment from tipping one axle over its limit. A floor-level
+    item needs no lateral contact for support (see `_support_ratio`), so that
+    position is otherwise unreachable by any point this module already generates.
+
+    Solving `axle_reactions`'s own boundary equation for this item's centre --
+    "where would the front/rear reaction land exactly on its limit if this item's
+    centre were here" -- turns the two axle limits into two extra x-origins worth
+    trying, on top of the ordinary extreme points. Both are exact integer ticks,
+    biased toward the safe side of their own limit (never past it) since a
+    placement that lands exactly on the boundary is still allowed by
+    `axle_load_exceeded`'s own strict `>` comparison; the caller runs every
+    candidate through the same collision and constraint checks regardless, so a
+    boundary that turns out unreachable (blocked, out of bounds, or infeasible for
+    the other axle) is simply rejected same as any other candidate.
+
+    Never assumes there is room: the caller clamps and discards out-of-range
+    results.
+    """
+    if item_weight_ticks <= 0:
+        return []
+    front, rear = axles
+    denominator = 2 * (rear.position.ticks - front.position.ticks)
+    other_total = tare_weight_ticks + sum(unit.weight_ticks for unit in other_units)
+    other_doubled_x = tare_weight_ticks * tare_doubled_center_x + sum(
+        unit.weight_ticks * (2 * unit.box.origin.x + unit.box.dimensions.length.ticks)
+        for unit in other_units
+    )
+    total = other_total + item_weight_ticks
+    origins: list[int] = []
+    if front.max_load is not None:
+        # Smallest doubled centre for which numerator_front <= front limit * denominator.
+        required = 2 * total * rear.position.ticks - front.max_load.ticks * denominator - other_doubled_x
+        doubled_centre = -(-required // item_weight_ticks)  # ceil: never understate what front needs
+        origins.append(-(-(doubled_centre - item_length_ticks) // 2))  # ceil: stay on the safe side
+    if rear.max_load is not None:
+        # Largest doubled centre for which numerator_rear <= rear limit * denominator.
+        allowed = rear.max_load.ticks * denominator + 2 * total * front.position.ticks - other_doubled_x
+        doubled_centre = allowed // item_weight_ticks  # floor: never overstate what rear allows
+        origins.append((doubled_centre - item_length_ticks) // 2)  # floor: stay on the safe side
+    return origins

packvium-0.1.0/src/packvium/centre_of_mass.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+from .geometry import Dimensions
+
+if TYPE_CHECKING:
+    from .models import Placement
+
+
+def centre_of_mass_offset_ppm(inner_dimensions: Dimensions, placements: Sequence[Placement]) -> int:
+    """How far the weighted centre of mass sits from the container's own centre.
+
+    Reported as parts per million of the half-extent along whichever of the two
+    horizontal axes (length, width) is worse -- the Chebyshev, not Euclidean, offset,
+    so the result stays exact: a Euclidean distance would need a square root, and
+    this library's whole premise is exact fixed-point arithmetic. 0% means
+    centred; 100% means the mass sits at the very edge along that axis. Needed for
+    axle load and side-to-side balance, both of which care about the worst axis, not
+    a single blended number that could hide either one.
+
+    Every item contributes its own physical centre, weighted by its own mass -- an
+    item's clearance envelope is packing buffer, not part of what it weighs, so
+    `position`/`dimensions` are used rather than the (possibly larger) envelope.
+
+    Kept exact throughout via one combined numerator/denominator per axis and a
+    single final floor division, rather than rounding an intermediate centroid --
+    the same discipline `required_area`/`unused_volume_ppm` already use elsewhere.
+    """
+    total_weight = sum(p.instance.weight.ticks for p in placements)
+    if total_weight == 0:
+        return 0
+    length = inner_dimensions.length.ticks
+    width = inner_dimensions.width.ticks
+    doubled_weighted_x = sum(p.instance.weight.ticks * (2 * p.position.x + p.dimensions.length.ticks) for p in placements)
+    doubled_weighted_y = sum(p.instance.weight.ticks * (2 * p.position.y + p.dimensions.width.ticks) for p in placements)
+    numerator_x = doubled_weighted_x - total_weight * length
+    numerator_y = doubled_weighted_y - total_weight * width
+    offset_x_ppm = abs(numerator_x) * 1_000_000 // (total_weight * length)
+    offset_y_ppm = abs(numerator_y) * 1_000_000 // (total_weight * width)
+    return max(offset_x_ppm, offset_y_ppm)

packvium-0.1.0/src/packvium/config.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from ._compat import dataclass
+from enum import Enum
+
+from .effort import EffortBudget
+from .units import Length
+
+
+class SolverProfile(str, Enum):
+    FAST = "fast"
+    BALANCED = "balanced"
+    QUALITY = "quality"
+    EXACT_SMALL = "exact_small"
+
+
+@dataclass(frozen=True, slots=True)
+class PackingConfig:
+    profile: SolverProfile = SolverProfile.BALANCED
+    time_limit_ms: int = 1000
+    top_k: int = 3
+    seed: int = 42
+    max_containers: int | None = None
+    clearance: Length = Length(0)
+    minimum_support_ratio: float = 0.0
+    exact_item_limit: int = 7
+    multi_start_orders: int = 8
+    validate_result: bool = True
+    max_candidates_per_item: int = 1
+    max_candidate_points: int = 4096
+    solvers: tuple[str, ...] = ()
+    objective: str = "default"
+    effort_budget: EffortBudget | None = None
+    #: A carrier's published dimensional-weight divisor. Required only when
+    #: `objective` is `"shipping_cost"` -- see `extensions.ShippingCostSolutionScorer`.
+    dimensional_weight_divisor: int | None = None
+    dimensional_weight_length_unit: str = "in"
+    dimensional_weight_weight_unit: str = "lb"
+    # Default True reproduces every existing result byte-for-byte. False lets
+    # GridSolver's regular-lattice fast path skip materializing one `Placement`
+    # object per instance -- see `lattice_summary.py` -- when a caller
+    # only needs to know the packing fits, not each item's own coordinates.
+    require_placement_coordinates: bool = True
+    #: Opt-in worker-process ceiling for the multi-start portfolio. `1`
+    #: (the default) reproduces the original fully sequential orchestration
+    #: exactly, with zero behavioural change. A value above `1` lets
+    #: `SolverOrchestrator` run starts after the first concurrently in separate
+    #: processes -- see docs/ALGORITHMS-AND-COMPLEXITY.md's "Multi-start
+    #: orchestration" section for the eligibility rules and determinism argument.
+    parallel_starts: int = 1
+    #: Width of the deterministic beam over partial container plans.  The default
+    #: keeps the historical greedy path; ``quality()`` opts into the bounded search.
+    container_plan_beam_width: int = 1
+    #: Hard counted-work ceiling for container-plan nodes, independent of wall time.
+    container_plan_node_limit: int = 1
+
+    def __post_init__(self) -> None:
+        if (self.time_limit_ms <= 0 or self.top_k <= 0 or self.exact_item_limit <= 0
+                or self.multi_start_orders <= 0 or self.max_candidates_per_item <= 0
+                or self.parallel_starts <= 0 or self.container_plan_beam_width <= 0
+                or self.container_plan_node_limit <= 0):
+            raise ValueError("positive configuration values required")
+        if self.max_candidate_points < 16:
+            raise ValueError("max_candidate_points must be at least 16")
+        if not 0 <= self.minimum_support_ratio <= 1: raise ValueError("minimum_support_ratio must be between 0 and 1")
+        if self.dimensional_weight_divisor is not None and self.dimensional_weight_divisor <= 0:
+            raise ValueError("dimensional_weight_divisor must be positive")
+
+    @classmethod
+    def fast(cls, time_limit_ms: int = 200, **kwargs) -> "PackingConfig":
+        return cls(profile=SolverProfile.FAST, time_limit_ms=time_limit_ms, top_k=1, multi_start_orders=1, **kwargs)
+
+    @classmethod
+    def balanced(cls, time_limit_ms: int = 1000, top_k: int = 3, **kwargs) -> "PackingConfig":
+        return cls(profile=SolverProfile.BALANCED, time_limit_ms=time_limit_ms, top_k=top_k, **kwargs)
+
+    @classmethod
+    def quality(cls, time_limit_ms: int = 5000, top_k: int = 5, **kwargs) -> "PackingConfig":
+        kwargs.setdefault("container_plan_beam_width", 16)
+        kwargs.setdefault("container_plan_node_limit", 100_000)
+        return cls(profile=SolverProfile.QUALITY, time_limit_ms=time_limit_ms, top_k=top_k, multi_start_orders=24, max_candidates_per_item=16, **kwargs)
+
+    @classmethod
+    def exact_small(cls, time_limit_ms: int = 10000, **kwargs) -> "PackingConfig":
+        return cls(profile=SolverProfile.EXACT_SMALL, time_limit_ms=time_limit_ms, **kwargs)