Running Notebooks

leap-c ships interactive marimo notebooks (see the notebooks/ folder) that demonstrate how to formulate and solve optimal control problems with the differentiable acados layer.

notebooks/getting_started/ is a sequential course on two small systems (a mass-spring-damper and an R1C1 house-heating problem):

  • 01_intro_diff_mpc.py: differentiable MPC end-to-end in five minutes.

  • 02_from_acados_to_diff_mpc.py: converting an existing plain AcadosOcp into a differentiable one.

  • 03_gradients_through_the_solver.py: V vs. Q, the three autograd routes, and where gradients die.

  • 04_parameter_management.py: differentiable vs. non-differentiable parameters, stage splits, override shapes, guard rails.

  • 05_batched_solves_and_forecasts.py: the batch dimension; weather/price forecasts through both parameter interfaces.

  • 06_planner_interface.py: an observation-to-action planner with a time-varying slacked comfort band, closed-loop against a mismatched house.

  • 07_imitation_learning.py: behavior cloning through the solver.

  • 08_rl_on_closed_loop_cost.py: tuning the planner by backpropagating through closed-loop rollouts.

See notebooks/README.md for the full API coverage map and reading order.

You can run these notebooks either locally (recommended for development) or via a pre-built Docker image (a convenient fallback if you do not want to build acados yourself).

Local setup

First complete the native installation, then install the notebook and torch extras. Recommended (uv):

uv pip install -e ".[notebooks,torch]"

Alternatively (pip):

pip install -e ".[notebooks,torch]"

Launch the marimo server from the repository root:

marimo edit notebooks

Open the printed URL (default http://localhost:8080) in your browser.

Docker fallback

If you do not want to build acados locally, you can use the pre-built notebook image published to GitHub Container Registry. No build step is required:

docker run -it --rm -p 7860:7860 ghcr.io/leap-c/leap-c:notebook

Open http://localhost:7860 in your browser. The image is multi-arch (linux/amd64 + linux/arm64), so it works on Apple Silicon Macs as well as x86_64 machines.

Persisting notebook changes

By default, notebook edits are saved inside the container and lost when it stops. To persist changes to the host, mount the notebooks/ directory:

docker run -it --rm -p 7860:7860 \
  -v "$(pwd)/notebooks:/home/leap/leap-c/notebooks" \
  ghcr.io/leap-c/leap-c:notebook

Edits made in the browser are then saved directly to your local notebooks/ folder.

CPU shell image

If you only need a reproducible shell environment (for example to run tests without installing acados), use the cpu image:

docker run -it --rm -v "$(pwd):/workspace" -w /workspace ghcr.io/leap-c/leap-c:cpu

Advanced Docker usage

For local image builds, GPU support, VS Code Dev Containers, HuggingFace Spaces, Dockerfile stage details, CI behavior, and troubleshooting, see the detailed Docker reference:

docker/README.md