Running it on your laptop

Published

26/06/2026

During the workshop you use the cloud JupyterHub — your instructors give you the link and your login. This page is for running the same environment on your own computer: as a backup during the workshop, or (mainly) afterwards, to keep working on your projects once the cloud servers are switched off.

The environment is packaged as a single Docker image. It contains the same Julia 1.12 + PINN stack, the same Python (PyTorch / JAX) stack, and the course materials that are used on the cloud hub. The image is built from the public repository AccumulationPoint/pinns-course-core — where you can read exactly how it’s assembled (the Dockerfile, the package list, and the build) — and published to the GitHub Container Registry.

Prefer not to use Docker? There’s a native-install path at the bottom of this page.

Prerequisites

  • Docker Desktop (Windows / macOS) or Docker Engine (Linux).
  • The image is built for x86-64 (Intel/AMD) CPUs. On an Apple-Silicon Mac (M1/M2/M3/M4), Docker Desktop runs it through its built-in emulation layer — no extra setup on your part, but training runs are noticeably slower than on a native x86-64 machine.
  • ~10 GB of free disk (the image unpacks to about 9 GB, plus some working space).

Getting Docker running

You need Docker installed and its engine running. Pick your platform:

Windows. Install Docker Desktop and enable the WSL 2 backend when prompted (if it complains, run wsl --install in an administrator PowerShell and reboot). Launch Docker Desktop and wait until the whale icon says “Engine running.” Run the commands in PowerShell; docker version should show both a Client and a Server section. If you get error during connect … the target machine actively refused it, the engine isn’t up (start Docker Desktop) or a stray DOCKER_HOST is set — clear it with Remove-Item Env:DOCKER_HOST and retry.

Inside WSL (Ubuntu on Windows). Easiest: keep Docker Desktop on Windows and turn on Settings → Resources → WSL Integration for your distro — then docker works in the WSL shell. (Or install Docker Engine inside the distro, as for Linux.)

macOS. Install Docker Desktop, launch it, wait for “Engine running.” You can skip the Docker Hub sign-in — it isn’t needed. On Apple Silicon the image runs under emulation automatically (a one-line --platform warning is harmless).

Linux. Install Docker Engine; the service is usually already running (sudo systemctl start docker if not). Either use sudo, or add yourself to the docker group once (sudo usermod -aG docker $USER, then log out and back in).

Everyone. The first run prints Unable to find image … locally and then downloads it — that’s normal, not an error. No login is needed (the image is public). Stop a running container with Ctrl-C.

Run it

On macOS and Windows, start Docker Desktop first and wait until it reports that the engine is running (the whale icon in the menu bar / system tray stops animating) — the docker command only works once it is up. On Linux the Docker Engine service is normally already running.

Then, in a terminal:

docker run --rm -p 8888:8888 ghcr.io/accumulationpoint/pinns-course-core

The first run downloads the image (a few GB — once only). When it starts it prints a http://127.0.0.1:8888/lab link; open that in your browser. You get JupyterLab with Julia 1.12 and Python 3 kernels, ready to go — using NeuralPDE and import torch work immediately, with no installation.

Inside you’ll find:

  • ~/course-materials — a snapshot of the course site (the same notebooks and code).
  • ~/welcome_julia.ipynb, ~/welcome_python.ipynb — the same short intros as on the hub.

Keeping your work

The --rm flag means the container is disposable: when you stop it, anything saved inside it is discarded. To keep your work, mount a folder from your computer:

docker run --rm -p 8888:8888 -v "$PWD/work:/home/jovyan/work" \
  ghcr.io/accumulationpoint/pinns-course-core

Now anything you save under ~/work in JupyterLab is written to a work/ folder next to where you ran the command, and stays there after the container stops.

What about the GPU?

This laptop image is CPU-only (the PyTorch / JAX / Julia stacks are CPU builds). That is fine for every exercise in the course — just slower on the larger training runs. GPU acceleration is what the cloud GPU hub is for during the workshop; any notebook cell marked as GPU code is meant to be run there, on a machine with an NVIDIA GPU.

Updating the image

The image is published on the GitHub Container Registry as ghcr.io/accumulationpoint/pinns-course-core. When the course software stack is updated, a new version is published under the same name (:latest).

Important: if you already downloaded the image earlier (say at the install party), Docker will keep using that cached older copy — docker run does not check for a newer one automatically. To move to the latest build you have to ask for it explicitly. Either pull before running:

docker pull ghcr.io/accumulationpoint/pinns-course-core

or, equivalently, delete your local copy and let the next run re-download it:

docker rmi ghcr.io/accumulationpoint/pinns-course-core   # remove the cached image
docker run --rm -p 8888:8888 ghcr.io/accumulationpoint/pinns-course-core

(The very first docker run already downloads the image, so you only need this later, to refresh an image you downloaded earlier. If a refresh seems to do nothing, the tag may be momentarily unchanged — there’s no harm in re-running it.)

Without Docker — a native Julia install

If you’d rather not use Docker, you can install the course stack natively. This is slower to set up — it downloads and precompiles the whole stack from scratch (expect 15–30 min the first time, whereas Docker ships it precompiled) — and it’s a CPU setup, but it needs no Docker and plugs into your own editor / VS Code.

1. Install Julia with Juliaup (the Julia version manager — it lets you add and switch Julia versions later):

  • macOS / Linux: curl -fsSL https://install.julialang.org | sh
  • Windows: winget install julia -s msstore (or the installer from julialang.org/install).

Then match the course’s Julia version:

juliaup add 1.12
juliaup default 1.12

(Handy later: juliaup update, juliaup status, and juliaup default <version> to switch the version your julia command points at.)

2. Get the course materials and environment. The course repo’s Project.toml pins the same packages (NeuralPDE, Lux, ModelingToolkit, …):

git clone https://github.com/open-AIMS/Julia_PINN_training_2026
cd Julia_PINN_training_2026

3. Build the environment (the slow, one-time download + precompile) and add the Jupyter kernel:

julia --project=. -e 'using Pkg; Pkg.instantiate(); Pkg.add("IJulia")'

4. Run it. Either work in the REPL / VS Code (with the Julia extension) via julia --project=., or launch JupyterLab straight from Julia (IJulia installs a minimal Jupyter for you if you don’t have one):

julia --project=. -e 'using IJulia; jupyterlab(dir=pwd())'

Python side (optional) — for the Python notebooks, install the Python packages into a virtual environment:

pip install numpy scipy pandas scikit-learn matplotlib jupyterlab jax torch

For most people Docker is the easier path — one command, everything precompiled. The native install is for those who want a local Julia toolchain or to fold the course into their own setup.