shnitsel.data.shnitsel_db_format ================================ .. py:module:: shnitsel.data.shnitsel_db_format Attributes ---------- .. autoapisummary:: shnitsel.data.shnitsel_db_format.T shnitsel.data.shnitsel_db_format.ShnitselDB Classes ------- .. autoapisummary:: shnitsel.data.shnitsel_db_format.MetaInformation shnitsel.data.shnitsel_db_format.ShnitselDBRoot Functions --------- .. autoapisummary:: shnitsel.data.shnitsel_db_format.collect_trajectories shnitsel.data.shnitsel_db_format.build_shnitsel_db shnitsel.data.shnitsel_db_format.convert_shnitsel_tree Module Contents --------------- .. py:data:: T .. py:class:: MetaInformation .. py:attribute:: input_format :type: Literal['sharc', 'newtonx', 'ase', 'pyrai2md'] | None :value: None .. py:attribute:: input_type :type: Literal['static', 'dynamic'] | None :value: None .. py:attribute:: input_format_version :type: str | None :value: None .. py:attribute:: theory_basis_set :type: str | None :value: None .. py:attribute:: est_level :type: str | None :value: None .. py:class:: ShnitselDBRoot(compounds = None) Bases: :py:obj:`xarray.DataTree` DataTree root node to keep track of Shnitsel data in a predefined structural hierarchy .. py:method:: is_level(target_level) Check whether we are at a certain level :param target_level: Desired level to check for :type target_level: str :returns: True if this level satisfies the requirements :rtype: bool .. py:method:: 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) :param group_name: The name of the group to be created. :type group_name: str :param filter_func_compound: Filter function that should return True if the group should be created for this compound. Defaults to None. :type filter_func_compound: Callable[[CompoundInfo], bool] | None, optional :param filter_func_trajectories: Filter function to determine whether a group or trajectory should be included in the new group. Defaults to None. :type filter_func_trajectories: Callable[[Trajectory|TrajectoryGroup], bool] | None, optional :param flatten_compound_trajectories: Flag to determine whether all trajectories under selected compounds should be ungrouped before selecting for the new group. Defaults to False. :type flatten_compound_trajectories: bool, optional :param \*\*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. :rtype: ShnitselDB .. py:method:: 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 .. py:method:: apply_trajectory_setup_properties(properties) Method to apply attributes on all trajectories in this tree :param properties: The attributes to set with their respective values. :type properties: MetaInformation .. py:method:: 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. :param other: The other CompoundGroup to be merged :type other: CompoundGroup :raises ValueError: Raised if the compound_info differs on some CompoundGroup. :returns: A ShnitselDBRoot object representing the merged database state :rtype: ShnitselDBRoot .. py:method:: 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. :param compounds: 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. :type compounds: str | Iterable[str] | Callable[[str],bool], optional :returns: A new database tree where only the filtered compounds are retained :rtype: ShnitselDBRoot .. py:method:: filter_trajectories(filter_func = None, est_level = None, basis_set = None, **kwargs) Function to filter trajectories based on their attributes. :param filter_func: 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. :type filter_func: Callable[[xr.Dataset], bool] | None, optional :param est_level: 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. :type est_level: str | List[str] | None, optional :param basis_set: Option to filter for a certain basis set. Can be a single key value or a set of values to retain. Defaults to None. :type basis_set: str | List[str] | None, optional :param \*\*kwargs: Key-value pairs, where the key denotes an attribute :returns: _description_ :rtype: Self .. py:method:: map_over_trajectories(map_func, result_var_name = 'result', result_as_dict = False, parallel = False) Method to apply a function to all trajectories :param map_func: Function to be applied to each individual trajectory in this database structure. :type map_func: Callable[[Trajectory], T] :param result_var_name: The name of the result variable to be assigned in either the result dataset or in the result dict. :type result_var_name: str,optional :param result_as_dict: Whether to return the result as a dict or as a ShnitselDB structure. Defaults to False which yields a ShnitselDB. :type result_as_dict: bool, optional :param parallel: Whether the application of the function map_func can be evaluated in parallel. :type parallel: bool, optional :returns: The result, either again as a ShnitselDB structure or as a layered dict structure. :rtype: ShnitselDB|dict .. py:function:: collect_trajectories(db, only_direct_children = False) Function to retrieve all Trajectories in a subtree of a ShnitselDB :param db: The subtree of the database in question :type db: xr.DataTree :param only_direct: Whether to only gather trajectories from direct children of this subtree. :type only_direct: bool, optional :returns: List of Trajectory entries in the Database :rtype: List[Trajectory] .. py:function:: 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 :param data: Input data to be wrapped in a ShnitselDB format :type data: Trajectory | xr.DataTree | List[Trajectory | xr.DataTree] :raises ValueError: If a list of ShnitselDBRoot objects was provided :raises 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. :raises ValueError: If conversion of an xr.DataTree object yields an unknown ShnitselDB type. :raises ValueError: If the provided data is of no ShnitselDB format type. :returns: The resulting ShnitselDB dataset structure. :rtype: ShnitselDB .. py:function:: convert_shnitsel_tree(data, restrict_levels=None) Function to convert a generic xarray.DataTree into a Shnitsel-specific structure. :param data: The generic DataTree to convert to Shnitsel-levels :type data: xr.DataTree :raises ValueError: If the "DataTree_Level" attribute is not set for a generic xr.DataTree node, we cannot convert. :raises ValueError: If the "DataTree_Level" attribute has an invalid value which is not recognized by Shnitsel. :returns: _description_ :rtype: ShnitselDBRoot|CompoundGroup|TrajectoryData|TrajectoryGroup .. py:type:: ShnitselDB :canonical: ShnitselDBRoot