QMol_TDDFT_abs_CAP

Absorbing boundaries using a complex absorbing potential (CAP) at the edges of the discretization domain

Description

Use QMol_TDDFT_abs_CAP to describe absorbing boundaries with a CAP. During the TDDFT propagation, the CAP is added to the Kohn-Sham potential.

Class properties

Complex absorbing potential (CAP)

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

amplitude (V0)

Amplitude of the CAP [ positive scalar (default 0.5) ]

• When constructing the CAP, the selected shape is multiplied by the specified amplitude (including for user-defined shapes).

length (L)

Length of the absorbing region at the edges of the domain discretization [ positive scalar (default 10) | positive two-vector ]

• Scalar length defines a CAP with the same length on both sides of the discretization domain.
• length = [L_left, L_right] independently specifies the CAP length on each side of the domain.
• Note: The CAP is defined inward from the two ends of the DFT model discretization domain, which should therefore budget for this.

shape

Shape of the CAP [ 'sin^1/8' (default) | 'sin' | 'sin^2' | function handle ]

• 'sin^1/8' uses a $\sin^{1/8}$ -shaped CAP.
• 'sin' uses a $\sin$ -shaped CAP.
• 'sin^2' uses a $\sin^2$ -shaped CAP.
• A function handle enables user-defined CAPs, with the signature @(x) fun(x), where fun(0)=0 and fun(1)=V_max returns the values for the CAP at the beginning and end of the absorbing domain, respectively (the absorbing domain at the two ends of the discretization domain are linearly mapped to the segment [0 1] when calling the CAP function). fun must be real valued and positive; the sign and complex coefficients are properly assigned when the object is initialized. We recommend setting V_max to 1 and using the amplitude property to control the CAP height.

Other properties

These properties cannot be edited with the set method.

isCAP (=true)

This constant property can be used to distinguish CAP from mask (isCAP = false) absorbing boundary conditions at run time.

isInitialized (isInit)

Whether the absorbing-boundary CAP object is properly initialized. This is used throughout the QMol-grid package to check that the absorber 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 an absorbing-boundary CAP object with empty class properties.

obj = QMol_TDDFT_abs_CAP;

Create an absorbing-boundary CAP object with the name properties set to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the CAP properties and is case insensitive.

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

Changing class properties

set

Update the name properties of an absorbing-boundary CAP object to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the CAP 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 CAP 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_TDDFT_abs_CAP class.

Initializing the object

initialize

Initialize a QMol_TDDFT_abs_CAP object and set the isInitialized flag to true.

obj.initialize(DFT,isForward);

• DFT is the DFT-model handle object, i.e., QMol_DFT_spinPol or QMol_DFT_spinRes, being propagated in the TDDFT simulation.
• isForward specifies whether the TDDFT propagation is forward (true) or backward (false) in time.
• To avoid any mismatch in internal properties, initialize first reset the object before performing the initialization.

Run-time documentation

getMemoryProfile

Get an estimate of the memory held by a QMol_TDDFT_abs_CAP object with either

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

• The object must be properly initialized.
• The estimate only includes the discretization of the CAP 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_TDDFT_abs_CAP object.

ref = obj.showDocumentation;

• The output ref is a cell vector containing the list of references to be included in the bibliography.

CAP function

To use the CAP, the QMol_TDDFT_abs_CAP object must be properly initialized.

getPotential

Apply the mask function to a set of Kohn-Sham orbitals.

obj.getPotential(Vks);

• This adds the CAP to the Kohn-Sham potential object Vks, by performing the in-place operation ${\mathcal{V}}_{{\mathrm{K}\mathrm{S}}} \gets {\mathcal{V}}_{{\mathrm{K}\mathrm{S}}} +{\mathcal{V}}_{{\mathrm{C}\mathrm{A}\mathrm{P}}}$.
• For developers: For similarity with other getPotential methods in the QMol-grid package, the full signature is Vks = getPotential(obj,Vks). Note that getPotential does not perform any Kohn-Sham potential allocation and calling the function without a valid potential object will cause an error.

Examples

Create a discretization domain and minimal DFT-model object

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

Create the CAP absorber and display the run-time documentation

ABC  = QMol_TDDFT_abs_CAP('length',5);
ABC.initialize(DFT,true);
ABC.showDocumentation;

yielding

  * Absorbing boundaries                       complex absorbing potential
    Length = 5 a.u. on both ends
    Amplitude = 0.5 a.u.    Shape  = sin^1/8
    V-01.21.000 (06/17/2024)                                     F. Mauger

Display the estimated memory footprint for the object

ABC.getMemoryProfile(true);

  * Absorbing boundaries (mask)                                     7.0 KB

Test suite

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

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

For developers

Other hidden class properties

QMol_TDDFT_abs_CAP defines a handful of additional transient/constant 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_TDDFT_abs_CAP objects, i.e., isInitialized == false, have empty DFT.
• For practical reasons, DFT is editable by QMol_TDDFT classes.

V

Discretization of the CAP on the domain grid [ [] (default) | vector ]

• Un-initialized QMol_TDDFT_abs_CAP objects, i.e., isInitialized == false , have empty V.

nKSO

Number of Kohn-Sham orbitals in the DFT model [ [] (default) | integer | two-integer vector ]

• For spin-polarized models, nKSO = [N_up, N_down] specifies the number of up- and down-spin Kohn-Sham orbitals, respectively.

Notes

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

• QMol_TDDFT_abs_CAP was introduced in version 01.10.