QMol_DFT_orbital - fmauger1/QMol-grid GitHub Wiki

QMol_DFT_orbital

One-body-density object

Description

Use QMol_DFT_orbital to store Kohn-Sham orbitals for (TD)DFT simulations. QMol_DFT_orbital is a handle class.

Class properties

Kohn-Sham orbitals

The QMol_DFT_orbital class defines the following public get-access properties; each can be changed using the set method:

orbital (KSO)

Discretization of the Kohn-Sham orbitals [ matrix (default []) ]

  • For spin restricted DFT model; irrelevant for spin polarized ones
  • Properly allocated orbital is a numel(disc.xspan)-by-N matrix, where N is the number of orbitals and matching the domain discretization of the associated (TD)DFT model

orbitalUp (KSOup)

Discretization of the up-spin channel Kohn-Sham orbitals [ matrix (default []) ]

  • For spin polarized DFT model; irrelevant for spin restricted ones
  • Properly allocated orbitalUp is a numel(disc.xspan)-by-Nup matrix, where Nup is the number of orbitals in the up-spin channel and matching the domain discretization of the associated (TD)DFT model

orbitalDown (KSOdw)

Discretization of the down-spin channel Kohn-Sham orbitals [ matrix (default []) ]

  • For spin polarized DFT model; irrelevant for spin restricted ones
  • Properly allocated orbitalDown is a numel(disc.xspan)-by-Ndw matrix, where Ndw is the number of orbitals in the down-spin channel and matching the domain discretization of the associated (TD)DFT model

isSpinPol

Whether the Kohn-Sham orbitals are spin polarized (true) or spin restricted (false). isSpinPol is used by other classes to determine whether they should use the orbital or orbitalUp and orbitalDown properties in their calculations.

Other properties

These properties cannot be edited with the set method.

isInitialized (isInit)

Whether the orbital object is properly initialized. This is used throughout the QMol-grid package to check that the orbitals object holds meaningful information and is ready for use.

isBasis

Flag indicating that QMol_DFT_orbital objects are not a discretization over a basis set [ false ]

  • At run time, isBasis can be used to discriminate QMol_DFT_orbital objects from QMol_DFT_orbital_basis (which overloads the class)
  • For class development purposes, isBasis is technically a static method. Practically, though, it can virtually almost always be treated as a constant property.

Class methods

Creation

constructor

Create a Kohn-Sham orbitals object with empty class properties.

obj = QMol_DFT_orbital;

Create a Kohn-Sham orbitals object with the name properties set to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the Kohn-Sham orbitals properties and is case insensitive.

obj = QMol_DFT_orbital(name1,value1);
obj = QMol_DFT_orbital(name1,value1,name2,value2,___);

Changing class properties

set

Update the name properties of a Kohn-Sham orbitals object to the specified value. Several name-value pairs can be specified consecutively. Suitable name is any of the Kohn-Sham orbitals 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 reset method 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 Kohn-Sham orbitals 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. The clear method can be used to delete specific properties before saving an instance of the QMol_DFT_orbital class.

Initializing the object

initialize

Minimally initialize a Kohn-Sham orbitals objects and set the isInitialized flag to true

obj.initialize;
  • To avoid any mismatch in internal properties, initialize first reset the object before performing the initialization

Future development my require access to the associated domain-discretization object, which can be provided at initialization

obj.initialize(disc);

Run-time documentation

getMemoryProfile

Get an estimate of the memory held by a QMol_DFT_orbital object with either

mem = obj.getMemoryProfile;
mem = obj.getMemoryProfile(false);
  • The object must be properly initialized with a domain discretization.
  • The estimate only includes the discretization of the orbitals on the domain grid and ignores other (small) properties.
  • The output mem is the estimated size in bytes.

Additionally display the detail of the memory footprint with

mem = obj.getMemoryProfile(true);

Comparing orbitals

The class overloads the == and ~= operators to facilitate the comparison between orbitals objects

eq (==)

Test if two Kohn-Sham orbitals objects describe the same density

obj1 == obj2
  • For spin-restricted objects, it is defined as both objects holding the same number of orbitals and all(abs(data1.orbital-data2.orbital) <= eqTol,'all')
  • For spin-polarized objects, it is defined as both objects holding the same numbers of up- and down-spin orbitals and all(abs(data1.orbitalUp-data2.orbitalUp) <= eqTol,'all') && all(abs(data1.orbitalDown-data2.orbitalDown) <= eqTol,'all')
  • eqTol = 1e-10 is a tolerance parameter to account for possible roundoff mismatch between two orbitals objects.
  • Any mismatch in the size of the two objects orbitals components or spin-polarized/restricted returns a false result.
  • If both Kohn-SHam orbitals objects have been initialized with a domain-discretization object. The equality operator also checks that the to orbitals objects have the same domain discretization obj1.disc == obj2.disc.

ne (~=)

Test if two Kohn-Sham orbitals objects describe different densities

obj1 ~= obj2

It is equivalent to ~(obj1 == obj2) .

Examples

Most end users will get Kohn-Sham orbitals objects indirectly, through DFT and TDDFT simulations -- see their respective documentations for examples.

Test suite

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

QMol_test.test('DFT_orbital');
QMol_test.test('-summary','DFT_orbital');

For developers

QMol_DFT_orbital implements a streamlined version of the clear all method, since it might be called frequently in DFT and TDDFT computations. If adding properties to the class, the streamlined clear all must be updated accordingly.

After initialization, the domain discretization is stored in the transient property disc. The current version of QMol_DFT_orbital does not use this property; it is implemented for support in future development of the QMol-grid package. Like for QMol_DFT_density, future versions might remove the transient nature of disc.

QMol_DFT_orbital overloads QMol_suite.

Notes

  • QMol_DFT_orbital was introduced in version 01.00
  • Version 01.10 integrated initialization with a domain discretization object
  • getMemoryProfile was introduced in version 01.10