shnitsel.io.ase.format_reader
=============================

.. py:module:: shnitsel.io.ase.format_reader


Attributes
----------

.. autoapisummary::

   shnitsel.io.ase.format_reader._ase_default_pattern_regex
   shnitsel.io.ase.format_reader._ase_default_pattern_glob
   shnitsel.io.ase.format_reader.DataType


Classes
-------

.. autoapisummary::

   shnitsel.io.ase.format_reader.ASEFormatInformation
   shnitsel.io.ase.format_reader.ASEFormatReader


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

.. py:class:: ASEFormatInformation

   Bases: :py:obj:`shnitsel.io.format_reader_base.FormatInformation`


   Information to keep track of relevant information for


.. py:data:: _ase_default_pattern_regex
   :value: '*.db'


.. py:data:: _ase_default_pattern_glob
   :value: '*.db'


.. py:data:: DataType

.. py:class:: ASEFormatReader

   Bases: :py:obj:`shnitsel.io.format_reader_base.FormatReader`


   Class for providing the ASE format reading functionality in the standardized `FormatReader` interface


   .. py:method:: find_candidates_in_directory(path)

      Function to return a all potential matches for the current file format  within a provided directory at `path`.
      Parameters

      ----------
      path : PathOptionsType
          The path to a directory to check for potential candidate files or subdirectories

      :returns: * *list[pathlib.Path]* -- A list of paths that should be checked in detail for whether they represent the format of this FormatReader.
                * *None* -- If no potential candidates were found



   .. py:method:: check_path_for_format_info(path, hints_or_settings = None)

      Check if the `path` is a ASE-style `.db` file

      Designed for a single input file

      :param path: The path to check for being a ASE-style `.db` file
      :type path: PathOptionsType
      :param hints_or_settings: Configuration options provided to the reader by the user, by default None
      :type hints_or_settings: dict | None, optional

      :returns: The object holding all relevant format information for the path contents if it represents a ASE-style
                NetCDF file
      :rtype: FormatInformation

      :raises FileNotFoundError: If the `path` is not a directory.
      :raises FileNotFoundError: If `path` is a directory but does not satisfy the ASE file format input requirements



   .. py:method:: read_from_path(path, *, format_info, loading_parameters = None, expect_dtype = None)

      Read an ASE-style file from `path`.

      Implements `FormatReader.read_from_path()`.
      Designed for a single input file.

      :param path: Path to an ASE-format `.db` file.
      :type path: pathlib.Path
      :param format_info: Format information on the provided `path` that has been previously parsed.
      :type format_info: FormatInformation
      :param loading_parameters: Loading parameters to e.g. override default state names, units or configure the error reporting behavior, by default None
      :type loading_parameters: LoadingParameters | None, optional
      :param expect_dtype: An optional parameter to specify the return type.
                           For ASE-style db files, the return type can be either a single frameset (Frames), a trajectory (Trajectory) a collection/list
                           of such sets or a blank xr.Dataset if conversion did not succeed.
                           If for some reason a datatype that is convertible to a Shnitsel-type from arbitrary xr.Dataset containers (SupportsFromXrConversion)
                           is contained within the database, it will be deserialized.
                           This type should specify either the type of the full result or the type of data entries in a hierarchical Shnitsel tree structure.
      :type expect_dtype: type[DataType] | UnionType | None, optional

      :returns: * *xr.Dataset*
                * *| ShnitselDataset*
                * *| SupportsFromXrConversion*
                * *| TreeNode[Any, ShnitselDataset | SupportsFromXrConversion | xr.Dataset]*
                * *| TreeNode[Any, DataType]*
                * *| DataType*
                * *| None* -- The data stored in the ASE-style file.
                  Can be either a single frameset (Frames), a trajectory (Trajectory) a collection/list
                  of such sets or a blank xr.Dataset if conversion did not succeed.
                  If for some reason a datatype that is convertible to a Shnitsel-type from arbitrary xr.Dataset containers (SupportsFromXrConversion)
                  is contained within the database, it will be deserialized.

      :raises ValueError: Not enough loading information was provided via `path` and `format_info`, e.g. if both are None.
      :raises FileNotFoundError: Path was not found or was not of appropriate ASE-style `.db` format



   .. py:method:: get_units_with_defaults(unit_overrides = None)

      Apply units to the default unit dictionary of the format ASE

      :param unit_overrides: Units denoted by the user to override format default settings. Defaults to None.
      :type unit_overrides: dict[str, str] | None, optional

      :raises NotImplementedError: The class does not provide this functionality yet

      :returns: The resulting, overridden default units
      :rtype: dict[str, str]