QMol_SE_eigs

`QMol_SE_eigs`

Eigen-state solver for Schrödinger-equation models.

Description

Use QMol_SE_eigs to compute the eigen states of a Schrödinger-equation (SE) Hamiltonian operator

$$ \hat{\mathcal{H}} \psi_k =E_k ~\psi_k ,~~{\mathrm{f}\mathrm{o}\mathrm{r}}~~k=1,2,\ldots~~~~~~(1) $$

where $\lbrace \psi_k \rbrace_k$ are the eigen states, with eigen values $\lbrace E_k \rbrace_k$ . The SE-Hamiltonian operator is assumed Hermitian and QMol_SE_eigs returns real-valued eigen values/states. The quantum ground state corresponds to the eigen state with lowest energy. QMol_SE_eigs is a handle class.

Class properties

Eigen solver

The eigen solver uses MATLAB eigs function and duplicates its options (using the same names); see the eigs documentation for details. Each eigen-solver property can be changed using the set method:

`IsFunctionSymmetric (issym)`

Symmetry of the SE Hamiltonian operator [ true (default) | false ]

This property is only implemented for completeness and should always be true. Setting IsFunctionSymmetric = false triggers a warning and may lead to erroneous results.

Tolerance (tol)

Convergence tolerance [ nonnegative scalar (1e-12) ]

`MaxIterations (maxit)`

Maximum number of iterations [ nonnegative integer (300) ]

`SubspaceDimension (p)`

Number of Lanczos basis vectors [ nonnegative integer (100) ]

SubspaceDimension must be larger than the number of wave functions
If SubspaceDimension is too large -- larger than the effective dimension of the discrete problem -- QMol_SE_eigs instead uses the problem's dimension.

`Display (disp)`

Display diagnostic information [ 'iter' | 'final' (default) | 'none' ]

Display = 'iter' displays both the eigen-state information and MATLAB eigs diagnostic information.
Display = 'final' displays the eigen-state information: calculation parameters and analysis of results.
Display = 'none' does not display any information.

`Symmetry (sym)`

Symmetry of the eigen states [ string | [] (default) ]

For problems with a symmetric target, specify the symmetry of the wave functions. This can help converge eigen state calculations.
Note that the specified symmetry must be strictly enforced in the discrete problem -- i.e., a perfectly symmetric target that is exactly centered in the simulation domain (along the requested symmetry directions).
For 1D models, the syntax of the Symmetry option is '# Sx + # Ax', where # specifies the umber of symmetric (Sx) and antisymmetric (Ax) eigen states. If only one state in the specified symmetry subspace is requested, the number # can be omitted ('Sx' is equivalent to '1 Sx') and if no state is requested, the symmetry can be ignored altogether ('# Sx' alone is equivalent to '# Sx + 0 Ax'). The two symmetry subgroups can be specified in arbitrary order ('# Sx + # Ax' is equivalent to '# Ax + # Sx'). The sum of the number of states in each sub group should match the number of wave functions in the Schrödinger-equation model.

Other properties

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

`isInitialized (isInit)`

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

Class methods

Creation

constructor

Create a Schrödinger-equation eigen-state solver object with empty class properties.

obj = QMol_SE_eigs;

Create a Schrödinger-equation eigen-state solver object with the name properties set to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the eigen solver properties and is case insensitive.

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

Changing class properties

`set`

Update the name properties of a Schrödinger-equation eigen-state solver object to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the eigen-solver 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 eigen-solver 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.

Initializing the object

`initialize`

Initialize a QMol_SE_eigs object and set the isInitialized flag to true

obj.initialize(SE);

SE is the Schrödinger-equation handle object, i.e., QMol_SE, that describes the SE Hamiltonian operator of Eq. (1)
To avoid any mismatch in internal properties, initialize first reset the object before performing the initialization

Run-time documentation

`showDocumentation`

Display the run-time documentation for the specific configuration of a QMol_SE_eigs object, which must have been initialized beforehand

ref = obj.showDocumentation;

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

Eigen-state computation

`computeGroundState`

Compute the lowest-energy eigen states of Eq. (1) with

obj.computeGroundState(SE);

SE is the Schrödinger-equation handle object, i.e., QMol_SE, that describes the SE Hamiltonian operator of Eq. (1)
To avoid any mismatch in internal properties, computeGroundState first reset the object and (re)initializes the SE before performing the eigen-state calculation.
The result wave functions are stored in the input SE object (in SE.wavefunction).
To get the eigen energy, use SE.getEnergy('wave function').

Examples

Simple eigen-state computation

First we create a Schrödinger-equation model

% Domain and atomic centers
x   =   -20:.1:15;
A1  =   QMol_Va_softCoulomb('name','atom 1','charge',3,'position',-3);
A2  =   QMol_Va_softCoulomb('name','atom 2','charge',2,'position',2);

% Potential
V   =   QMol_SE_V('atom',{A1,A2});

% Schrodinger-equation model
SE  =   QMol_SE(                        ...
            'xspan',                x,  ...
            'numberWaveFunction',   3,  ...
            'potential',            V);
SE.initialize;

Next, we create the eigen-state solver object and compute the ground state

eigSt = QMol_SE_eigs;
eigSt.computeGroundState(SE);

yielding

=== Build Schrodinger-equation (SE) model ================================
  * Discretization                                                      OK
  * Wave function(s)                                                    OK
  * Potential                                                           OK

  * Eigen-state solver for SE Hamiltonians            MATLAB eigs function
    Tolerance  = 1e-12 
    Max. iter. = 300
    Basis dim. = 100
    V-01.21.001 (07/01/2024)                                     F. Mauger

=== References ===========================================================
  [Mauger 2024b] F. Mauger and C. Chandre, "QMol-grid: A MATLAB package
    for quantum-mechanical simulations in atomic and molecular systems," 
    arXiv:2406.17938 (2024).

=== Funding ==============================================================
    The original development of the QMol-grid toolbox, and its (TD)DFT
  features, was supported by the U.S. Department of Energy, Office of
  Science, Office of Basic Energy Sciences, under Award No. DE-SC0012462.
    Addition of the (TD)SE features was supported by the National Science
  Foundation under Grant No. PHY-2207656.

=== Wave-function energies ===============================================
  Wave fcn      Energy (-eV)         Error(a.u.)
  --------     ------------          -----------
      1           74.539              2.563e-13
      2           57.397              2.944e-13
      3           49.267              2.922e-13
  ----------------------------------------------

=== Schrodinger-equation-component energies ==============================
  Component      Energy (a.u.)      Energy (eV)
  -----------    -------------     -------------
  Kinetic             0.886             24.105
  Potential          -7.545           -205.308
  -----------    -------------     -------------
  Total              -6.659           -181.203
  ----------------------------------------------

##########################################################################

To finish with, we can plot resulting wave functions

figure; hold on
plot(SE.xspan,SE.wfcn.wfcn(:,1),'-','LineWidth',2,'DisplayName','wfcn #1')
plot(SE.xspan,SE.wfcn.wfcn(:,2),'-','LineWidth',2,'DisplayName','wfcn #2')
plot(SE.xspan,SE.wfcn.wfcn(:,3),'-','LineWidth',2,'DisplayName','wfcn #3')
xlabel('position (a.u.)'); xlim(SE.xspan([1 end]));
ylabel('wave function')
legend show

which gives

Impose eigen-state symmetry

We briefly modify the previous example to make it symmetric

% Domain and atomic centers
x   =   -20:.1:20;
A1  =   QMol_Va_softCoulomb('name','atom 1','charge',1.5,'position',-3);
A2  =   QMol_Va_softCoulomb('name','atom 2','charge',1.5,'position',3);

% Potential
V   =   QMol_SE_V('atom',{A1,A2});

% Schrodinger-equation model
SE  =   QMol_SE(                        ...
            'xspan',                x,  ...
            'numberWaveFunction',   3,  ...
            'potential',            V);
SE.initialize;

Next, we create the eigen-state solver with a specific symmetry configuration (2 symmetric and one antisymmetric states), initialize it, and access its run-time documentation

eigSt = QMol_SE_eigs('Symmetry','2 Sx + Ax');
eigSt.computeGroundState(SE);

yielding (note the added symmetry information as compared to above)

=== Build Schrodinger-equation (SE) model ================================
  * Discretization                                                      OK
  * Wave function(s)                                                    OK
  * Potential                                                           OK

  * Eigen-state solver for SE Hamiltonians            MATLAB eigs function
    Tolerance  = 1e-12 
    Max. iter. = 300
    Basis dim. = 100
    State sym. = 2 Sx + 1 Ax
    V-01.21.001 (07/01/2024)                                     F. Mauger

=== References ===========================================================
  [Mauger 2024b] F. Mauger and C. Chandre, "QMol-grid: A MATLAB package
    for quantum-mechanical simulations in atomic and molecular systems," 
    arXiv:2406.17938 (2024).

=== Funding ==============================================================
    The original development of the QMol-grid toolbox, and its (TD)DFT
  features, was supported by the U.S. Department of Energy, Office of
  Science, Office of Basic Energy Sciences, under Award No. DE-SC0012462.
    Addition of the (TD)SE features was supported by the National Science
  Foundation under Grant No. PHY-2207656.

=== Wave-function energies ===============================================
  Wave fcn      Energy (-eV)         Error(a.u.)
  --------     ------------          -----------
      1           36.312              4.003e-13
      2           35.824              3.447e-13
      3           23.257              2.542e-13
  ----------------------------------------------

=== Schrodinger-equation-component energies ==============================
  Component      Energy (a.u.)      Energy (eV)
  -----------    -------------     -------------
  Kinetic             0.531             14.457
  Potential          -4.037           -109.850
  -----------    -------------     -------------
  Total              -3.506            -95.393
  ----------------------------------------------

##########################################################################

Again plotting the wave functions

figure; hold on
plot(SE.xspan,SE.wfcn.wfcn(:,1),'-','LineWidth',2,'DisplayName','wfcn #1')
plot(SE.xspan,SE.wfcn.wfcn(:,2),'-','LineWidth',2,'DisplayName','wfcn #2')
plot(SE.xspan,SE.wfcn.wfcn(:,3),'-','LineWidth',2,'DisplayName','wfcn #3')
xlabel('position (a.u.)'); xlim(SE.xspan([1 end]));
ylabel('wave function')
legend show

Test suite

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

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

For developers

Other hidden class properties

QMol_SE_eigs 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`

Schrodinger-equation-model object [ [] (default) | QMol_SE handle object ]

This is a copy of the SE-model handle object passed to initialize.
Un-initialized QMol_SE_eigs objects, i.e., isInitialized == false , have empty SE.

`symState`

Identified symmetry configuration [ [] (default) | array ]

After a QMol_SE_eigs object is initialized, this describes the symmetry configuration to impose in eigen-state computations.
For 1D models, symState is a 2-by-n matrix where each column specifies (i) the number of states (first row) and (ii) the symmetry of the states (second row), with -1 for antisymmetric, 0 for no symmetry imposed, and 1 for symmetric.

Notes

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

QMol_SE_eigs was introduced in version 01.20.

This wiki is a copy of the documentation provided with the QMol-grid package (accessible in MATLAB documentation, via the "Supplemental Software" section).
Copyright © 2024, Francois Mauger, all right reserved.