QMol_SE_V

Potential for Schrödinger-equation models.

Description

Use QMol_SE_V to describe the potential in Schrödinger-equation (SE) models both with grid and basis-set discretizations. It supports describing the potential as a user-defined shape or a sum of atomic-like centers, or a combination of both.

Class properties

Potential model

The QMol_SE_V 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 potential (next).

inputPotential (Vin)

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

• Function handle inputPotential is the preferred method to supply a user-defined 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 Schrödinger-equation domain discretization, potentially causing errors.
• Leave empty to only provide atomic-center description of the potential (previous).

inputPotentialDerivative (DVin)

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

• For computations that require the derivative (gradient) of the potential; can be ignored otherwise. The input should correspond to the derivative of the user-define potential component inputPotential. No check is performed for this and calculations that rely on the potential derivative will produce erroneous results otherwise.
• Function handle inputPotentialDerivative 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 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 Schrödinger-equation domain discretization, potentially causing errors.
• If left empty and the potential derivative is required, a finite-difference approximation of the potential derivative from inputPotential is used instead. For more accurate results, always provide the inputPotentialDerivative associated with inputPotential whenever the potential derivative is required.

diffDx

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

• This is the stencil used to evaluate the derivative of function-handle inputPotential when no inputPotentialDerivative is provided.

Other properties

These properties cannot be edited with the set method.

potential (V)

Total potential, including all the atom-center pseudopotentials and user defined inputPotential.

potentialMatrix (mV)

For basis-set discretization, matrix representation of the total potential in the discretization basis.

• mV is computed at the initialization of the object.
• It is defined as mV(k,l) = $\langle \phi_k |\hat{\mathcal{V}} |\phi_l \rangle$ where $|\phi_k \rangle$ are the basis vectors and $\hat{\mathcal{V}}$ is the total potential operator.
• mV is left empty for grid discretizations or before the object is initialized, i.e., isInitialized == false .

potentialDerivative (DV)

Total potential derivative, including all the atom-center pseudopotentials and user defined inputPotential or inputPotentialDerivative.

• Warning: The potential derivative is not calculated when the object is initialized. This should independently be requested with the setDerivative method.

potentialDerivativeMatrix (mDV)

For basis-set discretization, matrix representation of the total potential derivative in the discretization basis.

• mDV is not computed at the initialization of the object but with calling the setDerivative method.
• It is defined as mDV(k,l) = $\langle \phi_k |\partial_x \hat{\mathcal{V}} |\phi_l \rangle$ where $|\phi_k \rangle$ are the basis vectors and $\partial_x \hat{\mathcal{V}}$ is the derivative of the total potential operator.
• mDV is left empty for grid discretizations or before the object is initialized, i.e., isInitialized == false .

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.

isBasis

Whether the discretization uses a grid (isBasis = false) or a basis set (isBasis = true)

• It is a local copy of SE.disc.isBasis, used by member methods to determine which type of discretization is used for the model.
• Un-initialized QMol_SE_V objects, i.e., isInitialized == false , have empty isBasis.

numberAtom (nbA)

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

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

Class methods

Creation

constructor

Create a potential object with empty class properties.

obj = QMol_SE_V;

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

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

Changing class properties

set

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

Initializing the object

initialize

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

obj.initialize(SE);

• SE is the Schrödinger-equation handle object, i.e., QMol_SE, to which the potential is attached.
• This calculates the total potential and stores the result in the member property V. For basis-set model, it also builds the associated matrix representation mV.
• 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(SE); end

Run-time documentation

getMemoryProfile

Get an estimate of the memory held by a QMol_SE_V 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_SE_V 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 call 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.

Potential

Before using any of the potential methods, the QMol_SE_V object must be properly initialized.

getEnergy

Get the potential energy for the parent Schrödinger-equation object.

E = obj.getEnergy;

• This computes the potential energy associated with the wave functions in the parent Schrödinger-equation model.
• The output scalar E contains the numerical evaluation of the potential energy $E=\int |\psi (x)|^2 ~\mathcal{V}(x)~dx$ , where $\mathcal{V}$ is the potential. For SE models with several wave functions, the output energy corresponds to the sum of the potential energies over all the wave functions.

Get the external energy for a specific wave function.

E = obj.getEnergy(wfcn);

• Same as above but with using the input wave function object wfcn in the numerical computation of the energy.
• wfcn should be a QMol_SE_wfcn object defined over the same domain discretization as the parent Schrödinger-equation model.

setDerivative

Initialize the potential gradient.

obj.getPotentialDerivative;

• This calculates the potential gradient and stores the result in the member property DV. For basis-set model, it also builds the associated matrix representation mDV.
• The initialization parses through the atom-center pseudopotentials, inputPotential, and inputPotentialDerivative and determines the most accurate way to calculates the total potential derivative.
• If a functional handle inputPotential component is specified but no inputPotentialDerivative, the user-defined potential component is evaluated numerically using a centered finite difference scheme with the diffDx stencil.
• If a vector inputPotential component is specified but no inputPotentialDerivative, the user-defined potential component is evaluated numerically using a centered finite difference scheme with the stencil imposed by the Schrödinger-equation domain discretization.
• Once initialized, access the potential derivative via the member property DV.

Examples

Create a discretization domain.

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

Create a 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);

% Potential
V   = QMol_SE_V('atom',{Va_1,Va_2,Va_3},'inputPotential',@(x) .05*x);

Create a minimal Schrödinger-equation-model object required to initialize the external potential class and display the run-time documentation.

SE = QMol_SE('discretization',disc);
disc.initialize(SE);
V.initialize(SE);
V.showDocumentation;

yielding

  * Potential
    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.

V.getMemoryProfile(true);

  * Potential                                                    
    > potential                                                     3.5 KB
    > potential gradient                                            3.5 KB

Plot the potential and its gradient.

% Calculate the gradient
V.setDerivative;

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

For developers

Other hidden class properties

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

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_SE_V objects, i.e., isInitialized == false , have empty SE.
• For practical reasons, SE is editable by QMol_SE and QMol_SEq classes.

Run-time documentation

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

Compatible atom-like center (pseudopotentials) objects

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

Notes

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

• QMol_SE_V was introduced in version 01.20.