QMol_DFT_Vks_grad - fmauger1/QMol-grid GitHub Wiki

QMol_DFT_Vks_grad

Kohn-Sham-potential gradient operator object.

Description

Use QMol_DFT_Vks_grad to store the Kohn-Sham-potential gradient operator for (TD)DFT simulations. QMol_DFT_Vks_grad is a handle class.

Class properties

Kohn-Sham potential gradient

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

potentialGradient (DV)

Discretization of the explicit part of the Kohn-Sham potential gradient [ vector (default []) ]

  • For spin restricted DFT model; irrelevant for spin restricted ones.
  • Properly allocated potentialGradient is a numel(disc.xspan)-by-1 vector matching the domain discretization of the associated (TD)DFT model.

potentialGradientUp (DVup)

Discretization of the explicit part of the up-spin channel Kohn-Sham potential gradient [ vector (default []) ]

  • For spin polarized DFT model; irrelevant for spin restricted ones.
  • Properly allocated potentialGradientUp is a numel(disc.xspan)-by-1 vector matching the domain discretization of the associated (TD)DFT model.

potentialGradientDown (DVdw)

Discretization of the explicit part of the down-spin channel Kohn-Sham potential gradient [ vector (default []) ]

  • For spin polarized DFT model; irrelevant for spin restricted ones.
  • Properly allocated potentialGradientDown is a numel(disc.xspan)-by-1 vector matching the domain discretization of the associated (TD)DFT model.

potentialGradientImplicit (DVimp)

Implicit components of the Kohn-Sham potential gradient [ cell of handle functions (default {}) ]

  • For both spin restricted and polarized models, holds the implicit components of the Kohn-Sham potential gradient. Implicit potential are defined through their action on orbitals instead of the value-at-grid-point their explicit counterparts.
  • Each component of potentialGradientImplicit contains a handle function describing one implicit-potential gradient component.
  • For spin resctricted models, the signature for implicit-potential gradient components is Hp = funV(p). p and Hp are both numel(disc.xspan)-by-1 vectors respectively containing the discretization of the orbital to which the potential gradient should be applied and its result.
  • For spin polarized models, the signature for implicit-potential gradient components is Hp = funV(p,isUp). p and Hp are both numel(disc.xspan)-by-1 vectors respectively containing the discretization of the orbital to which the potential gradient should be applied and its result. The second logical input isUp specifies whether applying the up- (true) or down-spin (false) potential gradient operator to the input orbital.

isSpinPol

Whether the Kohn-Sham potential gradient is spin polarized (true) or spin restricted (false). isSpinPol is used by other classes to determine whether they should use the potentialGradient or potentialGradientUp and potentialGradientDown properties, and the proper interface for any potentialGradientImplicit component, in their calculations.

Other properties

These properties cannot be edited with the set method.

isInitialized (isInit)

Whether the Kohn-Sham-potential gradient operator object is properly initialized. This is used throughout the QMol-grid package to check that the potential gradient object holds meaningful information and is ready for use. Changing its isSpinPol may cause simulations to fail or produce erroneous results.

Class methods

Creation

constructor

Create a Kohn-Sham-potential gradient operator object with empty class properties.

obj = QMol_DFT_Vks_grad;

Create a Kohn-Sham-potential gradient operator object with the name properties set to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the Kohn-Sham potential gradient properties and is case insensitive.

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

Most often, Kohn-Sham-potential gradient operator objects are created through domain-discretization or DFT objects.

obj = disc.DFT_allocatePotentialGradient;
obj = DFT.getPotentialGradient;
  • Note: potential gradient property assignation is provided for extended support. Most end users will not need these as editing the potential gradient may cause simulations to produce erroneous results or fail altogether.

Changing class properties

set

Update the name properties of a Kohn-Sham potential gradient object to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the Kohn-Sham potential gradient 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 false.

  • Note: potential property assignation is provided for extended support. Most end users will not need these as editing the potential gradient may cause simulations to produce erroneous results or fail altogether.

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 Kohn-Sham potential gradient 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_Vks_grad class.

Initializing the object

initialize

Minimally initialize a Kohn-Sham-potential gradient operator object and sets the isInitialized flag to true.

obj.initialize;
  • To avoid any mismatch in internal properties, initialize first reset the object before performing the initialization.
  • Minimal initialization is discouraged, instead the object should be initialized with its associated domain-discretization object (next).

Initialize a Kohn-Sham-potential gradient operator object with its associated domain-discretization object.

obj.initialize(disc);

Run-time documentation

getMemoryProfile

Get an estimate of the memory help a QMol_DFT_density 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 the explicit part of the Kohn-Sham potential 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);

Arithmetic with potential gradients

add

For spin restricted DFT models, add an explicit potential gradient component to a QMol_DFT_Vks_grad object.

obj.add(1,DV);
  • This performs the in-place addition potentialGradient = potentialGradient + DV .
  • The input DV should be a numel(disc.xspan)-by-1 vector matching the domain discretization of the associated (TD)DFT model.
  • 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 provided must be specified.

For spin polarized DFT models, add the same explicit potential gradient components to both the up- and down-spin components of a QMol_DFT_Vks_grad object.

obj.add(1,DV);
  • This performs the in-place additions potentialGradientUp = potentialGradientUp + DV and potentialGradientDown = potentialGradientDown + DV.
  • The input DV should be a numel(disc.xspan)-by-1 vector matching the domain discretization of the associated (TD)DFT model.
  • 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 provided must be specified.

For spin polarized DFT models, add different explicit potential gradient components to the up- and down-spin components of a QMol_DFT_Vks_grad object.

obj.add(1,DVup,DVdown);
  • This performs the in-place additions potentialGradientUp = potentialGradientUp + DVup and potentialGradientDown = potentialGradientDown + DVdown.
  • The inputs DVup and DVdown should each be numel(disc.xspan)-by-1 vector matching the domain discretization of the associated (TD)DFT model.
  • Replace any of DVup and DVdown by scalar 0 to add an explicit potential gradient component solely to the other spin channel.
  • 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 provided must be specified.

For both spin restricted and polarized DFT models, add an implicit potential gradient component to a QMol_DFT_Vks_grad object.

obj.add(1,funDV);
  • funDV is a function handle describing the implicit-potential gradient component (which is then added to the potentialGradientImplicit list).
  • For spin restricted models, the signature for the input function handle is Hp = funDV(p). p and Hp are both numel(disc.xspan)-by-1 vectors respectively containing the discretization of the orbital to which the potential gradient should be applied and its result.
  • For spin polarized models, the signature for the input function handle is Hp = funDV(p,isUp). p and Hp are both numel(disc.xspan)-by-1 vectors respectively containing the discretization of the orbital to which the potential gradient should be applied and its result. The second logical input isUp specifies whether applying the up- (true) or down-spin (false) potential operator to the input orbital.
  • 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 provided must be specified.

applyPotential

For spin-restricted models, apply the potential gradient operator to a wave function.

Hp = obj.applyPotentialGradient(1,p);
  • This computes the action of the entire -- including both explicit and implicit components -- Kohn-Sham potential gradient operator on the input wave function p. All implicit components require the associated functional object to have their potential kernels properly set beforehand (with setPotentialKernel -- see the functional documentation). applyPotential does not perform or check for this initialization.
  • p and Hp are both numel(disc.xspan)-by-1 vectors respectively containing the discretization of the orbital to which the potential gradient should be applied and its result.
  • applyPotentialGradient requires the Kohn-Sham potential gradient object to have been initialized with a domain discretization.
  • 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.

For spin-polarized models, apply the up- and down-spin Kohn-Sham potential gradient operators to a wave function respectively with

Hp = obj.applyPotentialGradient(1,p,true);
Hp = obj.applyPotentialGradient(1,p,false);
  • This computes the action of the entire -- including both explicit and implicit components -- Kohn-Sham potential gradient operator on the input wave function p. All implicit components require the associated functional object to have their potential kernels properly set beforehand (with setPotentialKernel -- see the functional documentation). applyPotential does not perform or check for this initialization.
  • p and Hp are both numel(disc.xspan)-by-1 vectors respectively containing the discretization of the orbital to which the potential gradient should be applied and its result.
  • applyPotentialGradient requires the Kohn-Sham potential object to have been initialized with a domain discretization.
  • 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.

Examples

Most users will not use Kohn-Sham potential gradient objects directly or will get them indirectly, through DFT and TDDFT simulations -- see their respective documentations for examples.

Test suite

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

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

For developers

QMol_DFT_Vks_grad implements a streamlined version of the clear all method, since it might be called frequently in DFT and TDDFT computations. If adding properties to the class, the streamlined clear all must be updated accordingly.

QMol_DFT_Vks_grad overloads QMol_suite.

Notes

  • QMol_DFT_Vks_grad was introduced in version 01.10.