Skip to content

Prerequisites and Installation

During this part of the tutorial we will suppose that a compiled FHI-aims executable is available on the computer under the path $HOME/bin/aims.x.

There are several options for how the packages can be installed on the computer:

  • a system-wide installation (for a superuser on the local computer)
  • an installation in a Python virtual environment
  • an installation in a conda environment

We recommend using virtual environment, either vanilla Python on conda-based, as this will isolate the installed packages from the system and allows granular control over the names and specific versions of the packages installed. The full installation instructions for the packages can be found in their documentation. As atomate2 depends on pymatgen, you can follow only atomate2 instructions to get everything up and running. This will require several things:

  • installing Python packages;
  • providing a database (MongoDB) for calculation outputs;
  • configuring the database to work with atomate2.

We will give short instructions below.

Installation

Python venv

venv Python module provides a way to create and use lightweight virtual environments, which contain an isolated Python directory tree with a number of installed packages. You should understand, that no separate Python installation is made; the Python version available in the virtual environment is usually the most recent Python version that can be found on the machine. You can find the tutorial for venv module in Python documentation.

In order to use venv virtual environment you need to create and activate it. Creation can be done with the following shell command: 

user@host:~$ python -m venv atomate2-env

This will create the environment folder in $HOME/atomate2-env. To activate the folder, issue 

user@host:~$ source atomate2-env/bin/activate
(atomate2-env) user@host:~$

Notice how the shell invitation string changes to reflect that we now use the virtual environment. To deactivate the environment, issue deactivate command: 

(atomate2-env) user@host:~$ deactivate
user@host:~$

While in the environment, we can install and use Python packages. Installation of packages is usually done with pip - short for package installer for Python. Let's install atomate2 in the environment: 

(atomate2-env) user@host:~$ pip install atomate2
Collecting atomate2
...
Successfully installed Flask-3.0.2 Jinja2-3.1.3 MarkupSafe-2.1.5 PyYAML-6.0.1 Werkzeug-3.0.1 aioitertools-0.11.0 annotated-types-0.6.0 anyio-4.3.0 atomate2-0.0.14...

If you see the last line, then the installation is completed successfully.

conda (or mamba) environment

conda is a command-line tool from Anaconda Python distribution, aimed at easing the process of creating and managing Python virtual environments. In contrast to venv, each conda virtual environment can contain its own Python interpreter as well as binary libraries, making it more suitable for managing complex dependencies. conda is usually available as a module at various supercomputing facilities and is the preferred way of installing atomate2 on a computing cluster. To install atomate2 in a conda virtual environment, you can follow the instructions from atomate2 developers.

Information on conda

According to the Section 2 of its license conditions, using conda is free for personal use, but requires buying a commercial license if used by the institutions with over 200 employees. This also includes research institutions and their employees. Taking this into account, we now recommend using mamba, the command line tool that can be used to manage conda environments. mamba uses the same commands and configuration options as conda, and can be used as a drop-in replacement for the latter. Throughout this section of the Tutorial, conda and mamba commands are interchangeable.

Jupyter Notebooks

Jupyter Notebooks are versatile tools for interactive computing, widely used in data science, research, and education. They combine code execution, text, equations, visualizations, and more in a single document-like interface. If you want to use Jupyter Notebooks to run the tutorials, please install the notebook Python package by running 

(atomate2-env) user@host:~$ pip install notebook
or 
(atomate2-env) user@host:~$ conda install notebook
depending on the flavor of virtual environment used.

After the installation is complete, you can try running the notebook by issuing the following command: 

(atomate2-env) user@host:~$ jupyter notebook

A browser window should come up with the page showing the files in the current directory. If that's the case, then Jupyter Notebook Server is installed successfully. If you're unfamiliar with Jupyter Notebooks, consider going through Getting Started guide in the Jupyter docs.

Info

At this stage pymatgen as well as atomate2 are installed in the virtual environment of your choice. Now, you can go through the Pymatgen tutorial. If you are more interested in running atomate2 workflows, please continue installing and setting up the environment.

ASE

Apart from atomate2, ASE ase has also to be installed in the same environment. Issuing pip install ase should do. Follow the FHI-aims with ASE tutorial to get a grasp on what can be done with FHI-aims and ASE.

MongoDB database

MongoDB is a popular open-source, NoSQL database program that uses a document-oriented data model. Instead of storing data in tables and rows as in a traditional relational database, MongoDB stores data in JSON-like documents with dynamic schemas, known as BSON (Binary JSON). atomate2 documentation suggests 3 ways of getting a MongoDB instance to use:

  • Use a commercial service like MongoDB Atlas, which offers a 500MB free MongoDB instance;
  • Ask the supercomputing center support to see if they have MongoDB instance running on premises;
  • Use a self-hosted server.

atomate2 advises using option 1 or 2 if you are running calculations on supercomputer facilities; if this is the case, then follow the documentation therein. However, if you want to run the tutorial on a local machine, where you have superuser rights, then it makes sense to have a local installation of MongoDB as well. Its documentation outlines the ways to install it for a variety of OS flavors. Particularly, here you can find the instructions of installing and running free MongoDB Community Edition on Ubuntu Linux.

If you install your own instance of MongoDB, it can be insightful to also download and install MongoDB Compass, which is the GUI for MongoDB.