Underwater Systems

This course is titled “Underwater Systems” and provides a foundation in oceanic engineering, covering both theoretical concepts and practical applications.

It is part of the Master Degree in Robotics and Automation Engineering, University of Pisa, Italy

Teaching semester: Spring 2026

Language of instruction: Italian and English

Course coordinators:

Riccardo Costanzi and Andrea Munafo

Facts

  • Version: 1
  • Credits: 6
  • Study level: Master’s degree level

How to use this material

This is the course handbook. It is composed of a PDF, which is what you are most likely reading now, and of a companion website and jupyter notebooks.

The website is available at: andreamunafo.github.com/underwater-systems The notebooks are available on github.

You are welcome to download the notebooks and run them on your own. This will give you a chance to investigate some concepts more deeply, changing parameters and code, and verifying the impact that they have directly.

You can open and run each notebook in any order your prefer depending on your interest.

Notebooks: Installation Instructions

This repository’s notebooks are designed for Python 3.10 and depend on several Python libraries:

  • jupyter notebooks
  • numpy
  • pandas
  • matplotlib

Apart from installing the necessary python dependencies there is no much else that you need to do to open the notebooks.

However, if you want to run the code, you need to do one more step and intalling the underwater_system package in your system. This is to tell python where to look for the modules that constitute the package and hence resolve paths.

Installing the package is easy, you need to run thefollowing command in your terminal, ideally from the root directory of this repository:

pip install -e '.[dev]'

Explanation of the command components: - -e: Stands for “editable”, allowing you to modify and immediately utilize the package during development. - .: Targets the current directory, implying the package is installed from here. - [dev]: Specifies additional “development” dependencies, which are required for tasks like documentation and testing, but not for the package’s core functionality.

To avoid polluting your OS with unnecessary libraries we strongly recommend to run the notebooks within a virtual environment. You can do that easily using Anaconda (among others).

For a quick guide on setting up an Anaconda environment, refer to the 00_Getting_started_with_Python_and_Jupyter_Notebook.ipynb

notebook.

Troubleshooting

In case you encounter the following error:

ModuleNotFoundError: No module named 'underwater_systems'

It indicates that the underwater_system package is missing. The underwater_system package is this repository, and you need to install it in your system some of the code to work. Refer to the previous section to install.

Automating Jupyter Book PDF Generation with Images

This handout is built from the website and notebook. You can build the PDF yourself if you prefer. To do so, you can follow the instructions reported below.

Overview

The build_jupyterbook_with_images.py script automates the process of including images in the PDF version of your Jupyter Book. It copies an ‘images’ directory to the appropriate location within the Jupyter Book build directory and then executes the build process.

Prerequisites

  • Python 3.x installed.
  • Jupyter Book and its dependencies are installed.
  • pyppeteer

Structure Assumptions

  • The script is located in the bin directory at the project root.
  • The images folder, which contains the images to be included in the PDF, is at the project root.
  • The Jupyter notebooks are in a directory named nbs at the project root.

Usage Instructions

  1. Navigate to the bin directory where the script is located.

  2. Run the script using Python:

    python bin/build_jupyterbook_with_images.py

  3. The script will copy the images folder to the Jupyter Book build directory and then start the build process for the PDF version of your Jupyter Book.

  4. Upon successful execution, the script will output a confirmation message. If any issues occur, error messages will be displayed.

Fix for pyppeteer.errors.TimeoutError

If you encounter a timeout error (pyppeteer.errors.TimeoutError: Navigation Timeout Exceeded: 30000 ms exceeded) when building your Jupyter Book, a simple fix can be applied.

Steps to Apply the Fix

  1. Locate the pdf.py file in your Jupyter Book or pyppeteer environment.

  2. Open pdf.py and navigate to line 50.

  3. Modify the line from:

    await page.goto(f"file:///{html_file}", {"waitUntil": ["networkidle2"]})

    to:

    await page.goto(f"file:///{html_file}", {"timeout": 0, "waitUntil": ["networkidle2"]})

This change sets the timeout to zero, effectively removing the timeout limit, and allows the page to load completely before proceeding, which can resolve the timeout issue encountered during the PDF generation process.

Acknowledgements and references

This handout is build from a number of contributions, but first and foremost, it is strongly based on the class held by prof. Andrea Caiti at the University of Pisa.

Relevant textbooks and resources used to prepare these notebooks are reported in 00_Syllabus.ipynb

Frequently Asked Questions (FAQ)

You might have a lot of questions on the course, its structure, our lab and marine robotics in general. Some of them will probably be addressed as we go through the class. The most frequent ones we receive are answered here: 00_FAQ.ipynb