🚀Quick Start

If you’re eager to experience it firsthand, you can try this Notebook:

Installation of AutoMeKin

AutoMeKin offers four different installation and deployment methods:

1. Build with micromamba $\scriptstyle($recommended option$\scriptstyle)$
2. Build from source
3. Singularity container
4. Auto installer

1. Build with micromamba

This is the recommended option. The packages git and curl must be installed beforehand.

First, clone the repository:

git clone https://github.com/emartineznunez/AutoMeKin.git

Go to the AutoMeKin directory:

cd AutoMeKin

To build AutoMeKin and its dependencies (including amk_tools, qcore and molden) within a micromamba environment named amk_env, just type:

bash Build_micromamba.sh

Build_micromamba.sh should be executed only when installing a new version or when using the code for the first time.
After successfully creating the environment, you must activate it and load the AutoMeKin module. These four instructions will be displayed once the build process is complete. For your convenience, you can copy these sentences into a script or file.

Before using qcore for the first time, remember to agree to the Software License Agreement and to set your token by running:

entos --license

2. Build from source

The most recent version is available at GitHub and can be installed as indicated in this section.

You can build, system-wide and including dependencies, following the steps indicated in these scripts:

• CentOS-based script
• Ubuntu-based script

To install everything manually, follow the next steps.

Installing dependencies

The following packages are required beforehand:
GNU Autoconf, GNU Bash, GNU bc, environment-modules, GNU Awk, gawk, GNU C Compiler, gcc, GNU Fortran Compiler, gfortran, GNU Parallel, SQLite>= 3
The installation of molden is highly recommended to analyze the results.

Additionally,

The following Python3 libraries are needed:
ASE>= 3.21.1, Matplotlib>= 3.3.4, NetworkX>= 2.5, NumPy>= 1.19.5, SciPy>= 1.5.4, amk_tools

Installting other electronic structure packages

While mopac comes with the distribution, gaussian and/or Entos Qcore should be installed by the user.

Entos Qcore, which is free for academia, can be easily installed following these steps:

1. Install miniconda
2. Add the following line to $HOME/.condarc, creating the file if not present:

   auto_activate_base: false
   

   which avoids activation of base environment.

3. Install qcore version 0.8.14 in the conda environment qcore-0.8.14-env:

   conda create -n qcore-0.8.14-env -c entos -c conda-forge qcore==0.8.14 'tbb<2021'
   

4. Activate the newly created environment:

   conda activate qcore-0.8.14-env
   

5. After installation, each user will be asked to read the Software License Agreement to generate a unique token:

   qcore --academic-license
   

Installing AutoMeKin

Once the above packages are installed, you can now install AutoMeKin following these steps:

git clone https://github.com/emartineznunez/AutoMeKin.git

cd AutoMeKin

autoreconf -i

./configure --prefix=path_to_program

Where you can specify where you want to install it, e.g., /opt/AutoMeKin

make 

make install

For convenience, and once “Environment Modules” has been installed, you should add the following line to your .bashrc file:

module use path_to_program/modules

where path_to_program is the path where you installed amk (e.g., $HOME/amk-2021).

3. Singularity container

If singularity is already installed in your computer, you can obtain the container from sylabs. First check the latest image, Tag, by typing:

singularity search automekin

and replace <Tag> below by that number. Then, from your $HOME type:

singularity pull library://emartineznunez/default/automekin:<Tag>

You can start an instance of the container and run it using:

singularity instance start automekin_<Tag>.sif automekin

singularity run instance://automekin

which will allow you to run low-level scripts. You can stop the instance using:

singularity instance stop automekin

Note, however, that if you want to use G09/G16 you must bind it to the container. To help you do so, we created the scripts SingularitygXX.sh (replace XX with 09 or 16), which can be downloaded as:

curl -LJO https://github.com/emartineznunez/Singularity_amk/raw/main/SingularitygXX.sh

The script should be run with the complete path to the sif file as argument as in the example:

SingularitygXX.sh $HOME/automekin_<Tag>.sif

Note that SingularitygXX.sh will start a new instance of the container every time it is executed. To list the instances use:

singularity instance list

And stop them as indicated above.

4. Auto installer

An auto installer script is provided to install singularity and download the last release container image from sylabs as $HOME/automekin_<tag>.sif. Note that this is done only the first time you use it unless a new image is available. Then, the script will detect singularity and the image (that must be located in your $HOME) and will only start an instance of the container. The container includes amk_tools.

This option offers an outdated version of singularity, lacking proper image verifying capabilities. Consequently, an error is consistently triggered upon downloading a new image.

To start/stop the container follow these steps:

• Download script:

   curl -LJO https://github.com/emartineznunez/Singularity_amk/raw/main/installer/Automekin.sh
  

•  chmod +x Automekin.sh
  

•  ./Automekin.sh
  

Depending on your Linux configuration, before running the autoinstaller you might need to change some parameters which will require admin or root privilege. If that is the case and once you changed the parameters with your admin or root accounts, no further admin or root privilege will be needed. Return to your user account and run the auto installer again.

Once the above steps are completed, singularity will be installed under ${TMPDIR-/tmp}/amk_installer-${USER}/software in bash shell script syntax and an instance of the container will be started using a sandbox image deployed under /tmp/selfextract.XXXXXX folder (where XXXXXX is a randomly generated character sequence). The container comes with all AutoMeKin’s tools installed in $AMK, which can be run from the container. A bash shell session under $HOME will start under the deployed instance. Note that you can open new sessions and access AutoMeKin’s output files from your Linux environment and use your own tools as well.

• To exit the container just type: exit

• Once your calculations are done, remember to stop the instance:

  ./Automekin.sh stop
  

To download the file directly from your terminal, curl must be installed. The autoinstaller also works on Ubuntu 20.04 LTS on Windows.