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: Union[Sequence[float], ndarray], weights: Sequence[Union[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: matplotlib.axes.Axes = None, show: bool = False, filename: str = None, mplargs: dict = None) → matplotlib.axes.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: Optional[Union[Sequence[float], ndarray]] = None)

classmethod from_data(energies: Union[Sequence[float], ndarray], weights: Sequence[Union[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: matplotlib.axes.Axes = None, show: bool = False, filename: str = None, mplargs: dict = None) → matplotlib.axes.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])