Polarization

class Polarization(configuration, kpoints_a=None, kpoints_b=None, kpoints_c=None, cartesian_directions=None)

Class for calculating the polarization of a configuration.

Parameters:
  • configuration (BulkConfiguration) – The configuration with attached calculator that supports Berry-phase polarization calculations.

  • kpoints_a (sequence (size 3) of int | MonkhorstPackGrid | KpointDensity) – The k-point sampling to use for integrating along the first direction.
    Default: The Monkhorst-Pack grid used for the self-consistent calculation.

  • kpoints_b (sequence (size 3) of int | MonkhorstPackGrid | KpointDensity) – The k-point sampling to use for integrating along the second direction.
    Default: The Monkhorst-Pack grid used for the self-consistent calculation.

  • kpoints_c (sequence (size 3) of int | MonkhorstPackGrid | KpointDensity) – The k-point sampling to use for integrating along the third direction.
    Default: The Monkhorst-Pack grid used for the self-consistent calculation.

  • cartesian_directions (list of CartesianDirection.{X,Y,Z}) – Specify whether the polarization should only be evaluated along specific Cartesian directions. Only supported for orthorhombic lattices.
    Default: [CartesianDirection.X, CartesianDirection.Y, CartesianDirection.Z]

cartesianDirections()
Returns:

The Cartesian components for which the tensor is evaluated.

Return type:

list of CartesianDirection.{X,Y,Z}

cartesianQuantum()

Returns the cartesian polarization quantum, which for direction \(i\) is \(P_i=\frac{|e|R_i}{\Omega}\), where \(|e|\) is the electronic charge, \(R_i\) is the \(i'\) th lattice vector, and \(\Omega\) is the unit cell volume.

Returns:

The cartesian polarization quantum.

Return type:

PhysicalQuantity of type charge per area

electronicFractionalPolarization()
Returns:

The electronic fractional polarization as a length 3 array corresponding to the x, y, and z direction. Note, that all values are wrapped to the interval [-0.5, 0.5]

Return type:

numpy.array

ionicFractionalPolarization()

Returns the purely ionic fractional polarization \(P_i = \sum_j Z_j^{ion}\tau_j\), where \(Z_j^{ion}\) and \(\tau_j\) are the valence charge and fractional coordinate of atom \(j\) .

Returns:

The ionic fractional polarization as a length 3 array corresponding to the x, y, and z direction. Note, that all values are wrapped to the interval [-0.5, 0.5]

Return type:

numpy.array

metatext()
Returns:

The metatext of the object or None if no metatext is present.

Return type:

str | None

nlprint(stream=None)

Print a string containing an ASCII table useful for plotting the AnalysisSpin object.

Parameters:

stream (python stream) – The stream the table should be written to.
Default: NLPrintLogger()

setMetatext(metatext)

Set a given metatext string on the object.

Parameters:

metatext (str | None) – The metatext string that should be set. A value of “None” can be given to remove the current metatext.

totalCartesianPolarization()
Returns:

The total cartesian polarization.

Return type:

PhysicalQuantity of type charge per area

totalFractionalPolarization()

Returns the sum of the electronic and ionic parts polarization.

Returns:

The total fractional polarization as a length 3 array corresponding to the x, y, and z direction. Note, that all values are wrapped to the interval [-0.5, 0.5]

Return type:

numpy.array

uniqueString()

Return a unique string representing the state of the object.

Usage Examples

Calculate the polarization of tetragonal BaTiO3 using the experimental structure and lattice constants:

# -------------------------------------------------------------
# Bulk configuration
# -------------------------------------------------------------

# Set up lattice
lattice = SimpleTetragonal(3.9945*Angstrom, 4.0335*Angstrom)

# Define elements
elements = [Barium, Titanium, Oxygen, Oxygen, Oxygen]

# Define coordinates
fractional_coordinates = [[ 0.      ,  0.      ,  0.      ],
                          [ 0.5     ,  0.5     ,  0.51427 ],
                          [ 0.5     ,  0.5     ,  0.974477],
                          [ 0.5     ,  0.      ,  0.487618],
                          [ 0.      ,  0.5     ,  0.487618]]

# Set up configuration
bulk_configuration = BulkConfiguration(
    bravais_lattice=lattice,
    elements=elements,
    fractional_coordinates=fractional_coordinates
    )

# -------------------------------------------------------------
# Calculator
# -------------------------------------------------------------
#----------------------------------------
# Basis Set
#----------------------------------------
basis_set = [
    GGABasis.Oxygen_DoubleZetaPolarized,
    GGABasis.Titanium_DoubleZetaPolarized,
    GGABasis.Barium_DoubleZetaPolarized,
    ]

#----------------------------------------
# Exchange-Correlation
#----------------------------------------
exchange_correlation = GGA.PBE

numerical_accuracy_parameters = NumericalAccuracyParameters(
    k_point_sampling=(5, 5, 5),
    )

calculator = LCAOCalculator(
    basis_set=basis_set,
    exchange_correlation=exchange_correlation,
    numerical_accuracy_parameters=numerical_accuracy_parameters,
    )

bulk_configuration.setCalculator(calculator)
nlprint(bulk_configuration)
bulk_configuration.update()

# -------------------------------------------------------------
# Polarization
# -------------------------------------------------------------
polarization = Polarization(
    configuration=bulk_configuration,
    kpoints_a=MonkhorstPackGrid(11,5,5),
    kpoints_b=MonkhorstPackGrid(5,11,5),
    kpoints_c=MonkhorstPackGrid(5,5,11),
    )

nlprint(polarization)

polarization.py

The output from the calculation is:

+------------------------------------------------------------------------------+
| Polarization                                                                 |
+------------------------------------------------------------------------------+
| Electronic fractional polarization.                                          |
| Values wrapped to the interval [-0.5,0.5]                                    |
|       [ -9.11083600e-12 ]                                                    |
|  Pe=  [  2.57089606e-11 ]                                                    |
|       [ -4.64533955e-01 ]                                                    |
+------------------------------------------------------------------------------+
| Ionic fractional polarization.                                               |
| Values wrapped to the interval [-0.5,0.5]                                    |
|       [  0.00000000e+00 ]                                                    |
|  Pi=  [  0.00000000e+00 ]                                                    |
|       [ -2.44642000e-01 ]                                                    |
+------------------------------------------------------------------------------+
| Total fractional polarization. Pt = Pe + Pi.                                 |
| Values wrapped to the interval [-0.5,0.5]                                    |
|       [ -9.11083600e-12 ]                                                    |
|  Pt=  [  2.57089606e-11 ]                                                    |
|       [  2.90824045e-01 ]                                                    |
+------------------------------------------------------------------------------+
| Total cartesian polarization.                                                |
|       [ -9.05991488e-12 ]                                                    |
|  Pt=  [  2.55652714e-11 ] C/Meter**2                                         |
|       [  2.92022177e-01 ]                                                    |
+------------------------------------------------------------------------------+
| Polarization quantum.                                                        |
|       [  9.94410928e-01 ]                                                    |
|  Pq=  [  9.94410928e-01 ] C/Meter**2                                         |
|       [  1.00411978e+00 ]                                                    |
+------------------------------------------------------------------------------+

Notes

  • Note that the implementation does not work for metallic systems. Usage in 2D systems should be done with thorough testing of the used settings and results.

  • The output contains five calculated quantities. First, the electronic fractional polarization, Pe, is calculated from the Berry phase obtained from the occupied bands, as described in Ref. [1]. The three values correspond to the x,y, and z direction.

  • The second quantity, Pi, is the purely ionic fractional polarization \(P_i = \sum_j Z_j^{ion}\tau_j\), where \(Z_j^{ion}\) and \(\tau_j\) are the valence charge and fractional coordinate of atom \(j\) .

  • The third quantity, Pt, is the total fractional polarization which is the sum of the electronic and ionic parts. Note, that all fractional polarizations are wrapped to the interval [-0.5,0.5] which explains the sign change of the polarization in the z- direction. The sum Pe(z) + Pi(z) = -0.709 is outside the range [-0.5,0.5] and is thus wrapped to the interval [-0.5,0.5] by adding a fractional quantization quantum (equal to 1), i.e. Pt(z) = -0.709 + 1 = 0.291.

  • It is an important finding of the so-called modern theory of polarization, that the polarization is a multivalued quantity or a lattice, c.f. Ref. [1]. This is why the values are wrapped to the interval [-0.5,0.5].

  • The fourth quantity is the total cartesian polarization given in units of \(C/m^2\).

  • The fifth quantity is the cartesian polarization quantum, which for direction \(i\) is \(P_i=\frac{|e|R_i}{\Omega}\), where \(|e|\) is the electronic charge, \(R_i\) is the \(i'\) th lattice vector, and \(\Omega\) is the unit cell volume.