Metadata-Version: 2.4
Name: gpuastar-experiments
Version: 0.1.0
Summary: Examples and benchmarks for GPUAStar optional backends
Project-URL: GitHub, https://github.com/misaghsoltani/GPUAStar
Author-email: Misagh Soltani <msoltani@email.sc.edu>
License-Expression: MIT
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Typing :: Typed
Requires-Python: <3.15,>=3.10
Requires-Dist: gpuastar==0.1.0
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: tomli<3,>=2.1; python_version < '3.11'
Provides-Extra: cpp
Requires-Dist: gpuastar-experiments-cpp==0.1.0; (implementation_name == 'cpython' and python_version < '3.15' and ((platform_system == 'Linux' and (platform_machine == 'x86_64' or platform_machine == 'aarch64')) or (platform_system == 'Darwin' and platform_machine == 'arm64') or (platform_system == 'Windows' and platform_machine == 'AMD64'))) and extra == 'cpp'
Provides-Extra: runtime
Requires-Dist: jinja2<4,>=3.1.2; (implementation_name == 'cpython') and extra == 'runtime'
Requires-Dist: matplotlib<4,>=3.10.5; (implementation_name == 'cpython' and python_version >= '3.14') and extra == 'runtime'
Requires-Dist: matplotlib<4,>=3.8.4; (implementation_name == 'cpython' and python_version < '3.13') and extra == 'runtime'
Requires-Dist: matplotlib<4,>=3.9.2; (implementation_name == 'cpython' and python_version >= '3.13' and python_version < '3.14') and extra == 'runtime'
Requires-Dist: numpy<2,>=1.26; (implementation_name == 'cpython' and platform_system == 'Darwin' and platform_machine == 'x86_64' and python_version < '3.13') and extra == 'runtime'
Requires-Dist: numpy<3,>=2.0.0; (implementation_name == 'cpython' and python_version < '3.13' and (platform_system != 'Darwin' or platform_machine != 'x86_64')) and extra == 'runtime'
Requires-Dist: numpy<3,>=2.1; (implementation_name == 'cpython' and python_version >= '3.13' and python_version < '3.14') and extra == 'runtime'
Requires-Dist: numpy<3,>=2.3.2; (implementation_name == 'cpython' and python_version >= '3.14') and extra == 'runtime'
Requires-Dist: pandas<4,>=2.2.2; (implementation_name == 'cpython' and python_version < '3.13') and extra == 'runtime'
Requires-Dist: pandas<4,>=2.2.3; (implementation_name == 'cpython' and python_version >= '3.13' and python_version < '3.14') and extra == 'runtime'
Requires-Dist: pandas<4,>=3; (implementation_name == 'cpython' and python_version >= '3.14') and extra == 'runtime'
Requires-Dist: setuptools<82,>=69; (implementation_name == 'cpython') and extra == 'runtime'
Requires-Dist: torch<2.3,>=2.2.2; (implementation_name == 'cpython' and platform_system == 'Darwin' and platform_machine == 'x86_64' and python_version < '3.13') and extra == 'runtime'
Requires-Dist: torch<3,>=2.11; (implementation_name == 'cpython' and python_version >= '3.14' and python_version < '3.15' and ((platform_system == 'Linux' and (platform_machine == 'x86_64' or platform_machine == 'aarch64')) or (platform_system == 'Darwin' and platform_machine == 'arm64') or (platform_system == 'Windows' and platform_machine == 'AMD64'))) and extra == 'runtime'
Requires-Dist: torch<3,>=2.5.1; (implementation_name == 'cpython' and platform_system == 'Linux' and platform_machine == 'aarch64' and python_version < '3.13') and extra == 'runtime'
Requires-Dist: torch<3,>=2.6; (implementation_name == 'cpython' and python_version < '3.14' and ((platform_system == 'Linux' and platform_machine == 'x86_64') or (platform_system == 'Linux' and platform_machine == 'aarch64' and python_version >= '3.13') or (platform_system == 'Darwin' and platform_machine == 'arm64') or (platform_system == 'Windows' and platform_machine == 'AMD64'))) and extra == 'runtime'
Description-Content-Type: text/markdown

# gpuastar-experiments

`gpuastar-experiments` contains the domain and experiment code that is kept out of the base `gpuastar` package:

- **Example domains** in [src/gpuastar_experiments/environments/](src/gpuastar_experiments/environments/): Rubik's Cube (`cube3`), sliding tile puzzles (`puzzle15`, `puzzle24`, `puzzle35`, `puzzle48`), Lights Out (`lightsout7`), and Sokoban (`sokoban`), together with their tensor-based adapters.
- **Test datasets and trained model checkpoints** in `src/gpuastar_experiments/data/` and `src/gpuastar_experiments/saved_models/`.
- **Hydra default overlays** in [src/gpuastar_experiments/configs/hydra/command_defaults/](src/gpuastar_experiments/configs/hydra/command_defaults/), made visible to the `gpuastar` CLI by the search-path plugin in [src/hydra_plugins/gpuastar_experiments_searchpath.py](src/hydra_plugins/gpuastar_experiments_searchpath.py). With this package installed, `command=astar_search` and `command=aoti_export` receive Rubik's Cube example defaults for the environment, dataset, model, and results paths.
- **The experiment suite** in [src/gpuastar_experiments/experiments/](src/gpuastar_experiments/experiments/), driven by the `gpuastar-experiment` console script and the presets in `experiments/conf/experiment/`. The shell wrappers in [scripts/](scripts/) call the presets.
- **Benchmark runners**: the standalone CUDA solver examples in `src/gpuastar_experiments/program/`.
- **Compiled example domains for the C++ solver** in [cpp/](cpp/), packaged separately as `gpuastar-experiments-cpp`.

## Installation

```bash
python -m pip install "gpuastar[experiments]"
```

The CUDA examples also require the CUDA solver:

```bash
python -m pip install "gpuastar[cu,experiments]"
```

## Running from a source checkout

The Pixi environments defined at the repository root include this package. Two examples:

```bash
CUDA_VISIBLE_DEVICES=1 pixi run -e cu-experiments cu-example-program
CUDA_VISIBLE_DEVICES=1 pixi run -e cu-experiments cu-cube3-smoke
```

To run an experiment preset:

```bash
pixi run -e dev gpuastar-experiment experiment=quick_validation
```

The available presets and the output layout are documented in the [repository README](../README.md#experiment-suite) and in [docs/benchmarks.md](../docs/benchmarks.md).
