HartreePotential

class HartreePotential(configuration)

A class for calculating the Hartree potential for a configuration.

Parameters:configuration (BulkConfiguration | MoleculeConfiguration) – The configuration for which the Hartree potential should be calculated.
axisProjection(projection_type='sum', axis='c', spin=None, projection_point=None, coordinate_type=<class 'NL.ComputerScienceUtilities.NLFlag._NLFlag.Fractional'>)

Get the values projected on one of the Cartesian axes.

Parameters:
  • projection_type (str) –
    The type of projection to perform. Should be either
    • ‘sum’ for the sum over the plane spanned by the two other axes.
    • ‘average’ or ‘avg’ for the average value over the plane spanned by the two other axes.
    • ‘line’ for the value along a line parallel to the axis and through a point specified by the projection_point parameter.


    Default: ‘sum’

  • axis (str) – The axis to project the data onto. Should be either ‘a’, ‘b’ or ‘c’.
    Default: ‘c’
  • spin (Spin.Sum | Spin.Z | Spin.X | Spin.Y | Spin.Up | Spin.Down | Spin.RealUpDown | Spin.ImagUpDown) – Which spin component to project on.
    Default: Spin.All
  • projection_point (sequence, PhysicalQuantity) – Axis coordinates of the point through which to take a line if projection_type is ‘projection_point’. Must be given as a sequence of three coordinates [a, b, c]. It the numbers have units of length, they are first divided by the length of the respective primitive vectors [A, B, C], and then interpreted as fractional coordinates. Unitless coordinates are immidiately interpreted as fractional.
  • coordinate_type (Fractional | Cartesian) – Flag to toggle if the returned axis values should be given in units of Angstrom (NLFlag.Cartesian) or in units of the norm of the axis primitive vector (NLFlag.Fractional).
    Default: Fractional
Returns:

A 2-tuple of 1D numpy.arrays containing the axis values and the projected data.

Return type:

tuple.

derivatives(x, y, z, spin=None)

Calculate the derivative in the point (x, y, z).

Parameters:
  • x (PhysicalQuantity with type length) – The Cartesian x coordinate.
  • y (PhysicalQuantity with type length) – The Cartesian y coordinate.
  • z (PhysicalQuantity with type length) – The Cartesian z coordinate.
  • spin (Spin.All | Spin.Sum | Spin.Up | Spin.Down | Spin.X | Spin.Y | Spin.Z) – The spin component to project on.
    Default: Spin.All
Returns:

The gradient at the specified point for the given spin. For Spin.All, a tuple with (Spin.Sum, Spin.X, Spin.Y, Spin.Z) components is returned.

Return type:

PhysicalQuantity of type energy × length-1

evaluate(x, y, z, spin=None)

Evaluate in the point (x, y, z).

Parameters:
  • x (PhysicalQuantity with type length) – The Cartesian x coordinate.
  • y (PhysicalQuantity with type length) – The Cartesian y coordinate.
  • z (PhysicalQuantity with type length) – The Cartesian z coordinate.
  • spin (Spin.All | Spin.Sum | Spin.Up | Spin.Down | Spin.X | Spin.Y | Spin.Z) – The spin component to project on.
    Default: Spin.All
Returns:

The value at the specified point for the given spin. For Spin.All, a tuple with (Spin.Sum, Spin.X, Spin.Y, Spin.Z) components is returned.

Return type:

PhysicalQuantity of type energy

gridCoordinate(i, j, k)

Return the coordinate for a given grid index.

Parameters:
  • i (int) – The grid index in the A direction.
  • j (int) – The grid index in the B direction.
  • k (int) – The grid index in the C direction.
Returns:

The Cartesian coordinate of the given grid index.

Return type:

PhysicalQuantity of type length.

metatext()
Returns:The metatext of the object or None if no metatext is present.
Return type: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()
primitiveVectors()
Returns:The primitive vectors of the grid.
Return type:PhysicalQuantity of type length.
scale(scale)

Scale the field with a float.

Parameters:scale (float) – The parameter to scale with.
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.
shape()
Returns:The number of grid points in each direction.
Return type:tuple of three int.
spin()
Returns:The spin the Hartree potential is calculated for, always Spin.All.
Return type:Spin.All
spinProjection(spin=None)

Construct a new GridValues object with the values of this object projected on a given spin component.

Parameters:spin (Spin.All | Spin.Sum | Spin.X | Spin.Y | Spin.Z) – The spin component to project on.
Default: Spin.All
Returns:A new GridValues object for the specified spin.
Return type:GridValues
toArray()
Returns:The values of the grid as a numpy array slicing off any units.
Return type:numpy.array
unit()
Returns:The unit of the data in the grid.
Return type:A physical unit.
unitCell()
Returns:The unit cell of the grid.
Return type:PhysicalQuantity of type length.
volumeElement()
Returns:The volume element of the grid represented by three vectors.
Return type:PhysicalQuantity of type length.

Usage Examples

Calculate the Hartree potential and save it to a file:

# Set up a configuration.
molecule_configuration = MoleculeConfiguration(
    elements=[Nitrogen, Hydrogen, Hydrogen, Hydrogen],
    cartesian_coordinates=[[ 0.     ,  0.      ,  0.124001],
                           [ 0.     ,  0.941173, -0.289336],
                           [ 0.81508, -0.470587, -0.289336],
                           [-0.81508, -0.470587, -0.289336]]*Angstrom
    )

# Define a calculator.
calculator = LCAOCalculator()
molecule_configuration.setCalculator(calculator)

# Calculate and save the Hartree potential.
potential = HartreePotential(molecule_configuration)
nlsave('hartree_pot.nc', potential)

nh3_hartree_potential.py

Read in the Hartree potential from a file and calculate the average along the \(z\)-axis:

# Import a HartreePotential object.
potential = nlread('hartree_pot.hdf5', HartreePotential)[0]

# Calculate the average along z axis.
v_z = numpy.apply_over_axes(numpy.mean, potential[:,:,:], [0,1]).flatten()

# Add unit.
v_z = v_z * potential.unit()

# Get the volume element of the grid.
dX, dY, dZ = potential.volumeElement()
dz = dZ.norm()

# Print out the result.
shape = potential.shape()
for i in range(shape[2]):
    print(dz*i, v_z[i])

nh3_hartree_potential_average.py

For more examples on working with 3D grids, see ElectronDensity.

Notes

The Hartree potential and the electrostatic potential

  • The Hartree potential \(V_H ({\bf r})\) is calculated from the Poisson equation as

    \[\nabla^2 V_H [n] ({\bf r}) = -\frac{e^2}{4 \pi \epsilon_0} n({\bf r}),\]

    where \(n ({\bf r})\) is the valence electron density, \(e\) is the unit charge, and \(\epsilon_0\) is the vacuum permittivity. More details on solving this equation are given in The Hartree Potential.

  • In a similar fashion, the Hartree difference potential is calculated from the electron difference density as

    \[\nabla^2 \delta V_H [\delta n] ({\bf r}) = -\frac{e^2}{4 \pi \epsilon_0} \delta n({\bf r}),\]

    with the electron difference density \(\delta n ({\bf r})\) being defined through the relation

    \[n ({\bf r}) = \delta n ({\bf r}) + \sum_{I}^{N_{\mathrm{atoms}}} n_I ({\bf r}),\]

    where \(n_I({\bf r})\) is the compensation charge of atom \(I\) and \(N_{\mathrm{atoms}}\) is the number of atoms in the system.:cite:Soler2002

Note that the electron density and electron difference density are calculated differently for ATK-DFT calculators (see Electron density) and ATK-SE calculators (see Electron density).

  • The electrostatic potential is given by

    \[V_{\bf E} ({\bf r}) = -\frac{V_H ({\bf r})}{e},\]

    and the electrostatic difference potential by

    \[\delta V_{\bf E} ({\bf r})= -\frac{\delta V_H ({\bf r})}{e}.\]

Note that the Hartree potential and Hartree difference potential have units of energy (default: Hartree), while the electrostatic potential and electrostatic difference potential have units of electric potential (default: Volt). Furthermore, they are of opposite sign since \(V_H ({\bf r})\) is the potential energy that an electron (i.e., a negative unit charge) has in an electrostatic potential \(V_{\bf E} ({\bf r})\).

The quantities defined above can be calculated with the following classes: