# QMol_DFT_eig_basis - fmauger1/QMol-grid GitHub Wiki

`QMol_DFT_eig_basis`

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

# Description

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

## Creation

### constructor

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

```
obj = QMol_DFT_eig_basis;
```

## Initializing the object

`initialize`

Initialize a `QMol_DFT_eig_basis`

object and set the `isInitialized`

flag to `true`

```
obj.initialize(DFT);
```

`DFT`

is the DFT-model handle object,*i.e.*,`QMol_DFT_spinPol`

or`QMol_DFT_spinRes`

, that describes the DFT Hamiltonian operator of Eq. (1)

## Run-time documentation

`showDocumentation`

Display the run-time documentation for the specific configuration of a `QMol_DFT_eigs`

object, which must have been `initialize`

d 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

`computeEigenstates`

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

# 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);
% 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;
% 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);
DFT.initialize;
```

Next, we create the eigen-state solver object, `initialize`

it, and access its run-time documentation

```
eigSt = QMol_DFT_eig_basis;
eigSt.initialize(DFT);
eigSt.showDocumentation;
```

yielding

```
* 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 =
-2.939619364189480
-2.927121774999187
-2.018312725404784
```

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

```
QMol_test.test('DFT_eig_basis');
QMol_test.test('-summary','DFT_eig_basis');
```

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

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

# Notes

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.