QMol_DFT_Vks - fmauger1/QMol-grid GitHub Wiki

QMol_DFT_Vks

Kohn-Sham-potential operator object

Description

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

Class properties

Kohn-Sham potential

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

potential (V)

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

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

potentialUp (Vup)

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

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

potentialDown (Vdw)

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

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

potentialImplicit (Vimp)

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

  • For both spin restricted and polarized models, holds the implicit components of the Kohn-Sham potential. Implicit potential are defined through their action on orbitals instead of the value-at-grid-point their explicit counterparts.
  • Each component of potentialImplicit contains a handle function describing one implicit-potential component.
  • For spin resctricted models, the signature for implicit-potential 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 should be applied and its result.
  • For spin polarized models, the signature for implicit-potential 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 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.

isSpinPol

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

Other properties

These properties cannot be edited with the set method.

isInitialized (isInit)

Whether the Kohn-Sham-potential operator 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.

isBasis

Flag indicating that QMol_DFT_Vks objects are not a discretization over a basis set [ false ]

  • At run time, isBasis can be used to discriminate QMol_DFT_Vks objects from QMol_DFT_Vks_basis (which overloads the class).
  • For class development purposes, isBasis is technically a static method. Practically, though, it can virtually almost always be treated as a constant property.

Class methods

Creation

constructor

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

obj = QMol_DFT_Vks;

Create a Kohn-Sham-potential 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 properties and is case insensitive.

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

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

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

Changing class properties

set

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

Initializing the object

initialize

Minimally initialize a Kohn-Sham-potential 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 operator object with its associated domain-discretization object.

obj.initialize(disc);

Run-time documentation

getMemoryProfile

Get an estimate of the memory held by a QMol_DFT_Vks 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 potentials

add

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

obj.add(V);
  • This performs the in-place addition potential = potential + V .
  • The input V should be a numel(disc.xspan)-by-1 vector matching the domain discretization of the associated (TD)DFT model.

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

obj.add(V);
  • This performs the in-place additions potentialUp = potentialUp + V and potentialDown = potentialDown + V .
  • The input V should be a numel(disc.xspan)-by-1 vector matching the domain discretization of the associated (TD)DFT model.

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

obj.add(Vup,Vdown);
  • This performs the in-place additions potentialUp = potentialUp + Vup and potentialDown = potentialDown + Vdown .
  • The inputs Vup and Vdown should each be numel(disc.xspan)-by-1 vector matching the domain discretization of the associated (TD)DFT model.
  • Replace any of Vup and Vdown by scalar 0 to add an explicit potential component solely to the other spin channel.

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

obj.add(funV);
  • funV is a function handle describing the implicit-potential component (which is then added to the potentialImplicit list).
  • For spin resctricted models, the signature for the input function handle 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 should be applied and its result.
  • For spin polarized models, the signature for the input function handle 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 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.

applyPotential

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

Hp = obj.applyPotential(p);
  • This computes the action of the entire -- including both explicit and implicit components -- Kohn-Sham potential 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 should be applied and its result.
  • applyPotential requires the Kohn-Sham potential object to have been initialized with a domain discretization.

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

Hp = obj.applyPotential(p,true);
Hp = obj.applyPotential(p,false);
  • This computes the action of the entire -- including both explicit and implicit components -- Kohn-Sham potential 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 should be applied and its result.
  • applyPotential requires the Kohn-Sham potential object to have been initialized with a domain discretization.

Examples

Most users will not use Kohn-Sham potential 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');
QMol_test.test('-summary','DFT_Vks');

For developers

QMol_DFT_Vks 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.

Unlike the one-body density, Kohn-Sham potentials generally do not have vanishing or periodic boundary conditions. This makes one-the-fly computation of their gradient more challenging. Computation of the potential gradient is handled in the QMol_DFT interface class and stored in a separate QMol_DFT_grad_Vks object.

QMol_DFT_Vks overloads QMol_suite.

Notes

  • QMol_DFT_Vks was introduced in version 01.00.
  • Version 01.10 integrated initialization with a domain discretization object.
  • getMemoryProfile was introduced in version 01.10.