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, p_elecs_in_cartesian=True, p_ions_in_cartesian=False)[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).

p_elecs: np.array of electronic contribution to the polarization with shape [N, 3] p_ions: np.array of ionic contribution to the polarization with shape [N, 3] p_elecs_in_cartesian: whether p_elecs is along Cartesian directions (rather than lattice directions).

Default is True because that is the convention for VASP.

p_ions_in_cartesian: whether p_ions is along Cartesian directions (rather than lattice directions).

Default is False because calc_ionic (which we recommend using for calculating the ionic contribution to the polarization) uses lattice directions.

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

get_lattice_quanta(convert_to_muC_per_cm2=True, all_in_polar=True)[source]

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_polarization_change(convert_to_muC_per_cm2=True, all_in_polar=True)[source]

Get difference between nonpolar and polar same branch polarization.

get_polarization_change_norm(convert_to_muC_per_cm2=True, all_in_polar=True)[source]

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

get_same_branch_polarization_data(convert_to_muC_per_cm2=True, all_in_polar=True)[source]

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.

Note, using convert_to_muC_per_cm2=True and all_in_polar=True calculates the “proper polarization” (meaning the change in polarization does not depend on the choice of polarization branch) while convert_to_muC_per_cm2=True and all_in_polar=False calculates the “improper polarization” (meaning the change in polarization does depend on the choice of branch). As one might guess from the names. We recommend calculating the “proper polarization”.

convert_to_muC_per_cm2: convert polarization from electron * Angstroms to

microCoulomb per centimeter**2

all_in_polar: convert polarization to be in polar (final structure) polarization lattice

max_spline_jumps(convert_to_muC_per_cm2=True, all_in_polar=True)[source]

Get maximum difference between spline and same branch polarization data.

same_branch_splines(convert_to_muC_per_cm2=True, all_in_polar=True)[source]

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

smoothness(convert_to_muC_per_cm2=True, all_in_polar=True)[source]

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

class PolarizationLattice(lattice: Union[List, numpy.ndarray, pymatgen.core.lattice.Lattice], species: List[Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Specie, pymatgen.core.periodic_table.DummySpecie, pymatgen.core.composition.Composition]], coords: Sequence[Sequence[float]], charge: float = None, validate_proximity: bool = False, to_unit_cell: bool = False, coords_are_cartesian: bool = False, site_properties: dict = 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.

  • coords (Nx3 array) – list of fractional/cartesian coordinates of each species.

  • charge (int) – overall charge of the structure. Defaults to behavior in SiteCollection where total charge is the sum of the oxidation states.

  • validate_proximity (bool) – Whether to check if there are sites that are less than 0.01 Ang apart. Defaults to False.

  • to_unit_cell (bool) – Whether to map all sites into the unit cell, i.e., fractional coords between 0 and 1. 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


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