index | modules | gitlab | page source

# Density of states collections

The dosdata and doscollection modules contained in ase.spectrum form a new framework, intended to replace the DOS implementations in ase.dft.dos and ase.dft.pdos.

This module provides DOSCollection and GridDOSCollection objects that contain a set of related DOS data objects. This would typically represent partitioned contributions to a density-of-states, such as atomic contributions to a vibrational spectrum or orbital contributions to an electronic spectrum.

## More details

class ase.spectrum.doscollection.DOSCollection(dos_series: Iterable[DOSData])

  Base class for a collection of DOSData objects

  classmethod from_data(energies: Sequence[float] | ndarray, weights: Sequence[Sequence[float] | ndarray], info: Sequence[Dict[str, str]] = None) → DOSCollection

    Create a DOSCollection from data sharing a common set of energies

    This is a convenience method to be used when all the DOS data in the collection has a common energy axis. There is no performance advantage in using this method for the generic DOSCollection, but for GridDOSCollection it is more efficient.

    Parameters:

      - energy – common set of energy values for input data

      - weights – array of DOS weights with rows corresponding to different datasets

      - info – sequence of info dicts corresponding to weights rows.

    Returns:

      Collection of DOS data (in RawDOSData format)

  plot(npts: int = 1000, xmin: float = None, xmax: float = None, width: float = 0.1, smearing: str = 'Gauss', ax: Axes = None, show: bool = False, filename: str = None, mplargs: dict = None) → Axes

    Simple plot of collected DOS data, resampled onto a grid

    If the special key ‘label’ is present in self.info, this will be set as the label for the plotted line (unless overruled in mplargs). The label is only seen if a legend is added to the plot (i.e. by calling \(ax.legend()\)).

    Parameters:

      - npts – output data range, as passed to self.sample_grid

      - xmin – output data range, as passed to self.sample_grid

      - xmax – output data range, as passed to self.sample_grid

      - width – Width of broadening kernel, passed to self.sample_grid()

      - smearing – selection of broadening kernel for self.sample_grid()

      - ax – existing Matplotlib axes object. If not provided, a new figure with one set of axes will be created using Pyplot

      - show – show the figure on-screen

      - filename – if a path is given, save the figure to this file

      - mplargs – additional arguments to pass to matplotlib plot command (e.g. {‘linewidth’: 2} for a thicker line).

    Returns:

      Plotting axes. If “ax” was set, this is the same object.

  sample_grid(npts: int, xmin: float = None, xmax: float = None, padding: float = 3, width: float = 0.1, smearing: str = 'Gauss') → GridDOSCollection

    Sample the DOS data on an evenly-spaced energy grid

    Parameters:

      - npts – Number of sampled points

      - xmin – Minimum sampled energy value; if unspecified, a default is chosen

      - xmax – Maximum sampled energy value; if unspecified, a default is chosen

      - padding – If xmin/xmax is unspecified, default value will be padded by padding * width to avoid cutting off peaks.

      - width – Width of broadening kernel, passed to self.sample_grid()

      - smearing – selection of broadening kernel, for self.sample_grid()

    Returns:

      (energy values, sampled DOS)

  select(**info_selection: str) → DOSCollection

    Narrow DOSCollection to items with specified info

    For example, if

        dc = DOSCollection([DOSData(x1, y1, info={'a': '1', 'b': '1'}),
                            DOSData(x2, y2, info={'a': '2', 'b': '1'})])

    then

        dc.select(b='1')

    will return an identical object to dc, while

        dc.select(a='1')

    will return a DOSCollection with only the first item and

        dc.select(a='2', b='1')

    will return a DOSCollection with only the second item.

  select_not(**info_selection: str) → DOSCollection

    Narrow DOSCollection to items without specified info

    For example, if

        dc = DOSCollection([DOSData(x1, y1, info={'a': '1', 'b': '1'}),
                            DOSData(x2, y2, info={'a': '2', 'b': '1'})])

    then

        dc.select_not(b='2')

    will return an identical object to dc, while

        dc.select_not(a='2')

    will return a DOSCollection with only the first item and

        dc.select_not(a='1', b='1')

    will return a DOSCollection with only the second item.

  sum_all() → DOSData

    Sum all the DOSData contained in this Collection

  sum_by(*info_keys: str) → DOSCollection

    Return a DOSCollection with some data summed by common attributes

    For example, if

        dc = DOSCollection([DOSData(x1, y1, info={'a': '1', 'b': '1'}),
                            DOSData(x2, y2, info={'a': '2', 'b': '1'}),
                            DOSData(x3, y3, info={'a': '2', 'b': '2'})])

    then

        dc.sum_by('b')

    will return a collection equivalent to

        DOSCollection([DOSData(x1, y1, info={'a': '1', 'b': '1'})
                       + DOSData(x2, y2, info={'a': '2', 'b': '1'}),
                       DOSData(x3, y3, info={'a': '2', 'b': '2'})])

    where the resulting contained DOSData have info attributes of {‘b’: ‘1’} and {‘b’: ‘2’} respectively.

    dc.sum_by(‘a’, ‘b’) on the other hand would return the full three-entry collection, as none of the entries have common ‘a’ and ‘b’ info.

  total() → DOSData

    Sum all the DOSData in this Collection and label it as ‘Total’

class ase.spectrum.doscollection.GridDOSCollection(dos_series: Iterable[GridDOSData], energies: Sequence[float] | ndarray | None = None)
  classmethod from_data(energies: Sequence[float] | ndarray, weights: Sequence[Sequence[float] | ndarray], info: Sequence[Dict[str, str]] = None) → GridDOSCollection

    Create a GridDOSCollection from data with a common set of energies

    This convenience method may also be more efficient as it limits redundant copying/checking of the data.

    Parameters:

      - energies – common set of energy values for input data

      - weights – array of DOS weights with rows corresponding to different datasets

      - info – sequence of info dicts corresponding to weights rows.

    Returns:

      Collection of DOS data (in RawDOSData format)

  plot(npts: int = 0, xmin: float = None, xmax: float = None, width: float = None, smearing: str = 'Gauss', ax: Axes = None, show: bool = False, filename: str = None, mplargs: dict = None) → Axes

    Simple plot of collected DOS data, resampled onto a grid

    If the special key ‘label’ is present in self.info, this will be set as the label for the plotted line (unless overruled in mplargs). The label is only seen if a legend is added to the plot (i.e. by calling \(ax.legend()\)).

    Parameters:

      - npts – Number of points in resampled x-axis. If set to zero (default), no resampling is performed and the stored data is plotted directly.

      - xmin – output data range; this limits the resampling range as well as the plotting output

      - xmax – output data range; this limits the resampling range as well as the plotting output

      - width – Width of broadening kernel, passed to self.sample()

      - smearing – selection of broadening kernel, passed to self.sample()

      - ax – existing Matplotlib axes object. If not provided, a new figure with one set of axes will be created using Pyplot

      - show – show the figure on-screen

      - filename – if a path is given, save the figure to this file

      - mplargs – additional arguments to pass to matplotlib plot command (e.g. {‘linewidth’: 2} for a thicker line).

    Returns:

      Plotting axes. If “ax” was set, this is the same object.

  select(**info_selection: str) → DOSCollection

    Narrow GridDOSCollection to items with specified info

    For example, if

        dc = GridDOSCollection([GridDOSData(x, y1,
                                            info={'a': '1', 'b': '1'}),
                                GridDOSData(x, y2,
                                            info={'a': '2', 'b': '1'})])

    then

        dc.select(b='1')

    will return an identical object to dc, while

        dc.select(a='1')

    will return a DOSCollection with only the first item and

        dc.select(a='2', b='1')

    will return a DOSCollection with only the second item.

  select_not(**info_selection: str) → DOSCollection

    Narrow GridDOSCollection to items without specified info

    For example, if

        dc = GridDOSCollection([GridDOSData(x, y1,
                                            info={'a': '1', 'b': '1'}),
                                GridDOSData(x, y2,
                                            info={'a': '2', 'b': '1'})])

    then

        dc.select_not(b='2')

    will return an identical object to dc, while

        dc.select_not(a='2')

    will return a DOSCollection with only the first item and

        dc.select_not(a='1', b='1')

    will return a DOSCollection with only the second item.

class ase.spectrum.doscollection.RawDOSCollection(dos_series: Iterable[RawDOSData])