Module for defining common data used and produced by atomistic simulation packages.

class VolumetricData(structure: Structure, data, distance_matrix=None, data_aug=None)[source]

Bases: MSONable

Simple volumetric object. Used to read LOCPOT/CHGCAR files produced by vasp as well as cube files produced by other codes.


Structure associated with the Volumetric Data object

..attribute:: is_spin_polarized

True if run is spin polarized

..attribute:: dim

Tuple of dimensions of volumetric grid in each direction (nx, ny, nz).

..attribute:: data

Actual data as a dict of {string: np.array}. The string are “total” and “diff”, in accordance to the output format of Vasp LOCPOT and CHGCAR files where the total spin density is written first, followed by the difference spin density.


Total number of grid points in volumetric data.

Typically, this constructor is not used directly and the static from_file constructor is used. This constructor is designed to allow summation and other operations between VolumetricData objects.

  • structure – Structure associated with the volumetric data

  • data – Actual volumetric data. If the data is provided as in list format, it will be converted into an np.array automatically

  • data_aug – Any extra information associated with volumetric data (typically augmentation charges)

  • distance_matrix – A pre-computed distance matrix if available. Useful so pass distance_matrices between sums, short-circuiting an otherwise expensive operation.


Copy of Volumetric object

classmethod from_cube(filename)[source]

Initialize the cube object and store the data as data


filename (str) – of the cube to read

classmethod from_hdf5(filename, **kwargs)[source]

Reads VolumetricData from HDF5 file.


filename – Filename




Get the averaged total of the volumetric data a certain axis direction. For example, useful for visualizing Hartree Potentials from a LOCPOT file.


ind (int) – Index of axis.


Average total along axis


Returns the grid for a particular axis.


ind (int) – Axis index.

get_integrated_diff(ind, radius, nbins=1)[source]

Get integrated difference of atom index ind up to radius. This can be an extremely computationally intensive process, depending on how many grid points are in the VolumetricData.

  • ind (int) – Index of atom.

  • radius (float) – Radius of integration.

  • nbins (int) – Number of bins. Defaults to 1. This allows one to obtain the charge integration up to a list of the cumulative charge integration values for radii for [radius/nbins, 2 * radius/nbins, ….].


Differential integrated charge as a np array of [[radius, value], …]. Format is for ease of plotting. E.g., plt.plot(data[:,0], data[:,1])

linear_add(other, scale_factor=1.0)[source]

Method to do a linear sum of volumetric objects. Used by + and - operators as well. Returns a VolumetricData object containing the linear sum.

  • other (VolumetricData) – Another VolumetricData object

  • scale_factor (float) – Factor to scale the other data by.


VolumetricData corresponding to self + scale_factor * other.

linear_slice(p1, p2, n=100)[source]

Get a linear slice of the volumetric data with n data points from point p1 to point p2, in the form of a list.

  • p1 (list) – 3-element list containing fractional coordinates of the first point.

  • p2 (list) – 3-element list containing fractional coordinates of the second point.

  • n (int) – Number of data points to collect, defaults to 100.


List of n data points (mostly interpolated) representing a linear slice of the data from point p1 to point p2.


Scale the data in place by a factor.

property spin_data[source]

data}. Essentially, this provides the actual Spin.up and Spin.down data instead of the total and diff. Note that by definition, a non-spin-polarized run would have Spin.up data == Spin.down data.


The data decomposed into actual spin data as {spin

to_cube(filename, comment=None)[source]

Write the total volumetric data to a cube file format, which consists of two comment lines, a header section defining the structure IN BOHR, and the data.

  • filename (str) – Name of the cube file to be written.

  • comment (str) – If provided, this will be added to the second comment line


Writes the VolumetricData to a HDF5 format, which is a highly optimized format for reading storing large data. The mapping of the VolumetricData to this file format is as follows: -> f[“vdata”] VolumetricData.structure ->

f[“Z”]: Sequence of atomic numbers f[“fcoords”]: Fractional coords f[“lattice”]: Lattice in the pymatgen.core.lattice.Lattice matrix


f.attrs[“structure_json”]: String of json representation


filename (str) – Filename to output to.

value_at(x, y, z)[source]

Get a data value from at a given point (x, y, z) in terms of fractional lattice parameters. Will be interpolated using a RegularGridInterpolator on if (x, y, z) is not in the original set of data points.

  • x (float) – Fraction of lattice vector a.

  • y (float) – Fraction of lattice vector b.

  • z (float) – Fraction of lattice vector c.


Value from (potentially interpolated) correspondisng to the point (x, y, z).