Installation

Quick Installation of Nanoworks to Linux Systems

For Debian/Ubuntu systems, run the automated installation script:

$ curl -fsSL https://raw.githubusercontent.com/sblisesivdin/nanoworks/refs/heads/main/install_scripts/install-all-Debian-based.sh | bash

Detailed Installation of Nanoworks to Linux Systems

Installation of system libraries to Debian-based distributions

You can also use the same commands on a pure Debian-based Linux system or Windows systems with WSL. If you do not know how to install Linux on Windows 11 with WSL, you can view this video. On the WSL system, you can use either Debian or Ubuntu. We recommend Ubuntu due to the support provided by Microsoft. First, install the required system files:

$ sudo apt update && sudo apt upgrade -y
$ sudo apt install -y python3-venv python3-pip unzip python-is-python3 \
                 python3-dev libopenblas-dev libxc-dev libscalapack-mpi-dev \
                 libfftw3-dev libkim-api-dev openkim-models libkim-api2 pkg-config \
                 task-spooler build-essential

Installation of system libraries to Fedora-based distributions

First, install the required system files:

$ sudo dnf update
$ sudo dnf install python3-devel openblas-devel libxc-devel scalapack-openmpi-devel fftw-devel pkgconf

You also must install kim-api, kim-api-devel, and openkim-models. At the time of writing these instructions, packages for Fedora 43 and 44 cannot be installed remotely. Therefore, we must download them, then install them with dnf locally. The order is important:

$ wget https://download.copr.fedorainfracloud.org/results/lecris/cmake-ninja/fedora-rawhide-x86_64/08840866-kim-api/kim-api-2.2.1-11.fc43.x86_64.rpm
$ wget https://download.copr.fedorainfracloud.org/results/lecris/cmake-ninja/fedora-rawhide-x86_64/08840866-kim-api/kim-api-devel-2.2.1-11.fc43.x86_64.rpm
$ wget https://download.copr.fedorainfracloud.org/results/lecris/cmake-ninja/fedora-rawhide-x86_64/08841484-openkim-models/openkim-models-2021.01.28-12.fc43.x86_64.rpm
$ sudo dnf install kim-api-2.2.1-11.fc43.x86_64.rpm
$ sudo dnf install kim-api-devel-2.2.1-11.fc43.x86_64.rpm
$ sudo dnf install openkim-models-2021.01.28-12.fc43.x86_64.rpm

Also on Fedora-bades systems, we may need to specify g++ as the C and C++ compiler in the system. After GPAW 26.7.0, the GPAW C-extension will now be built as C++ code.

(.venv_nw) $ export CC=g++
(.venv_nw) $ export CXX=g++

Creation of GPAW configuration file (Required for high-performance DFT calculations)

Although Nanoworks automatically installs all necessary Python libraries, GPAW need some configuration inputs for its compilation. For this, a configuration file must be created before installing Nanoworks. Therefore, creating a config file called siteconfig.py file is important. You can use any text editor. Here, we are creating a file with the cat command, writing necessary information inside it, then closing it with the Ctrl-D command (^D).

$ mkdir -p ~/.gpaw
$ cat > ~/.gpaw/siteconfig.py
fftw = True
scalapack = True
libraries = ['xc', 'blas', 'fftw3', 'scalapack-openmpi']
^D

If you have problems with libraries fftw, scalapack, you can remove them from the siteconfig.py file. They are simply optional. However, for better performance, you need these configuration.

Python Virtual Environment Installation

Then, if you do not have a Python environment, create one and activate it:

$ python -m venv ~/.venv_nw
$ source ~/.venv_nw/bin/activate

OPTIONAL: DFT-D3 Dispersion Correction

For the DFT-D3 dispersion correction, you need to install the dftd3 package on your system. Legacy dftd3 just works fine.

(.venv_nw) $ cd ~/.venv_nw/bin
(.venv_nw) $ mkdir build_d3
(.venv_nw) $ cd build_d3
(.venv_nw) $ wget https://www.chemie.uni-bonn.de/grimme/de/software/dft-d3/dftd3.tgz
(.venv_nw) $ tar -xzf dftd3.tgz
(.venv_nw) $ make
(.venv_nw) $ mv dftd3 ../
(.venv_nw) $ cd ..
(.venv_nw) $ rm -rf build_d3

OPTIONAL: Quantum ESPRESSO Backend

Nanoworks can also use Quantum ESPRESSO as an alternative DFT engine. Current native QE support covers PBE plane-wave ground-state calculations and non-spin DOS/PDOS workflows. QE DOS calculations currently use tetrahedron occupations.

Quantum ESPRESSO itself is not installed automatically by the Nanoworks Python package. A working Quantum ESPRESSO installation with pw.x, dos.x and projwfc.x available in PATH is required for the currently supported workflows.

Nanoworks can install the required PseudoDojo pseudopotential libraries for the QE backend:

(.venv_nw) $ nanoworks --install-qe-pseudos

This installs the standard PBE scalar-relativistic and fully-relativistic UPF pseudopotential sets under:

~/.nanoworks/pseudos/qe/pseudodojo/pbe/

The currently supported QE ground-state and DOS/PDOS workflows use the scalar-relativistic PBE pseudopotentials. Fully-relativistic pseudopotentials are installed for future spin-orbit-coupling support.

Quantum ESPRESSO 7.2 is the initially validated version.

Installation of Nanoworks and Python Modules

There are many Python packages needed to be installed. Nanoworks handles the dependencies automatically.

If you want to perform DFT calculations only, (which includes ASE and all necessary background libraries for dftsolve):

(.venv_nw) $ pip3 install nanoworks

To prevent potential past faulty installations from being retrieved from the cache, you can add –no-cache-dir to the end. If you also want to perform Molecular Dynamics (mdsolve) or Machine Learning calculations (mlsolve), you can install the optional dependencies. Note the use of quotes to prevent terminal parsing errors.

For Molecular Dynamics: Installs ASAP3 and KIM (kimpy).

(.venv_nw) $ pip3 install "nanoworks[md]"

For Machine Learning Potentials: Installs PyTorch, MACE (Multi-Atomic Cluster Expansion), CHGNet (Charge-Informed Graph Neural Network), and SevenNet (Scalable Equivariance Enabled Neural Network).

(.venv_nw) $ pip3 install "nanoworks[ml]"

To install everything (DFT base, MD, and ML):

(.venv_nw) $ pip3 install "nanoworks[all]"

Installation of Examples

Nanoworks software has an examples directory containing numerous examples in the DFT, MD and ML topics. You can copy this directory to the easily accessible ~/.nanoworks/examples location with the following command.

(.venv_nw) $ nanoworks --install-examples"

Each example contains README.md files. You can run the related example with a single command in each example.