Installation

Installation#

Conda installation#

Conda is an open-source package and environment management system that runs on Windows, MacOS, and Linux. The conda repository contains a large number of open-source certified packages enabling scientific work. It is recommended that you install the minimal installer for conda named miniconda that includes only conda, Python, the packages they depend on, and a small number of other useful packages, including pip, zlib and a few others.

Faster conda solver

The new conda-libmamba-solver run much faster than the previous solver, as discussed in this blog post. We thus recommend that you use libmamba, which is the default for newer conda distributions. In order to check which version you are using, run conda info and you find the solver in use under user-agent. If your distribution does not use libmamba, this can be done by updating conda, installing the new solver to your base environment, and configuring your selection:

conda update -n base conda
conda install -n base conda-libmamba-solver
conda config --set solver libmamba

Following this, start a conda terminal, or Anaconda Powershell as it is referred to on a Windows system. Conda supports multiple environments and you start in the one named base as is typically indicated by the prompt. The packages required by eChem is then most conveniently installed by the echem.yml file (except for Windows user—see below). Download and run the following in the same folder:

conda env create -f echem.yml

And activate it with

conda activate echem

You can list your conda environments with

conda env list

The activated environment will be marked with an asterisk. Using such an environment enables the local installation of different software packages without interfering with the base (default) environment, and can often be used on HPC services where permissions to install programs in the default environment may not be permitted.

You should now be ready to start a Jupyter notebook with the command

jupyter-lab

which should open in your default web browser.

Note

JupyterLab only has permission to go down in the file tree from where it was initiated, so make sure to initiate it sufficiently high up.

For Windows users#

If you are using a Windows system, we recommend that you use Anaconda Powershell prompt for running your notebook(s). This enables you to use Unix commands, with, e.g, cd (change directory) for moving to the folder where the notebooks are located, e.g.:

cd ~/eChem

For moving to a folder called eChem in the user’s main directory.

Environment file#

Currently, the following software packages are not available for a conda installation in a Windows system:

  • adcc

  • gator

  • xTB

As such, you either need to use echem_windows.yml environment file in order to use functionalities in eChem save those above, or run Linux through Windows (e.g. using Windows Subsystem for Linux (WSL)).

Warning

If the module imports fail in Windows, ensure that it does not attempt to import functionalities from any of the packages above.

If your notebook doesn’t run#

If you experience issues with a crashing kernel, this may relate to several OpenMP runtimes linked to the program, which causes the kernel to die. If your kernel dies, try rerunning the notebook with the below lines added in connection to the module imports. This is an undocumented, temporary solution, but we have so far not had any problems when using it.

import veloxchem as vlx
...

import os
os.environ["KMP_DUPLICATE_LIB_OK"] = "TRUE"

Compiling a local eChem book#

If you want to download the full eChem project, this is most conveniently done by cloning the repository:

git clone https://github.com/kthpanor/echem.git

You find the Notebook files under ./docs. If you want to perform local changes and compile your own version of the eChem book, you need the jupyter-book package, which is included in echem.yml. Building the (local) book is done by running the following in the eChem folder:

jupyter-book build .

You can see the resulting book by navigating to ./_build/html and opening index.html.

Contents