Metadata-Version: 2.1
Name: packsim
Version: 0.1.0
Summary: Reproducible robot bin-packing simulation for the RoboBPP benchmark
Author-email: wzf <wangzhoufeng7346@gmail.com>
License: MIT License
        
        Copyright (c) 2025-2026 wzf
        
        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.
        
Project-URL: Documentation, https://robot-bin-packing-benchmark.github.io/documentation.html
Project-URL: Package index, https://pypi.org/project/packsim/
Keywords: bin packing,motion planning,robotics,simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.9,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: LICENSES/Apache-2.0.txt
License-File: LICENSES/BSD-3-Clause.txt
License-File: LICENSES/Boost-1.0.txt
License-File: LICENSES/MIT-Third-Party.txt
License-File: LICENSES/ODE-BSD-3-Clause.txt
Requires-Dist: numpy==1.23.5
Requires-Dist: scipy==1.10.1
Requires-Dist: pybullet==3.2.7
Requires-Dist: gym==0.26.2
Requires-Dist: transforms3d==0.4.2
Requires-Dist: PyYAML==6.0.2
Requires-Dist: easydict==1.13
Requires-Dist: tqdm==4.67.1
Provides-Extra: release
Requires-Dist: build==1.2.2.post1; extra == "release"
Requires-Dist: twine==5.1.1; extra == "release"
Requires-Dist: wheel==0.45.1; extra == "release"
Requires-Dist: auditwheel==6.1.0; platform_system == "Linux" and extra == "release"
Provides-Extra: test
Requires-Dist: build==1.2.2.post1; extra == "test"
Requires-Dist: pytest==8.3.5; extra == "test"
Requires-Dist: tomli==2.0.2; python_version < "3.11" and extra == "test"

# 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:

```bash
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`](docs/installation.md) for the supported Miniforge
setup and clean-install checks.

## Quick start

The existing dictionary API remains available:

```python
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:

```python
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:

```python
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

| Setting | Components | Bundled replay |
| --- | --- | --- |
| 1 | Packing environment | 27 actions |
| 2 | Packing environment and PyBullet physics | 24 physics-aware actions |
| 3 | Packing environment, PyBullet, IRB6700, and OMPL | 24 physics-aware actions |

Run a headless canonical simulation from any directory:

```bash
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:

| Setting | Expected result |
| --- | --- |
| 1 | 27 requested, 27 placed, mean occupancy `0.8692859120457622` |
| 2 | 24 requested, 23 placed, item index 23 rejected by the stability preflight, mean occupancy `0.8889730809076817` |
| 3 | Native OMPL loads and the robot planner exits cleanly with a structured result |

## Diagnostics

Run the environment check before reporting an installation problem:

```bash
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:

| Symptom | Action |
| --- | --- |
| `No matching distribution found` | Confirm Linux x86-64 and CPython 3.8. |
| OMPL or shared-library load error | Confirm that pip installed the repaired `manylinux_2_31_x86_64` wheel, then save `packsim doctor --json`. |
| PyBullet cannot connect to X | Run headless without `--gui`. |
| A custom input cannot be found | Use the bundled defaults or pass an absolute path. |

## Development

Installation details are in [`docs/installation.md`](docs/installation.md).
Maintainer build, validation, and upload commands are in
[`docs/release.md`](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`](THIRD_PARTY_NOTICES.md) and the `LICENSES` directory.
