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.
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 virtual (e.g. conda) environment:
pip install shnitsel-toolsThe 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.
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.
- parsing trajcetory and initial condition data obtained by SHARC
- parsing trajectory data produced with Newton-X
- convert ASE databases
Four notebooks demonstrate a workflow for the comparative analysis of homologous/isoelectronic molecules, from filtration via dimensional reduction and clustering to kinetics.
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.pyWe recommend installation using the uv tool, available at https://docs.astral.sh/uv/.
Please clone this repo and run the following in the shnitsel-tools directory:
git clone 'https://github.com/SHNITSEL/shnitsel-tools.git'
cd shnitsel-tools
uv venv # create an environment under ./.venv
source .venv/bin/activate # activate the new environment
uv pip install -e .[dev] # install shnitsel in editable modeIn the above, the option -e installs in editable mode, meaning that Python will see changes you make
to the source, while [dev] installs the optional development dependencies.
If you would like to contribute your changes, please fork this repo, and make a pull request.