Before the seminar

Install Docker, download the hands-on folder and check that it runs

1 Prerequisites and setup

Complete this setup before attending the seminar, so that the hands-on time goes on the exercises rather than on installation. Allow 20–40 minutes, depending on your operating system and internet connection.

The hands-on part runs in Jupyter notebooks inside a ready-made Docker container: a packaged Linux environment with Python, PyTorch and the seminar’s code already installed. You do not need to install Python, Conda, Jupyter or any Python package.

1.1 What you need

  • A laptop or desktop computer running a supported, up-to-date version of Windows, macOS or Linux, with at least 8 GB of memory and 3 GB of free disk space.
  • An internet connection before the seminar. The container image is a one-off download of about 500 MB; the hands-on folder is about 41 MB.
  • Permission to install applications on your computer. On an institution-managed computer, you may need help from your IT administrator.
  • Docker, installed and running (Step 1).

You will use a terminal for a few commands, mainly to check Docker: - Windows: PowerShell (or Windows Terminal with a PowerShell tab). - macOS: Terminal (Applications → Utilities → Terminal). - Linux: your usual terminal application.

1.2 Step 1 — Install Docker

Docker runs the seminar’s computational environment in a container. Install Docker Desktop on Windows or macOS. On Linux, install Docker Engine, or Docker Desktop for Linux if you prefer a graphical application.

1.2.1 Windows 10/11

Docker Desktop uses the WSL 2 backend for the recommended Linux-container workflow.

  1. Check that your Windows version supports WSL 2 and hardware virtualization is enabled in your computer’s BIOS/UEFI. Your institution’s IT team may need to help with managed computers.

  2. Open PowerShell as Administrator.

  3. Run:

    wsl --install

  4. Restart Windows if prompted. Complete the first-time Ubuntu/WSL setup if Windows asks you to create a Linux username and password.

  5. Open PowerShell and run:

    wsl --update
wsl --version

  6. Download Docker Desktop for Windows from the official Docker installation page.

  7. Run the installer. Select the WSL 2 backend when prompted. Follow the installation wizard.

  8. Start Docker Desktop from the Windows Start menu.

  9. Accept the Docker terms and wait until Docker Desktop reports that its engine is running.

  10. Keep Docker Desktop running while using the seminar repository.

If WSL 2 is already installed and working, you do not need to reinstall it. If your machine is managed by your institution and you cannot enable virtualization or install WSL 2, contact your IT administrator before the seminar.

1.2.2 macOS

  1. Check whether your Mac has an Apple silicon processor or an Intel processor:
    • Open Apple menu → About This Mac.
    • The Chip field indicates Apple silicon; the Processor field indicates Intel.
  2. Open the official Docker Desktop for Mac installation page.
  3. Download the installer for your processor type.
  4. Open the downloaded .dmg file.
  5. Drag Docker to the Applications folder as directed.
  6. Open Docker from Applications.
  7. Accept the Docker terms and complete any first-run prompts.
  8. Wait until Docker Desktop reports that its engine is running.

1.2.3 Ubuntu Linux — Docker Engine

The following commands install Docker Engine and the Compose plugin from Docker’s official APT repository on supported Ubuntu releases (64-bit).

  1. Open a terminal.

  2. Remove conflicting distribution packages if they are installed:

    sudo apt remove -y docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc

    If some packages are not installed, APT may simply report that they could not be found.

  3. Install prerequisites and add Docker’s official signing key:

    sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

  4. Add the official Docker repository:

    sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

  5. Install Docker Engine, the CLI, container runtime, Buildx and the Compose plugin:

    sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

  6. Start Docker and enable it at boot:

    sudo systemctl enable --now docker

  7. Verify that the service is active:

    sudo systemctl status docker --no-pager

  8. For this seminar, the simplest reliable approach is to prefix Docker commands with sudo on Linux, for example sudo docker run --rm hello-world and sudo ./start.sh. You can optionally configure non-root Docker access by following Docker’s Linux post-installation instructions. Be aware that membership in the docker group grants root-level privileges.

For distributions other than Ubuntu, follow Docker’s official Engine installation guide. Docker Desktop for Linux is also available; see the Linux Desktop installation guide.

1.3 Step 2 — Check that Docker works

Open a new terminal after installation. Docker Desktop must be running on Windows and macOS.

Run:

docker version

You should see both a Client and a Server section. If the server section is missing or the command says it cannot connect to the Docker daemon, start Docker Desktop (Windows/macOS) or the Docker service (Linux).

Now run Docker’s test container:

docker run --rm hello-world

Docker should download a small image and print a message confirming that the installation works.

1.4 Step 3 — Download and start the hands-on folder

  1. Download inundation-seminar-1.0.zip (about 41 MB) from Google Drive. The link opens a preview page: click the Download button (the arrow at the top right). Drive then says it cannot scan the file for viruses because it is large; choose Download anyway.
  2. Unzip it somewhere convenient, for example your Documents folder. You get a folder inundation-seminar-1.0.
    • Windows: right-click the zip and choose Extract All. Do not run the files from inside the zip.
    • macOS: double-click the zip, or let Safari unzip it for you.
  3. Start it:
    • Windows: open the folder and double-click start.bat. A black terminal window opens and must stay open. If Windows SmartScreen warns about an unknown app, choose More info → Run anyway.
    • macOS: open a terminal in the folder. In Finder, right-click the folder and choose Services → New Terminal at Folder; or type cd (with a space) in Terminal, drag the folder onto the window and press Return. Then run ./start.sh.
    • Linux: open a terminal in the folder and run ./start.sh, or sudo ./start.sh if you have not set up Docker for your user.
  4. The first start downloads the container image (about 500 MB), which takes a few minutes. Later starts take a few seconds and work offline. If Docker Desktop asks for permission to access the folder, allow it.
  5. A browser tab opens on JupyterLab. If it does not, open http://localhost:8888.
  6. In the file list on the left, open notebooks, then 01_solver.ipynb. Choose Run → Run All Cells. The notebook should finish in under a minute and show plots of a dam break and a small basin, with no red error messages.
  7. To stop, close the browser tab and press Ctrl+C twice in the terminal window. On Windows, answer Y if asked “Terminate batch job?”. Anything you save stays in the folder.

The image works on Intel and AMD computers and on Apple-silicon Macs. The server is reachable only from your own computer, so it has no password.

1.4.1 What is in the folder

Notebook Chapter What you do Time
01_solver.ipynb 1 Run the shallow-water solver on a dam break, a lake at rest and a small basin 5 min
02_pinn.ipynb 2 Train a physics-informed neural network on a travelling wave 5 min
03_neural_operators.ipynb 3, 4 Compare the trained FNO and PINO with the solver on scenarios they never saw 5–8 min
04_emulator.ipynb 5 Answer a what-if question with 200 runs at once, then train your own small FNO 5–10 min

The folder also holds the seminar’s dataset (80 scenarios) and the two trained models the notes report, so nothing has to be generated or trained before you start. During the seminar’s hands-on part we work through notebooks 3 and 4; notebooks 1 and 2 are a good warm-up beforehand.

1.4.2 If something goes wrong

  • “Docker is not running”: start Docker Desktop and wait until it reports that the engine is running.
  • “port is already allocated”: another program uses port 8888. On macOS and Linux run PORT=8890 ./start.sh; on Windows, in PowerShell in the folder, run $env:PORT=8890; .\start.bat. Then open http://localhost:8890.
  • macOS, “permission denied” for start.sh: run bash start.sh instead.
  • Linux, “permission denied” from Docker: run sudo ./start.sh.
  • A notebook stops with an error or hangs: choose Kernel → Restart Kernel and Run All Cells.
  • The download of the image fails part-way: run the start script again; it carries on from where it stopped.

1.5 Pre-seminar readiness checklist

Before the seminar, make sure you can tick off every item:

If any step fails, note the exact command and the complete error message and bring them to the seminar. Please do not wait until the seminar begins to install Docker or download the folder: the container image alone is about 500 MB, too much for a shared network on the day.

1.6 Official installation references