pymatgen.analysis.ferroelectricity.polarization module

class EnergyTrend(energies)[source]

Bases: object


Test if spline endpoints are at minima for a given slope cutoff.


Get maximum difference between spline and energy trend.


Get rms average difference between spline and energy trend.


Fit spline to energy trend data.

class Polarization(p_elecs, p_ions, structures)[source]

Bases: object

Class for recovering the same branch polarization for a set of polarization calculations along the nonpolar - polar distortion path of a ferroelectric.

p_elecs, p_ions, and structures lists should be given in order of nonpolar to polar! For example, the structures returned from:


if nonpolar is the nonpolar Structure and polar is the polar structure.

It is assumed that the electronic and ionic dipole moment values are given in electron Angstroms along the three lattice directions (a,b,c).

classmethod from_outcars_and_structures(outcars, structures, calc_ionic_from_zval=False)[source]

Create Polarization object from list of Outcars and Structures in order of nonpolar to polar.

Note, we recommend calculating the ionic dipole moment using calc_ionic than using the values in Outcar (see module comments). To do this set calc_ionic_from_zval = True


Returns the dipole / polarization quanta along a, b, and c for all structures.


Get the electronic and ionic dipole moments / polarizations.

convert_to_muC_per_cm2: Convert from electron * Angstroms to microCoulomb
per centimeter**2

Get difference between nonpolar and polar same branch polarization.


Get magnitude of difference between nonpolar and polar same branch polarization.


Get same branch dipole moment (convert_to_muC_per_cm2=False) or polarization for given polarization data (convert_to_muC_per_cm2=True).

Polarization is a lattice vector, meaning it is only defined modulo the quantum of polarization:

P = P_0 + sum_i frac{n_i e R_i}{Omega}

where n_i is an integer, e is the charge of the electron in microCoulombs, R_i is a lattice vector, and Omega is the unit cell volume in cm**3 (giving polarization units of microCoulomb per centimeter**2).

The quantum of the dipole moment in electron Angstroms (as given by VASP) is:

sum_i n_i e R_i

where e, the electron charge, is 1 and R_i is a lattice vector, and n_i is an integer.

Given N polarization calculations in order from nonpolar to polar, this algorithm minimizes the distance between adjacent polarization images. To do this, it constructs a polarization lattice for each polarization calculation using the pymatgen.core.structure class and calls the get_nearest_site method to find the image of a given polarization lattice vector that is closest to the previous polarization lattice vector image.

convert_to_muC_per_cm2: convert polarization from electron * Angstroms to
microCoulomb per centimeter**2

Get maximum difference between spline and same branch polarization data.


Fit splines to same branch polarization. This is used to assess any jumps in the same branch polarizaiton.


Get rms average difference between spline and same branch polarization data.

class PolarizationLattice(lattice, species, coords, charge=None, validate_proximity=False, to_unit_cell=False, coords_are_cartesian=False, site_properties=None)[source]

Bases: pymatgen.core.structure.Structure

Create a periodic structure.

  • lattice – The lattice, either as a pymatgen.core.lattice.Lattice or simply as any 2D array. Each row should correspond to a lattice vector. E.g., [[10,0,0], [20,10,0], [0,0,30]] specifies a lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].
  • species

    List of species on each site. Can take in flexible input, including:

    1. A sequence of element / specie specified either as string symbols, e.g. [“Li”, “Fe2+”, “P”, …] or atomic numbers, e.g., (3, 56, …) or actual Element or Specie objects.
    2. List of dict of elements/species and occupancies, e.g., [{“Fe” : 0.5, “Mn”:0.5}, …]. This allows the setup of disordered structures.
  • fractional_coords – list of fractional coordinates of each species.
  • validate_proximity (bool) – Whether to check if there are sites that are less than 0.01 Ang apart. Defaults to False.
  • coords_are_cartesian (bool) – Set to True if you are providing coordinates in cartesian coordinates. Defaults to False.
  • site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g., {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.
get_nearest_site(coords, site, r=None)[source]

Given coords and a site, find closet site to coords. :param coords: cartesian coords of center of sphere :type coords: 3x1 array :param site: site to find closest to coords :param r: radius of sphere. Defaults to diagonal of unit cell

Returns:Closest site and distance.
calc_ionic(site, structure, zval)[source]

Calculate the ionic dipole moment using ZVAL from pseudopotential

site: PeriodicSite structure: Structure zval: Charge value for ion (ZVAL for VASP pseudopotential)

Returns polarization in electron Angstroms.

get_total_ionic_dipole(structure, zval_dict)[source]

Get the total ionic dipole moment for a structure.

structure: pymatgen Structure zval_dict: specie, zval dictionary pairs center (np.array with shape [3,1]) : dipole center used by VASP tiny (float) : tolerance for determining boundary of calculation.


Creates zval_dictionary for calculating the ionic polarization from Potcar object

potcar: Potcar object