shnitsel-tools 0.0.1.post1

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.

Usage

The package is organized into top-level functions for reading data, accessor methods available on xr.Dataset and xr.DataArray objects, plotting routines found in the shnitsel.plot namespace, and functions taking an RDKit Mol object as their principal argument under shnitsel.rd. The adventurous may find something useful under shnitsel.core, though this should be considered internal and therefore subject to change.

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.

Collection & storage

• parsing trajcetory and initial condition data obtained by SHARC
• parsing trajectory data produced with Newton-X
• convert ASE databases

Management

exploration of electronic properties

Postprocessing & visualization of data

• datasheet for trajectory data
• principal component analysis and trajectory classification

Workflow walkthrough

Four notebooks demonstrate a workflow for the comparative analysis of homologous/isoelectronic molecules, from filtration via dimensional reduction and clustering to kinetics.

Tree

shnitsel
├── core
│   ├── ase.py
│   ├── datasheet
│   │   ├── colormaps.py
│   │   ├── common.py
│   │   ├── dip_trans_hist.py
│   │   ├── hist.py
│   │   ├── __init__.py
│   │   ├── nacs_hist.py
│   │   ├── oop.py
│   │   ├── per_state_hist.py
│   │   ├── structure.py
│   │   └── time.py
│   ├── filter_unphysical.py
│   ├── filtre.py
│   ├── indexes.py
│   ├── __init__.py
│   ├── parse
│   │   ├── common.py
│   │   ├── __init__.py
│   │   ├── nx.py
│   │   ├── pyrai2md.py
│   │   ├── sharc_icond.py
│   │   ├── sharc_traj.py
│   │   └── xyz.py
│   ├── plot
│   │   ├── __init__.py
│   │   ├── kde.py
│   │   ├── p3mhelpers.py
│   │   ├── pca_biplot.py
│   │   ├── polychrom.py
│   │   ├── select.py
│   │   └── spectra3d.py
│   ├── postprocess.py
│   ├── spectra.py
│   └── xrhelpers.py
├── __init__.py
├── plot
│   └── __init__.py
├── rd.py
└── xarray.py

Installation

You can create the environment with a custom path using one of the following methods:

Option 1: Using pip

The following should work as usual:

pip install shnitsel-tools

Option 2: Using venvs with `uv`

If you would like to work on the source code, we recommend installing using the `uv` tool, available at https://docs.astral.sh/uv/. Run the following in the `shnitsel-tools` directory:

uv venv  # create an environment under ./.venv
. .venv/bin/activate  # activate the new environment
uv pip install -e .  # install shnitsel in editable mode

To install the optional development dependencies run

uv pip install -e '.[dev]'

Option 3: Using the `--prefix` Flag

You can create the environment and specify the desired path by using the conda env create command with the --prefix flag:

conda env create --prefix /home/user/anaconda3/envs/shnitsel -f shnitsel-tools.yml

Option 4: Adding the Path to the .yml File

Alternatively, you can manually add the desired path to the shnitsel-tools.yml file and create the environment directly:

1. Open the shnitsel-tools.yml file for editing:

vi shnitsel-tools.yml

2. Add the following line to the file:

prefix: /home/user/anaconda3/envs/shnitsel

3. Create the environment with a custom path.

conda env create -f shnitsel-rdkit.yml

Further Information