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

abstract get_energies() → Union[Sequence[float], ndarray][source]

Get energy data stored in this object

abstract get_weights() → Union[Sequence[float], ndarray][source]

Get DOS weights stored in this object

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