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.

Tests

Running the test-suite can help confirm that shnitsel-tools is correctly installed in your environment. To run the tests, please install shnitsel-tools by cloning the repo as described here (conda users) or here (uv users). Then run the pytest program without arguments while inside the repository directory, with the virtual environment activated. More information on how to invoke pytest is available here.

If you are a contributor, please consider using the tox command to run tests across the different supported Python versions.

Overview of repository contents

$ tree -I '_*' shnitsel/
shnitsel
├── analyze
│   ├── generic.py
│   ├── hops.py
│   ├── lda.py
│   ├── pca.py
│   ├── pls.py
│   ├── populations.py
│   ├── spectra.py
│   └── stats.py
├── bridges.py
├── clean
│   ├── common.py
│   ├── dispatch_plots.py
│   ├── filter_energy.py
│   ├── filter_geo.py
│   └── filtration_class.py
├── cli
│   ├── convert_to_shnitsel.py
│   ├── generate_datasheet.py
│   └── merge_shnitsel_files.py
├── core
│   ├── feature_detection.py
│   └── typedefs.py
├── data
│   ├── atom_helpers.py
│   ├── charge_helpers.py
│   ├── dataset_containers
│   │   ├── data_series.py
│   │   ├── dataset_vis.py
│   │   ├── frames.py
│   │   ├── inter_state.py
│   │   ├── multi_layered.py
│   │   ├── multi_series.py
│   │   ├── multi_stacked.py
│   │   ├── per_state.py
│   │   ├── shared.py
│   │   ├── trajectory_collection.py
│   │   ├── trajectory.py
│   │   └── xr_conversion.py
│   ├── helpers.py
│   ├── multi_indices.py
│   ├── proxy_class.py
│   ├── shnitsel_db
│   │   └── db_function_decorator.py
│   ├── shnitsel_db_helpers.py
│   ├── state_helpers.py
│   ├── traj_combiner_methods.py
│   ├── trajectory_grouping_params.py
│   ├── trajectory_variable_description.py
│   └── tree
│       ├── child_support_functions.py
│       ├── compound.py
│       ├── data_group.py
│       ├── data_leaf.py
│       ├── datatree_level.py
│       ├── node.py
│       ├── selection.py
│       ├── support_functions.py
│       ├── tree_completion.py
│       ├── tree.py
│       ├── tree_vis.py
│       └── xr_conversion.py
├── filtering
│   ├── filter.md
│   ├── helpers.py
│   ├── state_selection.py
│   └── structure_selection.py
├── geo
│   ├── alignment.py
│   ├── analogs.py
│   ├── geocalc_
│   │   ├── algebra.py
│   │   ├── angles.py
│   │   ├── bla_chromophor.py
│   │   ├── dihedrals.py
│   │   ├── distances.py
│   │   ├── helpers.py
│   │   ├── positions.py
│   │   └── pyramids.py
│   └── geocalc.py
├── io
│   ├── ase
│   │   ├── format_reader.py
│   │   ├── parse.py
│   │   └── write.py
│   ├── format_reader_base.py
│   ├── format_registry.py
│   ├── molcas
│   │   └── molcas_opt.py
│   ├── newtonx
│   │   ├── format_reader.py
│   │   └── parse.py
│   ├── pyrai2md
│   │   ├── format_reader.py
│   │   └── parse.py
│   ├── read.py
│   ├── sharc
│   │   ├── format_reader.py
│   │   ├── parse_initial_conditions.py
│   │   ├── parse_trajectory.py
│   │   └── qm_helpers.py
│   ├── shared
│   │   ├── helpers.py
│   │   ├── messages.py
│   │   ├── trajectory_finalization.py
│   │   ├── trajectory_setup.py
│   │   └── variable_flagging.py
│   ├── shnitsel
│   │   ├── format_reader.py
│   │   ├── parse.py
│   │   └── write.py
│   ├── xr_io_compatibility.py
│   └── xyz
│       └── parse.py
├── rd.py
├── test_support
│   └── trajectory_verification.py
├── units
│   ├── conversion.py
│   ├── defaults.py
│   └── definitions.py
├── vis
│   ├── colormaps.py
│   ├── datasheet
│   │   ├── datasheet_page.py
│   │   ├── datasheet.py
│   │   └── figures
│   │       ├── common.py
│   │       ├── dip_trans_hist.py
│   │       ├── energy_bands.py
│   │       ├── hist.py
│   │       ├── nacs_hist.py
│   │       ├── per_state_hist.py
│   │       ├── socs_hist.py
│   │       ├── soc_trans_hist.py
│   │       ├── structure.py
│   │       └── time.py
│   ├── plot
│   │   ├── common.py
│   │   ├── filtration.py
│   │   ├── kde.py
│   │   ├── p3mhelpers.py
│   │   ├── pca_biplot.py
│   │   ├── polychrom.py
│   │   ├── select.py
│   │   ├── spectra3d.py
│   │   └── time.py
│   ├── static
│   │   ├── css
│   │   │   └── style.css
│   │   └── html
│   │       └── icons-svg-inline.html
│   ├── support
│   │   ├── ipython_visualization.py
│   │   ├── multi_plot.py
│   │   └── visualizeable.py
│   └── vmd
│       └── script.tcl
└── xarray.py

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.

Installation using conda

For tutorials, tests or development (conda)

If you would like to work through the tutorials, run the tests, or modify the code, please use the following commands:

git clone 'https://github.com/SHNITSEL/shnitsel-tools.git'
cd shnitsel-tools
conda create -n shnitsel python==3.12 pip
conda activate shnitsel
pip install -e .[vis,dev]

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:

conda create -n shnitsel python==3.12 pip
conda activate shnitsel
pip install shnitsel-tools[vis]

Installation using uv

This tool 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. It can be installed by following the instructions at https://docs.astral.sh/uv/.

For tutorials, tests or development (uv)

If you would like to work through the tutorials or modify the code, run the tests, please use the following commands:

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

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  # create a directory here named ./shnitsel
source shnitsel/bin/activate  # activate the new environment
uv pip install shnitsel-tools[vis]

If you only want to use the command-line

The following will ensure the command-line programs provided are always available, without requiring environments to be activated first.
This may be the easiest approach for use on HPC. It is not expected to support interactive notebook-based workflows.

uv tool install shnitsel-tools

Further Information