shnitsel.io.ase.parse
=====================

.. py:module:: shnitsel.io.ase.parse


Attributes
----------

.. autoapisummary::

   shnitsel.io.ase.parse.dummy_leading_dim
   shnitsel.io.ase.parse.multi_level_prefix


Functions
---------

.. autoapisummary::

   shnitsel.io.ase.parse.shapes_from_metadata
   shnitsel.io.ase.parse._json_deserialize_ndarray
   shnitsel.io.ase.parse.apply_dataset_meta_from_db_metadata
   shnitsel.io.ase.parse.read_ase


Module Contents
---------------

.. py:data:: dummy_leading_dim
   :type:  str
   :value: 'leading_dim_unknown'


.. py:data:: multi_level_prefix
   :type:  str
   :value: '_MultiIndex_levels_for_'


.. py:function:: shapes_from_metadata(db_meta, db_format = None)

   Function to assign shapes based on the chosen db_format and potential information in the metadata of a database.

   If conflicting information on the db_format is provided and present in the database, en error will be raised.

   :param db_meta: The metadata dict of an ASE database.
   :type db_meta: dict
   :param db_format: The requested format of the database. Defaults to None.
   :type db_format: Literal['spainn', 'schnet'] | None, optional

   :returns: Dict of data_var shapes
             dict[str, list[str]]: Dict of coordinate shapes
             str: The name of the leading dimension. Should be `frame` or `time`, but can be `leading_dim_unknown` if unknown
   :rtype: dict[str, list[str]]

   :raises ValueError: If a db_format of database was requested that conflicts with the format of the database.


.. py:function:: _json_deserialize_ndarray(value)

.. py:function:: apply_dataset_meta_from_db_metadata(dataset, db_meta, default_attrs)

   Apply attributes from db metadata and perform some validation checks on the result.

   Loads remaining missing coordinate variables from db metadata if available.
   Checks size of resulting dimensions if specified in db metadata.
   Further initializes the multi indices if specified in the metadata.

   :param dataset: Trajectory dataset parsed from ASE db
   :type dataset: Trajectory
   :param db_meta: Metadata from the trajectory db file
   :type db_meta: dict
   :param default_attrs: Attributes to apply to variables by default
   :type default_attrs: dict

   :returns: Dataset with attributes set from from db metadata and dimension sizes asserted
   :rtype: Trajectory


.. py:function:: read_ase(db_path, db_format = None, loading_parameters = None)

   Reads an ASE DB containing data in the SPaiNN or SchNet format

   :param db_path: Path to the database
   :type db_path: pathlib.Path
   :param db_format: Must be one of 'spainn' or 'schnet' or None; determines interpretation of array shapes If None is provided, no shape will be assumed
   :type db_format: Literal['spainn', 'schnet'] | None, optional
   :param loading_parameters: Potentially configured parameters to overwrite loading behavior
   :type loading_parameters: LoadingParameters

   :rtype: An `xr.Dataset` of frames

   :raises ValueError: If `db_format` is not one of 'spainn' or 'schnet'
   :raises FileNotFoundError: If `db_path` is not a file
   :raises ValueError: If `db_path` does not contain data corresponding to the format `db_format`