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
.ssh
directory 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 max@127.0.0.1 -p 2222
and type the default passwordmoritz
.
1.2.1. Linux and MacOS¶
After the ssh key files are in place, add the following block to your
~/.ssh/config
file:
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:
ssh aiidatutorial
Note
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 \
max@127.0.0.1 -p 2222
Note
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 ~/.ssh/config
file:
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
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 a second
ssh
connection in a separate terminal and execute workon aiida
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.
Note
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
terminal:
wget <URL>
where you replace <URL>
with the actual HTTPS URL copied from the
tutorial text in your browser. This will download the file to the
current directory.
1.5. Troubleshooting¶
If you encounter errors such as
ImportError: No module named aiida
orNo command ’verdi’ found
, double check that you have loaded the virtual environment withworkon aiida
before launchingpython
,ipython
or thejupyter
notebook server. Your command line prompt should start with(aiida)
, e.g.,(aiida) max@workhorse:~$
.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.