1. Getting set up

1.1. Start your virtual machine

On your Huawei cloud account:

  • Add a new security group aiida-tutorial, open ports 22, 5000, 8888

  • Start a new server:
    • Flavor s6.large.2 (2 vCPUs, 4 GB RAM) should be sufficient

    • Use shared image aiida-tutorial

    • Use security group aiida-tutorial

    • Use name workhorse (important)

    • No need to set a password

  • Copy the IP address of your new server

Please ask your tutors for the password for the max user, and read the instructions below on how to connect using your operating system.

1.1.1. Linux and MacOS

It’s recommended for you to place the ssh key you received in a folder dedicated to your ssh configuration, to do so:

  • If not already present, create a .ssh directory in your home (mkdir ~/.ssh), and set its permissions: chmod 700 ~/.ssh

Add the following block your ~/.ssh/config file:

Host aiidatutorial
    Hostname IP_ADDRESS
    User max
    ForwardX11 yes
    ForwardX11Trusted yes
    LocalForward 8888 localhost:8888
    LocalForward 5000 localhost:5000
    ServerAliveInterval 120

replacing the IP address (IP_ADDRESS) and the NUM by the one you received.

Afterwards you can connect to the server using this simple command:

ssh aiidatutorial


Here’s a copy-paste ready command for you to use directly with zero configuration:

ssh \
      -L 8888:localhost:8888 \
      -L 5000:localhost:5000 \
      -o ServerAliveInterval=120 \
      -X -C \


On MacOS you need to install XQuartz in order to use X-forwarding.

1.1.2. Windows

If you’re running Windows 10, you may want to consider installing the Windows Subsystem for Linux (and then follow the instructions above). Alternatively:

  • Install the PuTTY SSH client.

  • Run PuTTY

    • Put the given IP address as hostname, type aiidatutorial in “Saved Sessions” and click “Save”.

    • Go to Connection > Data and put max as autologin username.

    • Go to Connection > SSH > Tunnels, type 8888 in the “Source Port” box, type localhost:8888 in “Destination” and click “Add”.

    • Repeat the previous step for port 5000 instead of 8888.

    • Go back to the “Session” screen, select “aiidatutorial” and click “Save”

    • Finally, click “Open” (and click “Yes” on the putty security alert to add the VM to your known hosts). You should be redirected to a bash terminal on the virtual machine.


Next time you open PuTTY, select aiidatutorial and click “Load” before clicking “Open”.

In order to enable X-forwarding:

1.2. Start jupyter

Once connected to your virtual machine, type in the remote terminal

workon aiida

This will enable the virtual environment in which AiiDA is installed, allowing you to use AiiDA. Now type in the same shell:

jupyter notebook --no-browser

This will run a server with a web application called jupyter, which is used to create interactive python notebooks. In order to connect to the jupyter notebook server:

  • copy the URL that has been printed to the terminal (similar to http://localhost:8888/?token=2a3ba37cd1...)

  • open a web browser on your laptop and paste the URL

  • You will see a list of folders on your personal VM.

While keeping the first ssh connection running, open another ssh connection in a second terminal and type workon aiida here too. This terminal is the one we will actually use in this tutorial.


Our SSH configuration assumes that jupyter will serve the notebooks on port 8888. If you want to serve notebooks on different ports, you’ll also need to adjust the SSH configuration.

1.3. Downloading files

Throughout this tutorial, you will encounter links to download python scripts, jupyter notebooks and more. These files should be downloaded to the environment/working directory you use to run the tutorial. In particular, when running the tutorial on a linux virtual machine, copy the link address and download the files to the machine using the wget utility on the terminal:

wget <LINK>

where you replace <LINK> with the actual HTTPS link that you copied from the tutorial text in your browser. This will download that file in your current directory.

1.4. Troubleshooting

  • If you get errors ImportError: No module named aiida or No command ’verdi’ found, double check that you have loaded the virtual environment with workon aiida before launching python, ipython or the jupyter notebook server.

  • If your browser cannot connect to the jupyter notebook server, check that you have correctly configured SSH tunneling/forwarding as described above. Keep in mind that you need to start the jupyter server from the terminal connected to the VM, while the web browser should be opened locally on your laptop.

  • See the jupyter notebook documentation for compatibility of jupyter with various web browsers.

1.5. Getting help

There are a number of helpful resources available to you for getting more information about AiiDA. Please consider: