This repository contains the Simulator and Supplementary Materials for the paper "Never too Prim to Swim: An LLM-Enhanced RL-based Adaptive S-Surface Controller for AUVs under Extreme Sea Conditions".

⚠️ Work-in-Progress Notice: This repository contains a code implementation for demonstration purposes.

Run this command to install the dependencies:

pip install -r requirements.txt

Important: The visualization module requires the H.264 codec. Download the openh264 binary and place it in the project’s root directory.

Next, install our modified Python Vehicle Simulator (PVS), which includes our S-surface controller implementation:

cd PVS/
pip install -e .

We provide implementations for two high-level underwater tasks described in the paper. The code resides in data_collection/.

Execute training with:

python train_td3.py --wave 0.5 --usbl

• --wave: JONSWAP wave amplitude. (Default: 0, namely disable)
• --usbl: Enables USBL positioning noise (disable to use ground-truth positions).

Additional hyperparameters (e.g., for control, simulation, TD3 algorithm) can be adjusted via command-line arguments. Refer to the source code for details.

Run inference with a trained model:

python eval_td3.py

Arguments follow the same definitions as above.

Both phases generate visualization files and logs:

• Training:
  • Visualization records: record_train/yyyy_mm_dd_hh_mm_ss.pkl (timestamped).
  • Logs: Saved to logs/.
• Evaluation:
  • Visualization records: record_eval/yyyy_mm_dd_hh_mm_ss.pkl.

• 2D Visualization:

  python genvideo_2D.py --preview -1 --fname XXX --mode train --speed 5  

  • --preview N: Previews N-th frames (negative values skip preview).
  • --fname: Input filename (without .pkl).
  • --speed: Playback speed multiplier.
    Output: output_2D.mp4 (H.264/AVC, 10 Mbps). Use FFmpeg for further format conversion.

• 3D Visualization:

  python genvideo_3D.py --preview -1 --fname XXX --mode train --speed 5  

  Parameters match the 2D script.

The 6-DOF simulator is adapted from the Python Vehicle Simulator.

If you find the code repository useful for your work, please cite:

@article{xie2025AUVRScontrol,
      title={Never too Prim to Swim: An LLM-Enhanced RL-based Adaptive S-Surface Controller for AUVs under Extre Sea Conditions},
      author={Xie, Guanwen and Xu, Jingzehua and Ding, Yimian and Zhang, Zhi and Zhang, Shuai and Li, Yi},
      journal={arXiv preprint arXiv:2503.00527},
      year={2025}}