This is the official OneOcean repository, combining the simulation code, project website, platform guide, and interactive demo.

Project website · Platform · Online demo

Authors: Shuaijun Liu¹, Qifu Wen²˒³, Xingwei Chen¹, Xinwen Hu⁴, Feiyang You¹, Sijia Chen¹, Ningxin Su¹,*.

¹ The Hong Kong University of Science and Technology (Guangzhou)

² Boston University · ³ Shanghai Jiao Tong University · ⁴ Tencent

*Corresponding author: Ningxin Su, ningxinsu@hkust-gz.edu.cn.

The repository includes:

• Data_pipeline/: ocean-environment data pipeline and dataset-variant generation.
• OCPNet/: pollution-field and current-aware pollution modeling code.
• benchmark_core/: core quantitative benchmark used for the large evaluation tables.
• tracks/oceangym_benchmark/: OceanGym and HoloOcean benchmark used for scene-grounded underwater evaluation and media generation.
• integrations/ros2/: optional ROS 2 Jazzy bridge for standard robot middleware integration.
• docs/demo/: interactive browser demo, deployed with the project website.
• tests/: regression tests for the benchmark.

Repository layout

OneOcean/
├── Data_pipeline/
├── OCPNet/
├── benchmark_core/
├── integrations/
│   └── ros2/
├── tracks/
│   └── oceangym_benchmark/
├── tests/
├── tools/
├── docs/
└── DATA_PIPELINE_LOG.md

Environment

Base Python dependencies are listed in requirements.txt.

Notes:

• The data pipeline requires Copernicus Marine credentials in the environment:
  • COPERNICUSMARINE_USERNAME
  • COPERNICUSMARINE_PASSWORD
• The OceanGym benchmark requires a working HoloOcean and Ocean package installation. That dependency is managed separately from the base requirements.
• Behavior Cloning (BC) training and some local planner backends in benchmark_core/ require extra ML dependencies such as torch.

Quickstart

1. Build the combined environment dataset

python3 Data_pipeline/run_pipeline.py --overwrite
python3 Data_pipeline/generate_variants.py --which tiny,scene,public --overwrite

The pipeline rationale, depth-handling decisions, and reproducibility notes are recorded in DATA_PIPELINE_LOG.md. The public schema, custom-data validation workflow, coordinate convention, and release variants are defined in docs/DATASET_CONTRACT.md.

Validate a generated or custom product before exporting it:

python3 tools/validate_environment_product.py \
  Data_pipeline/Data/Combined/variants/scene/combined/combined_environment.nc \
  --json-out runs/validation/scene.json

2. Run the benchmark core

Export a drift cache from the combined dataset:

python3 -m benchmark_core.cli.export_drift_cache \
  --nc Data_pipeline/Data/Combined/variants/scene/combined/combined_environment.nc \
  --u-var utotal \
  --v-var vtotal \
  --time-index 0 \
  --depth-index 0 \
  --out runs/benchmark_core/_cache/drift_scene_t0_d0.npz

Run one benchmark episode:

python3 -m benchmark_core.cli.run \
  --drift-npz runs/benchmark_core/_cache/drift_scene_t0_d0.npz \
  --task go_to_goal_current \
  --difficulty medium \
  --controller go_to_goal \
  --pollution-model gaussian \
  --n-agents 1 \
  --seed 0 \
  --dynamics-model 6dof \
  --constraint-mode hard \
  --bathy-mode hard \
  --validate

Run a sweep:

python3 -m benchmark_core.cli.run_matrix \
  --drift-npz runs/benchmark_core/_cache/drift_scene_t0_d0.npz \
  --preset paper_v1 \
  --dynamics-model 6dof \
  --constraint-mode hard \
  --bathy-mode hard \
  --validate

3. Run the OceanGym benchmark

Render baseline scene media:

python3 tracks/oceangym_benchmark/render_scene_media.py \
  --preset ocean_worlds_camera

Export a data-grounded current time series:

python3 tracks/oceangym_benchmark/export_current_series_npz.py \
  --dataset Data_pipeline/Data/Combined/combined_environment.nc \
  --out_npz runs/_cache/data_grounding/currents/cmems_center_uovo.npz

Run the OceanGym task suite:

python3 tracks/oceangym_benchmark/run_task_suite.py \
  --preset ocean_worlds_camera \
  --current_npz runs/_cache/data_grounding/currents/cmems_center_uovo.npz \
  --episodes 3

Documentation

• Data_pipeline/README.md: data pipeline usage and dataset assembly details.
• docs/DATASET_CONTRACT.md: environment schema, custom-data validation, and NetCDF-to-NPZ round-trip checks.
• docs/MODEL_SCOPE.md: implemented dynamics equations, default parameters, pollution probes/sinks, and model limitations.
• docs/LLM_PLANNER_DIAGNOSTICS.md: existing-run planner validity, fallback, latency, token, and task-level analysis.
• benchmark_core/README.md: quantitative benchmark protocol and CLI usage.
• tracks/oceangym_benchmark/README.md: OceanGym benchmark usage, media generation, and external-scene notes.
• integrations/ros2/README.md: ROS 2 frame, topic, service, build, and launch contract.
• docs/: project and platform website sources.

Regression test

python3 -m pytest -q