[TOC]

## Step-by-step hands-on

### Sign up

Goal: go to http://aiidalab.psi.ch/ and sign up.

<details>
<summary>__Click me for details sign up instruction__</summary>

A new AiiDAlab user needs to first sign up and wait for an administrator to approve the account.
Visit http://aiidalab.psi.ch/hub/signup to sign up.

:::info
Be sure your password has at least 10 characters, doesn't have spaces or commas and is not too common.
:::

After signing up, you will get a message:

Your information has been sent to the admin

Please wait for the authorization from the admin. The admin will let you know when your account is ready.

After sign up please send us ([e-mail], [e-mail]) an email and we will approve it ASAP (before sunset :smile:) .
</details>

### Login and open QeApp

Goal: login and open QeApp.

<details>
<summary>__Click me for details login and open QeApp instruction__</summary>

Go to this link (from the PSI VPN or the PSI network): aiidalab.psi.ch

<img width=300 src=https://i.imgur.com/XJODOUH.png>

It will take a bit of time (~3 minutes) for the very first login, since the Quantum ESPRESSO app will be installed. You will see a progress bar as shown below. Please have a cup of coffee and be back later!

<img width=500 src=https://i.imgur.com/geRwWaN.png>

After login, you will find the Quantum ESPRESSO (QE) app on the page. Please click the QE logo to open the app.

<img wdith=300 src=https://i.imgur.com/SX7DBfz.png>

A new page opens, and you can start your new QeApp adventure with the guide at the top of the page.

<img widht=300 src=https://i.imgur.com/YRlqePb.png>

</details>

### Run calculation on the AiiDAlab machine

Goal: running a XPS calculation on ETFA molecule using the AiiDAlab machine. Get the XPS spectra of C 1s.

<details>
<summary>__Click me for details running instruction__</summary>

As shown at the top of the page, there will be four steps to carry out a QE calculation.

#### Step 1 Select a structure
You can select a structure from four sources.
- Upload file
- OPTIMADE
- AiiDA database
- From Examples

First download the `etfa` strucutre [here](https://raw.githubusercontent.com/superstar54/xps-data/main/structures/etfa.xyz), copy and save it as `etfa.xyz` file. Then, use the `Upload file` tab, and select the file.

In the end, click the `Confirm` button.

---
#### Step 2 Configure workflow
Set the input parameters

- There are three relax types:
- Structure as is
- Atomic positions
- Full geometry

- There are two properties that can be computed:
- Band structure
- Projected density of states

For this test calculation, please click all of them.

Please select `fast` as the protocol for this calculation, in order to quickly get the result, since you only have two CPUs both for running AiiDAlab and to run the QE calculation.
Note, of course, that this is only for demo purposes: for any production calculation, please set up a "real" remote computer (cluster, supercomputer) and use it!
You can check the next section on how to setup a remote computer, and the Quantum ESPRESSO codes to run a band structure calculation on it.

In the end, click the `Confirm` button.

---
#### Step 3 Choose computational resources.

##### Codes
We have set up a default computer (`localhost`) and the following codes:

- pw-7.2@localhost
- dos-7.2@localhost
- projwfc-7.2@localhost

For this calculation, you can use the default codes.

##### Resources
You can set the number of CPUs to 1 for the test.

Click the `Submit` button and the calcuation is launched.

:::info
*NOTE*:
There is no need to wait for the computation to finish: you can go head and submit a new calculation in parallel.
:::

---
#### Step 4 Check the status and results.
The job may take ~3 minutes. While waiting, you can also check the job information by clicking the Workchain item in the tree view.

In addition, above `Step 1`, there is a textbox showing the status of a workflow.


When the job is finished, refresh the if needed; then you can view the `Final Geometry` and the `Electronic Structure` in the `Step 4` section.


</details>

---
### Setup remote computer/code and run a calculation on it

This time, the goal is to submit a band structure calculation of magnetic cobalt on a remote machine (i.e., on a different computational resource). The instruction in collapsible text is for CSCS machine.

<details>
<summary>__Click me for detail operation instructions__</summary>

#### Step 1
Again use the "From examples" structure importer and select cobalt.

#### Step 2

Turn on the `Magnetism` option.

For protocol, please select "fast" (or select the "precise" protocol if you have enough resource to test).

#### Step 3 Choose computational resources
Now you need set up a new computer (e.g., the CSCS Daint or Eiger machine if you have acount on it) and the codes on this newly setup computer (i.e., you need to tell AiiDA where the executables are, which modules to load etc.).

:::info
The widget to assist you in the computer/code setup is not very convinient for CSCS machines, because CSCS requires to specify the account and setting up a default one is not currently straightforward in AiiDA; we are working to improve this.
If you use `merlin.psi.ch`, you can use the "Quick setup" of codes.
:::

#### Setup new code
- Click the button `Setup new code`.
- In the `Domain` field, please select `daint.cscs.ch`.
- Click `Detailed Setup`, then it will show three steps.
- password-less SSH
- computer in AiiDA
- code in AiiDA

##### Set up password-less SSH connection
- In the `SSH username`, input your username for CSCS.
- Click `Setup ssh`.
- On the textbox above `Detailed Setup`, input your password, and click `Continue`.
- Wait a few seconds, it will ask you to input your password again, and click `Continue`

If you see a message as below:

30s timeout ...

Please click the `Setup ssh` button again and input the password.

##### Setup a computer in AiiDA

Click the button `Setup computer`, then add one line in the `Prepend text` to specify your account (it is the project account, such as `mr32` or `mrcloud`) at CSCS. Replace the `<account_name>` string with it!

#SBATCH --account=<account_name>

You can find further parameters in the screenshot below.

<img width=400 src=https://i.imgur.com/7LufQM5.png>

Click the button `test computer`, then wait 1 minute: you will see this log message if everything was setup correctly:

Report: Testing computer<daint-mc> for user<aiida@localhost>...
* Opening connection... [OK]
* Checking for spurious output... [OK]
* Getting number of jobs from scheduler... [OK]: 2255 jobs found in the queue
* Determining remote user name... [OK]: xingwang
* Creating and deleting temporary file... [OK]
Success: all 5 tests succeeded

##### Set up a code

In the field `Select computer`, please select the computer you just setup, in this case `daint-mc`. Check all other options, and then click the button `Setup code` to setup the `pw.x` code.

<img width=400 src=https://i.imgur.com/0KsUc1m.png>

Similarly, setup the `dos.x` and `projwfc.x` codes, needed by the app to compute DOS and PDOS. You can skip the computer setup step, since it needs to be done only once per comouter, and go to `Set up a code in AiiDA` directly to setup the remaining codes.

After you finishing the codes setup, you can launch a new calculation with the newly setup codes, that should be called:

- pw-7.0@daint-mc
- dos-7.0@daint-mc
- projwfc-7.0@daint-mc

<img width=600 src=https://i.imgur.com/2PtpZXd.png>

In the end, click the `Submit` button.

#### Step 4 Check the status and results.


</details>

## Free solo

### Task 1

*Level: Basic*

Goal: play around with any operation that may/may not work, and try to run into some unexpected issue; then, report back to us. The App is in a beta-test stage, and we sure there are some bugs you can catch!

If you manage to crash the app, you'll see the following page: click `Create bug report` button and report the issue to us; this will help you already include some relevant information in the bug report (Note: you need a GitHub acount to report). Once the issue is reported, press the button `Restart app` to restart the app.

### Task 2

*Level: Intermediate*

Goal: select a compound from the OPTIMADE structure importer (e.g. some material you are currently working on for your research) or upload it from your machine, and compute its band structure.

## Feedback reminder

Feedback form: https://forms.gle/Wib9SwrVG4rtNcqi7