QMol_DFT_Vh_conv

`QMol_DFT_Vh_conv`

Hartree potential and functional, computed with an explicit-convolution scheme, for DFT models.

Description

Use QMol_DFT_Vh_conv to describe the Hartree potential and Hartree-energy functional in DFT models. To ensure the proper description of the Hartree potential and energy, QMol_DFT_Vh_conv uses an explicit convolution scheme over an extended domain, twice as large as that of the DFT's domain discretization.

The computation of the Hartree potential or energy is computationally expensive. The use of an explicit convolution scheme is virtually always slower than the fast-Fourier-transform alternative of QMol_DFT_Vh_fft but does not require any tuning of the extended domain.

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

Class properties

Hartree-potential model

The QMol_DFT_Vh_conv 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).

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.

Class methods

Creation

constructor

Create a Hartree-potential object with empty class properties.

obj = QMol_DFT_Vh_conv;

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 properties and is case insensitive.

obj = QMol_DFT_Vh_conv(name1,value1);
obj = QMol_DFT_Vh_conv(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 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 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_conv class.

Initializing the object

`initialize`

Initialize a QMol_DFT_Vh_conv 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_conv 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_conv 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_conv 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_conv 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 compute 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 Hartree 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_conv;

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                      explicit convolution
    Interaction pot. = @(x)1./sqrt(x.^2+2) (elec.-elec.)
    V-01.21.000 (06/17/2024)                                     F. Mauger

Display the estimated memory footprint for the object.

V_H.getMemoryProfile(true);

  * Hartree functional                                              7.0 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_conv');
QMol_test.test('-summary','DFT_Vh_conv');

For developers

Other hidden class properties

QMol_DFT_Vh_conv 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_conv objects, i.e., isInitialized == false , have empty DFT.
For practical reasons, DFT is editable by QMol_DFT classes.

`V`

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

This has virtually no use outside of the QMol_DFT_Vh_conv 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_conv was introduced in version 01.00.
getMemoryProfile was introduced in version 01.10.

This wiki is a copy of the documentation provided with the QMol-grid package (accessible in MATLAB documentation, via the "Supplemental Software" section).
Copyright © 2024, Francois Mauger, all right reserved.