eChem Installation Instructions

We recommend that you install the required software through conda, using the echem.yml file provided (download here). First, you will need to install conda. If you don't already have conda installed, we recommend that you use the minimal conda installer called miniconda (scroll down to the bottom of the page to find the Miniconda installers). Please download the appropriate installer for your operating system and follow the installation instructions on the miniconda website.

Once you have miniconda, you can install, run, and control Jupyter using a command prompt. For Linux and MacOS, you can directly use a terminal, while for Windows, we recommend that you use the Anaconda Powershell prompt (which should be available once you have installed miniconda).

Download the echem.yml file (or echem_minimal.yml) and navigate to the folder with the prompt command:

(Windows users, please use the echem_windows.yml file instead):

cd <path>

Check which type of solver your conda is using by running the following command:

conda info

Check the information printed on the line starting with user-agent. If you see "conda-libmamba-solver" on this line, you are all set. If you see a different solver name, please run the following commands:

conda update -n base conda

conda install -n base conda-libmamba-solver

conda config --set solver libmamba

Now you are ready to install the software indicated in the echem.yml file by running the following command:

(Windows users, please use the echem_windows.yml file instead):

conda env create -f echem.yml

Once the installation is finished, activate the new conda environment:

conda activate echem

To see that the installation worked correctly, start a Jupyter notebook by running the command:

jupyter-lab

Creat a new notebook using the Python3 ipykernel and run the following Python code in the first cell:

import veloxchem as vlx

If you get no errors, then the installation worked correctly. If you get any errors, if the kernel crashes at the import veloxchem stage, or if you have any difficulties with any of the previous steps, you can find us in room 202, Science II building, on Tuesday, 18 March, from 11:00 – 12:00 and 14:00 – 15:00.

Troubleshooting tips

For Windows users:

- If the ipykernel crashes when running the import veloxchem cell, the cause may be the use of an incorrect MPI library. You can check this, by running python in the Anaconda Power Shell:

python

import veloxchem as vlx

If you get the error below, the issue is related to the MPI library:

Abort(1090959) on node 0 (rank 0 in comm 0): Fatal error in PMPI_Init_thread: Unknown error class, error stack:

MPIR_Init_thread(193)........:

MPID_Init(1715)..............:

MPIDI_OFI_mpi_init_hook(1594):

...

To fix this MPI issue, run the following command in the Anaconda Power Shell, with the echem conda environment active:

conda install msmpi -c conda-forge

- The environment variable KMP_DUPLICATE_LIB_OK needs to be set to "TRUE".
- If the user would like to set environment variables in the Anaconda Powershell prompt (instead of using os.environ in the notebook), use the following command: $env:KMP_DUPLICATE_LIB_OK="TRUE" (note that Anaconda Powershell prompt is different from Anaconda prompt).
For ARM mac users:
- Make sure that the arch command returns arm64 in terminal.
- Make sure that the "Miniconda3 macOS Apple M1 64-bit" installer was used to install miniconda.
- Make sure that, after activating base or any other conda environment, the following command also returns arm64: python -c 'import platform; print(platform.machine())'.
For all users:
- Python 3.11 might print some warnings about frozen modules. To suppress those warnings, set the environment variable PYDEVD_DISABLE_FILE_VALIDATION to 1.
- If the user does not want to use all threads on the laptop, set OMP_NUM_THREADS to a suitable number.

Useful Tutorials

We have chosen to use Python as the high-level programming and interfacing layer on account of its flexibility, ease of use, and extensive ecosystem. As the framework for carrying out the calculation and for analysis, as well as enabling the intermingling of calculation and text, we use Jupyter. If you are unfamiliar in the use of these software packages, there is a wealth of resources which can help you get better accommodated with these tools, such as:

For those unfamiliar with using Jupyter, you can try an online version, and tutorials such as this one for creating and running a notebook for calculating π with Monte Carlo.
For Python, you can look at W3Schools, which hosts comprehensive tutorials for a large number of programming languages and modules.
The main quantum chemical software which will be used is VeloxChem.

Page updated

Google Sites

Report abuse