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
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
which should open in your default web browser.
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.:
For moving to a folder called
eChem in the user’s main directory.
Currently, the following software packages are not available for a conda installation in a Windows system:
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)).
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