1. Getting set up¶
1.1. Choice of web browser¶
During the use of AiIDA infrastructure, we sometimes or often use web browser. The recommended browser is Chrome or Firefox. Safari on macOS is not recommended.
1.2. Connect to your virtual machine¶
The steps below explain how to connect to your personal Quantum Mobile virtual machine (VM) on Virtualbox using the Secure Shell protocol. The software on this VM already includes a pre-configured AiiDA installation as well as some test data for the tutorial. It’s recommended for you to place the ssh key you will create 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
Generate private and pubilc ssh key pair by
ssh-keygen -f aiida_tutorial.
Copy the public key to VM by
ssh-copy-id -i ~/.ssh/aiida_tutorial.pub email@example.com -p 2222and type the default password
1.2.1. Linux and MacOS¶
After the ssh key files are in place, add the following block to your
Host aiidatutorial Hostname 127.0.0.1 Port 2222 User max IdentityFile ~/.ssh/aiida_tutorial ForwardX11 yes ForwardX11Trusted yes LocalForward 8888 localhost:8888 LocalForward 5000 localhost:5000 ServerAliveInterval 120
Afterwards you can connect to VM using this simple command:
Here’s a copy-paste ready command for you to use directly with zero configuration:
ssh \ -i ~/.ssh/aiida_tutorial \ -L 8888:localhost:8888 \ -L 5000:localhost:5000 \ -o ServerAliveInterval=120 \ -X -C \ firstname.lastname@example.org -p 2222
On MacOS you need to install XQuartz in order to use X-forwarding.
1.2.2. Windows 10¶
If you’re running Windows 10, it is recommended to consider
installing the Windows Subsystem for Linux (WSL) (and
then follow the instructions above for linux). VcXsrv is also installed with
WSL in order to use X-forwarding. Some WSL setup (networking and
X-forwarding) is written here.
Short summary of the configuration is as follows. After the ssh key
files are in place, add the following block to your
Host aiidatutorial Hostname 127.0.0.1 Port 2222 User max IdentityFile ~/.ssh/aiida_tutorial ForwardX11 yes ForwardX11Trusted yes LocalForward 8888 localhost:8888 LocalForward 5000 localhost:5000 RemoteForward 6010 localhost:6000 ServerAliveInterval 120
RemoteForward is for X-forwarding with VcXsrv. In this
configuration, in WSL
$ echo 'export DISPLAY=:0.0' >> ~/.bashrc
and in Quantum Mobile VM
$ echo 'export DISPLAY=:10.0' >> ~/.bashrc
1.3. 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
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
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 a second
ssh connection in a separate terminal and execute
there as well. We will use the second terminal to directly interact
with the virtual machine on the command line, while we use the first
one to only serve the jupyter notebook.
You can safely ignore all warnings related to port forwarding when opening a second ssh connection. Those are caused by the fact that the ports are now already in use which in this context is perfectly fine.
1.4. 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 VM, copy the link
address and download the files to the machine using
wget in the
where you replace
<URL> with the actual HTTPS URL copied from the
tutorial text in your browser. This will download the file to the
If you encounter errors such as
ImportError: No module named aiidaor
No command ’verdi’ found, double check that you have loaded the virtual environment with
workon aiidabefore launching
jupyternotebook server. Your command line prompt should start with
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.