QMol_DFT_Vext

External potential and functional for DFT models.

Description

Use QMol_DFT_Vext to describe the external potential and external-energy functional in DFT models. It supports describing the molecular potential as a user-defined shape or a sum of atomic-like centers, or a combination of both.

Class properties

External-potential model

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

atom

Atomic centers in the atomic or molecular model [ cell (default []) ]

• atom = {V1,V2,___} where each of the Vs is a compatible atom-like center (pseudopotentials).
• Leave empty to only provide a user-defined external potential (next).

externalPotential (Vext)

User-defined external potential [ [] (default) | function handle | vector ]

• Function handle externalPotential is the preferred method to supply a user-defined external potential component. The signature for the function 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.
• The discretization of the user-defined external potential component can also be supplied as an N-by-1 vector, where N is the number of point in the domain discretization. This is discouraged as the user-defined external potential component will not automatically adjust to changes in DFT domain discretization, potentially causing errors.
• Leave empty to only provide atomic-center description of the external potential (previous).

externalPotentialDerivative (DVext)

User-defined external potential derivative [ [] (default) | function handle | vector ]

• For computations that require the derivative (gradient) of the external potential; can be ignored otherwise. The input should correspond to the derivative of the user-define potential component externalPotential. No check is performed for this and getPotentialDerivative will produce erroneous results otherwise.
• Function handle externalPotentialDerivative is the preferred method to supply a user-defined external potential derivative component. The signature for the function should be DV = funDV(x), where the output DV has the same shape as the input vector x and contains element-wise values of the potential derivative at the query points x.
• The discretization of the user-defined external potential derivative component can also be supplied as an N-by-1 vector, where N is the number of point in the domain discretization. This is discouraged as the user-defined external potential derivative component will not automatically adjust to changes in DFT domain discretization, potentially causing errors.
• If left empty and the potential derivative is required, a finite-different approximation of the potential derivative from externalPotential is used instead. For more accurate results, always provide the externalPotentialDerivative associated with externalPotential whenever the external-potential derivative is required.

diffDx

Differentiation stencil for numerical evaluation of derivatives [ non-negative scalar (default 1e-5) ]

• This is the stencil used in getPotentialDerivative to evaluate the derivative of function-handle externalPotential when no externalPotentialDerivative is provided.

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. Changing its isSpinPol may cause simulations to fail or produce erroneous results.

numberAtom (nbA)

Number of atomic centers in the object [ positive integer (default []) ]

• This is defined as numel(atom).
• Un-initialized QMol_DFT_Vext objects, i.e., isInitialized == false , have empty numberAtom.

Class methods

Creation

constructor

Create an external-potential object with empty class properties.

obj = QMol_DFT_Vext;

Create an external-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 external-potential model properties and is case insensitive.

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

Changing class properties

set

Update the name properties of an external-potential object to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the external-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.
• This also resets all the atom-like centers in the object, equivalent to the command for k = 1:nbA , atom{k}.reset; end

clear

Clear all class properties.

obj.clear;

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

Initializing the object

initialize

Initialize a QMol_DFT_Vext 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 external potential is attached.
• To avoid any mismatch in internal properties, initialize first reset the object before performing the initialization.
• This initializes all the atom-like centers in the object, equivalent to the command for k = 1:nbA , atom{k}.initialize(DFT); end

Run-time documentation

getMemoryProfile

Get an estimate of the memory held by a QMol_DFT_Vext 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_Vext object.

ref = obj.showDocumentation;

• The output ref is a cell vector containing the list of references to be included in the bibliography.
• The run-time documentation performs the following steps: (1) It calls the implementation-specific run-time documentation with the property showDoc. (2) It parses through the atom-like centers listed in atom, and call their run-time documentation to list the specific parameters for each of them. (3) For each type of pseudopotential used, call again the run-time documentation to display their generic description. This ensures a full but compact description of the molecular model without repeating general properties of pseudopotentials that are used several times in the molecular model.

External potential

Before using any of its external-potential methods, the QMol_DFT_Vext object must be properly initialized.

getEnergy

Get the external energy for the parent DFT object.

E = obj.getEnergy;

• This computes the external 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.
• For spin-restricted models, the output scalar E contains the numerical evaluation of the external energy $E=\int \rho (x){\mathcal{V}}_{{\mathrm{e}\mathrm{x}\mathrm{t}}} (x)~dx$ , where ${\mathcal{V}}_{{\mathrm{e}\mathrm{x}\mathrm{t}}}$ is the (total) external potential and the one-body density $\rho$ is computed from the parent DFT-model's Kohn-Sham orbitals.
• For spin-polarized models, the output vector E = [Eup,Edown] contains the numerical evaluations of the up- and down-spin channel external energies, respectively defined as $E^{\uparrow } =\int \rho^{\uparrow } (x){\mathcal{V}}_{{\mathrm{e}\mathrm{x}\mathrm{t}}} (x)~dx$ and $E^{\downarrow } =\int \rho^{\downarrow } (x){\mathcal{V}}_{{\mathrm{e}\mathrm{x}\mathrm{t}}} (x)~dx$ .
• This is equivalent to, but more efficient than, to obj.getEnergy(DFT.getDensity) with DFT being the same DFT-model handle object used to initialize the external-potential object.

Get the external 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 external potential with either

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

• This creates a new Kohn-Sham potential object V in which the external potential is stored.
• For spin-restricted models, access the discretization of the external potential with V.potential.
• For spin-restricted models, access the discretization of the external potential with either V.potentialUp or V.potentialDown.
• Note that getPotential does not initialize the output potential object V.

Overwrite the external potential in an existing Kohn-Sham potential object with either

obj.getPotential(V);
obj.getPotential(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);

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

getPotentialDerivative

Get the external potential gradient with either

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

• This creates a new Kohn-Sham potential gradient object DV in which the external potential gradient is stored.
• The first time getPotentialDerivative is called, the object stores an internal copy of the derivative. Later call to getPotentialDerivative then repeat this internal copy rather than compute again the derivative. The internal copy is erased whenever any of the set, reset, or clear method is called, forcing a new evaluation of the external-potential derivative the next time getPotentialDerivative is called.
• If a functional handle externalPotential component is specified but no externalPotentialDerivative, the user-defined external potential component is evaluated numerically using a centered finite difference scheme with the diffDx stencil.
• If a vector externalPotential component is specified but no externalPotentialDerivative, the user-defined external potential component is evaluated numerically using a centered finite difference scheme with the stencil imposed by the DFT domain discretization.
• For spin-restricted models, access the discretization of the external potential gradient with DV.potentialGradient.
• For spin-restricted models, access the discretization of the external 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.

Overwrite the external potential gradient in an existing Kohn-Sham potential gradient object with either

obj.getPotentialDerivative(1,DV);
obj.getPotentialDerivative(1,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 external potential gradient to it.

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

obj.getPotentialDerivative(1,DV,true);

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

Examples

Create a discretization domain.

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

Create an external potential object with three atomic centers (pseudopotentials) and a dressing field.

% List of atomic centers
Va_1 = QMol_Va_softCoulomb('name','X_1','charge',2,'softeningParameter',0.8,'position',-3);
Va_2 = QMol_Va_Gaussian('name','X_2','potentialDepth',1,'potentialWidth',5,'position',0);
Va_3 = QMol_Va_softCoulomb('name','X_3','charge',1,'softeningParameter',0.5,'position',3);

% External potential
Vext = QMol_DFT_Vext('atom',{Va_1,Va_2,Va_3},'externalPotential',@(x) .05*x);

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

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

yielding

  * External-potential functional
    V-01.21.000 (06/17/2024)                                     F. Mauger
  * User-defined component                                     (free form)
    Potential =     function handle
  * Atom-like center(s)
    > X_1, parameterized as                                 (soft Coulomb)
      Z =  2.00 | a =  0.80 | X0 =  -3.00
    > X_2, parameterized as                                     (Gaussian)
      V0 =  1.00 | s =  5.00 | X0 =   0.00
    > X_3, parameterized as                                 (soft Coulomb)
      Z =  1.00 | a =  0.50 | X0 =   3.00
  * Gaussian-shape potential                                    (Gaussian)
    Parameterized as V(x) = -V0 * exp( -(x-X0).^2 / (2*s^2) )
    V-01.21.000 (06/17/2024)                                     F. Mauger
  * Soft-Coulomb potential [Javanainen 1988]                (soft Coulomb)
    Parameterized as V(x) = -Z ./ sqrt( (x-X0).^2 + a^2 ). 
    V-01.21.000 (06/17/2024)                                     F. Mauger

Display the estimated memory footprint for the object.

Vext.getMemoryProfile(true);

  * External functional                                          
    > potential                                                     3.5 KB
    > potential gradient                                            3.5 KB

Plot the external potential and its gradient.

% Get potential and gradient
V  = Vext.getPotential;
DV = Vext.getPotentialDerivative(1);

% Plot the results
figure; hold on
plot(disc.xspan,V.potential,'-','LineWidth',2,'DisplayName','V_{ext}')
plot(disc.xspan,DV.potentialGradient,'-','LineWidth',2','DisplayName','{\nabla}V_{ext}')
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_Vext');
QMol_test.test('-summary','DFT_Vext');

For developers

Other hidden class properties

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

V

Discretization of the total external potential [ [] (default) | vector ]

• This is the internal copy of the total -- user-defined + from list of atomic-like centers -- external potential over the domain discretization associated with DFT.disc.
• It is computed whith initialize after which V is a numel(DFT.disc.x)-by-1 vector.
• Un-initialized QMol_DFT_Vext objects, i.e., isInitialized == false , have empty V.

DV

Discretization of the total external potential gradient [ [] (default) | vector ]

• This is the internal copy of the total -- user-defined + from list of atomic-like centers -- external potential gradient over the domain discretization associated with DFT.disc.
• It is computed at the first call of getPotentialDerivative after which DV is a numel(DFT.disc.x)-by-1 vector. Later call to getPotentialDerivative simply access this local copy of the gradient.
• Un-initialized QMol_DFT_Vext objects, i.e., isInitialized == false , have empty DV.

Run-time documentation

If editing the QMol_DFT_Vext class, update its run-time documentation accordingly in showDoc.

Other private class properties

setDerivative

This is the method in charge of evaluating the potential gradient at the first call of getPotentialDerivative. Update the method accordingly to any changes to QMol_DFT_Vext.

Compatible atom-like center (pseudopotentials) objects

See QMol_Vmol's documentation for details on how to define pseudopotentials that are compatible with QMol_DFT_Vext.

Notes

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

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