Difference between revisions of "Installation instructions"

From AutoMeKin
Jump to navigation Jump to search
(Singularity's image)
(Build from source)
 
(226 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
==Electronic structure packages==
 +
The program employs two levels of electronic structure: semiempirical (or Low-Level LL) and ab initio/DFT (or High-Level HL). The LL calculations can be carried out with MOPAC or Entos Qcore, and the HL calculations with Gaussian (G09/G16) or Entos Qcore.
 +
 +
While MOPAC comes with AutoMeKin, if you want to employ xtb method, [https://www.entos.ai/qcore/documentation/ Entos Qcore] must be installed. Additionally, for the HL calculations you may want to use G09/G16, or Entos Qcore.
 +
 +
To install [https://software.entos.ai/qcore/tutorial/ Entos Qcore], we recommend following these steps:
 +
 +
1. [https://conda.io/projects/conda/en/latest/user-guide/install/linux.html Install miniconda3]
 +
 +
2. Add the following line to $HOME/.condarc (create the file if not present):
 +
 +
<code>auto_activate_base: false</code>
 +
 +
which avoids activation of base environment.
 +
 +
3. Install qcore version 0.8.14 in a conda environment (qcore-0.8.14-env):
 +
 +
<code>conda create -n qcore-0.8.14-env -c entos -c conda-forge qcore==0.8.14 'tbb<2021'</code>
 +
 +
4. Activate the newly created environment:
 +
 +
<code>conda activate qcore-0.8.14-env</code>
 +
 +
5. After installation, each user will be asked to read the Software License Agreement to generate a unique token:
 +
 +
<code>qcore --academic-license</code>
 +
 
==Auto installer==
 
==Auto installer==
This is the easiest way to use AutoMeKin. The auto installer script installs singularity in your computer and downloads the image from sylabs. Note that this is done only the first time you use it. Then, the script will detect singularity and the image (that must be located in your <code>$HOME</code>) and will only launch the container.
+
This is the easiest way to install/use AutoMeKin. The auto installer script installs singularity in your computer and downloads the last release container image from sylabs (https://cloud.sylabs.io/library/emartineznunez/default/automekin) as <code>$HOME/automekin_<tag>.sif</code>. 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 <code>$HOME</code>) and will only start an instance of the container. The container includes [https://github.com/dgarayr/amk_tools '''amk-tools''']
  
1) Download AutoMeKin's auto installer script [[Media:automekin.sh| automekin.sh ]]<br />
+
1) Download AutoMeKin's auto installer script Automekin.sh ('''Last update April 4, 2022''') from your terminal:
 +
 
 +
<code>curl -LJO https://github.com/emartineznunez/Singularity_amk/raw/main/installer/Automekin.sh</code>
  
 
2) Make the script executable:
 
2) Make the script executable:
  
<code>chmod +x automekin.sh</code>
+
<code>chmod +x Automekin.sh</code>
 +
 
 +
3) Run the script:
 +
 
 +
<code>./Automekin.sh</code>
 +
 
 +
Note that 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.
 +
 
 +
4) Once the above steps are completed, singularity will be installed under <code>${TMPDIR-/tmp}/amk_installer-${USER}/software</code> in bash shell script syntax and an instance of the container will be started using a sandbox image deployed under <code>/tmp/selfextract.XXXXXX</code> folder (where <code>XXXXXX</code> is a randomly generated character sequence). The container comes with all AutoMeKin's tools installed in <code>$AMK</code> plus vim, gnuplot and molden which can be run from the container. A bash shell session under <code>$HOME</code> 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.
 +
 
 +
5) To exit the container just type:
 +
 
 +
<code>exit</code>
 +
 
 +
6) Once your calculations are done, remember to stop the instance:
 +
 
 +
<code>./Automekin.sh stop</code>
 +
 
 +
'''Important notes:'''
 +
 
 +
<ol start="1">
 +
<li>'''To download the file directly from your terminal, curl must be installed'''</li>
 +
<li>'''Make sure your auto installer is up to date (see above)'''</li>
 +
<li>'''The autoinstaller also works on Ubuntu 20.04 LTS on Windows 10. To install Ubuntu 20.04 LTS on Windows 10, follow these instructions: https://docs.microsoft.com/en-us/windows/wsl/install-win10'''</li>
 +
<li>'''AutoMeKin's third-party packages in the container are updated (see below the minimum required version numbers). Local installations of different versions of these Python packages might interfere in the execution of AutoMeKin'''</li>
 +
</ol>
 +
 
 +
==Singularity container==
 +
 
 +
If singularity is already installed in your computer, you can obtain the container from sylabs. First check what the latest image (Tag) is by typing:
 +
 
 +
<code>singularity search automekin</code><br />
 +
 
 +
and replace <code><Tag></code> below by that number. Then, from your $HOME type:<br />
 +
 
 +
<code>singularity pull library://emartineznunez/default/automekin:<Tag></code><br />
 +
 
 +
You can start an instance of the container and run it using:
 +
 
 +
<code>singularity instance start automekin_<Tag>.sif automekin</code><br/>
 +
<code>singularity run instance://automekin</code>
 +
 
 +
which will allow you to run low-level scripts. You can stop the instance using:
 +
 
 +
<code>singularity instance stop automekin</code>
  
3) Run the auto installer script:
+
Note, however, that if you want to use <code>G09/G16</code> you must bind it to the container. To help you do so, we created the scripts SingularitygXX.sh (XX=09/16), which can be downloaded as:  
  
<code>./automekin.sh</code>
+
<code>curl -LJO https://github.com/emartineznunez/Singularity_amk/raw/main/Singularityg09.sh</code>
  
Note that 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 not be needed.
+
<code>curl -LJO https://github.com/emartineznunez/Singularity_amk/raw/main/Singularityg16.sh</code>
Return to your user account and run the auto installer again.
 
  
4) The auto installer will install singularity and run automekin2020_872.sif image. The container comes with all tools of AutoMeKin plus vim, gnuplot and molden which can be run from the container. AutoMeKin is installed in <code>$AMK</code>
+
The script should be run with the complete path to the sif file as argument as in the example:
  
==Singularity's image==
+
<code>SingularitygXX.sh $HOME/automekin_<Tag>.sif</code>
  
If singularity is already installed in your computer, you can obtain the image running (from your $HOME):<br />
+
Note that <code>SingularitygXX.sh</code> will start a new instance of the container every time it is executed. To list the instances use:
  
<code>singularity pull library://emartineznunez/default/automekin2020:872</code><br />
+
<code>singularity instance list</code>
  
The container is launched by just typing the name of the image you have just downloaded from sylabs:
+
And stop them as indicated above.
  
<code>automekin2020_872.sif</code>
+
==Build from source==
  
which will allow you to run low-level scripts.
+
The most recent and up to date version is avaialable at:
  
Note, however, that if you want to use <code>g09</code> you must bind it the container using this script:
+
<code>https://github.com/emartineznunez/AutoMeKin</code>
  
<nowiki>
+
You can build (system-wide) from source using this script (on a CentOS):
if G09DIR=$(dirname $(which g09 2> /dev/null) 2> /dev/null)
 
then
 
  if [ -d $GAUSS_SCRDIR ]
 
  then
 
      SINGULARITYENV_GAUSS_SCRDIR=/scratch SINGULARITYENV_PREPEND_PATH=/opt/g09 singularity run --bind $G09DIR:/opt/g09 --bind $GAUSS_SCRDIR:/scratch $HOME/automekin2020_872.sif
 
  else
 
      SINGULARITYENV_PREPEND_PATH=/opt/g09 singularity run --bind $G09DIR:/opt/g09 $HOME/automekin2020_872.sif
 
  fi
 
else
 
  echo "Gaussian 09 not available, only low-level calculations available"
 
  singularity run $HOME/automekin2020_872.sif
 
fi</nowiki>
 
  
==Tarball==
+
<code>curl -LJO https://raw.githubusercontent.com/emartineznunez/AutoMeKin/main/Build_Centos.sh</code>
  
Download the tarball from [[Media:amk-SOURCE-2020.tar.gz| here ]]<br />
+
You can also check how to install AutoMeKin using Ubuntu:
  
Untar and unzip the file:
+
<code>https://colab.research.google.com/github/emartineznunez/AutoMeKin/blob/main/AutoMeKin.ipynb</code>
  
<code>tar xvfz Amk-SOURCE-20XX.tar.gz</code>
+
which involves the installation of the following dependencies (before the installation of AutoMeKin):
  
  
Line 57: Line 117:
  
 
Before installing amk for the first time, be aware that the following packages are needed:
 
Before installing amk for the first time, be aware that the following packages are needed:
 +
 +
- [https://www.gnu.org/software/autoconf/ GNU Autoconf]
  
 
- [https://www.gnu.org/software/bash/ GNU Bash]
 
- [https://www.gnu.org/software/bash/ GNU Bash]
Line 78: Line 140:
 
- [https://wiki.gnome.org/Projects/Zenity Zenity]
 
- [https://wiki.gnome.org/Projects/Zenity Zenity]
  
You can install the missing ones manually, or you can use the scripts located in amk-SOURCE-20XX and called ''install-required-packages-distro.sh'' (where distro=ubuntu-16.4lts, centos7 or sl7), which will do the work for you.The ubuntu-16.4lts script installs all dependencies, but for the RHEL derivatives (centos7 and sl7) you have to install parallel separately, and you have two choices:
+
You can install the missing ones manually, or you can use the scripts located in amk-SOURCE-2021 and called ''install-required-packages-distro.sh'' (where distro=ubuntu-16.4lts, centos7 or sl7), which will do the work for you.The ubuntu-16.4lts script installs all dependencies, but for the RHEL derivatives (centos7 and sl7) you have to install parallel separately, and you have two choices:
  
 
a) ''install-gnu-parallel-from-source.sh''. This script installs parallel latest version from source thanks to Ole Tange (the author). Also it can fallback to a user private installation into $HOME/bin if you have not administrator permisions to install it globally.
 
a) ''install-gnu-parallel-from-source.sh''. This script installs parallel latest version from source thanks to Ole Tange (the author). Also it can fallback to a user private installation into $HOME/bin if you have not administrator permisions to install it globally.
Line 86: Line 148:
 
The program employs python3 and the following python3 libraries are needed (which can be easily installed with pip):
 
The program employs python3 and the following python3 libraries are needed (which can be easily installed with pip):
  
- [https://wiki.fysik.dtu.dk/ase/ ASE]
+
- [https://wiki.fysik.dtu.dk/ase/ ASE (version >= 3.21.1)]
 
 
- [https://matplotlib.org/ Matplotlib]
 
 
 
- [https://networkx.github.io/ NetworkX]
 
  
- [https://www.numpy.org/ NumPy]
+
- [https://matplotlib.org/ Matplotlib (version >= 3.3.4)]
  
- [https://www.scipy.org/ SciPy]
+
- [https://networkx.github.io/ NetworkX (version >= 2.5)]
  
The program runs using two levels of theory: semiempirical (or Low-Level LL) and ab initio/DFT (or High-Level HL). So far, the only program interfaced with amk to perform the ab initio/DFT calculations is G09. Therefore, if you want to perform the HL calculations G09 should be installed and should run like in this example:
+
- [https://www.numpy.org/ NumPy (version >= 1.19.5)]
  
<code>g09<inputfile>outputfile</code>
+
- [https://www.scipy.org/ SciPy (version >= 1.5.4)]
  
 
These packages might also be useful to analyze the results:
 
These packages might also be useful to analyze the results:
Line 109: Line 167:
 
'''Installation'''
 
'''Installation'''
  
Once the above packages are installed, either:
+
Once the above packages are installed, you can now install AutoMeKin following these steps:.<br />
  
Go to AutoMeKin if you cloned it from github
+
Clone AutoMeKin from GitHub:
  
<code>cd AutoMeKin</code>
+
<code>git clone https://github.com/emartineznunez/AutoMeKin.git</code>
  
or go to the amk-SOURCE-20XX folder, if you downloaded the tarball.
+
Go to the AutoMeKin folder.
  
<code>cd amk-SOURCE-20XX</code>
+
<code>cd AutoMeKin</code>
  
In both cases, the process continues the same way. Now type:
+
Now type:
  
<code>./configure</code>
+
<code>autoreconf -i</code>
  
This will install amk in $HOME/amk-20XX by default. If you want to install it in a different directory, type:
+
<code>./configure --prefix=path_to_program</code>
  
<code>./configure --prefix=path_to_program</code>
+
Where you can specify where you want to install it, e.g., <code>/opt/AutoMeKin</code>
  
 
Finally, complete the installation:
 
Finally, complete the installation:
Line 135: Line 193:
 
The last command (<code>make clean</code>) is only necessary if you want to remove from the src directory the object files and executables created in the compilation process.
 
The last command (<code>make clean</code>) is only necessary if you want to remove from the src directory the object files and executables created in the compilation process.
  
For convenience, and once “Environment Modules” has been installed, you should add the following line to your ''.bashrc'' file:
+
For convenience, and once “Environment Modules” has been installed, you should add the following line to your <code>.bashrc</code> file:
  
''module use path_to_program/modules''
+
<code>module use path_to_program/modules</code>
  
where ''path_to_program'' is the path where you installed amk (e.g., ''$HOME/amk-20XX'').
+
where <code>path_to_program</code> is the path where you installed amk (e.g., <code>$HOME/amk-2021</code>).
  
==Running the test==
+
==Running the tests==
  
To run the formic acid test example (explained in the [[Media:amk_tutorial.pdf| tutorial ]]) for a few trajectories follow these steps:
+
To run the tests follow these steps:
  
1) Load the module:
+
1) Load the module (unless you use singularity):
  
<code>module load amk/20XX</code>
+
<code>module load amk/2021</code>
  
2) Run the script if amk has been installed in $HOME:
+
2) Run the following script to run all tests:
  
 
<code>run_test.sh</code>
 
<code>run_test.sh</code>
  
or
+
'''Note that each test takes from a few seconds to several minutes.'''
 
 
<code>run_test.sh --prefix=path_to_program</code>
 
 
 
otherwise. For instance, if you use Singularity, AutoMeKin is installed in $AMK and therefore you should use:<br/>
 
 
 
<code>run_test.sh --prefix=$AMK</code>
 
 
 
 
The results of each test will be gathered in a different directory.  
 
The results of each test will be gathered in a different directory.  
  
Line 167: Line 218:
 
<code>run_test.sh --tests=FA, FAthermo</code>
 
<code>run_test.sh --tests=FA, FAthermo</code>
  
which will run FA and FAthermo tests only. These are the tests available in this version: <code>assoc</code>,
+
which will run FA and FAthermo tests only. These are the tests available in this version: <code>assoc</code>, <code>assoc_qcore</code>
<code>rdiels_alder</code>, <code>diels_alder</code>, <code>FA_biasH2</code>, <code>FA_biasH2O</code>, <code>FA_bxde</code>, <code>FA_singletraj</code>, <code>FA</code>, <code>FAthermo</code>,
+
<code>rdiels_bias</code>, <code>diels_bias</code>, <code>FA_biasH2</code>, <code>FA_biasH2O</code>, <code>FA_bxde</code>, <code>FA_singletraj</code>, <code>FA</code>, <code>FAthermo</code>,
<code>FA_programopt</code> and <code>vdW</code>.
+
<code>FA_programopt</code>, <code>vdW</code>, <code>FA_ck</code>, <code>FA_qcore</code>, <code>FA_bxde_qcore</code> and <code>ttors</code>
 
 
The <code>--prefix</code> and <code>--tests</code> options can be used simultaneously.
 
 
 
'''Note that each each test takes from a few seconds to several minutes.'''
 
  
 
==Older versions==
 
==Older versions==
Download the tarball for the 2018 version from [[Media:amk-SOURCE-2018rev.tar.gz| here ]]<br />
+
Download the [[Media:Amk-SOURCE-2020.tar.gz| tarball ]] for the 2020 version (revision 993)<br />
  
 
And follow the instructions given above (tarball).
 
And follow the instructions given above (tarball).
  
==Github==
+
Download [[Media:Tutorial2020.pdf| tutorial2020 ]]<br />
 
 
AutoMekin is also on GitHub.<br/>
 
2018 version: [[File:github2.png|90px|link=https://github.com/emartineznunez/AutoMeKin]]
 
 
 
2020 version: [[File:github2.png|90px|link=https://github.com/emartineznunez/AutoMeKin2020]]
 
  
  
 
Return to [[AutoMeKin]]
 
Return to [[AutoMeKin]]

Latest revision as of 07:25, 2 February 2024

Electronic structure packages

The program employs two levels of electronic structure: semiempirical (or Low-Level LL) and ab initio/DFT (or High-Level HL). The LL calculations can be carried out with MOPAC or Entos Qcore, and the HL calculations with Gaussian (G09/G16) or Entos Qcore.

While MOPAC comes with AutoMeKin, if you want to employ xtb method, Entos Qcore must be installed. Additionally, for the HL calculations you may want to use G09/G16, or Entos Qcore.

To install Entos Qcore, we recommend following these steps:

1. Install miniconda3

2. Add the following line to $HOME/.condarc (create the file if not present):

auto_activate_base: false

which avoids activation of base environment.

3. Install qcore version 0.8.14 in a 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

Auto installer

This is the easiest way to install/use AutoMeKin. The auto installer script installs singularity in your computer and downloads the last release container image from sylabs (https://cloud.sylabs.io/library/emartineznunez/default/automekin) 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

1) Download AutoMeKin's auto installer script Automekin.sh (Last update April 4, 2022) from your terminal:

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

2) Make the script executable:

chmod +x Automekin.sh

3) Run the script:

./Automekin.sh

Note that 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.

4) 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 plus vim, gnuplot and molden 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.

5) To exit the container just type:

exit

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

./Automekin.sh stop

Important notes:

  1. To download the file directly from your terminal, curl must be installed
  2. Make sure your auto installer is up to date (see above)
  3. The autoinstaller also works on Ubuntu 20.04 LTS on Windows 10. To install Ubuntu 20.04 LTS on Windows 10, follow these instructions: https://docs.microsoft.com/en-us/windows/wsl/install-win10
  4. AutoMeKin's third-party packages in the container are updated (see below the minimum required version numbers). Local installations of different versions of these Python packages might interfere in the execution of AutoMeKin

Singularity container

If singularity is already installed in your computer, you can obtain the container from sylabs. First check what the latest image (Tag) is 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 (XX=09/16), which can be downloaded as:

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

curl -LJO https://github.com/emartineznunez/Singularity_amk/raw/main/Singularityg16.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.

Build from source

The most recent and up to date version is avaialable at:

https://github.com/emartineznunez/AutoMeKin

You can build (system-wide) from source using this script (on a CentOS):

curl -LJO https://raw.githubusercontent.com/emartineznunez/AutoMeKin/main/Build_Centos.sh

You can also check how to install AutoMeKin using Ubuntu:

https://colab.research.google.com/github/emartineznunez/AutoMeKin/blob/main/AutoMeKin.ipynb

which involves the installation of the following dependencies (before the installation of AutoMeKin):


Installing dependencies

Before installing amk for the first time, be aware that the following packages are needed:

- GNU Autoconf

- GNU Bash

- GNU bc

- environment-modules

- GNU Awk (gawk)

- GNU C Compiler (gcc)

- Gnuplot

- GNU Fortran Compiler (gfortran)

- GNU Parallel

- SQLite (version >= 3)

- Zenity

You can install the missing ones manually, or you can use the scripts located in amk-SOURCE-2021 and called install-required-packages-distro.sh (where distro=ubuntu-16.4lts, centos7 or sl7), which will do the work for you.The ubuntu-16.4lts script installs all dependencies, but for the RHEL derivatives (centos7 and sl7) you have to install parallel separately, and you have two choices:

a) install-gnu-parallel-from-source.sh. This script installs parallel latest version from source thanks to Ole Tange (the author). Also it can fallback to a user private installation into $HOME/bin if you have not administrator permisions to install it globally.

b) install-gnu-parallel-from-epel.sh. Enables the EPEL repository and installs parallel from it.

The program employs python3 and the following python3 libraries are needed (which can be easily installed with pip):

- ASE (version >= 3.21.1)

- Matplotlib (version >= 3.3.4)

- NetworkX (version >= 2.5)

- NumPy (version >= 1.19.5)

- SciPy (version >= 1.5.4)

These packages might also be useful to analyze the results:

- molden

- sqlitebrowser


Installation

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

Clone AutoMeKin from GitHub:

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

Go to the AutoMeKin folder.

cd AutoMeKin

Now type:

autoreconf -i

./configure --prefix=path_to_program

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

Finally, complete the installation:

make
make install
make clean

The last command (make clean) is only necessary if you want to remove from the src directory the object files and executables created in the compilation process.

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).

Running the tests

To run the tests follow these steps:

1) Load the module (unless you use singularity):

module load amk/2021

2) Run the following script to run all tests:

run_test.sh

Note that each test takes from a few seconds to several minutes. The results of each test will be gathered in a different directory.

If you want to run a subset of tests use the following:

run_test.sh --tests=FA, FAthermo

which will run FA and FAthermo tests only. These are the tests available in this version: assoc, assoc_qcore rdiels_bias, diels_bias, FA_biasH2, FA_biasH2O, FA_bxde, FA_singletraj, FA, FAthermo, FA_programopt, vdW, FA_ck, FA_qcore, FA_bxde_qcore and ttors

Older versions

Download the tarball for the 2020 version (revision 993)

And follow the instructions given above (tarball).

Download tutorial2020


Return to AutoMeKin