QMol_DFT_eig_basis - fmauger1/QMol-grid GitHub Wiki


Eigen-state solver for DFT models with basis-set discretization.


Use QMol_DFT_eig_basis to compute the eigen states of a DFT Hamiltonian operator

$$ \mathcal{P}{\hat{\mathcal{H}} }_{{\mathrm{D}\mathrm{F}\mathrm{T}}} \left\lbrack \lbrace \phi_k \rbrace_k \right\rbrack {\mathcal{P}}^{\dagger} ~\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$ , and $\mathcal{P}$ is the orthogonal projection on the hull of the basis-set discretization. QMol_DFT_eig_basis performs a full diagonalization of the Hamiltonian matrix $\mathcal{P}{\hat{\mathcal{H}} }_{{\mathrm{D}\mathrm{F}\mathrm{T}}} \left\lbrack \lbrace \phi_k \rbrace_k \right\rbrack {\mathcal{P}}^{\dagger}$ using MATLAB eig function. The DFT-Hamiltonian operator is assumed Hermitian and QMol_DFT_eig_basis returns real-valued eigen values/states. Note that the eigenstates computed by QMol_DFT_eig_basis 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_eig_basis is a handle class.

Most users only create QMol_DFT_eig_basis object, with selected class properties, to pass to the SCF solver without directly interacting with any of the class methods.

Class properties

QMol_DFT_eig_basis does not define any properties for end users to change. To facilitate simulations, it defines the transient property

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



Create a DFT eigen-state solver object with empty class properties.

obj = QMol_DFT_eig_basis;

Initializing the object


Initialize a QMol_DFT_eig_basis object and set the isInitialized flag to true


Run-time documentation


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 ref is a cell vector containing the list of references to be included in the bibliography.

Eigen-state computation


Compute the eigen states and energies of Eq. (1) with either

E = obj.computeEigenstates;
E = obj.computeEigenstates([]);
  • For spin-restricted DFT models, E is 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 initialize the object, i.e., computeEigenstates overwrites 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);
  • Vks is a compatible Kohn-Sham potential


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);
% 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), ...

% Discretization domain
disc=   QMol_disc_basis('x',x,'basis',V);

% 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(                           ...
            'discretization',               disc,   ...
            'occupation',                   [2 2 1],...
            'externalPotential',            Vext,   ...
            'HartreePotential',             Vh,     ...
            'exchangeCorrelationPotential', Vxc);

Next, we create the eigen-state solver object, initialize it, and access its run-time documentation

eigSt = QMol_DFT_eig_basis;


  * Eigen-state solver for DFT Hamiltonians            MATLAB eig function
    using a direct diagonalization of the DFT Hamiltonian matrix.
    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 =


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



  Orbital      Occ. (elec.)         Energy (-eV)               Error(a.u.)
  -------      ------------         ------------               -----------
      1            2.00                35.488                   1.002e-01
      2            2.00                35.071                   1.001e-01
      3            1.00                14.701                   1.482e-01

Test suite

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


For developers

Other hidden class properties

QMol_DFT_eig_basis defines a handful of additional transient and hidden properties to facilitate and speed up computations. These properties cannot be edited by any function outside of the object (SetAccess=private attribute).


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_eigs objects, i.e., isInitialized == false , have empty DFT.


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

  • QMol_DFT_eig_basis was introduced in version 01.00.