QMol_SEq

QMol_SEq

Parent class for Schrödinger equation (SE) model objects.

Description

QMol_SEq defines an abstract class for the description of SE models. It is designed to be agnostic of (i) the model dimension and (ii) the chosen discretization (Cartesian grid or basis). These are to be handled by the specific SE-implementation classes and their components.

Class properties

SE model

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

discretization (disc)

Domain discretization object [ handle object (default []) ]

numberWaveFunction (N)

Number of wave functions [ positive integer | (default []) ]

waveFunction (wfcn)

Wave function object [ handle object (default []) ]

potential (V)

Potential object [handle object (default []) ]

Other properties

To facilitate simulations, the QMol_SEq defines a handful of additional transient properties. These cannot be edited with the set method.

isInitialized (isInit)

Whether the SE-model object is properly initialized. This is used throughout the QMol-grid package to check that the SE-model object holds meaningful information and is ready for use.

Constant properties

dim

• Specifies the dimension of the SE model

Class methods

Creation

constructor

Create a SE-model object with empty class properties.

obj = QMol_SEq;

Create a SE-model object with the name properties set to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the SE-model properties and is case insensitive.

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

Changing class properties

set

Update the name properties of a SE-model object to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the SE-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.
• To avoid any mismatch in the SE component internal properties, this also resets the discretization (domain discretization), waveFunction , and potential components objects.

clear

Clear all class properties

obj.clear;

Clear a specific set of the class properties. Suitable name is any of the SE-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_Seq class.

Initializing the object

initialize

Initialize a SE-model object in silent mode, i.e., without displaying any initialization status, and set the isInitialized flag to true with either

obj.initialize;
obj.initialize(0)

• This initializes discretization (domain discretization), waveFunction , and potential component objects.
• To avoid any mismatch in internal properties, initialize first reset the object before performing the initialization

To perform the same initialization but with displaying the status of the object initialization, including the QMol-grid package header and footer,

obj.initialize(1);

To perform the initialization and display the status of the object initialization, without the QMol-grid package header and footer,

obj.initialize(2);  % 2 or any integer larger than 1

Run-time documentation

getMemoryProfile

Get an estimate of the memory help a QMol_SEq object with either

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

• The object does not need to be initialized for the memory footprint evaluation.
• getMemoryProfile makes efforts to return the object in the same configuration as before the profiling but small side effects cannot be entirely excluded: all the SE-model properties are left unchanged while the other properties may be altered. Notably, if the object was not initialized (isInitialized = false ), getMemoryProfile resets the object.
• The estimate includes (1) the domain discretization, (2) wave function(s), and (3) the potential. Note that all these components may not be used in actual simulations and the memory estimate tries to be conservative. On the other hand, it 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_SEq object, which must have been initialized beforehand

obj.showDocumentation;

The run-time documentation performs the following steps

• Display the QMol-grid package header (showing the kernel, external component versions)
• Call the SE-model implementation-specific run-time documentation with the property showDoc.
• Display the discretization (domain discretization) object run-time documentation
• Display the potential object run-time documentation
• Display the electronic structure, with the number of wave functions
• Display the bibliography associated with the list of cited references (from the previous steps)
• Display the funding information
• Display the QMol-grid package footer

SE and orbital energies

All the following methods require the object to have been initialized.

getEnergy

Compute the SE-component energies with either

[Etot,Ekin,Epot] = obj.getEnergy;
[Etot,Ekin,Epot] = obj.getEnergy('SE');

• Etot is the total (sum of the following components) energy; Ekin is the total kinetic, defined as the sum of the kinetic energies for each of the wave functions; Epot is the total potential energy, defined as the sum of the potential energies for each of the wave functions.

Compute the wave function energies and error

[E,DE] = obj.getEnergy('wave function');

• For each wave function $\left|\psi \right\rangle$ , the orbital energy is defined as the real $E=\langle \psi |\hat{\mathcal{H}} |\psi \rangle$ and the error is defined as the positive real $\left\|(\hat{\mathcal{H}} -E)|\psi \rangle \right\|$ . $\hat{\mathcal{H}}$ is the total SE Hamiltonian operator.
• E is a vector containing the respective wave function energies
• DE is a vector containing the respective wave function errors

Specify the potential for computing the wave function energies and error with

[E,DE] = obj.getEnergy('wave function',V);

• V is a compatible potential

showEnergy

Display the SE energy components with

obj.showEnergy('SE');

Display the wave function energies and errors with either

obj.showEnergy;
obj.showEnergy('wave function');

• The energy and error the same as in getEnergy.

Overloading the class

To define a specific implementation of SE models, overloading classes must define the following methods with the specified signature and attributes

propertyNames

To enable name-value pair constructor, name-value pair set, and the clear methods

methods (Static=true,Access=?QMol_suite)
function [ClassName,PropNames] = propertyNames()
%propertyNames returns the names of member properties that can be set
%   through name-value assignment
    
    % Parent-class components
    [~,PropNames]       =   QMol_SEq.propertyNames;

    ClassName           =   'QMol_child_class';
    PropNames           =   [PropNames,{'property1','property2'}];
end
end

showDoc

Display the run-time documentation for the specific implementation of the molecular potential.

methods (Access=?QMol_SEq)
function ref = showDoc(obj)
%showDoc displays the documentation reflecting the specific implementation
%   of the SE model
    
    % Add specific documentation here

end
end

• If no reference is cited, return ref = {} otherwise ref = {'ref 1','ref 2',___}, where each of the ref corresponds to the bibliographic code for the reference (generally of the form 'name_of_first_author publication_year') and is case insensitive -- see the documentation page for a list of citable references.
• Note that only implementation-specific properties should be covered here. All properties common to all SE models (e.g., electronic structure) are handled in the parent QMol_SEq class run-time documentation.

Test suite

For consistency with the rest of the QMol-grid package, QMol_SEq defines an associated test suite. Run the test suite for the class in normal or summary mode respectively with

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

See QMol_test for details regarding how to create a test suite for new classes.

Notes

• QMol_SEq was introduced in version 01.20.