PEXSI
PEXSI::PPEXSIData Class Reference

Main class for parallel PEXSI. More...

#include <ppexsi.hpp>

## Public Member Functions

PPEXSIData (MPI_Comm comm, Int numProcRow, Int numProcCol, Int outputFileIndex)

void LoadRealSymmetricMatrix (Int nrows, Int nnz, Int nnzLocal, Int numColLocal, Int *colptrLocal, Int *rowindLocal, Real *HnzvalLocal, Int isSIdentity, Real *SnzvalLocal, Int verbosity)

void SymbolicFactorizeRealSymmetricMatrix (std::string ColPerm, Int numProcSymbFact, Int verbosity)
Symbolically factorize the loaded matrices for real arithmetic factorization and selected inversion. More...

void SymbolicFactorizeComplexSymmetricMatrix (std::string ColPerm, Int numProcSymbFact, Int verbosity)
Symbolically factorize the loaded matrices for complex arithmetic factorization and selected inversion. More...

void SelInvRealSymmetricMatrix (double *AnzvalLocal, Int verbosity, double *AinvnzvalLocal)

void SelInvComplexSymmetricMatrix (double *AnzvalLocal, Int verbosity, double *AinvnzvalLocal)

void CalculateNegativeInertiaReal (const std::vector< Real > &shiftVec, std::vector< Real > &inertiaVec, Int verbosity)
Compute the negative inertia (the number of eigenvalues below a shift) for real symmetric matrices. The factorization. More...

void CalculateFermiOperatorReal (Int numPole, Real temperature, Real gap, Real deltaE, Real mu, Real numElectronExact, Real numElectronTolerance, Int verbosity, Real &numElectron, Real &numElectronDrvMu)
Compute the Fermi operator for a given chemical potential for real symmetric matrices. More...

void DFTDriver (Real numElectronExact, Real temperature, Real gap, Real deltaE, Int numPole, Int isInertiaCount, Int maxPEXSIIter, Real muMin0, Real muMax0, Real mu0, Real muInertiaTolerance, Real muInertiaExpansion, Real muPEXSISafeGuard, Real numElectronPEXSITolerance, Int matrixType, Int isSymbolicFactorize, Int ordering, Int numProcSymbFact, Int verbosity, Real &muPEXSI, Real &numElectronPEXSI, Real &muMinInertia, Real &muMaxInertia, Int &numTotalInertiaIter, Int &numTotalPEXSIIter)
Main driver for solving KSDFT.

const GridTypeGridPole () const

const DistSparseMatrix< Real > & RhoRealMat () const
Density matrix. More...

const DistSparseMatrix< Real > & EnergyDensityRealMat () const
Energy density matrix. More...

const DistSparseMatrix< Real > & FreeEnergyDensityRealMat () const
Total Helmholtz free energy matrix (band energy part only). More...

Real TotalEnergyH () const

Real TotalEnergyS () const

Real TotalFreeEnergy () const

PPEXSIData (const PEXSI::GridType *g, Int nprow, Int npcol)

void Solve (Int numPole, Real temperature, Real numElectronExact, Real gap, Real deltaE, Real &mu, Real &muMin, Real &muMax, const DistSparseMatrix< Real > &HMat, const DistSparseMatrix< Real > &SMat, Int muMaxIter, Real numElectronTolerance, std::string ColPerm, Int numProcSymbFact, bool isFreeEnergyDensityMatrix, bool isEnergyDensityMatrix, bool isDerivativeTMatrix, std::vector< Real > &muList, std::vector< Real > &numElectronList, std::vector< Real > &numElectronDrvMuList, bool &isConverged)
Solve is the main subroutine for PPEXSI. More...

DistSparseMatrix< Real > & DensityMatrix ()
DensityMatrix returns the single particle density matrix.

DistSparseMatrix< Real > & FreeEnergyDensityMatrix ()
DensityMatrix returns the free energy density matrix.

DistSparseMatrix< Real > & EnergyDensityMatrix ()
DensityMatrix returns the energy density matrix for computing the force.

Real CalculateNumElectron (const DistSparseMatrix< Real > &SMat)
CalculateNumElectron computes the number of electrons given the current density matrix. More...

Real CalculateNumElectronDrvMu (const DistSparseMatrix< Real > &SMat)
CalculateNumElectronDrvMu computes the derivative of the number of electrons with respect to the chemical potential. More...

Real CalculateNumElectronDrvT (const DistSparseMatrix< Real > &SMat)
CalculateNumElectronDrvT computes the derivative of the number of electrons with respect to the temperature (1/beta, in atomic unit). More...

Real CalculateTotalEnergy (const DistSparseMatrix< Real > &HMat)
CalculateTotalEnergy computes the total energy (band energy part only). More...

Real CalculateFreeEnergy (const DistSparseMatrix< Real > &SMat)
CalculateFreeEnergy computes the total Helmholtz free energy (band energy part only). More...

Real CalculateForce (const DistSparseMatrix< Real > &HDerivativeMat, const DistSparseMatrix< Real > &SDerivativeMat)
CalculateFreeEnergy computes the force, including the Hellman-Feynman force and the Pulay force. More...

Real EstimateZeroTemperatureChemicalPotential (Real temperature, Real mu, const DistSparseMatrix< Real > &SMat)
Estimate the chemical potential at zero temperature using quadratic approximation. More...

void CalculateNegativeInertia (const std::vector< Real > &shiftVec, std::vector< Real > &inertiaVec, const DistSparseMatrix< Real > &HMat, const DistSparseMatrix< Real > &SMat, std::string ColPerm, Int numProcSymbFact)
Compute the negative inertia (the number of eigenvalues below a shift). More...

void CalculateNegativeInertiaReal (const std::vector< Real > &shiftVec, std::vector< Real > &inertiaVec, const DistSparseMatrix< Real > &HMat, const DistSparseMatrix< Real > &SMat, std::string ColPerm, Int numProcSymbFact)
Compute the negative inertia (the number of eigenvalues below a shift) with real arithmetic which directly using SuperLU.

void EstimateSpectralRadius (Int method, const DistSparseMatrix< Real > &HMat, const DistSparseMatrix< Real > &SMat, const NumVec< Real > &v0, Real tol, Int maxNumIter, Int &numIter, Real &sigma)
Estimate the spectral radius of the matrix stencil (H,S). More...

## Detailed Description

Main class for parallel PEXSI.

## Member Function Documentation

 void PEXSI::PPEXSIData::CalculateFermiOperatorReal ( Int numPole, Real temperature, Real gap, Real deltaE, Real mu, Real numElectronExact, Real numElectronTolerance, Int verbosity, Real & numElectron, Real & numElectronDrvMu )

Compute the Fermi operator for a given chemical potential for real symmetric matrices.

This routine also computes the single particle density matrix, the Helmholtz free energy density matrix, and the energy density matrix (for computing the Pulay force) simultaneously. These matrices can be called later via member functions DensityMatrix, FreeEnergyDensityMatrix, EnergyDensityMatrix.

Parameters
 [in] numPole Number of poles for the pole expansion [in] temperature Temperature [in] gap Band gap [in] deltaE Upperbound of the spectrum width [in] mu Initial guess of chemical potential. [in] numElectronExact Exact number of electrons. [in] numElectronTolerance Tolerance for the number of electrons. This is just used to discard some poles in the pole expansion. [in] verbosity The level of output information. = 0 : No output. = 1 : Basic output (default) = 2 : Detailed output. [out] numElectron The number of electron calculated at mu. [out] numElectronDrvMu The derivative of the number of electron calculated with respect to the chemical potential at mu.
 Real PEXSI::PPEXSIData::CalculateForce ( const DistSparseMatrix< Real > & HDerivativeMat, const DistSparseMatrix< Real > & SDerivativeMat )

CalculateFreeEnergy computes the force, including the Hellman-Feynman force and the Pulay force.

Parameters
 [in] HDerivativeMat Derivative of the Hamilotian matrix with respect to the atomic position R_{i,j}, i = 1, ..., natoms, j=1,2,3. [in] HDerivativeMat Derivative of the overlap matrix with respect to the atomic position R_{i,j}, i = 1, ..., natoms, j=1,2,3.
Returns
The force f_{i,j} with respect to the atomic position R_{i,j}, i = 1, ..., natoms, j=1,2,3.
 Real PEXSI::PPEXSIData::CalculateFreeEnergy ( const DistSparseMatrix< Real > & SMat )

CalculateFreeEnergy computes the total Helmholtz free energy (band energy part only).

For more information see Alavi, A., Kohanoff, J., Parrinello, M., & Frenkel, D. (1994). Ab initio molecular dynamics with excited electrons. Physical review letters, 73(19), 2599–2602.

Parameters
 [in] HMat Hamilotian matrix.
Returns
The Helmholtz free energy Tr[rho_f H]
 void PEXSI::PPEXSIData::CalculateNegativeInertia ( const std::vector< Real > & shiftVec, std::vector< Real > & inertiaVec, const DistSparseMatrix< Real > & HMat, const DistSparseMatrix< Real > & SMat, std::string ColPerm, Int numProcSymbFact )

Compute the negative inertia (the number of eigenvalues below a shift).

This subroutine computes the negative inertia of the matrix

I = H - shift * S

where I is the same as the number of eigenvalues lambda for

H x = lambda S x

with lambda < shift according to the Sylvester's law of inertia.

Parameters
 [in] shiftVec Shift vectors. [out] inertiaVec Negative inertia count, the same size as shiftVec. [in] HMat Hamiltonian matrix saved in distributed compressed sparse column format. See DistSparseMatrix. [in] SMat Overlap matrix saved in distributed compressed sparse column format. See DistSparseMatrix.

Note: If SMat.size == 0, SMat is treated as an identity matrix.

Parameters
 [in] ColPerm Permutation method used for SuperLU_DIST [in] numProcSymbFact Number of processors used for parallel symbolic factorization and PARMETIS/PT-SCOTCH.
 void PEXSI::PPEXSIData::CalculateNegativeInertiaReal ( const std::vector< Real > & shiftVec, std::vector< Real > & inertiaVec, Int verbosity )

Compute the negative inertia (the number of eigenvalues below a shift) for real symmetric matrices. The factorization.

uses real arithemetic factorization routine. This subroutine computes the negative inertia of the matrix

I = H - shift * S

where I is the same as the number of eigenvalues lambda for

H x = lambda S x

with lambda < shift according to the Sylvester's law of inertia.

Parameters
 [in] shiftVec Shift vectors. [out] inertiaVec Negative inertia count, the same size as shiftVec. [in] HMat Hamiltonian matrix saved in distributed compressed sparse column format. See DistSparseMatrix. [in] SMat Overlap matrix saved in distributed compressed sparse column format. See DistSparseMatrix.

Note: If SMat.size == 0, SMat is treated as an identity matrix.

Parameters
 [in] verbosity The level of output information. = 0 : No output. = 1 : Basic output (default) = 2 : Detailed output.
 Real PEXSI::PPEXSIData::CalculateNumElectron ( const DistSparseMatrix< Real > & SMat )

CalculateNumElectron computes the number of electrons given the current density matrix.

Parameters
 [in] SMat overlap matrix.
Returns
The number of electrons Tr[ S]
 Real PEXSI::PPEXSIData::CalculateNumElectronDrvMu ( const DistSparseMatrix< Real > & SMat )

CalculateNumElectronDrvMu computes the derivative of the number of electrons with respect to the chemical potential.

Parameters
 [in] SMat overlap matrix.
Returns
The derivative of the number of electrons Tr[f'(H-) S]
 Real PEXSI::PPEXSIData::CalculateNumElectronDrvT ( const DistSparseMatrix< Real > & SMat )

CalculateNumElectronDrvT computes the derivative of the number of electrons with respect to the temperature (1/beta, in atomic unit).

Parameters
 [in] SMat overlap matrix.
Returns
The derivative of the number of electrons Tr[f'(H-) S]
 Real PEXSI::PPEXSIData::CalculateTotalEnergy ( const DistSparseMatrix< Real > & HMat )

CalculateTotalEnergy computes the total energy (band energy part only).

Parameters
 [in] HMat Hamilotian matrix.
Returns
The total energy Tr[ H ].
 const DistSparseMatrix& PEXSI::PPEXSIData::EnergyDensityRealMat ( ) const
inline

Energy density matrix.

Can be used to estimate the total band energy via Tr[EDM*S] or the force, including the Hellman-Feynman force and the Pulay force.

 void PEXSI::PPEXSIData::EstimateSpectralRadius ( Int method, const DistSparseMatrix< Real > & HMat, const DistSparseMatrix< Real > & SMat, const NumVec< Real > & v0, Real tol, Int maxNumIter, Int & numIter, Real & sigma )

Estimate the spectral radius of the matrix stencil (H,S).

The current method uses the locally optimal conjugate gradient (LOCG) method.

Note
Rigorously speaking we are not computing the spectral radius, but the largest generalized eigenvalue. For standard Kohn-Sham problem with pseudopotential this should be OK. But this should be changed later, at least as a safe guard, but also may have practical relavance in the case of e.g. all electron calculation.
Parameters
 [in] method Method for estimating the spectral radius = 0 : Locally optimal conjugate gradient (LOCG) method (default). This works for both S being an identity matrix or not. This is the only implemented one currently. [in] HMat Hamiltonian matrix saved in distributed compressed sparse column format. See DistSparseMatrix. [in] SMat Overlap matrix saved in distributed compressed sparse column format. See DistSparseMatrix. S can be an identity matrix. [in] v0 Initial starting vector.

If v0.m() == 0, then a random vector is used as the initial starting vector.

Parameters
 [in] tol Relative tolerance for estimating sigma. [in] maxNumIter Maximum number of iterations. [out] numIter The number of iterations. [out] sigma The estimated spectral radius.
 Real PEXSI::PPEXSIData::EstimateZeroTemperatureChemicalPotential ( Real temperature, Real mu, const DistSparseMatrix< Real > & SMat )

Estimate the chemical potential at zero temperature using quadratic approximation.

Parameters
 [in] temperature Temperature (in the unit of K), usually high (~3000K) [in] mu Computed chemical potential at high temperature [in] SMat Overlap matrix
Returns
Estimated chemical potential at zero temperature.
 const DistSparseMatrix& PEXSI::PPEXSIData::FreeEnergyDensityRealMat ( ) const
inline

Total Helmholtz free energy matrix (band energy part only).

The Helmholtz free energy is computed by Tr[rho_f*H]. For more information see Alavi, A., Kohanoff, J., Parrinello, M., & Frenkel, D. (1994). Ab initio molecular dynamics with excited electrons. Physical review letters, 73(19), 2599–2602.

 const DistSparseMatrix& PEXSI::PPEXSIData::RhoRealMat ( ) const
inline

Density matrix.

Can be used to estimate the number of electrons by Tr[DM*S] or the band energy via Tr[DM*H]

 void PEXSI::PPEXSIData::Solve ( Int numPole, Real temperature, Real numElectronExact, Real gap, Real deltaE, Real & mu, Real & muMin, Real & muMax, const DistSparseMatrix< Real > & HMat, const DistSparseMatrix< Real > & SMat, Int muMaxIter, Real numElectronTolerance, std::string ColPerm, Int numProcSymbFact, bool isFreeEnergyDensityMatrix, bool isEnergyDensityMatrix, bool isDerivativeTMatrix, std::vector< Real > & muList, std::vector< Real > & numElectronList, std::vector< Real > & numElectronDrvMuList, bool & isConverged )

Solve is the main subroutine for PPEXSI.

Compute the single particle density matrix, the Helmholtz free energy density matrix, and the energy density matrix (for computing the Pulay force) simultaneously. These matrices can be called later via member functions DensityMatrix, FreeEnergyDensityMatrix, EnergyDensityMatrix.

Parameters
 [in] numPole Number of poles for the pole expansion [in] temperature Temperature (in the unit of K) [in] numElectronExact Exact number of electrons [in] gap Band gap (in the unit of au) [in] deltaE Upperbound of the spectrum width [in,out] mu Input: Initial guess of chemical potential (in the unit of au). Output: The final update of the chemical potential, for which the number of electrons has NOT been computed. Note: The output mu is NOT the same as last element in muList. muList[end] corresponds to numElectronList[end]. [in,out] muMin Input: Initial guess for the lower bound of the chemical potential. Output: Lower bound of the chemical potential. [in,out] muMax Input: Initial guess for the upper bound of the chemical potential. Output: Upper bound of the chemical potential. [in] HMat Hamiltonian matrix saved in distributed compressed sparse column format. See DistSparseMatrix. [in] SMat Overlap matrix saved in distributed compressed sparse column format. See DistSparseMatrix. Note: If SMat.size == 0, SMat is treated as an identity matrix. [in] muMaxIter Maximum iteration number for chemical potential [in] numElectronTolerance Stopping criterion for the mu iteration [in] ColPerm Permutation method used for SuperLU_DIST [in] numProcSymbFact Number of processors used for parallel symbolic factorization and PARMETIS/PT-SCOTCH. [in] isFreeEnergyDensityMatrix Whether to compute the Helmholtz free energy matrix [in] isEnergyDensityMatrix Whether to compute the energy density matrix for force [in] isDerivativeTMatrix Whether to compute the derivative of the single particle density matrix with respect to the temperature. [out] muList Convergence history of the chemical potential [out] numElectronList Convergence history of the number of electrons [out] numElectronDrvMuList Convergence history of the derivative of electrons with respect to the chemical potential. [out] isConverged Whether PEXSI has converged.
 void PEXSI::PPEXSIData::SymbolicFactorizeComplexSymmetricMatrix ( std::string ColPerm, Int numProcSymbFact, Int verbosity )

Symbolically factorize the loaded matrices for complex arithmetic factorization and selected inversion.

The symbolic information is saved internally at luComplexMat_ and PMComplexMat_.

Parameters
 [in] ColPerm Permutation method used for SuperLU_DIST [in] numProcSymbFact Number of processors used for parallel symbolic factorization and PARMETIS/PT-SCOTCH. [in] verbosity The level of output information. = 0 : No output. = 1 : Basic output (default) = 2 : Detailed output.
 void PEXSI::PPEXSIData::SymbolicFactorizeRealSymmetricMatrix ( std::string ColPerm, Int numProcSymbFact, Int verbosity )

Symbolically factorize the loaded matrices for real arithmetic factorization and selected inversion.

The symbolic information is saved internally at luRealMat_ and PMRealMat_.

Parameters
 [in] ColPerm Permutation method used for SuperLU_DIST [in] numProcSymbFact Number of processors used for parallel symbolic factorization and PARMETIS/PT-SCOTCH. [in] verbosity The level of output information. = 0 : No output. = 1 : Basic output (default) = 2 : Detailed output.

The documentation for this class was generated from the following files: