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])[source]
Base class for a collection of DOSData objects
- classmethod from_data(energies: Sequence[float], weights: Sequence[Sequence[float]], info: Sequence[Dict[str, str]] = None) DOSCollection[source]
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[source]
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[source]
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[source]
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[source]
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[source]
Sum all the DOSData contained in this Collection
- sum_by(*info_keys: str) DOSCollection[source]
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[source]
Sum all the DOSData in this Collection and label it as ‘Total’
- class ase.spectrum.doscollection.GridDOSCollection(dos_series: Iterable[GridDOSData], energies: Optional[Sequence[float]] = None)[source]
- classmethod from_data(energies: Sequence[float], weights: Sequence[Sequence[float]], info: Sequence[Dict[str, str]] = None) GridDOSCollection[source]
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[source]
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[source]
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[source]
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.