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
(atomate2-env) user@host:~$ conda install notebook
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.