eChem Installation Instructions

We recommend that you install the required software through conda, using the echem_cluj.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. 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_cluj.yml file and navigate to the folder with the prompt command:

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_cluj.yml file by running the following command:

conda env create -f echem_cluj.yml

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

conda activate echem-cluj

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 two warnings, but no errors, then the installation worked correctly. If you get any errors, or you have any difficulties with any of the previous steps, you can contact us at echemcluj2023@gmail.com. We will also have some time on Monday to fix any potential issues.

Troubleshooting tips

For Windows users:
- 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.
There exists a plethora of different Jupyter books, such as this one dedicated to teaching scientific computing for chemists.
The main quantum chemical software which will be used is VeloxChem.