QMol_SE_eigs - fmauger1/QMol-grid GitHub Wiki
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. SettingIsFunctionSymmetric = falsetriggers 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) ]
SubspaceDimensionmust be larger than the number of wave functions- If
SubspaceDimensionis too large -- larger than the effective dimension of the discrete problem --QMol_SE_eigsinstead uses the problem's dimension.
Display (disp)
Display diagnostic information [ 'iter' | 'final' (default) | 'none' ]
Display = 'iter'displays both the eigen-state information andMATLABeigsdiagnostic 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
Symmetryoption 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
resetmethod 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,
initializefirstresetthe 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
refis 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,
computeGroundStatefirstresetthe object and (re)initializes theSEbefore performing the eigen-state calculation. - The result wave functions are stored in the input
SEobject (inSE.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_eigsobjects, i.e.,isInitialized == false, have emptySE.
symState
Identified symmetry configuration [ [] (default) | array ]
- After a
QMol_SE_eigsobject isinitialized, this describes the symmetry configuration to impose in eigen-state computations. - For 1D models,
symStateis 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_eigswas introduced in version 01.20.