1. Getting set up (if you are using a cloud machine)¶
Note: if you are working within a local VirtualBox machine (like the Quantum Mobile), you can skip this page and you can simply work within the VM.
The credentials of the custom VM that you can download
from the main page of this tutorial material
are the following: username:
1.1. Connect to your virtual machine¶
You should each have received from the instructors:
an IP address
a private SSH key
a public SSH key
The steps below explain how to use these in order to connect to your personal virtual machine (VM) on Amazon Elastic Cloud 2 using the Secure Shell protocol. The software on this VM is based on Quantum Mobile and already includes a pre-configured AiiDA installation as well as some test data for the tutorial.
If you decide to work in pairs, one of you should forward their credentials to the other and you should both use the same IP address and ssh key. Since you will be sharing the VM and user account, be careful not to delete the work of your colleague.
Please make sure you are not running any jupyter notebook on your computer. In this case, please kill all running kernels first. Otherwise, the port tunneling that we are setting up will not work.
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
.sshdirectory in your home (
mkdir ~/.ssh), and set its permissions:
chmod 700 ~/.ssh
Add the following block your
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
the one you received.
Afterwards you can connect to the server using this simple command:
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 \ max@IP_ADDRESS
On MacOS you need to install XQuartz in order to use X-forwarding.
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.
Put the given IP address as hostname, type
aiidatutorialin “Saved Sessions” and click “Save”.
Go to Connection > Data and put
maxas autologin username.
Go to Connection > SSH > Tunnels, type
8888in the “Source Port” box, type
localhost:8888in “Destination” and click “Add”.
Repeat the previous step for port
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
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
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
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
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. Additional useful notes¶
Read through the next sections if you are interested in knowing how to download files into the virtual machine, how to troubleshoot typical problems, or how to get additional help.
1.3.1. 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:
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.
If you get errors
ImportError: No module named aiidaor
No command ’verdi’ found, double check that you have loaded the virtual environment with
workon aiidabefore launching
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.