exc!ting
exciting
a full-potential all-electron package implementing linearized augmented planewave methods

Installation of the excitingJupyter Tutorial Environment

Read the following paragraphs before starting with the tutorials!

Compilation of exciting

Before starting, be sure that exciting is already compiled according to the procedure reported in Download and compile exciting. This is also documented in exciting’s INSTALL file in the repository root.

Defining the Relevant Environment Variables

In order to run the scripts used in the exciting tutorials it is important to define the relevant environment variables. This can be done, starting from exciting's root directory, by moving to

cd tools/excitingjupyter

and executing

source set_env_vars.sh

Installing the excitingJupyter Package

All Jupyter tutorials require Python 3.7 or above to run. As a first step in running the Jupyter tutorials, it is useful to create a virtual environment in which you can install and run the notebooks. Each venv has its own Python binary (which matches the version of the binary that was used to create this environment) and can have its own independent set of installed Python packages in its site directories. To create a venv, move to:

cd $EXCITINGROOT/tools/excitingjupyter

You can create the venv using an executable bash script:

source create_env.sh

This script will automatically activate the environment, so you can start right ahead.

Due to recent updates to the exciting tutorials, an additional step is required before you can start. You have to update the excitingscripts package via pip:

pip3 install --upgrade excitingscripts

Alternatively, you can do the installation by hand.

Manually installing excitingjupyter

# Create python venv for running excitingjupyter

mkdir venv && cd venv
python3 -m venv excitingvenv
source excitingvenv/bin/activate
cd ..

python3 -m pip install --upgrade --force pip
pip3 install --upgrade setuptools
# Install excitingtools
pip3 install -e ../exciting_tools

# Install excitingscripts from PyPI

pip3 install excitingscripts
# Install excitingjupyter
pip3 install .
# Install local kernal for jupyter
python3 -m ipykernel install --user --name=excitingjupyter

If you see the error invalid command: bdist_wheel when installing excitingtools, you need to run pip3 install wheel, then try again.

One can leave the venv at any time by typing deactivate. If you are repeating the installation procedure for the venv, remember to exit with deactivate before trying to regenerate it. Creating a venv for the exciting notebooks to run in is only required once, however you should ensure it is activated every time you wish to run a notebook. From exciting’s root:

source $EXCITINGROOT/tools/excitingjupyter/venv/excitingvenv/bin/activate

Adding Custom CSS Style

In order to add the layout style designed for the Jupyter tutorials, type the following commands starting from tools/excitingjupyter:

# Find path for custom CSS file:

path=$(python -c "import notebook; print(notebook.__file__)")
notebookpath=${path::-11} 
csspath="${notebookpath}static/custom/." 

# Add custom CSS style:

cp excitingjupyter/custom.css "$csspath"
cp ../../docs/logo/logotransp.png "$csspath"

Runtime Libraries

Please note that exciting requires certain libraries at runtime (for the SMP version, openBLAS or MKL), and setting them in a terminal shell is not sufficient as each Jupyter cell creates a new shell instance. The easiest way to ensure they are present is to add them to your .bashrc. For example, the SOL group uses the TCL module system so one would add:

module load intel/2019

to the .bashrc (which loads everything required). Please take an equivalent approach on your platform.

It is required to do this in the same terminal where Jupyter is started, before starting with the tutorials.

Starting Jupyter

To start working with the Jupyter notebooks, move to:

cd $EXCITINGROOT/tools/excitingjupyter/excitingjupyter

and execute:

jupyter-notebook

This will open your browser, where you can select the tutorial you want to work on. To start, e.g., with the first tutorials, click on the folder 01_getting_started, and select the notebook: 01_tutorial_how_to_start_an_exciting_calculation.ipynb.

This should launch an executable version of the notebook in a new tab of your browser.