Getting Started

• Back to the previous page: LabQSM#Getting Started

Machine setup

In order to go through this tutorial you need to have access to a Unix/Linux machine, where you can run Unix terminals. Software-wise, one needs the following:

• One quantum engine, i.e. a software able to run quantum mechanical DFT simulations. Here we consider Quantum ESPRESSO (QE). During this class we'll be using QE-v6.5, though any version newer that 6.0 would do.
• Structure visualization and builders: applications like XcrySDen or VESTA(QE compatible structure visualization) and Avogadro (molecular editor) will be used in the more advanced part of the class.

• General purpose scientific plotting tools. At least one of the following SW should be available: (XM)Grace, Gnuplot, or python with matplotlib support.

Several options are available:

• Opt1: Using the Quantum Mobile virtual machine (VM);
• Opt2: Connecting to existing machines, compliant with the class, as provided by the tutors
• Opt3: Installing your own machine

Opt1: Using Quantum Mobile

Quantum mobile is a ready-to-go VM, thought to provide all MaX flagship codes (incl QE) together with AiiDA seamlessly integrated in a plug-and-play linux (Ubuntu) environment. Quantum Mobile is available on the MaterialsCloud portal.

Step by step installation:

• Download the latest version of Quantum Mobile, following the link here: https://quantum-mobile.readthedocs.io/. By doing this you'll obtain a VM image.
• If not available, install VirtualBox to run the Quantum Mobile VM.
• Double click on the Quantum Mobile and follow the instruction to start the VM.
• At this point, after few minutes, you should see a virtualised Ubuntu OS. By opening a terminal you'll see that pw.x (and the other required executables) are available. Among others, all executables from the QE distribution, XcrySDen, Grace, gnuplot, and python are all pre-installed.
• The unix accounting within the VM is as follows:

   user: max    passwd: moritz

• The Ubuntu OS comes with US language by default including US keyboard. If you have an Italian keyboard you need to select it by clicking on Setting->Region & Language -> Input source. You need to search and select the Italian language. Once you have set the Italian language, move it as first of the list and you will be able to switch to the Italian keyboard clicking on the keyboard icon in the top right of your screen
• Further information about Quantum Mobile installation can be found here: https://github.com/marvel-nccr/quantum-mobile/releases/.

In order to use python to plot and fit data, it is also recommended to update python packages running the following:

• open a terminal
• become super-user typing

 $> sudo bash

• install python modules

 $>  pip3 install numpy
 $>  pip3 install matplotlib
 $>  pip3 install scipy

Similarly, the visualization SW Avogadro can be installed using sudo + app-get, as described in Plotting_and_visualization_tools#Avogadro.

Opt2: Connecting to existing machines

In order to follow this path, you need the following information:

• the complete name of a running Unix/Linux machine (<machine> in the following), something of the form pluto.fisica.unimo.it
• a unix username (<user>), available on the machine
• the username passwd

With these info, you can login to the remote machine via the ssh protocol by issuing the following command:

 ssh -Y <user>@<machine> 

More info about ssh available at Warming up with Unix commands#More commands.

Note that it would be very useful that the QE executables were placed in the executable path, such that you can e.g. find pw.x by typing:

 which pw.x

Make sure the required python modules (numpy, scipy, matplotlib) are installed, or asked the machine system admin.

More info about usage and policies of a HPC cluster available at Usage of a HPC cluster.

Opt3: Installing the needed software in your own machine

If you want to use your desktop or laptop, be sure you have the following software installed:

• Quantum ESPRESSO:

Download one of the latest tarsal archives (e.g. v6.5 or v6.6 from [1]), open it, and run the configure script. From command line you can issue:

 $>  wget  https://gitlab.com/QEF/q-e/-/archive/qe-6.5/q-e-qe-6.5.tar.gz
 $>  tar xvfz q-e-qe-6.5.tar.gz
 $>  cd q-e-qe-6.5
 $>  ./configure
 $>  make pw;  make pp

Most of the time the configure script is able to produce a (basic) working configuration even without specifying any flags. In case you want to refine the installation or have some troubles configuring, have a look at the configure manual

 $>  ./configure --help

• General purpose scientific plotting tools: python and gnuplot (and in most cases Grace as well) can be installed by using software managers such as apt-get or yum (RedHat/CentOS). For the case of gnuplot

 $>  sudo apt-get install gnuplot     (or)
 $>  sudo yum install gnuplot         (RedHat)
 $>  brew install gnuplot             (Mac Os with Homebrew installed)

• Structure visualization software (XcrySDen or VESTA): check out the download and installation pages of the SW webpage.

• Following the indications provided for QUantumMobile, install missing python modules if needed (having numpy, scipy, matplotlib can be useful).

Training material

In order to download the training material needed for these classes, clone the LabQSM repository from GitHub, by issuing the command:

 $>  git clone https://github.com/max-centre/LabQSM.git

No passed request is be prompted, and a folder called LabQSM is created locally. Inspect the contact of the folder by typing:

 $>  ls LabQSM/
        LAB_1     LICENSE   README.md docs      tools

On every new lecture, or when mentioned by the tutors, update the repository by typing:

 $>  cd LabQSM
 $>  git pull

You are now all set and ready to start the hands-on part.

Important notice: do not edit any of the files contained in the repository unless requested (otherwise you may not be able to update the repository using the git pull command, the presence of local changes conflicting with this git operation).