QMol_DFT_eigs - fmauger1/QMol-grid GitHub Wiki
QMol_DFT_eigs
Eigen-state solver for DFT models.
Description
Use QMol_DFT_eigs to compute the eigen states of a DFT Hamiltonian operator
$$ {\hat{\mathcal{H}} }_{{\mathrm{D}\mathrm{F}\mathrm{T}}} \left\lbrack \lbrace \phi_k \rbrace_k \right\rbrack ~\psi_l =E_l ~\psi_l ,~~{\mathrm{f}\mathrm{o}\mathrm{r}}~~l=1,2,\ldots~~~~~~(1) $$
where $\lbrace \phi_k \rbrace_k$ are the Kohn-Sham orbitals of the DFT model and $\lbrace \psi_l \rbrace_l$ are the eigen states, with eigen values $\lbrace E_l \rbrace_l$ . The DFT-Hamiltonian operator is assumed Hermitian and QMol_DFT_eigs returns real-valued eigen values/states. Note that the eigenstates computed by QMol_DFT_eigs may not correspond to the system's molecular orbitals for which $\phi_k =\psi_k$ . Those types of calculations are handled by a self-consistent-field (SCF) solver like QMol_DFT_SCF_Anderson. QMol_DFT_eigs is a handle class.
Most users only create QMol_DFT_eigs object, with selected class properties, to pass to the SCF solver without directly interacting with any of the class methods.
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 DFT 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 Kohn-Sham orbitals- If
SubspaceDimensionis too large -- larger than the effective dimension of the discrete problem --QMol_DFT_eigsinstead uses the problem's dimension.
Display (disp)
Display diagnostic information [ true | false (default) ]
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 SCF 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 Kohn_sham orbitals in the DFT model. - For spin-polarized DFT models, specify the up- and down-spin symmetries in a cell
{Symmetry_up, Symmetry_down}where each of theSymmetry_upandSymmetry_downstrings follow the above-listed requirements.
Other properties
To facilitate simulations, QMol_DFT_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 DFT eigen-state solver object with empty class properties.
obj = QMol_DFT_eigs;
Create a DFT 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 DFT-model properties and is case insensitive.
obj = QMol_DFT_eigs(name1,value1);
obj = QMol_DFT_eigs(name1,value1,name2,value2,___);
Changing class properties
set
Update the name properties of aDFT 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_DFT_eigs object and set the isInitialized flag to true
obj.initialize(DFT);
DFTis the DFT-model handle object, i.e.,QMol_DFT_spinPolorQMol_DFT_spinRes, that describes the DFT 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_DFT_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
computeEigenstates
Compute the eigen states and energies of Eq. (1) with either
E = obj.computeEigenstates;
E = obj.computeEigenstates([]);
- For spin-restricted DFT models,
Eis a vectors containing the respective energies of the computed eigen states. For spin-polarized DFT models,E = {E_up,E_down}are the up- and down-spin channel energies, respectively. - Note that only the energies are returned; the eigen states are stored in the DFT object used to
initializethe object, i.e.,computeEigenstatesoverwrites the DFT-model Kohn sham orbitals. - This forces the computation of the computation of the DFT-model Kohn-Sham potential.
Specify the Kohn-Sham potential to use in the eigen-state computation with
E = obj.computeEigenstates(Vks);
Vksis a compatible Kohn-Sham potential
Examples
Simple eigen-state computation
First we create a spin-restricted DFT models
% 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',3,'position',2);
% DFT potential components
Vext= QMol_DFT_Vext('atom',{A1,A2});
Vh = QMol_DFT_Vh_conv;
Vxc = QMol_DFT_Vx_LDA_exp;
% Spin-restricted DFT model
DFT = QMol_DFT_spinRes( ...
'xspan', x, ...
'occupation', [2 2 1],...
'externalPotential', Vext, ...
'HartreePotential', Vh, ...
'exchangeCorrelationPotential', Vxc);
DFT.initialize;
Next, we create the eigen-state solver object, initialize it, and access its run-time documentation
eigSt = QMol_DFT_eigs;
eigSt.initialize(DFT);
eigSt.showDocumentation;
yielding
* Eigen-state solver for DFT Hamiltonians MATLAB eigs function
Tolerance = 1e-12
Max. iter. = 300
Basis dim. = 100
V-01.21.000 (06/17/2024) F. Mauger
We can now compute the eigen-states and energies of Eq. (1)
E = eigSt.computeEigenstates
which gives
E =
-2.954096176667686
-2.933903112075727
-2.148472642273518
Again, because the eigen-state computation is performed with the (initial) electronic structure in the DFT object -- rather than self consistently -- the updated set of Kohn-Sham orbitals is not an eigen-state of the DFT Hamiltonian operator. We can check this by displaying the orbital energies and errors
DFT.showEnergy('orbital');
yielding
Orbital Occ. (elec.) Energy (-eV) Error(a.u.)
------- ------------ ------------ -----------
1 2.00 34.483 1.139e-01
2 2.00 34.097 1.181e-01
3 1.00 13.625 1.528e-01
------------------------------------------------------------------------
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',3,'position',-3);
A2 = QMol_Va_softCoulomb('name','atom 2','charge',3,'position',3);
% DFT potential components
Vext= QMol_DFT_Vext('atom',{A1,A2});
Vh = QMol_DFT_Vh_conv;
Vxc = QMol_DFT_Vx_LDA_exp;
% Spin-restricted DFT model
DFT = QMol_DFT_spinRes( ...
'xspan', x, ...
'occupation', [2 2 1],...
'externalPotential', Vext, ...
'HartreePotential', Vh, ...
'exchangeCorrelationPotential', Vxc);
DFT.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_DFT_eigs('Symmetry','2 Sx + Ax');
eigSt.initialize(DFT);
eigSt.showDocumentation;
yielding (note the added symmetry information as compared to above)
* Eigen-state solver for DFT Hamiltonians MATLAB eigs function
Tolerance = 1e-12
Max. iter. = 300
Basis dim. = 100
State sym. = 2 Sx + 1 Ax
V-01.21.000 (06/17/2024) F. Mauger
We can now compute the eigen-states and energies of Eq. (1)
E = eigSt.computeEigenstates
which gives
E =
-2.841467033665281
-2.837538418285015
-1.978965635739010
One more time, the result is not an eigen-state of the DFT Hamiltonian operator:
DFT.showEnergy('orbital');
yielding
Orbital Occ. (elec.) Energy (-eV) Error(a.u.)
------- ------------ ------------ -----------
1 2.00 34.481 9.767e-02
2 2.00 34.374 9.837e-02
3 1.00 13.425 1.177e-01
------------------------------------------------------------------------
Test suite
Run the test suite for the class in normal or summary mode respectively with
QMol_test.test('DFT_eigs');
QMol_test.test('-summary','DFT_eigs');
For developers
Other hidden class properties
QMol_DFT_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).
DFT
DFT-model object [ [] (default) | QMol_DFT_spinPol handle object | QMol_DFT_spinRes handle object ]
- This is a copy of the DFT-model handle object passed to
initialize. - Un-initialized
QMol_DFT_eigsobjects, i.e.,isInitialized == false, have emptyDFT.
symState
Identified symmetry configuration [ [] (default) | array | cell ]
- After a
QMol_DFT_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. - For spin-polarized models,
symState = {symState_up, symState_down}specifies the up- and down-spin symmetry configurations, respectively.
Notes
The results displayed in this documentation page were generated using version 01.21 of the QMol-grid package.
QMol_DFT_eigswas introduced in version 01.00.