Tutorials#
This page show how to work with AiiDA and run a simple ABACUS calculation using the computer, code, and pseudo potential family we configured.
Quick start#
No time to install?
Click the Binder badge 
to launch a zero-install JupyterLab.
In two minutes you’ll have AiiDA + ABACUS fully set-up—complete with ready-to-run notebooks that let you submit calculations, track provenance, and visualize results right in your browser.
You can also run binder-example.ipynb in the examples directory locally for a glimpse into aiida-abacus.
Run locally#
To start locally, we’ll set up both AiiDA environment and ABACUS.
We provide an easy installation and configuration guide for a local ABACUS LTSv3.10.0 tested on Ubuntu 22.04 LTS calculation with Pseudo-Dojo v0.4 here. You can follow the guide or skip if some steps are already done. Adapt the configuration to suit your tastes.
First you should choose one package manager like conda, uv, and then install packages with it.
Prerequisites#
1. Package manager installation#
It is recommended to use a virtual environment, like conda and uv. To install if you have not already had one, run the following command(see conda install and uv installation):
Install Miniconda:
$ mkdir -p ~/miniconda3
$ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
$ bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
$ rm ~/miniconda3/miniconda.sh
After installing, close and reopen your terminal application or refresh it by running the following command:
$ source ~/miniconda3/bin/activate
Finally initialize conda on all available shells:
$ conda init --all
Install uv with one single line:
$ curl -LsSf https://astral.sh/uv/install.sh | sh
If installing from PyPI:
$ pipx install uv
And pip can also be used:
$ pip install uv
Next we will setup AiiDA & ABACUS.
If you’re new to both AiiDA and ABACUS, follow this complete setup:
If you already have ABACUS compiled, skip to AiiDA setup.
If you already have an AiiDA environment, skip to ABACUS compilation.
Tip
Quick one-command install
If you simply want everything ready on Ubuntu/WSL, run once:
$ git clone https://github.com/MCresearch/aiida-abacus.git
$ cd aiida-abacus
$ sudo apt update
$ xargs -a .binder/apt.txt sudo apt install -y # system deps
$ conda create -n aiida python=3.10 -y && conda activate aiida
$ bash .binder/postBuild # 5-stage automatic setup
$ git clone https://github.com/MCresearch/aiida-abacus.git
$ cd aiida-abacus
$ sudo apt update
$ xargs -a .binder/apt.txt sudo apt install -y # system deps
$ uv sync --extra tutorial
$ source .venv/bin/activate
$ bash .binder/postBuild # 5-stage automatic setup
The script performs the following stages — each can be executed manually if you prefer full control.
2. AiiDA environment setup#
Now let’s install Python packages needed.
$ conda create -n aiida python=3.10 -y
$ conda activate aiida
$ cd aiida-abacus
$ pip install -e .
$ pip install pymatgen ase-weas-widget aiida-vasp sumo
Packages will be installed into the named env
~/miniconda3/envs/aiida/.
$ cd aiida-abacus
$ uv sync --extra tutorial # --extra for project.optional-dependencies
$ source .venv/bin/activate
Packages will be installed into the local
.venv/directory, isolated per project. If you want to use the venv, change directory to aiida-abacus first.
Run this to install aiida-abacus itself in editable mode with dependencies and get some useful packages ready.
3. ABACUS compilation#
We have tested the installation on
✅ Ubuntu 22.04 LTS
Note on ABACUS dependencies: For earlier linux distributions, you may need to build ELPA from source. See ABACUS installation guide.
Install build dependencies for ABACUS (on Ubuntu here):
$ sudo apt update
$ xargs -a .binder/apt.txt sudo apt install -y # system deps
Build ABACUS (Long-Term Support Version 3.10.0) from source and install in current working directory(i.e. aiida-abacus dir):
$ git clone https://github.com/deepmodeling/abacus-develop.git
$ cd abacus-develop && \
git checkout LTSv3.10.0 && \
cmake -B build -DCMAKE_INSTALL_PREFIX=`pwd` -DENABLE_DEEPKS=OFF -DENABLE_LIBXC=ON -DENABLE_LIBRI=ON -DENABLE_RAPIDJSON=ON && \
cmake --build build -j`nproc` && \
cmake --install build && \
rm -rf build
This compiles ABACUS with LibXC and LibRI support and places the binary at abacus-develop/bin/abacus.
Note
You can use your own local ABACUS executable as long as it has the same output format as LTS version.
Verify ABACUS compilation:
$ ./bin/abacus -v
Should output: ABACUS version v3.10.0
4. Configuration#
Finally we’ll configure the computer and code used for AiiDA calculation.
$ verdi presto
$ verdi code create core.code.installed -n \
-Y localhost -L abacus \
-D "ABACUS LTSv3.10.0" -P abacus.abacus \
-X $(pwd)/abacus-develop/bin/abacus
$ aiida-pseudo install pseudo-dojo -f upf
$ verdi -p presto computer configure core.local localhost \
-n --no-use-login-shell --safe-interval 1
verdi prestocreates a lightweight AiiDA profile.verdi code createadds the freshly built executable to AiiDA asabacus@localhost.aiida-pseudodownloads the Pseudo-Dojo v0.4 PBE SR standard UPF family.The last command non-interactively configures the localhost computer with a 1-second polling interval and disables login-shell execution, preventing any spurious output from
.bashrcor.zshrc.
After these steps, we’re ready to submit our first calculation.
Run a calculation#
Follow the instructions above to install AiiDA and configure ABACUS code on the computer.
Activate the AiiDA virtual environment, so every subsequent call to
verdi, or any plugin uses the correct interpreter and dependencies.
$ conda activate aiida
$ source .venv/bin/deactivate
Start the daemon.
$ verdi daemon start
Check that the
daemonis running:$ verdi daemon status Daemon is running as PID xxxxxxx since yyyy-MM-dd HH:mm:ss Active workers [1]: PID MEM % CPU % started ------- ------- ------- ------------------- xxxxxxx 0.159 0 yyyy-MM-dd HH:mm:ss Use `verdi daemon [incr | decr] [num]` to increase / decrease the number of workers
Check the code and pseudopotential families used in the calculation.
Note
Check installed code by
$ abacus -v ABACUS version v3.10.0 $ verdi code list Full label Pk Entry point ----------------------- ------ ------------------- abacus@localhost 2 core.code.installed $ verdi code test abacus@localhost Success: all tests succeeded.
Check installed pseudos by
$ verdi group list -a PK Label Type string User ---- ----------------------------------------------------------------------------------- ------------------------- --------------- 1 PseudoDojo/0.4/PBE/SR/standard/upf pseudo.family.pseudo_dojo aiida@localhost
Tip
Using ABACUS-specific orbitals: For calculations requiring numerical atomic orbitals beyond standard pseudopotentials, use the
aiida-abacus pseudoscommands. See How to manage pseudopotentials and orbitals for details.
Now let us run an example script. It will submit the ABACUS calculation.
$ verdi run examples/example_pw_Si2.py
Inspect the calculation progress:
$ verdi process list -a PK Created Process label ♻ Process State Process status ------ --------- ----------------- --- --------------- ---------------- 233 5m ago AbacusCalculation ⏹ Finished [0]
Now let’s check the report for this process: (Replace 233 with the PK shown in the previous step and run)
$ verdi process report 233
It will present a log report of the process. To investigate more about the calculation, like raw inputs/outputs, see the How To Check the results page for details.
Note
AiiDA supports many different schedulers apart from Direct Execution. If you are using a Batch Job Scheduler like SLURM to manage the job queues and execution on a compute resource, see supported Batch Job Schedulers.