shnitsel-tools 0.0.2.dev2

Collect, manage, process, analyse & visualize surface hopping data

shnitsel-tools

Surface Hopping Nested Instances Training Set for Excited-state Learning Tools

   

---

About

shnitsel-tools is designed to to support the entire data lifecycle of surface hopping (SH) trajectory data upon simulation: data managment, storage, processing, visualization and interpretation. The tool is compatible with surface hopping data generated using the software packages SHARC 3/4, Newton-X, and PyRAI2MD. The package leverages Xarray to benefit from efficient multidimensional data handling, improved metadata management, and a structure that aligns naturally with the needs of quantum chemical datasets.

Installation

shnitsel-tools is normally used interactively via Jupyter Notebook on a local machine. However, some users might find it convenient to convert trajectories to NetCDF on-cluster, as the NetCDF file will likely download faster than the raw text files. Either way the following should work as usual, ideally in a fresh virtual (e.g. conda) environment:

pip install shnitsel-tools[vis]

For more detailed installation instructions, see here

Usage

For documentation including an API reference, please see https://shnitsel.github.io/tools/docs/_build/index.html.

shnitsel-tools mostly exposes data as Xarray (xr) objects, so familiarity with that library is beneficial. Xarray is somewhat like Pandas for higher-dimensional data, or like Numpy with labels and other metadata.

• Overview of data structures
• Official quick overview
• Xarray in 45 minutes for a more detailed introduction

Tutorials

For a quick start, see the tutorials directory, which contains Jupyter Notebooks showing the workflow for parsing, writing and loading SHNITSEL databases as well as how to postprocess and visualize the respective data.

Detailed installation instructions

Optional dependencies

In the following, the [vis] suffix causes optional plotting dependencies to be installed. If you are using shnitsel-tools on an HPC, you can omit it.

If you would like to contribute to shnitsel-tools, you may find the development dependencies useful. These can be obtained by adding [dev] at the end of the package name.

To install all optional dependencies, please add [vis,dev] after the package name.

Using conda

Before anything else, please run:

conda create -n shnitsel python==3.12 pip
conda activate shnitsel

For tutorials or development

If you would like to work through the tutorials, please use the following commands while the conda environment is active:

git clone 'https://github.com/SHNITSEL/shnitsel-tools.git'
cd shnitsel-tools
git switch develop
pip install .[vis]

If you would like changes you make to the code in the shnitsel-tools directory to be reflected in your environment, please add the -e flag ("editable mode") to the final line of the above block:

# Same commands as before, and then:
pip install -e .[vis]  # or .[vis,dev] to include development tools

For ordinary use

If you would just like to use the package, it is unnecessary to clone the repository. Instead, it should suffice to run the following command with the conda environment active:

pip install --pre shnitsel-tools[vis]

Using uv

This tool, available at https://docs.astral.sh/uv/, is typically faster and more light-weight than pip and conda. Unlike conda, it creates traditional Python virtual environments, which are stored in the folder in which the command is run and activated by sourcing a shell-script.

git clone 'https://github.com/SHNITSEL/shnitsel-tools.git'
cd shnitsel-tools

uv pip install -e .[dev]  # install shnitsel in editable mode

For tutorials or development

If you would like to work through the tutorials, please use the following commands:

git clone 'https://github.com/SHNITSEL/shnitsel-tools.git'
cd shnitsel-tools
git switch develop
uv venv --python 3.12  # create an environment under ./.venv
source .venv/bin/activate  # activate the new environment
uv pip install .[vis]

If you would like changes you make to the code in the shnitsel-tools directory to be reflected in your environment, please add the -e flag ("editable mode") to the final line of the above block:

# Same commands as before, and then:
uv pip install -e .[vis]  # or .[vis,dev] to include development tools

For command-line only use

The following will ensure the command-line programs provided are always available, without requiring environments to be activated first.

uv tool install --pre shnitsel-tools

For ordinary use

If you would just like to use the package, it is unnecessary to clone the repository. Instead, it should suffice to run the following commands:

uv venv --python 3.12 shnitsel  # creates a directory here called ./shnitsel
source shnitsel/bin/activate  # activate the new environment
uv pip install --pre shnitsel-tools[vis]

Further Information