QMol_DFT

QMol_DFT

Parent class for density-functional theory (DFT) model objects.

Description

QMol_DFT defines an abstract class for the description of DFT models. It is designed to be agnostic of (i) the model dimension, (ii) the chosen discretization (Cartesian grid or basis), and (ii) spin polarized or restricted configuration. These are to be handled by the specific DFT-implementation classes and their components.

Class properties

DFT model

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

discretization (disc)

Domain discretization object [ handle object (default []) ]

occupation (occ)

Kohn-Sham orbital population parameters [ vector | cell | (default []) ]

• For spin-restricted DFT models, occupation = [n1,n2,___] with each of the $0\le n\le 2$ specifies the number of electrons associated with each of the Kohn-Sham orbitals.
• For spin-polarized DFT models, occupation = {[n_up1,n_up2,___],[n_down1,n_down2,___]} with each of the $0\le n\le 1$ specifies the number of electrons associated with the up- and down-spin Kohn-Sham orbitals.

orbital (KSO)

Kohn-Sham orbital object [ handle object (default []) ]

externalPotential (Vext)

External functional object [handle object (default []) ]

HartreePotential (Vh)

Hartree functional object [handle object (default []) ]

exchangeCorrelationPotential (Vxc)

Exchange-correlation functional object(s) [ [] (default) | handle object | cell ]

• Empty exchangeCorrelationPotential ignores exchange-correlation effects altogether in the DFT model.
• Provide multiple exchange-correlation functionals -- e.g., one exchange functional plus a separate correlation one -- grouped in a cell {Vxc1,Vxc2,___}
• If the DFT model includes a single exchange-correlation functional, it can be directly provided exchangeCorrelationPotential = Vxc or included in a cell exchangeCorrelationPotential = {Vxc}.

selfInteractionCorrection (SIC)

Flavor of self-interaction correction (SIC) [ 'none' (default) | 'ADSIC' | cell ]

• If a single SIC flag is provided, the same flavor of SIC corresponding to the flag, is applied to the Hartree and exchange-correlation functionals.
• selfInteractionCorrection = {SIC_H,SIC_XC} independently specifies the flavor of SIC to use for the Hartree and exchange-correlation functionals, respectively.
• If the DFT model uses several exchange-correlation functional, selfInteractionCorrection = {SIC_H,SIC_XC_1,SIC_XC_1,___} independently specifies the flavor of SIC for each of the exchange-correlation functionals, respectively.

Other properties

To facilitate simulations, the QMol_DFT defines a handful of additional transient properties. These cannot be edited with the set method.

isInitialized (isInit)

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

totalCharge (Ntot)

Total number of electrons in the DFT model [ scalar | vector (default []) ]

• For spin restricted DFT models, this is defined as sum(obj.occupation)
• For spin restricted DFT models, this is defined as [sum(obj.occupation{1}),sum(obj.occupation{2})]
• totalCharge is set by initialize; It is empty when the isInitialized flag is false

rho

One-body density placeholder [ density handle object (default []) ]

• Some methods require local computation of the one-body density before performing their own computation. In such cases, they should use this local density placeholder and avoid the allocation of another density object.
• rho is up for grab by any class in the QMol-grid package (Access=?QMol_suite). One should not assume that it retains meaningful values outside of a given method where it is used.

Vks

Kohn-Sham potential placeholder [ density handle object (default []) ]

• Like for the density, use this placeholder when a local computation of the Kohn-Sham potential is required in some computation.
• Vks is up for grab by any class in the QMol-grid package (Access=?QMol_suite). One should not assume that it retains meaningful values outside of a given method where it is used.

DVks

Kohn-Sham potential gradient placeholder [ density handle object (default []) ]

• Like for the density, use this placeholder when a local computation of the Kohn-Sham potential gradient is required in some computation.
• DVks is up for grab by any class in the QMol-grid package (Access=?QMol_suite). One should not assume that it retains meaningful values outside of a given method where it is used.

Constant properties

isSpinPol

• Flags spin polarized (isSpinPol = true) from restricted (isSpinPol = false) models.

dim

• Specifies the dimension of the DFT model

Class methods

Creation

constructor

Create a DFT-model object with empty class properties.

obj = QMol_DFT;

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

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

Changing class properties

set

Update the name properties of a DFT-model object to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the DFT-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.
• To avoid any mismatch in the DFT component internal properties, this also resets the discretization (domain discretization), orbital (Kohn-Sham orbitals), externalPotential (external functional and potential), HartreePotential (Hartree functional and potential), and exchangeCorrelationPotential (exchange-correlation functional and potential) components objects.

clear

Clear all class properties

obj.clear;

Clear a specific set of the class properties. Suitable name is any of the DFT-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 class.

Initializing the object

initialize

Initialize a DFT-model object in silent mode, i.e., without displaying any initialization status, and set the isInitialized flag to true with either

obj.initialize;
obj.initialize(0)

• This initializes discretization (domain discretization), orbital (Kohn-Sham orbitals), externalPotential (external functional and potential), HartreePotential (Hartree functional and potential), and exchangeCorrelationPotential (exchange-correlation functional and potential) component objects.
• To avoid any mismatch in internal properties, initialize first reset the object before performing the initialization

To perform the same initialization but with displaying the status of the object initialization, including the QMol-grid package header and footer,

obj.initialize(1);

To perform the initialization and display the status of the object initialization, without the QMol-grid package header and footer,

obj.initialize(2);  % 2 or any integer larger than 1

Run-time documentation

getMemoryProfile

Get an estimate of the memory help a QMol_DFT object with either

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

• The object does not need to be initialized for the memory footprint evaluation.
• getMemoryProfile makes efforts to return the object in the same configuration as before the profiling but small side effects cannot be entirely excluded: all the DFT-model properties are left unchanged while the other properties may be altered. Notably, if the object was not initialized (isInitialized = false ), getMemoryProfile resets the object.
• The estimate includes (1) the domain discretization, (2) Kohn-Sham orbitals, (3) one body density, (4) Kohn-Sham potential, (5) Kohn-Sham potential gradient, (6) External functional, (7) Hartree functional, and (8) exchange-correlation functional(s). Note that all these components may not be used in actual simulations and the memory estimate tries to be conservative. On the other hand, it 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 object, which must have been initialized beforehand

obj.showDocumentation;

The run-time documentation performs the following steps

• Display the QMol-grid package header (showing the kernel, external component versions)
• Call the DFT-model implementation-specific run-time documentation with the property showDoc.
• Display the discretization (domain discretization) object run-time documentation
• Display the HartreePotential (Hartree functional and potential) object run-time documentation
• Display the externalPotential (external functional and potential) object run-time documentation
• Display the exchangeCorrelationPotential (exchange-correlation functional and potential) object run-time documentation
• Display the electronic structure, with the occupation (number of electrons) in each Kohn-Sham orbital
• Display the bibliography associated with the list of cited references (from the previous steps)
• Display the funding information
• Display the QMol-grid package footer

One-body density and Kohn-Sham potential

All the following methods require the object to have been initialized.

getDensity

Compute and obtain the one-body density associated with the Kohn-Sham orbitals and occupation parameters

rho = obj.getDensity;

• This creates a new one-body density object rho in which the result is stored.

Alternatively, store the result in an existing one-body density object with

obj.getDensity(rho);

setPotentialKernel

Trigger the initialization of the kernels of implicit exchange-correlation potentials/functionals

obj.setPotentialKernel;

getPotential

Compute and obtain the total Kohn-Sham potential (sum of the external, Hartree, and exchange-correlation potentials)

V = obj.getPotential;

• Uses the one-body density associated with the Kohn-Sham orbitals and occupation parameters (this forces first the computation of the one-body density)

Specify the one-body density to be used in the calculation of the Kohn-Sham potential with

V = obj.getPotential(rho)

• rho is compatible one-body density object

Alternatively, store the results in an existing Kohn-Sham potential object respectively with

obj.getPotential([],V);  % Use current density (must be computed first)
obj.getPotential(rho,V); % Supply one-body density

getPotentialGradient

Compute and obtain the gradient of the total Kohn-Sham potential (sum of the external, Hartree, and exchange-correlation potentials)

DV = obj.getPotentialGradient;

• Uses the one-body density associated with the Kohn-Sham orbitals and occupation parameters (this forces first the computation of the one-body density)

Specify the one-body density to be used in the calculation of the Kohn-Sham potential gradient with

DV = obj.getPotentialGradient(rho)

• rho is compatible one-body density object

Alternatively, store the results in an existing Kohn-Sham potential object respectively with

obj.getPotentialGradient([],DV);  % Use current density (must be computed first)
obj.getPotentialGradient(rho,DV); % Supply one-body density

By default getPotentialGradient computes the gradient along all possible directions; Specify the directions along which the gradient should be computed with

DV = obj.getPotentialGradient([],[],dim);  % Use current density (must be computed first)
obj.getPotentialGradient([],DV,dim); 
DV = obj.getPotentialGradient(rho,[],dim); % Supply one-body density
obj.getPotentialGradient(rho,DV,dim); 

DFT and orbital energies

All the following methods require the object to have been initialized.

getEnergy

Compute the DFT-component energies with either

[Etot,Ekin,Eext,Eh,Exc] = obj.getEnergy;
[Etot,Ekin,Eext,Eh,Exc] = obj.getEnergy('DFT');

• Etot is the total (sum of the following components) energy; For spin-restricted models Ekin is the total kinetic energy and for spin-polarized ones Ekin = [Eup, Edown] is the kinetic energy in the up- and down-spin channels, respectively; Eext is the external energy; Eh is the Hartree energy; Exc is the exchange-correlation energy (summed over all exchange-correlation functionals).
• Uses the one-body density associated with the Kohn-Sham orbitals and occupation parameters (this forces first the computation of the one-body density)

Compute the Kohn-Sham orbital energies and error

[E,DE] = obj.getEnergy('orbital');

• For each orbital $\left|\phi \right\rangle$ , the orbital energy is defined as the real $E=\langle \phi |{\hat{\mathcal{H}} }_{{\mathrm{D}\mathrm{F}\mathrm{T}}} |\phi \rangle$ and the error is defined as the positive real $\left\|({\hat{\mathcal{H}} }_{{\mathrm{D}\mathrm{F}\mathrm{T}}} -E)|\phi \rangle \right\|$ . ${\hat{\mathcal{H}} }_{{\mathrm{D}\mathrm{F}\mathrm{T}}}$ is the total DFT Hamiltonian operator.
• For spin-restricted models, E is a vector containing the respective orbital energies
• For spin-polarized models, E = {Eup,Edown} are the orbital energies in the up- and down-spin channels, respectively.
• For spin-restricted models, DE is a vector containing the respective orbital errors
• For spin-polarized models, DE = {DEup,DEdown} are the orbital energy errors in the up- and down-spin channels, respectively.
• This uses one-body density associated with the Kohn-Sham orbitals and occupation parameters and its corresponding Kohn-Sham potential (this forces first the computation of both the one-body density and the Kohn-Sham potential).

Specify the one-body density (for the Kohn-Sham potential) for computing the Kohn-Sham orbital energies and error with

[E,DE] = obj.getEnergy('orbital',rho);

• rho is a compatible one-body density object.
• This forces the computation of the Kohn-Sham potential (for the input density).

Specify the Kohn-Sham potential for computing the Kohn-Sham orbital energies and error with

[E,DE] = obj.getEnergy('orbital',V);

• V is a compatible Kohn-Sham potential

showEnergy

Display the DFT energy components with

obj.showEnergy('DFT');

• This forces the computation of the one-body density and its associated Kohn-Sham potential.

Display the Kohn-Sham orbital energies and errors with either

obj.showEnergy;
obj.showEnergy('orbital');

• The energy and error the same as in getEnergy.
• This also forces the computation of the one-body density and its associated Kohn-Sham potential.

Overloading the class

To define a specific implementation of DFT models, overloading classes must define the following methods with the specified signature and attributes

propertyNames

To enable name-value pair constructor, name-value pair set, and the clear methods

methods (Static=true,Access=?QMol_suite)
function [ClassName,PropNames] = propertyNames()
%propertyNames returns the names of member properties that can be set
%   through name-value assignment
    
    % Parent-class components
    [~,PropNames]       =   QMol_DFT.propertyNames;

    ClassName           =   'QMol_child_class';
    PropNames           =   [PropNames,{'property1','property2'}];
end
end

showDoc

Display the run-time documentation for the specific implementation of the molecular potential.

methods (Access=?QMol_DFT)
function ref = showDoc(obj)
%showDoc displays the documentation reflecting the specific implementation
%   of the DFT model
    
    % Add specific documentation here

end
end

• If no reference is cited, return ref = {} otherwise ref = {'ref 1','ref 2',___}, where each of the ref corresponds to the bibliographic code for the reference (generally of the form 'name_of_first_author publication_year') and is case insensitive -- see the documentation page for a list of citable references.
• Note that only implementation-specific properties should be covered here. All properties common to all DFT models (e.g., electronic structure) are handled in the parent QMol_DFT class run-time documentation.

Test suite

For consistency with the rest of the QMol-grid package, QMol_DFT defines an associated test suite. Run the test suite for the class in normal or summary mode respectively with

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

See QMol_test for details regarding how to create a test suite for new classes.

Notes

• QMol_DFT was introduced in version 01.00.
• Version 01.10 moved handling of the one-body density spatial derivatives to QMol_DFT_density
• Version 01.10 introduced a separate class for the Kohn-Sham potential gradient QMol_DFT_Vks_grad
• getMemoryProfile was introduced in version 01.10