QMol_SE_eig_basis - fmauger1/QMol-grid GitHub Wiki
QMol_SE_eig_basis
Eigen-state solver for Schrödinger-equation models with basis-set discretization.
Description
Use QMol_SE_eig_basis to compute the eigen states of a Schrödinger-equation (SE) Hamiltonian operator
$$ \mathcal{P}\hat{\mathcal{H}} {\mathcal{P}}^{\dagger} \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$ , and $\mathcal{P}$ is the orthogonal projection on the hull of the basis-set discretization. QMol_SE_eig_basis performs a full diagonalization of the Hamiltonian matrix $\mathcal{P}\hat{\mathcal{H}} {\mathcal{P}}^{\dagger}$ using MATLAB eig function. The Schrödinger-equation-Hamiltonian operator is assumed Hermitian and QMol_SE_eig_basis produces 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 QMol_SE_eig_basis class defines the following public get-access properties; each can be changed using the set method:
display (disp)
Whether to display the ground-state calculation progress and results [ true (default) | false ]
Other properties
To facilitate simulations, QMol_SE_eig_basis 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_eig_basis;
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_eig_basis(name1,value1);
obj = QMol_SE_eig_basis(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_eig_basis 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_eig_basis 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);
% Atomic orbital vectors
AO = @(s,n,x0,x) (x(:)-x0).^n .*exp(-(x(:)-x0).^2 * .5/s^2);
V = [AO(1.3,0,A1.position,x),AO(1.7,1,A1.position,x),AO(0.8,2,A1.position,x), ...
AO(1.3,0,A2.position,x),AO(1.7,1,A2.position,x),AO(0.8,2,A2.position,x)];
% Discretization domain
disc= QMol_disc_basis('x',x,'basis',V);
disc.orthonormalizeBasis;
% Potential
V = QMol_SE_V('atom',{A1,A2});
% Schrodinger-equation model
SE = QMol_SE( ...
'discretization', disc, ...
'numberWaveFunction', 3, ...
'potential', V);
SE.initialize;
Next, we create the eigen-state solver object and compute the ground state
eigSt = QMol_SE_eig_basis;
eigSt.computeGroundState(SE);
yielding
=== Build Schrodinger-equation (SE) model ================================
* Discretization OK
* Wave function(s) OK
* Potential OK
* Eigen-state solver for SE Hamiltonians MATLAB eig function
using a direct diagonalization of the Hamiltonian matrix.
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.196 1.048e-15
2 57.267 5.937e-16
3 46.252 9.803e-16
----------------------------------------------
=== Schrodinger-equation-component energies ==============================
Component Energy (a.u.) Energy (eV)
----------- ------------- -------------
Kinetic 0.679 18.467
Potential -7.210 -196.183
----------- ------------- -------------
Total -6.531 -177.715
----------------------------------------------
##########################################################################
Test suite
Run the test suite for the class in normal or summary mode respectively with
QMol_test.test('SE_eig_basis');
QMol_test.test('-summary','SE_eig_basis');
For developers
Other hidden class properties
QMol_SE_eig_basiss 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.
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.