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
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
Find architecture, benchmark, and workflow docs	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 public Zenodo-backed release artifact	DOI 10.5281/zenodo.19563812
Trace upstream lineage and citations	ACKNOWLEDGMENTS.md

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

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

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.

Training and experiment tooling is optional for core imports. Install it explicitly when running PPO/SB3, Optuna, TensorBoard, or W&B workflows:

uv sync --extra training

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 public release artifact is published at 10.5281/zenodo.19563812. For benchmark-specific 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) for the release artifact unless the paper or dissertation specifies a newer artifact.

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.