FinsSim is an open, end-to-end platform for underwater-robot simulation, reinforcement learning, ROS 2 control, system identification, and sim-to-real evaluation (Project Page). It keeps the control and observation contract stable across Unity-based simulation, trained policies, ROS 2 evaluation, and the physical vehicle.
The hardware code is mainly designed for our FinsROV, while the ROS 2 network, other perception modules and the organized hardware architecture can be adapted to any other vehicles. We've also imported third-party models like BlueROV2 in Unity.
The Unity simulator is maintained in the companion FinsSimUnity repository and the Isaac Lab backend in FinsSimIsaacLab. This repository contains the Python, ROS 2, experiment, and integration workspace.
- Fidelity-Scalable Hydrodynamics — select simplified or calibrated Fossen-form dynamics and mesh-based hydrodynamics, integrate third-party vehicle models, and identify or replay-validate vehicle dynamics against recorded trials.
- Unified Learning Workflows — common Python/CLI entry points for control baselines, single-agent RL, and multi-agent RL; configuration-driven runs, parallel simulation, and domain-randomization tools for vehicle, actuator, and hydrodynamic uncertainty.
- Reliable Sim-to-Real Transfer — ROS 2 connects simulation, controllers, state estimation, and bounded thruster execution, with low-cost overhead refractive AprilTag localization fused with IMU and depth measurements for pool-scale deployment.
- Complete Experimental Verification — T1/T2 experiment recording, top-view camera capture, hydrodynamic identification, Unity–Fossen replay validation, and matched simulation/pool evaluation workflows.
python/
finssim_core/ Shared configuration, runtime, ports, and experiment utilities
finssim_cli/ The top-level `finssim` command-line interface
finssim_rl/ Single-agent reinforcement-learning backend
finssim_marl/ Multi-agent reinforcement-learning backend
ros2_ws/ ROS 2 control, bridge, perception, and identification packages
configs/ Versioned experiment configurations
docs/ Architecture, calibration, training, and validation documentation
simulators/
unity/ Optional Unity projects
FinsSimUnity/ Unity simulator and task definitions
isaaclab/ Optional Isaac Lab backend and task definitions
FinsSimIsaacLab/ Isaac Lab simulator and task definitions
This release-candidate branch does not ship the
python/finssim_irl inverse-reinforcement-learning package. IRL-related
material that remains under configs/ or docs/ is retained as development
reference only; it is not an installable, supported, or reproducible feature
of this release candidate. The source remains in the private development
line until its release plan is finalized.
Clone the repository, initialize only the retained third-party submodules, and create the managed Python environment:
git clone https://github.com/IWIN-FINS/FinsSim.git
cd FinsSim
git submodule update --init --recursive
uv sync --all-packages
uv run --package finssim-cli finssim infoUnity and Isaac Lab is optional and is intentionally an independent repository, rather than a submodule. To use that backend, clone a reviewed release into the expected local path:
git clone https://github.com/IWIN-FINS/FinsSimUnity.git \
simulators/unity/FinsSimUnity
git clone https://github.com/IWIN-FINS/FinsSimIsaacLab.git \
simulators/isaaclab/FinsSimIsaacLabPreview training commands without launching a Unity executable:
uv run --package finssim-cli finssim rl train \
-c configs/rl/example.yaml --dry-run
uv run --package finssim-cli finssim marl train \
-c configs/marl/example.yaml --dry-runTo train, set unity.env_path to a compatible Unity server build in the YAML
configuration, then remove --dry-run. See the backend and training documents
below before starting a real run.
External installations are deliberately not hard-coded. Set ISAACLAB_PATH,
UNITY_EDITOR_PATH, and (when using a separate Unity checkout)
FINSSIM_UNITY_ROOT in your shell or CI environment before using the matching
profiles.
| Topic | Entry point |
|---|---|
| Full documentation map | English · 中文 |
| Training backends | English · 中文 |
| Single-agent RL | English · 中文 |
| Multi-agent RL | English · 中文 |
| ROS 2 workspace | ros2_ws/README.md |
| Hydrodynamic identification | FinsROV profile identification |
| Unity–Fossen validation | Replay validator |
| Coordinate convention | Coordinate-system audit |
| License audit | 中文 |
If FinsSim contributes to academic work, please cite the accompanying paper.
CITATION.cff also retains the software record used by
GitHub's Cite this repository panel.
@article{zhang2026finssim,
title = {FinsSim: A Reality-Aligned Integrated Simulation Platform for Underwater Robot Learning},
author = {Zhang, Yu and Song, Yuanmingqing and Rao, Xiangyun and Fong, Pangkit and Zhang, Kunhao and Fang, Chongrong and He, Jianping},
journal = {arXiv preprint arXiv:2609.23943},
year = {2026},
doi = {10.48550/arXiv.2609.23943},
url = {https://arxiv.org/abs/2609.23943}
}FinsSim-owned portions are released under the Apache License 2.0. FinsSim may also be licensed under a separate commercial agreement for support, warranties, proprietary redistribution terms, or other rights not provided by the public license; see COMMERCIAL-LICENSE.md.
The repository is not uniformly Apache-2.0: imported and third-party components retain their own notices and licenses. Read THIRD_PARTY_NOTICES.md and the component-level license before redistributing or relicensing any part of the project.
Please use GitHub Issues for bug reports and feature discussions. Before opening a change, preserve the project's coordinate, observation/action, and thruster-order contracts; these interfaces are shared by the simulator, controllers, training code, and hardware bridge.
If FinsSim contributes to academic work, please cite the accompanying paper.
CITATION.cff also retains the software record used by
GitHub’s Cite this repository panel.
@article{zhang2026finssim,
title = {FinsSim: A Reality-Aligned Integrated Simulation Platform for Underwater Robot Learning},
author = {Zhang, Yu and Song, Yuanmingqing and Rao, Xiangyun and Fong, Pangkit and Zhang, Kunhao and Fang, Chongrong and He, Jianping},
journal = {arXiv preprint arXiv:2609.23943},
year = {2026},
doi = {10.48550/arXiv.2609.23943},
url = {https://arxiv.org/abs/2609.23943}
}We gratefully acknowledge the contributions of the following underwater hydrodynamics, robotics-simulation, and learning platforms. They informed the research landscape discussed by FinsSim and the accompanying paper. Links in this section provide attribution only: these projects are not bundled runtime dependencies of FinsSim, and their inclusion does not imply endorsement or feature equivalence.
The platform-scope comparison in the paper is based on the primary publication or software record linked below. It reports native support described by those sources; later external integrations may provide additional capabilities.
| Platform | Primary publication / software record | Upstream source |
|---|---|---|
| UUV Simulator | Manhaes et al., 2016 | GitHub |
| DAVE | Zhang et al., 2022 | GitHub |
| HoloOcean | Romrell et al., 2025 | Bitbucket |
| Stonefish | Grimaldi et al., 2025 | GitHub |
| MARUS | Loncar et al., 2022 | GitHub |
| MarineGym | Chu et al., 2025 | GitHub |
| UNav-Sim | Amer et al., 2023 | GitHub |
| Orca | orca4 software record / orca5 software record | orca4 / orca5 |
The following projects are maintained as source checkouts in the local research-reference workspace. DAVE, HoloOcean, UNav-Sim, MarineGym, Stonefish, and Orca are already listed above; the remaining checkouts and their upstream-supplied references are recorded here for complete attribution.
| Project | Publication / reference | Upstream source |
|---|---|---|
Gazebo Sim (gz-sim) |
Simulation-engine source; no project-specific paper is asserted here. | GitHub |
| BlueROV2 Gym | Puthumanaillam et al., 2024, TAB-Fields | GitHub |
| Isaac AUV Environment | Cai, Chang, and Girdhar, 2025, Learning to Swim | GitHub |
| URSim | Katara et al., 2019 | GitHub |
| SafeRLAUV | Aquatic Navigation: A Challenging Benchmark for Deep Reinforcement Learning (RLC 2024) | GitHub |
| RLforUTracking | Source implementation; its checkout does not provide a stable project-specific publication record. | GitHub |