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 fresh virtual (e.g. conda) environment:
pip install shnitsel-tools[vis]For more detailed installation instructions, see here
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
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.
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.
$ 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.pyIn 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.
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]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]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/.
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]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]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