shnitsel.data.shnitsel_db_format

Attributes

T
ShnitselDB

Classes

MetaInformation
ShnitselDBRoot	DataTree root node to keep track of Shnitsel data in a predefined structural hierarchy

Functions

collect_trajectories(db[, only_direct_children])	Function to retrieve all Trajectories in a subtree of a ShnitselDB
build_shnitsel_db(data)	Function to generate a full -- i.e. up to ShnitselDBRoot -- Shnitsel DB structure.
convert_shnitsel_tree(data[, restrict_levels])	Function to convert a generic xarray.DataTree into a Shnitsel-specific structure.

Module Contents

T

class MetaInformation

input_format: Literal['sharc', 'newtonx', 'ase', 'pyrai2md'] | None = None

input_type: Literal['static', 'dynamic'] | None = None

input_format_version: str | None = None

theory_basis_set: str | None = None

est_level: str | None = None

class ShnitselDBRoot(compounds=None)

Bases: xarray.DataTree

DataTree root node to keep track of Shnitsel data in a predefined structural hierarchy

Parameters:

compounds (Mapping[str, shnitsel.data.shnitsel_db.CompoundGroup] | None)

is_level(target_level)

Check whether we are at a certain level

Parameters:

target_level (str) – Desired level to check for

Returns:

True if this level satisfies the requirements

Return type:

bool

add_trajectory_group(group_name, filter_func_compound=None, filter_func_trajectories=None, flatten_compound_trajectories=False, **kwargs)

Function to group ungrouped trajectories into a new group based on filter conditions.

filter_func_compound can be used to only generate the group for certain compounds. This parameter should be a function that only returns True if the group should be created underneath this comound. filter_func_trajectories can be used to select only specific trajectories and groups underneath a compound to be part of this group. flatten_compound_trajectories can be set to True if existing groups within a compound are supposed to be dissolved (i.e. all trajectories gathered and put directly as children of the Compound)

Parameters:

• group_name (str) – The name of the group to be created.

• filter_func_compound (Callable[[CompoundInfo], bool] | None, optional) – Filter function that should return True if the group should be created for this compound. Defaults to None.

• filter_func_trajectories (Callable[[Trajectory|TrajectoryGroup], bool] | None, optional) – Filter function to determine whether a group or trajectory should be included in the new group. Defaults to None.

• flatten_compound_trajectories (bool, optional) – Flag to determine whether all trajectories under selected compounds should be ungrouped before selecting for the new group. Defaults to False.

• **kwargs – Key-value pairs for the group that should be set in the group’s key-value dict.

Returns:

A resulting ShnitselDB structure with the grouping applied.

Return type:

ShnitselDB

set_compound_info(compound_info, apply_to_all=False)

Function to set the compound information on either all unknown compounds or on all trajectories (if apply_to_all=True).

By default, the compound info will only be applied to trajectories with unknown compounds.

Args:

compound_info (CompoundInfo): The compound information. apply_to_all (bool, optional): A flag to

ShnitselDB: TypeAlias = ShnitselDBRoot specify that the compound information should be set to all trajectories in this tree. Use with caution! Defaults to False.

Raises:

ValueError: _description_

Returns:

ShnitselDBRoot: The updated database

Parameters:

compound_info (shnitsel.data.shnitsel_db.CompoundInfo)

Return type:

Self

apply_trajectory_setup_properties(properties)

Method to apply attributes on all trajectories in this tree

Parameters:

properties (MetaInformation) – The attributes to set with their respective values.

Return type:

None

merge_with(other)

Function to merge two ShnitselDBRoots into one

Called when merging two database states. Will fail if compounds in the two states have different compound_info. Attention: Trajectories that occur in both states will result in duplicate trajectories in the final result.

Parameters:

other (CompoundGroup) – The other CompoundGroup to be merged

Raises:

ValueError – Raised if the compound_info differs on some CompoundGroup.

Returns:

A ShnitselDBRoot object representing the merged database state

Return type:

ShnitselDBRoot

filter_compounds(compounds)

Function to filter out only a subset of compounds.

Either retains exactly the requested compound if provided a string, only the set of provided compounds if provided a list of keys and all compounds for which the selector function returns True otherwise. The return value will never be None, but it may be a ShnitselDB tree without any trajectories in it.

Parameters:

compounds (str | Iterable[str] | Callable[[str],bool], optional) – The name of a single compound, a list of names of compounds to retain or a function that says for each compound whether it will be retained.

Returns:

A new database tree where only the filtered compounds are retained

Return type:

ShnitselDBRoot

filter_trajectories(filter_func=None, est_level=None, basis_set=None, **kwargs)

Function to filter trajectories based on their attributes.

Parameters:

• filter_func (Callable[[xr.Dataset], bool] | None, optional) – A function to evaluate whether a trajectory should be retained. Should return True if the trajectory should stay in the filtered set. Defaults to None.

• est_level (str | List[str] | None, optional) – Option to filter for a certain level of electronic structure theory/calculation method. Can be a single key value or a set of values to retain. Defaults to None.

• basis_set (str | List[str] | None, optional) – Option to filter for a certain basis set. Can be a single key value or a set of values to retain. Defaults to None.

• **kwargs – Key-value pairs, where the key denotes an attribute

Returns:

_description_

Return type:

Self

map_over_trajectories(map_func, result_var_name='result', result_as_dict=False, parallel=False)

Method to apply a function to all trajectories

Parameters:

• map_func (Callable[[Trajectory], T]) – Function to be applied to each individual trajectory in this database structure.

• result_var_name (str,optional) – The name of the result variable to be assigned in either the result dataset or in the result dict.

• result_as_dict (bool, optional) – Whether to return the result as a dict or as a ShnitselDB structure. Defaults to False which yields a ShnitselDB.

• parallel (bool, optional) – Whether the application of the function map_func can be evaluated in parallel.

Returns:

The result, either again as a ShnitselDB structure or as a layered dict structure.

Return type:

ShnitselDB|dict

collect_trajectories(db, only_direct_children=False)

Function to retrieve all Trajectories in a subtree of a ShnitselDB

Parameters:

• db (xr.DataTree) – The subtree of the database in question

• only_direct (bool, optional) – Whether to only gather trajectories from direct children of this subtree.

• only_direct_children (bool)

Returns:

List of Trajectory entries in the Database

Return type:

List[Trajectory]

build_shnitsel_db(data)

Function to generate a full – i.e. up to ShnitselDBRoot – Shnitsel DB structure.

Wraps trajectories in xr.DataTree structures, converts xr.DataTree structures into Shnitsel-subclasses and converts lists of elements to either TrajectoryDate, TrajectoryGroup or Compoundgroup levels in a full ShnitselDB Tree

Parameters:

data (Trajectory | xr.DataTree | List[Trajectory | xr.DataTree]) – Input data to be wrapped in a ShnitselDB format

Raises:

• ValueError – If a list of ShnitselDBRoot objects was provided

• ValueError – If a list of xr.DataTree objects on different Levels of the ShnitselDB hierarchy was provided, e.g. a mix of TrajectoryData and CompoundGroup nodes.

• ValueError – If conversion of an xr.DataTree object yields an unknown ShnitselDB type.

• ValueError – If the provided data is of no ShnitselDB format type.

Returns:

The resulting ShnitselDB dataset structure.

Return type:

ShnitselDB

convert_shnitsel_tree(data, restrict_levels=None)

Function to convert a generic xarray.DataTree into a Shnitsel-specific structure.

Parameters:

data (xr.DataTree) – The generic DataTree to convert to Shnitsel-levels

Raises:

• ValueError – If the “DataTree_Level” attribute is not set for a generic xr.DataTree node, we cannot convert.

• ValueError – If the “DataTree_Level” attribute has an invalid value which is not recognized by Shnitsel.

Returns:

_description_

Return type:

ShnitselDBRoot|CompoundGroup|TrajectoryData|TrajectoryGroup

type ShnitselDB = ShnitselDBRoot