Density of states data
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 the RawDOSData and GridDOSData objects that contain a single series of spectral contributions with corresponding energies. This can then be resampled with broadening on-the-fly to create typical density-of-states plots.
Any DOS data object includes a .info
dictionary of metadata. The
classes in ase.spectrum.doscollection
can store multiple
DOSData objects and have methods for selecting and merging data series
based on this metadata.
DOSData is an abstract base class and should not be used
directly. RawDOSData is intended for “sparse” data such as an exact
set of eigenvalues for electronic states. Precision errors related to
binning/broadening are avoided by deferring binning until data is
plotted or extracted using get_dos()
. GridDOSData stores data on a
regular energy series, and is suitable for data that was imported in
this format (e.g. a Bloechl-corrected tetrahedron-integrated DOS on a
dense k-point mesh).
More details
- class ase.spectrum.dosdata.DOSData(info: Dict[str, str] = None)[source]
Abstract base class for a single series of DOS-like data
Only the ‘info’ is a mutable attribute; DOS data is set at init
- abstract copy() DOSData [source]
Returns a copy in which info dict can be safely mutated
- static label_from_info(info: Dict[str, str])[source]
Generate an automatic legend label from info dict
- 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 [source]
Simple 1-D plot of 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 for 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') GridDOSData [source]
Sample the DOS data on an evenly-spaced energy grid
- Parameters:
npts – Number of sampled points
xmin – Minimum sampled x value; if unspecified, a default is chosen
xmax – Maximum sampled x 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
smearing – selection of broadening kernel (only ‘Gauss’ is implemented)
- Returns:
(energy values, sampled DOS)
- class ase.spectrum.dosdata.GeneralDOSData(energies: Sequence[float] | ndarray, weights: Sequence[float] | ndarray, info: Dict[str, str] = None)[source]
Base class for a single series of DOS-like data
Only the ‘info’ is a mutable attribute; DOS data is set at init
This is the base class for DOSData objects that accept/set seperate “energies” and “weights” sequences of equal length at init.
- copy() D [source]
Returns a copy in which info dict can be safely mutated
- get_energies() ndarray [source]
Get energy data stored in this object
- get_weights() ndarray [source]
Get DOS weights stored in this object
- class ase.spectrum.dosdata.GridDOSData(energies: Sequence[float] | ndarray, weights: Sequence[float] | ndarray, info: Dict[str, str] = None)[source]
A collection of regularly-sampled data which represents a DOS
This is an appropriate data container for density-of-states (DOS) or spectral data where the intensity values form a regular grid. This is generally the result of sampling or integrating into discrete bins, rather than a collection of unique states. The data may be plotted or resampled for further analysis using the sample_grid() and plot() methods.
Metadata may be stored in the info dict, in which keys and values must be strings. This data is used for selecting and combining multiple DOSData objects in a DOSCollection object.
When RawDOSData objects are combined with the addition operator:
big_dos = raw_dos_1 + raw_dos_2
the weights data is summed (requiring a consistent energy grid) and the new info dictionary consists of the intersection of the inputs: only key-value pairs that were common to both of the input objects will be retained in the new combined object. For example:
(GridDOSData([0.1, 0.2, 0.3], [y1, y2, y3], info={'symbol': 'O', 'index': '1'}) + GridDOSData([0.1, 0.2, 0.3], [y4, y5, y6], info={'symbol': 'O', 'index': '2'}))
will yield the equivalent of:
GridDOSData([0.1, 0.2, 0.3], [y1+y4, y2+y5, y3+y6], info={'symbol': 'O'})
- 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 [source]
Simple 1-D plot of DOS data
Data will be resampled onto a grid with \(npts\) points unless \(npts\) is set to zero, in which case:
no resampling takes place
\(width\) and \(smearing\) are ignored
\(xmin\) and \(xmax\) affect the axis limits of the plot, not the underlying data.
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(). If no npts was set but width is set, npts will be set to 1000.
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.
- class ase.spectrum.dosdata.RawDOSData(energies: Sequence[float] | ndarray, weights: Sequence[float] | ndarray, info: Dict[str, str] = None)[source]
A collection of weighted delta functions which sum to form a DOS
This is an appropriate data container for density-of-states (DOS) or spectral data where the energy data values not form a known regular grid. The data may be plotted or resampled for further analysis using the sample_grid() and plot() methods. Multiple weights at the same energy value will only be combined in output data, and data stored in RawDOSData is never resampled. A plot_deltas() function is also provided which plots the raw data.
Metadata may be stored in the info dict, in which keys and values must be strings. This data is used for selecting and combining multiple DOSData objects in a DOSCollection object.
When RawDOSData objects are combined with the addition operator:
big_dos = raw_dos_1 + raw_dos_2
the energy and weights data is concatenated (i.e. combined without sorting or replacement) and the new info dictionary consists of the intersection of the inputs: only key-value pairs that were common to both of the input objects will be retained in the new combined object. For example:
(RawDOSData([x1], [y1], info={'symbol': 'O', 'index': '1'}) + RawDOSData([x2], [y2], info={'symbol': 'O', 'index': '2'}))
will yield the equivalent of:
RawDOSData([x1, x2], [y1, y2], info={'symbol': 'O'})
- plot_deltas(ax: Axes = None, show: bool = False, filename: str = None, mplargs: dict = None) Axes [source]
Simple plot of sparse DOS data as a set of delta functions
Items at the same x-value can overlap and will not be summed together
- Parameters:
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 Axes.vlines command (e.g. {‘linewidth’: 2} for a thicker line).
- Returns:
Plotting axes. If “ax” was set, this is the same object.