# Polarization¶

class Polarization(configuration, kpoints_a=None, kpoints_b=None, kpoints_c=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 (MonkhorstPackGrid) – The k-point sampling to use for integrating along the first direction. Default: MonkhorstPackGrid(nx, ny, nz), where nx, ny, nz are the sampling used for the self consistent calculation. kpoints_b (MonkhorstPackGrid) – The k-point sampling to use for integrating along the second direction. Default: MonkhorstPackGrid(nx, ny, nz), where nx, ny, nz are the sampling used for the self consistent calculation. kpoints_c (MonkhorstPackGrid) – The k-point sampling to use for integrating along the third direction. Default: MonkhorstPackGrid(nx, ny, nz), where nx, ny, nz are the sampling used for the self consistent calculation.
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. 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] 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] numpy.array
metatext()
Returns: The metatext of the object or None if no metatext is present. str | unicode | 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 | unicode | 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. 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] numpy.array

## 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 and orthogonal cells should be preferred when possible. Usage in 2D systems and with non-orthogonal unitcells 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. [jKSV93]. 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. [jKSV93]. 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.

 [jKSV93] (1, 2) R. D. King-Smith and D. Vanderbilt. Theory of polarization of crystalline solids. Phys. Rev. B, 47:1651–1654, Jan 1993. doi:10.1103/PhysRevB.47.1651.