PackSim

PackSim provides the regular-box simulation environments used by the RoboBPP robot bin-packing benchmark. The package includes a canonical occupancy dataset, replay actions, configuration files, PyBullet scenes, the IRB6700 robot model, and the native OMPL bindings required by the robot-planning mode.

Project documentation: https://robot-bin-packing-benchmark.github.io/documentation.html

Features

• self-contained canonical inputs for a first run;
• headless PyBullet simulation for server environments;
• three simulation settings, from packing-only to robot motion planning;
• backward-compatible simulate(dict) API;
• structured Python results and machine-readable command-line output;
• installation diagnostics with packsim doctor.

PackSim 0.1.0 supports regular 3D box packing with the bundled occupancy dataset and PCT replay. Irregular and 2D packing are outside this release.

Requirements

Version 0.1.0 retains native OMPL 1.5.2 bindings and therefore has a narrow runtime target:

• Linux x86-64/amd64;
• CPython 3.8;
• glibc 2.31 or newer;
• a repaired manylinux_2_31_x86_64 wheel.

Python 3.9 or newer, macOS, Windows, and ARM are not supported by this release. The wheel is platform-specific and is not published as py3-none-any.

Python 3.8 is end-of-life. Version 0.1.0 uses it only to preserve compatibility with the bundled OMPL ABI, and should be installed in an isolated environment. A later release will move to rebuilt or current OMPL bindings and a maintained Python version.

Installation

Create an isolated Python 3.8 environment, then install from PyPI:

python3.8 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade "pip<25.1"
python -m pip install packsim==0.1.0
packsim doctor

Ubuntu 24.04 does not provide Python 3.8 as its system Python. See docs/installation.md for the supported Miniforge setup and clean-install checks.

Quick start

The existing dictionary API remains available:

from packsim import simulate

summary = simulate({
    "setting": 1,
    "data": "occupancy",
    "test_data_config": 0,
    "gui": 0,
})
print(summary)

Configuration, actions, planning times, and occupancy data are loaded from the installed package when their paths are omitted. Results are written to ./packsim-results by default.

New code can use the structured API:

from packsim import SimulationConfig, run

result = run(SimulationConfig(
    setting=1,
    data="occupancy",
    test_data_config=0,
    gui=False,
))

print(result.status)
print(result.placed_items)
print(result.occupancy)
print(result.termination_reason)

Custom paths are still supported:

from packsim import simulate

simulate({
    "setting": 1,
    "data": "occupancy",
    "test_data_config": 0,
    "gui": 0,
    "config": "/absolute/path/to/default.yaml",
    "action_path": "/absolute/path/to/action.json",
    "planning_time_path": "/absolute/path/to/planning_time.json",
    "save_path": "/absolute/path/to/results",
})

Simulation settings

Run a headless canonical simulation from any directory:

packsim smoke-test --setting 1
packsim smoke-test --setting 2
packsim smoke-test --setting 3

Add --json for machine-readable output or --output DIR to select the result directory. Use --gui only when a desktop display is available.

status="completed" means the simulator reached a controlled terminal state. Check all_items_placed, placed_items, failed_item, and termination_reason for the outcome of an individual run.

The canonical regression values for 0.1.0 are:

Diagnostics

Run the environment check before reporting an installation problem:

packsim doctor
packsim doctor --json

The report checks Python and platform compatibility, installed dependency versions, canonical resource hashes, bundled OMPL locations, and an isolated native-library load on the supported runtime.

Common issues:

Development

Installation details are in docs/installation.md. Maintainer build, validation, and upload commands are in docs/release.md. The release process rejects universal, raw linux_x86_64, incomplete, or incorrectly tagged wheels.

License

Original PackSim code is distributed under the MIT License. Bundled components and assets retain their upstream licenses. See THIRD_PARTY_NOTICES.md and the LICENSES directory.