Robot SF

Gymnasium-based social navigation simulation and benchmarking for a robot moving through pedestrian-filled environments.

Status: Active development. Start here for a quick first touch, then use the linked docs for detailed workflows, benchmarks, and contributor guidance.

Start here

I want to...	Go to
Install and use Robot SF (newcomer path)	docs/user-guide.md — task-oriented: install, run a demo, load a map, choose a planner, run a benchmark, visualize results, troubleshoot
Understand the project quickly	Why Robot SF?
Decode an acronym or project term	docs/glossary.md
Install dependencies and run the first demos	Quickstart
Browse runnable examples	examples/README.md
Use benchmarks with evidence discipline	docs/research-guide.md
Discover and explain interesting benchmark cases	docs/case_workbench.md
Find architecture, contribution, and CI docs	docs/developer-guide.md
Browse all docs by audience	docs/README.md
Follow the contributor workflow	docs/dev_guide.md
Contribute docs, planners, scenarios, or fixes	CONTRIBUTING.md
Review repository conventions for agents and contributors	AGENTS.md
See the historical public Zenodo-backed release artifact	DOI 10.5281/zenodo.19563812
Trace upstream lineage and citations	ACKNOWLEDGMENTS.md

Current benchmark-data release

The approved benchmark-data release is the 14-arm S30/H600 matrix (48 scenarios, 30 seeds, differential-drive kinematics). Its bounded runtime smoke is documented in docs/benchmark_release_reproducibility.md and uses configs/benchmarks/releases/paper_experiment_matrix_v2_h600_s30_runtime_smoke_v0_2.yaml. Before a full campaign, the four hybrid arms must also pass the predeclared fallback-prone stress smoke. The old DOI above is historical; a fresh Zenodo concept is required for the current benchmark-data record. Social Navigation Quality Index (SNQI) is advisory/no-ranking, and the benchmark-data release remains separate from the software/package release.

Why Robot SF?

• Factory-based environments: reusable Gymnasium entry points for robot and pedestrian simulations.
• Curated examples: quickstart, advanced, benchmark, and plotting workflows live in examples/README.md.
• Benchmark-oriented tooling: reproducible evaluation, metrics aggregation, and analysis docs are indexed in docs/README.md.
• Repo-native contributor workflow: setup, validation, and shared scripts/dev/ entry points are documented in docs/dev_guide.md.

Quickstart

The repository uses uv for dependency management and keeps generated artifacts under the git-ignored output/ directory.

git clone https://github.com/ll7/robot_sf_ll7
cd robot_sf_ll7

scripts/dev/check_runtime_requirements.sh
uv sync --all-extras

# One-command visual demo: run a tiny deterministic episode and open a viewer.
uv run robot-sf demo

uv run python examples/quickstart/01_basic_robot.py
uv run python examples/quickstart/02_trained_model.py
uv run python examples/quickstart/03_custom_map.py

uv run robot-sf demo runs a short deterministic scenario, writes a recorded episode (episode.jsonl), a static browser viewer (viewer/index.html), a map thumbnail (thumbnail.png), and a plain-English summary under output/demo/latest/. It is the fastest install → run → see something path and is CPU-only. Open output/demo/latest/viewer/index.html in a browser to replay the episode.

Beginner notebooks

For an interactive, plotted walkthrough (run → compare → visualize), open the CPU-only notebooks under notebooks/:

uv run jupyter notebook notebooks/01_run_first_episode.ipynb

Each notebook is deterministic and writes its small artifact under output/notebooks/. Run all three headless with uv run python scripts/validation/run_notebooks_smoke.py.

Packaging smoke (wheel install smoke)

To validate a wheel install path in a clean environment:

uv build
scripts/validation/wheel_install_smoke.sh

The smoke installs the built wheel into a temporary venv, then verifies a minimal import with a small bootstrap dependency set (loguru, numba, matplotlib). This is a clean install + import guardrail, not a full runtime benchmark install.

Core simulation imports and basic environment creation are lightweight by default. Optional feature stacks can be installed via extras:

# Individual feature extras
uv sync --extra viz         # PyGame, Matplotlib, MoviePy, Seaborn
uv sync --extra maps        # OSMnx, GeoPandas, PyProj map tooling
uv sync --extra benchmark   # Pandas, SciPy benchmark & reporting tools
uv sync --extra training    # Stable-Baselines3, PyTorch, Optuna, W&B, TensorBoard

# Or install all feature extras
uv sync --extra all

CARLA is not installed by uv sync --all-extras. On CARLA-capable Linux x86_64 hosts, opt into the pinned host-side client with uv sync --all-extras --group carla and check the Docker runtime with scripts/dev/check_carla_runtime.sh.

These three scripts provide the fastest first-touch path:

1. 01_basic_robot.py introduces the environment factory and a headless rollout.
2. 02_trained_model.py replays the bundled PPO benchmark example.
3. 03_custom_map.py shows how to load and simulate a custom SVG map.

For host packages, optional capabilities, and a fuller setup walkthrough, see docs/dev_guide.md and docs/dev_runtime_requirements.md.

Where to go next

• Examples: examples/README.md organizes the quickstart path plus advanced features, benchmark runners, and plotting utilities.
• Documentation index: docs/README.md is the central map for architecture, benchmarking, training, analysis, and context notes.
• Benchmark and artifact context: the historical release artifact is published at 10.5281/zenodo.19563812. For current S30/H600 benchmark semantics and caveats, follow the benchmark docs linked from docs/README.md.

Dissertation and academic use

This repository is used as the Robot SF evidence base for dissertation work on scenario-based safety validation for autonomous micromobility vehicles. If you are:

• Reviewing the dissertation: use the public release artifact DOI above and the repository tag named by the dissertation or artifact metadata. The dissertation repository maps claims to Robot SF evidence and reproduction steps.

• Reproducing benchmark results: clone this repository, check out the release tag or commit specified by the artifact, and follow the Quickstart plus the benchmark section in docs/README.md.

• Building on this work: use CONTRIBUTING.md and docs/contributing_planner.md for current extension paths.

• Citing this work: use the DOI badge above (10.5281/zenodo.19563812) only for the historical release artifact. The current S30/H600 benchmark-data DOI is pending a fresh Zenodo concept; use the exact DOI named by the approved release manifest once assigned.

Development workflow

Use the development guide as the source of truth for contributor commands. The common local flow is:

uv run pre-commit install
scripts/dev/ruff_fix_format.sh
scripts/dev/run_tests_parallel.sh
BASE_REF=origin/main scripts/dev/pr_ready_check.sh

If you are contributing through an agent workflow or want the repository-specific automation rules, start with AGENTS.md.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for contribution types, PR expectations, and extension pathways. Before starting work:

1. Check AGENTS.md for agent-specific workflow guidance.
2. Read docs/dev_guide.md for local setup and validation.
3. Run tests locally with scripts/dev/run_tests_parallel.sh.
4. Run the final gate with BASE_REF=origin/main scripts/dev/pr_ready_check.sh.

For substantial changes, please open an issue first to discuss the approach.

Extending robot_sf

The framework is designed to be extended. Common extension points:

Adding a New Planner

Planner adapters usually live under robot_sf/planner/, with metadata and benchmark wiring described in docs/contributing_planner.md.

Adding Scenario Families

Scenario definitions live under configs/scenarios/. See docs/benchmark_suites.md, docs/scenario_zoo/index.md, and examples/README.md for how to load and customize scenarios.

Custom Maps

Maps are SVG files under maps/svg_maps/ and related map assets under maps/. To add a new map, create valid SVG geometry, update the relevant map/scenario config, and test with examples/quickstart/03_custom_map.py.

Acknowledgments and provenance

The root README stays intentionally short. Upstream lineage, cited papers, and related repositories are preserved in ACKNOWLEDGMENTS.md.