QMol_TDSE_abs_mask

Absorbing boundaries using a mask function at the edges of the discretization domain.

Description

Use QMol_TDSE_abs_mask to describe absorbing boundaries with a mask function. After each TDSE propagation time step, the wave functions in the attached Schrödinger-equation model are multiplied by the mask function.

Class properties

Mask function

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

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 mask function with the same length on both sides of the discretization domain.
• length = [L_left, L_right] independently specifies the mask function length on each side of the domain.
• Note: The mask function is defined inward from the two ends of the Schrödinger-equation model discretization domain, which should therefore budget for this.

shape

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

• 'cos^1/8' uses a $\cos^{1/8}$ -shaped mask function.
• 'cos^2' uses a $\cos^2$ -shaped mask function.
• A function handle enables user-defined mask function, with the signature @(x) fun(x), where fun(0)=1 and fun(1)=0, returns the values for the mask function 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 mask function).

Other properties

These properties cannot be edited with the set method.

isInitialized (isInit)

Whether the absorbing-boundary mask 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.

Class methods

Creation

constructor

Create an absorbing-boundary mask object with empty class properties.

obj = QMol_TDSE_abs_mask;

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

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

Changing class properties

set

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

Initializing the object

initialize

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

obj.initialize(SE);

• SE is the Schrödinger-equation-model handle object, i.e., QMol_SE, begin propagated in the TDSE simulation.
• To avoid any mismatch in internal properties, initialize first reset the object before performing the initialization.
• For developers: For compatibility with complex-absorbing-potential absorbers, the method also supports obj.initialize(SE,isFwd), where isFwd specifies forward vs backward time propagation but is ignored.

Run-time documentation

getMemoryProfile

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

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

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

ref = obj.showDocumentation;

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

Mask function

To use the mask function, the QMol_TDSE_abs_mask object must be properly initialized.

applyMask

Apply the mask function to a set of wave functions

obj.applyMask(wfcn);

• This multiplies each wave function in the object wfcn by the mask function (formally equivalent to in place $\psi (x)\gets \mathcal{W}(x)\,\psi (x)$ , where $\mathcal{W}$ is the mask function).

Examples

Create a discretization domain and minimal Schrödinger-equation-model object.

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

Create the mask-function absorber and display the run-time documentation.

ABC  = QMol_TDSE_abs_mask('length',5);
ABC.initialize(SE);
ABC.showDocumentation;

yielding

  * Absorbing boundaries                                     mask function
    Length = 5 a.u. on both ends
    Shape  = cos^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)                                     3.5 KB

Test suite

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

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

For developers

Other hidden class properties

QMol_TDSE_abs_mask 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).

SE

Schrödinger-equation-model object [ [] (default) | QMol_SE handle object ]

• This is a copy of the Schrödinger-equation-model handle object passed to initialize.
• Un-initialized QMol_TDSE_abs_mask objects, i.e., isInitialized == false, have empty SE.
• For practical reasons, SE is editable by QMol_SE classes.

W

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

• Un-initialized QMol_TDSE_abs_mask objects, i.e., isInitialized == false, have empty W.

Notes

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

• QMol_TDSE_abs_mask was introduced in version 01.20.