Octopus Tutorials

Attention

This page contains tutorials in Jupyter Notebook format. Not all tutorials have been migrated to this format yet.

You can access all tutorials in the old format under https://octopus-code.org/documentation/main/tutorial/.

Here you will find a collection of tutorials covering a wide range of topics, from the basics of performing calculations with Octopus to more advanced features. Several series of linked tutorials are proposed to guide you on how to perform certain types of calculations. These tutorials do not by any means cover all the things that Octopus can do for you, but hopefully they cover the most common options. You can find more information in the online Manual.

If you have never used Octopus before, then you should start with the Octopus Basics series of tutorials.

Running tutorials

To run the tutorials you need Octopus and several Python dependencies. There are different options how to get both:

In the cloud

You can run the tutorials online using MPCDF Binder. Note that you only get limited resources and that sessions are not persistent and terminated after a certain period of inactivity. Download results that you want to keep to prevent data loss.

Without compiling octopus

You can run the tutorials in the official Octopus docker image, we recommend using podman on Linux (if you use docker, replace the commands shown in the following as needed):

  • clone the octopus repository to get the tutorials

  • in the repository root run:

    podman run -it -v=$(pwd):/io -p 8888:8888 registry.gitlab.com/octopus-code/octopus:main bash

  • inside the container run:

    run-jupyter-lab

  • on the host open the jupyter lab url http://127.0.0.1/... in a browser and navigate to doc/jupyter_tutorials/

With compiling octopus

Compile octopus as explained in https://octopus-code.org/documentation/main/manual/install/ and ensure octopus is in your PATH.

Clone the repository and use either uv (recommended) or pip + venv to install dependencies.

uv

For uv run in the repository root:

uv run --only-group tutorials jupyter lab
pip + venv

For pip + venv run the following steps in the repository root:

python3 -m venv .env
source .env/bin/activate
pip install --group tutorials
jupyter lab

Note: you need pip >= 25.1 (to have support for dependency groups). If your version is older you can upgrade pip in the virtual environment: after source .env/bin/activate run pip install --upgrade pip.

Warning

This command will also install octopus via pip. If you do not want to use this octopus executable make sure to add the path to the desired octopus executable to your PATH after activating the virtual environment.

Open the jupyter lab url in a browser and navigate to doc/jupyter_tutorials/.

Available tutorials

  • Octopus Basics — getting started with Octopus.

  • 2-optical-response/index — how to calculate several types of optical response with different methods.

  • 3-periodic-systems/index — periodic boundary conditions, band structures, etc.

  • 4-models/index — working with model systems, like quantum dots or quantum wells.

  • 5-high-performance-omputing — periodic boundary conditions, band structures, etc.

  • 6-maxwell-tddft/index — numerical electrodynamics.

  • 7-qedft/index —

  • 8-advanced-tutorials/index —