QMol_DFT_Vh_fft

Hartree potential and functional, computed with a fast-Fourier-transform convolution scheme, for DFT models.

Description

Use QMol_DFT_Vh_fft to describe the Hartree potential and Hartree-energy functional in DFT models. QMol_DFT_Vh_fft performs the convolutions required for the computation of the Hartree potential and functional using fast-Fourier-transform over an extended domain. To ensure the proper description of the Hartree potential and energy, the extended domain must be properly calibrated. The fast-Fourier-transform convolution scheme should virtually always be faster than the explicit convolution of QMol_DFT_Vh_conv but does require proper tuning of the extended domain.

QMol_DFT_Vh_fft supports average-density self-interaction correction (ADSIC) [Legrand 2002].

Class properties

Hartree-potential model

The QMol_DFT_Vh_fft class defines the following public get-access properties; each can be changed using the set method:

interactionPotential (Vee)

Electron-electron interaction potential [ function handle (default @(x) 1./sqrt(x.^2+2) ) ]

• The signature for the (effective) electron-electron interaction potential should be V = funV(x), where the output V has the same shape as the input vector x and contains element-wise values of the potential at the query points x.
• Because the computation of the Hartree potential and energy is performed over an (internally handled) extended domain, a user-defined discretization of the electron-electron interaction potential is not supported (only function handle).

Extended domain

The extended domain configuration is sketched in the following figure: the electron-electron interaction potential is extended over a "ghost" domain, on both sides of the DFT domain at the ends of which it is smoothly dampened to zero. Class properties associated with the extended domain are defined with get-access attributes and can be changed using the set method:

ghostUnit (gU)

Units in which the length of the ghost domain is specified [ 'a.u.' | 'points' (default) ]

ghostLength (gL)

Length of the ghost domain [ positive integer | positive scalar | 0 (default) ]

• Note this is the total length of the ghost domain, which half of it distributed on each side of the DFT domain.

falloffUnit (fU)

Units in which the length of the fall-off domain is specified [ 'a.u.' | 'points' (default) ]

falloffShape (fS)

Shape of the fall off [ 'cos2' (default) | 'cos4' | 'gaussian' ]

• Over the fall-off domain, the interactionPotential is multiplied by the specified shape to smoothly reach zero at the edges.
• falloffShape = 'gaussian' is provided for completeness but is discouraged (as it never truly reaches zero).

falloffLength (fL)

Length of the fall-off domain [ positive integer | positive scalar | 0 (default) ]

addFalloffLength (aFL)

Whether to add the length taken by the fall-off to the ghost domain [ true (default) | false ]

• addFalloffLength = true adds twice falloffLength to ghostLength when building the extended domain.
• addFalloffLength = false specifies that the falloffLength (on both sides of the extended domain) have beed accounted for in ghostLength.

Other properties

These properties cannot be edited with the set method.

isInitialized (isInit)

Whether the potential object is properly initialized. This is used throughout the QMol-grid package to check that the potential object holds meaningful information and is ready for use.

Calibrating the extended domain

Since the Hartree potential is calculated via fast Fourier transforms, extended domains with small prime factor number of grid points tend to produce faster results -- for best performance, prime factors not greater than 7.

Depending on the calculations, one may use various calibration for the extended domain. Here we briefly describe three of them.

Accurate Hartree potential over the entire domain for all densities

To ensure a proper description of the Hartree potential and functional over the entire DFT domain, simply set the ghost domain to (at least) the size of the DFT domain (ghostLength = DFT.disc.xspan ) and add the total length occupied by the fall-off domains (addFalloffLength = true ).

Accurate Hartree potential over the entire domain for a specific density

For a given one-body density, one can achieve the proper description of Hartree potential and functional over the entire DFT domain by fitting the extended domain as illustrated in the figure above. As is apparent on the figure, densities that are centered over the DFT domain lead to the smallest extended domain.

Accurate Hartree potential only over the support of the density

If one only cares about the Hartree potential and functional over the support of the one-body density, the extended domain can be tightly fitted as illustrated in the figure above. Here as well, it is best to center the density over the DFT domain.

Class methods

Creation

constructor

Create a Hartree-potential object with empty class properties.

obj = QMol_DFT_Vh_fft;

Create a Hartree-potential object with the name properties set to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the Hartree-potential model or extended-domain properties and is case insensitive.

obj = QMol_DFT_Vh_fft(name1,value1);
obj = QMol_DFT_Vh_fft(name1,value1,name2,value2,___);

Changing class properties

set

Update the name properties of a Hartree-potential object to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the Hartree-potential model or extended-domain properties and is case insensitive.

obj.set(name1,value1);
obj.set(name1,value1,name2,value2,___);

This is the common name-value pair assignment method used throughout the QMol-grid package. The set method also reset the class. After running, the set property updates the isInitialized flag to a false value.

reset

Reset the object by deleting/re-initializing all run-time properties of the class and updating the isInitialized flag to false.

obj.reset;

• This is the common reset method available to all classes throughout the QMol-grid package.

clear

Clear all class properties

obj.clear;

Clear a specific set of the class properties. Suitable name is any of the Hartree-potential model or extended-domain properties and is case insensitive.

obj.clear(name1,name2,___);

This is the common clear method available to all classes throughout the QMol-grid package. The clear method also reset the class. The clear method can be used to delete specific properties before saving an instance of the QMol_DFT_Vh_fft class.

Initializing the object

initialize

Initialize a QMol_DFT_Vh_fft object and set the isInitialized flag to true.

obj.initialize(DFT);

• DFT is the DFT-model handle object, i.e., QMol_DFT_spinPol or QMol_DFT_spinRes, to which the Hartree potential is attached.
• To avoid any mismatch in internal properties, initialize first reset the object before performing the initialization.

Initialize a QMol_DFT_Vh_fft object for a specific flavor of self-interaction correction (SIC) and set the isInitialized flag to true.

obj.initialize(DFT,SIC);

• Omitted, [] or 'none' input SIC disable SIC.
• 'ADSIC' input SIC uses ADSIC [Legrand 2002].

Run-time documentation

getMemoryProfile

Get an estimate of the memory held by a QMol_DFT_Vh_fft object with either

mem = obj.getMemoryProfile;
mem = obj.getMemoryProfile(false);

• The object must be properly initialized with a domain discretization.
• The estimate only includes the discretization of member components on the domain grid and ignores other (small) properties.
• The output mem is the estimated size in bytes.

Additionally display the detail of the memory footprint with

mem = obj.getMemoryProfile(true);

showDocumentation

Display the run-time documentation for the specific configuration of a QMol_DFT_Vh_fft object.

ref = obj.showDocumentation;

• The output ref is a cell vector containing the list of references to be included in the bibliography.

Hartree potential

Before using any of its Hartree-functional methods, the QMol_DFT_Vh_fft object must be properly initialized.

getEnergy

Get the Hartree-functional energy for the parent DFT object.

E = obj.getEnergy;

• This computes the Hartree energy associated with the Kohn-Sham orbitals in the parent DFT model. To do so, it first computes the one-body density associated with the Kohn-Sham orbitals and their occupation parameters.
• The output scalar E contains the numerical evaluation of the Hartree energy $E=\frac{1}{2}\int \int \rho (x){\mathcal{V}}_{{\mathrm{e}\mathrm{e}}} (x-x^{\prime } )\rho (x^{\prime } )~dxdx^{\prime }$ , where ${\mathcal{V}}_{{\mathrm{e}\mathrm{e}}}$ is the electron-electron interaction potential and the one-body density $\rho$ is computed from the parent DFT-model's Kohn-Sham orbitals.
• When ADSIC is enabled, the Hartree energy is scaled by $(N-1)/N$ , where $N$ is the total number of electrons. By definition $N=\int \rho (x)~dx$ but, for efficacy purposes, its value is retrieved from the parent DFT model's orbital occupation coefficients.
• This is equivalent to, but more efficient than, obj.getEnergy(DFT.getDensity) with DFT being the same DFT-model handle object used to initialize the external-potential object.

Get the Hartree-functional energy for a specific one-body density.

E = obj.getEnergy(rho);

• Same as above but with using the input one-body-density object rho in the numerical computation of the energy.
• rho should be a QMol_DFT_density object defined over the same domain discretization as the parent DFT model.

getPotential

Get the Hartree potential for the parent DFT object with either

V = obj.getPotential;
V = obj.getPotential([]);

• This computes the Hartree potential associated with the Kohn-Sham orbitals in the parent DFT model. To do so, it first compute the one-body density $\rho$ associated with the Kohn-Sham orbitals and their occupation parameters.
• The output Kohn-Sham potential object contains the numerical evaluation of the Hartree potential ${\mathcal{V}}_{{\mathrm{H}}} (x)=\int {\mathcal{V}}_{{\mathrm{e}\mathrm{e}}} (x-x^{\prime } )\rho (x^{\prime } )~dx^{\prime }$.
• This creates a new Kohn-Sham potential object V in which the Hartree potential is stored.
• For spin-restricted models, access the discretization of the Hartree potential with V.potential.
• For spin-restricted models, access the discretization of the Hartree potential with either V.potentialUp or V.potentialDown.
• Note that getPotential does not initialize the output potential object V.

Get the Hartree potential for a specific one-body density.

V = obj.getPotential(rho);

• Same as above but with using the input one-body-density object rho in the numerical computation of the potential.
• rho should be a QMol_DFT_density object defined over the same domain discretization as the parent DFT model.

Overwrite the Hartree potential in an existing Kohn-Sham potential object with any of

obj.getPotential([],V);         % use parent DFT density
obj.getPotential([],V,false);
obj.getPotential(rho,V);        % supply the density
obj.getPotential(rho,V,false);

• This is similar to above without creating a new Kohn-Sham potential object.
• Any content in the input object V is erased before assigning the external potential to it.

Add the external potential to an existing Kohn-Sham potential object

obj.getPotential([],V,true);    % use parent DFT density
obj.getPotential(rho,V,true);   % supply the density

• This is formally equivalent to the in-place addition $\mathcal{V}\gets \mathcal{V}+{\mathcal{V}}_{{\mathrm{H}}}$ .

getPotentialDerivative

Get the Hartree potential gradient for the parent DFT object with either

DV = obj.getPotentialDerivative(1);
DV = obj.getPotentialDerivative(1,[]);

• This computes the Hartree potential gradient associated with the Kohn-Sham orbitals in the parent DFT model. To do so, it first compute the one-body density $\rho$ associated with the Kohn-Sham orbitals and their occupation parameters.
• The output Kohn-Sham potential gradient object contains the numerical evaluation of the Hartree potential gradient $\nabla {\mathcal{V}}_{{\mathrm{H}}} (x)=\int {\mathcal{V}}_{{\mathrm{e}\mathrm{e}}} (x-x^{\prime } )\nabla \rho (x^{\prime } )~dx^{\prime }$.
• This creates a new Kohn-Sham potential gradient object DV in which the Hartree potential gradient is stored.
• For spin-restricted models, access the discretization of the Hartree potential gradient with DV.potentialGradient.
• For spin-restricted models, access the discretization of the Hartree potential gradient with either DV.potentialGradientUp or DV.potentialGradientDown.
• Note that getPotential does not initialize the output potential gradient object DV.
• Note that the first input 1 is required. This is to provide a uniform signature with higher dimension where the dimension along which the gradient component is applied must be specified.

Get the Hartree potential for a specific one-body density.

V = obj.getPotentialDerivative(1,rho);

• Same as above but with using the input one-body-density object rho in the numerical computation of the potential gradient.
• rho should be a QMol_DFT_density object defined over the same domain discretization as the parent DFT model.

Overwrite the Hartree potential gradient in an existing Kohn-Sham potential gradient object with any of

obj.getPotentialDerivative(1,[],DV);        % use parent DFT density
obj.getPotentialDerivative(1,[],DV,false);
obj.getPotentialDerivative(1,rho,DV);       % supply the density
obj.getPotentialDerivative(1,rho,DV,false);

• This is similar to above without creating a new Kohn-Sham potential gradient object.
• Any content in the input object DV is erased before assigning the Hartree potential gradient to it.

Add the Hratree potential gradient to an existing Kohn-Sham potential gradient object with either

obj.getPotentialDerivative(1,[],DV,true);   % use parent DFT density
obj.getPotentialDerivative(1,rho,DV,true);  % supply the density

• This is formally equivalent to the in-place addition $\nabla \mathcal{V}\gets \nabla \mathcal{V}+\nabla {\mathcal{V}}_{{\mathrm{H}}}$ .

Examples

Create a discretization domain.

disc = QMol_disc('xspan',-20:.1:25);

Create a Hartree potential object with default parameters.

V_H = QMol_DFT_Vh_fft(...
        'ghostLength',      numel(disc.xspan),  ...
        'ghostUnit',        'points',           ...
        'addFalloffLength', true,               ...
        'falloffLength',    20,                 ...
        'falloffUnit',      'points',           ...
        'falloffShape',     'cos^2');

Create a minimal DFT-model object required to initialize the Hartree potential class and display the run-time documentation.

DFT = QMol_DFT_spinRes('discretization',disc);
disc.initialize(DFT);
V_H.initialize(DFT);
V_H.showDocumentation;

yielding

  * Hartree-potential functional        fast-Fourier-transform convolution
    Interaction pot. = @(x)1./sqrt(x.^2+2) (elec.-elec.)
    Ghost domain     = 451 (points), plus
    Falloff          = 20 (points), cos^2 shape
    Ext. domain size = 942 (2 x 3 x 157) points
    V-01.21.000 (06/17/2024)                                     F. Mauger

Display the estimated memory footprint for the object.

V_H.getMemoryProfile(true);

  * Hartree functional                                             14.7 KB

Since we do not define a full DFT system, we need to generate the one-body density.

% Create one-body density
rho = DFT.discretization.DFT_allocateDensity;
rho.set('density',3*exp(-(disc.x(:)+5).^2/4)+2*exp(-(disc.x(:)-5).^2/6));
rho.initialize(disc);

Plot the Hartree potential and its gradient.

% Get potential and gradient
V  = V_H.getPotential(rho);
DV = V_H.getPotentialDerivative(1,rho);

% Plot the results
figure; hold on
plot(disc.xspan,V.potential,'-','LineWidth',2,'DisplayName','V_{H}')
plot(disc.xspan,DV.potentialGradient,'-','LineWidth',2','DisplayName','{\nabla}V_{H}')
xlabel('position (a.u.)'); xlim(disc.xspan([1 end]));
ylabel('potential/gradient')
legend show

Test suite

Run the test suite for the class in normal or summary mode respectively with

QMol_test.test('DFT_Vh_fft');
QMol_test.test('-summary','DFT_Vh_fft');

For developers

Other hidden class properties

QMol_DFT_Vh_fft defines a handful of additional transient and hidden properties to facilitate and speed up computations. These properties cannot be edited with the set method, nor by any function outisde of the object (SetAccess=private attribute).

DFT

DFT-model object [ [] (default) | QMol_DFT_spinPol handle object | QMol_DFT_spinRes handle object ]

• This is a copy of the DFT-model handle object passed to initialize.
• Un-initialized QMol_DFT_Vh_fft objects, i.e., isInitialized == false , have empty DFT.
• For practical reasons, DFT is editable by QMol_DFT classes.

V

Fourier transform of the discretization of the electron-electron interaction potential over the extended domain [ [] (default) | vector ]

• This has virtually no use outside of the QMol_DFT_Vh_fft class.

SIC

Flavor of self-interaction correction (SIC) [ [] (default) | 0 | 1 ]

• SIC == 0 corresponds to no SIC.
• SIC == 1 corresponds to ADSIC [Legrand 2002].

References

[Legrand 2002] C. Legrand, E. Suraud, and P.-G. Reinhard, "Comparison of self-interaction-corrections for metal clusters," Journal of Physics B: Atomic, Molecular and Optical Physics 35, 1115 (2002).

Notes

The results displayed in this documentation page were generated using version 01.21 of the QMol-grid package.

• QMol_DFT_Vh_fft was introduced in version 01.00.
• getMemoryProfile was introduced in version 01.10.