ppexsi.hpp

Go to the documentation of this file.

/*
         Copyright (c) 2012 The Regents of the University of California,
         through Lawrence Berkeley National Laboratory.  

   Author: Lin Lin
         
   This file is part of PEXSI. All rights reserved.

         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:

         (1) Redistributions of source code must retain the above copyright notice, this
         list of conditions and the following disclaimer.
         (2) Redistributions in binary form must reproduce the above copyright notice,
         this list of conditions and the following disclaimer in the documentation
         and/or other materials provided with the distribution.
         (3) Neither the name of the University of California, Lawrence Berkeley
         National Laboratory, U.S. Dept. of Energy nor the names of its contributors may
         be used to endorse or promote products derived from this software without
         specific prior written permission.

         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
         ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
         WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
         ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
         (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
         LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
         ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
         (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
         SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

         You are under no obligation whatsoever to provide any bug fixes, patches, or
         upgrades to the features, functionality or performance of the source code
         ("Enhancements") to anyone; however, if you choose to make your Enhancements
         available either publicly, or directly to Lawrence Berkeley National
         Laboratory, without imposing a separate written license agreement for such
         Enhancements, then you hereby grant the following license: a non-exclusive,
         royalty-free perpetual license to install, use, modify, prepare derivative
         works, incorporate into other computer software, distribute, and sublicense
         such enhancements or derivative works thereof, in binary and source code form.
*/
#ifndef _PPEXSI_HPP_
#define _PPEXSI_HPP_
#include  "environment.hpp"
#include  "sparse_matrix_impl.hpp"
#include  "numvec_impl.hpp"
#include  "utility.hpp"
#include  "pole.hpp"
#include        "mpi_interf.hpp"
#include  "superlu_dist_interf.hpp"
#include        "pselinv.hpp"
#include  "c_pexsi_interface.h"

namespace PEXSI{

        class PPEXSIData{
        private:
                // *********************************************************************
                // Computational variables
                // *********************************************************************

                std::vector<Complex>  zshift_;      // Complex shift for the pole expansion
                std::vector<Complex>  zweightRho_;  // Complex weight for the pole expansion for density
                std::vector<Complex>  zweightRhoDrvMu_;  // Complex weight for the pole expansion for derivative of the Fermi-Dirac with respect to the chemical potential
                std::vector<Complex>  zweightRhoDrvT_;   // Complex weight for the pole expansion for derivative of the Fermi-Dirac with respect to the temperature T (1/beta, in au)
                std::vector<Complex>  zweightHelmholtz_;  // Complex shift for the pole expansion for Helmholtz free energy
                std::vector<Complex>  zweightForce_;  // Complex weight for the pole expansion for force

                const GridType*           gridPole_;          // Outer layer communicator. Also used for distributing the DistSparseMatrix.  Each DistSparseMatrix is replicated in the row (numPoleGroup) direction of gridPole.
                const GridType*           gridSelInv_;        // Inner layer communicator for SelInv
                const SuperLUGrid*    gridSuperLU_;           // Inner layer communicator for SuperLU factorization

                SuperNodeType         super_;                 // Supernode partition

                DistSparseMatrix<Real>     rhoMat_;                   // Density matrix 
                DistSparseMatrix<Real>     rhoDrvMuMat_;              // Derivative of the Fermi-Dirac with respect to mu
                DistSparseMatrix<Real>     rhoDrvTMat_;               // Derivative of the Fermi-Dirac with respect to T
                DistSparseMatrix<Real>     freeEnergyDensityMat_;     // Helmholtz free energy density matrix
                DistSparseMatrix<Real>     energyDensityMat_;         // Energy density matrix for computing the Pulay force

                // Saves all the indices of diagonal elements in H, so that
                // H.nzvalLocal(diagIdxLocal_[j]) are diagonal elements for all j.
                // This is manly used when S is implicitly given as an identity matrix.
                std::vector<Int>           diagIdxLocal_;    

                // *********************************************************************
                // Member functions
                // *********************************************************************
                Real CalculateChemicalPotentialNewtonFD( 
                                const Int iter, 
                                const Real numElectronExact, 
                                const Real numElectronTolerance,
                                const std::vector<Real>& muList,
                                const std::vector<Real>& numElectronList );

                Real CalculateChemicalPotentialNewtonBisection(
                                const Real numElectronExact, 
                                const Real numElectron,
                                const Real numElectronDrvMu,
                                const Real mu,
                                const Real muMin,
                                const Real muMax );

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

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



                DistSparseMatrix<Real>& DensityMatrix () { return rhoMat_; }

                DistSparseMatrix<Real>& FreeEnergyDensityMatrix () { return freeEnergyDensityMat_; }

                DistSparseMatrix<Real>& EnergyDensityMatrix() { return energyDensityMat_; }

                Real CalculateNumElectron( const DistSparseMatrix<Real>& SMat );

                Real CalculateNumElectronDrvMu( const DistSparseMatrix<Real>& SMat );

                Real CalculateNumElectronDrvT( const DistSparseMatrix<Real>& SMat );

                Real CalculateTotalEnergy( const DistSparseMatrix<Real>& HMat );

                Real CalculateFreeEnergy( const DistSparseMatrix<Real>& SMat );

                Real CalculateForce( 
                                const DistSparseMatrix<Real>& HDerivativeMat,  
                                const DistSparseMatrix<Real>& SDerivativeMat ); 


                Real EstimateZeroTemperatureChemicalPotential( 
                                Real temperature,
                                Real mu,
                                const DistSparseMatrix<Real>& SMat );


                void CalculateNegativeInertia( 
                                const std::vector<Real>&       shiftVec, 
                                std::vector<Real>&             inertiaVec,
                                const DistSparseMatrix<Real>&  HMat,
                                const DistSparseMatrix<Real>&  SMat,
                                std::string                    ColPerm,
                                Int                            numProcSymbFact );


                void CalculateNegativeInertiaReal( 
                                const std::vector<Real>&       shiftVec, 
                                std::vector<Real>&             inertiaVec,
                                const DistSparseMatrix<Real>&  HMat,
                                const DistSparseMatrix<Real>&  SMat,
                                std::string                    ColPerm,
                                Int                            numProcSymbFact );

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


} // namespace PEXSI
#endif