PEXSI
 All Classes Namespaces Files Functions Variables Typedefs Pages
c_pexsi_interface.h
Go to the documentation of this file.
1 /*
2  Copyright (c) 2012 The Regents of the University of California,
3  through Lawrence Berkeley National Laboratory.
4 
5  Author: Lin Lin
6 
7  This file is part of PEXSI. All rights reserved.
8 
9  Redistribution and use in source and binary forms, with or without
10  modification, are permitted provided that the following conditions are met:
11 
12  (1) Redistributions of source code must retain the above copyright notice, this
13  list of conditions and the following disclaimer.
14  (2) Redistributions in binary form must reproduce the above copyright notice,
15  this list of conditions and the following disclaimer in the documentation
16  and/or other materials provided with the distribution.
17  (3) Neither the name of the University of California, Lawrence Berkeley
18  National Laboratory, U.S. Dept. of Energy nor the names of its contributors may
19  be used to endorse or promote products derived from this software without
20  specific prior written permission.
21 
22  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
23  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
24  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
26  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
27  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
29  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
31  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 
33  You are under no obligation whatsoever to provide any bug fixes, patches, or
34  upgrades to the features, functionality or performance of the source code
35  ("Enhancements") to anyone; however, if you choose to make your Enhancements
36  available either publicly, or directly to Lawrence Berkeley National
37  Laboratory, without imposing a separate written license agreement for such
38  Enhancements, then you hereby grant the following license: a non-exclusive,
39  royalty-free perpetual license to install, use, modify, prepare derivative
40  works, incorporate into other computer software, distribute, and sublicense
41  such enhancements or derivative works thereof, in binary and source code form.
42 */
50 #ifndef _PEXSI_C_PEXSI_INTERFACE_H_
51 #define _PEXSI_C_PEXSI_INTERFACE_H_
52 #include <mpi.h>
53 #include <stdint.h>
54 
55 #ifdef __cplusplus
56 extern "C"{
57 #endif
58 
71  char* filename,
72  int* size,
73  int* nnz,
74  int* nnzLocal,
75  int* numColLocal,
76  MPI_Comm comm );
77 
98  char* filename,
99  int size,
100  int nnz,
101  int nnzLocal,
102  int numColLocal,
103  int* colptrLocal,
104  int* rowindLocal,
105  double* nzvalLocal,
106  MPI_Comm comm );
107 
108 
121  char* filename,
122  int* size,
123  int* nnz,
124  int* nnzLocal,
125  int* numColLocal,
126  MPI_Comm comm );
127 
151  char* filename,
152  int size,
153  int nnz,
154  int nnzLocal,
155  int numColLocal,
156  int* colptrLocal,
157  int* rowindLocal,
158  double* nzvalLocal,
159  MPI_Comm comm );
160 
161 
162 
163 // *********************************************************************
164 // The following routines belong to the second version of the interface
165 // *********************************************************************
166 
174 typedef intptr_t PPEXSIPlan;
175 
180 typedef struct {
184  double temperature;
188  double gap;
192  double deltaE;
196  int numPole;
209  double muMin0;
213  double muMax0;
217  double mu0;
252 
259  int solver;
260 
271  int ordering;
305 } PPEXSIOptions;
306 
307 
317  PPEXSIOptions* options );
318 
319 
357 PPEXSIPlan PPEXSIPlanInitialize(
358  MPI_Comm comm,
359  int numProcRow,
360  int numProcCol,
361  int outputFileIndex,
362  int* info );
363 
364 
396  PPEXSIPlan plan,
397  PPEXSIOptions options,
398  int nrows,
399  int nnz,
400  int nnzLocal,
401  int numColLocal,
402  int* colptrLocal,
403  int* rowindLocal,
404  double* HnzvalLocal,
405  int isSIdentity,
406  double* SnzvalLocal,
407  int* info );
408 
439  PPEXSIPlan plan,
440  PPEXSIOptions options,
441  int nrows,
442  int nnz,
443  int nnzLocal,
444  int numColLocal,
445  int* colptrLocal,
446  int* rowindLocal,
447  double* HnzvalLocal,
448  int isSIdentity,
449  double* SnzvalLocal,
450  int* info );
451 
452 
453 
466  PPEXSIPlan plan,
467  PPEXSIOptions options,
468  int* info );
469 
482  PPEXSIPlan plan,
483  PPEXSIOptions options,
484  int* info );
485 
486 
509  /* Input parameters */
510  PPEXSIPlan plan,
511  PPEXSIOptions options,
512  int numShift,
513  double* shiftList,
514  /* Output parameters */
515  double* inertiaList,
516  int* info );
517 
540  /* Input parameters */
541  PPEXSIPlan plan,
542  PPEXSIOptions options,
543  int numShift,
544  double* shiftList,
545  /* Output parameters */
546  double* inertiaList,
547  int* info );
548 
549 
550 
564  PPEXSIPlan plan,
565  PPEXSIOptions options,
566  double* AnzvalLocal,
567  int* info );
568 
582  PPEXSIPlan plan,
583  PPEXSIOptions options,
584  double* AnzvalLocal,
585  int* info );
586 
587 
609 /*
610 void PPEXSIInertiaCountRealUnsymmetricMatrix(
611  PPEXSIPlan plan,
612  PPEXSIOptions options,
613  int numShift,
614  double* shiftList,
615  double* inertiaList,
616  int* info );
617 */
618 
619 
620 
621 
622 
623 
624 
625 
626 
627 
628 
629 
687  PPEXSIPlan plan,
688  PPEXSIOptions options,
689  double mu,
690  double numElectronExact,
691  double* numElectronPEXSI,
692  double* numElectronDrvMuPEXSI,
693  int* info );
694 
695 
754  PPEXSIPlan plan,
755  PPEXSIOptions options,
756  double mu,
757  double numElectronExact,
758  double* numElectronPEXSI,
759  double* numElectronDrvMuPEXSI,
760  int* info );
761 
762 
781  PPEXSIPlan plan,
782  PPEXSIOptions options,
783  double* AnzvalLocal,
784  double* AinvnzvalLocal,
785  int* info );
786 
787 
809  PPEXSIPlan plan,
810  PPEXSIOptions options,
811  double* AnzvalLocal,
812  double* AinvnzvalLocal,
813  int* info );
814 
815 
834  PPEXSIPlan plan,
835  PPEXSIOptions options,
836  double* AnzvalLocal,
837  double* AinvnzvalLocal,
838  int* info );
839 
840 
862  PPEXSIPlan plan,
863  PPEXSIOptions options,
864  double* AnzvalLocal,
865  double* AinvnzvalLocal,
866  int* info );
867 
868 
869 
950 void PPEXSIDFTDriver(
951  PPEXSIPlan plan,
952  PPEXSIOptions options,
953  double numElectronExact,
954  double* muPEXSI,
955  double* numElectronPEXSI,
956  double* muMinInertia,
957  double* muMaxInertia,
958  int* numTotalInertiaIter,
959  int* numTotalPEXSIIter,
960  int* info );
961 
1030 void PPEXSIDFTDriver2(
1031  PPEXSIPlan plan,
1032  PPEXSIOptions options,
1033  double numElectronExact,
1034  double* muPEXSI,
1035  double* numElectronPEXSI,
1036  double* muMinInertia,
1037  double* muMaxInertia,
1038  int* numTotalInertiaIter,
1039  int* info );
1040 
1057  PPEXSIPlan plan,
1058  double* DMnzvalLocal,
1059  double* EDMnzvalLocal,
1060  double* FDMnzvalLocal,
1061  double* totalEnergyH,
1062  double* totalEnergyS,
1063  double* totalFreeEnergy,
1064  int* info );
1065 
1066 
1083  PPEXSIPlan plan,
1084  double* DMnzvalLocal,
1085  double* EDMnzvalLocal,
1086  double* FDMnzvalLocal,
1087  double* totalEnergyH,
1088  double* totalEnergyS,
1089  double* totalFreeEnergy,
1090  int* info );
1091 
1092 
1102 void PPEXSIPlanFinalize(
1103  PPEXSIPlan plan,
1104  int* info );
1105 
1117 void PPEXSIGetPoleDM(
1118  double* zshift,
1119  double* zweight,
1120  int Npole,
1121  double temp,
1122  double gap,
1123  double deltaE,
1124  double mu );
1125 
1137 void PPEXSIGetPoleEDM(
1138  double* zshift,
1139  double* zweight,
1140  int Npole,
1141  double temp,
1142  double gap,
1143  double deltaE,
1144  double mu );
1145 
1157 void PPEXSIGetPoleFDM(
1158  double* zshift,
1159  double* zweight,
1160  int Npole,
1161  double temp,
1162  double gap,
1163  double deltaE,
1164  double mu );
1165 
1166 #ifdef __cplusplus
1167 }// extern "C"
1168 #endif
1169 
1170 #endif // _PEXSI_C_PEXSI_INTERFACE_H_
void PPEXSIInertiaCountRealMatrix(PPEXSIPlan plan, PPEXSIOptions options, int numShift, double *shiftList, double *inertiaList, int *info)
Directly compute the negative inertia at a set of shifts for real matrices.
Definition: interface.cpp:694
double muMin0
Initial guess of lower bound for mu.
Definition: c_pexsi_interface.h:209
int isConstructCommPattern
Whether to construct PSelInv communication pattern.
Definition: c_pexsi_interface.h:251
void ReadDistSparseMatrixFormattedInterface(char *filename, int size, int nnz, int nnzLocal, int numColLocal, int *colptrLocal, int *rowindLocal, double *nzvalLocal, MPI_Comm comm)
Reading the data of a formatted DistSparseMatrix.
Definition: interface.cpp:120
double mu0
Initial guess for mu (for the solver) (AG)
Definition: c_pexsi_interface.h:217
void PPEXSIPlanFinalize(PPEXSIPlan plan, int *info)
Release the memory used by PEXSI.
Definition: interface.cpp:1187
double muInertiaExpansion
If the chemical potential is not in the initial interval, the interval is expanded by muInertiaExpans...
Definition: c_pexsi_interface.h:227
int ordering
Ordering strategy for factorization and selected inversion.
Definition: c_pexsi_interface.h:271
int rowOrdering
row permutation strategy for factorization and selected inversion.
Definition: c_pexsi_interface.h:280
double numElectronPEXSITolerance
Stopping criterion of the PEXSI iteration in terms of the number of electrons compared to numElectron...
Definition: c_pexsi_interface.h:237
intptr_t PPEXSIPlan
A handle for holding the internal PEXSI data structure.
Definition: c_pexsi_interface.h:174
double muInertiaTolerance
Stopping criterion in terms of the chemical potential for the inertia counting procedure.
Definition: c_pexsi_interface.h:222
void PPEXSILoadComplexHSMatrix(PPEXSIPlan plan, PPEXSIOptions options, int nrows, int nnz, int nnzLocal, int numColLocal, int *colptrLocal, int *rowindLocal, double *HnzvalLocal, int isSIdentity, double *SnzvalLocal, int *info)
Load the complex H and S matrices into the PEXSI internal data structure. H and S can be either compl...
Definition: interface.cpp:357
int symmetric
Matrix structure.
Definition: c_pexsi_interface.h:291
PPEXSIPlan PPEXSIPlanInitialize(MPI_Comm comm, int numProcRow, int numProcCol, int outputFileIndex, int *info)
Initialize the PEXSI plan.
Definition: interface.cpp:279
double muMax0
Initial guess of upper bound for mu.
Definition: c_pexsi_interface.h:213
void PPEXSILoadRealHSMatrix(PPEXSIPlan plan, PPEXSIOptions options, int nrows, int nnz, int nnzLocal, int numColLocal, int *colptrLocal, int *rowindLocal, double *HnzvalLocal, int isSIdentity, double *SnzvalLocal, int *info)
Load the real H and S matrices into the PEXSI internal data structure. H and S can be either real sym...
Definition: interface.cpp:308
void PPEXSICalculateFermiOperatorComplex(PPEXSIPlan plan, PPEXSIOptions options, double mu, double numElectronExact, double *numElectronPEXSI, double *numElectronDrvMuPEXSI, int *info)
Compute the density matrices and number of electrons for a given chemical potential. Here H and S are complex Hermitian matrices (even though S is real in electronic structure calculation)
Definition: interface.cpp:826
void PPEXSISetDefaultOptions(PPEXSIOptions *options)
Set the default options for DFT driver.
Definition: interface.cpp:251
void PPEXSIGetPoleDM(double *zshift, double *zweight, int Npole, double temp, double gap, double deltaE, double mu)
Pole expansion for density matrix (DM).
Definition: interface.cpp:1209
int transpose
Transpose.
Definition: c_pexsi_interface.h:297
void PPEXSIRetrieveRealDFTMatrix(PPEXSIPlan plan, double *DMnzvalLocal, double *EDMnzvalLocal, double *FDMnzvalLocal, double *totalEnergyH, double *totalEnergyS, double *totalFreeEnergy, int *info)
Retrieve the output matrices after running PPEXSIDFTDriver for real input matrices.
Definition: interface.cpp:1099
void PPEXSIDFTDriver(PPEXSIPlan plan, PPEXSIOptions options, double numElectronExact, double *muPEXSI, double *numElectronPEXSI, double *muMinInertia, double *muMaxInertia, int *numTotalInertiaIter, int *numTotalPEXSIIter, int *info)
Simplified driver for solving Kohn-Sham DFT.
Definition: interface.cpp:987
void PPEXSIInertiaCountComplexMatrix(PPEXSIPlan plan, PPEXSIOptions options, int numShift, double *shiftList, double *inertiaList, int *info)
Directly compute the negative inertia at a set of shifts for complex matrices.
Definition: interface.cpp:740
Structure for the input parameters in DFT calculations.
Definition: c_pexsi_interface.h:180
void PPEXSICalculateFermiOperatorReal(PPEXSIPlan plan, PPEXSIOptions options, double mu, double numElectronExact, double *numElectronPEXSI, double *numElectronDrvMuPEXSI, int *info)
Directly compute the negative inertia at a set of shifts.
Definition: interface.cpp:787
void PPEXSISelInvRealSymmetricMatrix(PPEXSIPlan plan, PPEXSIOptions options, double *AnzvalLocal, double *AinvnzvalLocal, int *info)
Simplified driver interface for computing the selected elements of a real symmetric matrix...
Definition: interface.cpp:866
int npSymbFact
Number of processors for PARMETIS/PT-SCOTCH. Only used if the ordering == 0.
Definition: c_pexsi_interface.h:285
void PPEXSISymbolicFactorizeRealSymmetricMatrix(PPEXSIPlan plan, PPEXSIOptions options, int *info)
Separately perform symbolic factorization to prepare factorization and selected inversion for real ar...
Definition: interface.cpp:405
void ReadDistSparseMatrixFormattedHeadInterface(char *filename, int *size, int *nnz, int *nnzLocal, int *numColLocal, MPI_Comm comm)
Read the sizes of a DistSparseMatrix in formatted form (txt) for allocating memory in C...
Definition: interface.cpp:63
int isInertiaCount
Whether inertia counting is used at the very beginning.
Definition: c_pexsi_interface.h:200
void PPEXSISymbolicFactorizeComplexSymmetricMatrix(PPEXSIPlan plan, PPEXSIOptions options, int *info)
Separately perform symbolic factorization to prepare factorization and selected inversion for complex...
Definition: interface.cpp:551
void ReadDistSparseMatrixHeadInterface(char *filename, int *size, int *nnz, int *nnzLocal, int *numColLocal, MPI_Comm comm)
Read the sizes of a DistSparseMatrix in unformatted form (csc) for allocating memory in C...
Definition: interface.cpp:153
void PPEXSISelInvComplexUnsymmetricMatrix(PPEXSIPlan plan, PPEXSIOptions options, double *AnzvalLocal, double *AinvnzvalLocal, int *info)
Simplified driver interface for computing the selected elements of a complex unsymmetric matrix...
Definition: interface.cpp:956
int maxPEXSIIter
Maximum number of PEXSI iterations after each inertia counting procedure.
Definition: c_pexsi_interface.h:205
void ParaReadDistSparseMatrixInterface(char *filename, int size, int nnz, int nnzLocal, int numColLocal, int *colptrLocal, int *rowindLocal, double *nzvalLocal, MPI_Comm comm)
Actual reading the data of a DistSparseMatrix using MPI-IO, assuming that the arrays have been alloca...
Definition: interface.cpp:214
void PPEXSIGetPoleEDM(double *zshift, double *zweight, int Npole, double temp, double gap, double deltaE, double mu)
Pole expansion for energy density matrix (EDM).
Definition: interface.cpp:1235
void PPEXSISelInvComplexSymmetricMatrix(PPEXSIPlan plan, PPEXSIOptions options, double *AnzvalLocal, double *AinvnzvalLocal, int *info)
Simplified driver interface for computing the selected elements of a complex symmetric matrix...
Definition: interface.cpp:926
double deltaE
An upper bound for the spectral radius of .
Definition: c_pexsi_interface.h:192
void PPEXSIRetrieveComplexDFTMatrix(PPEXSIPlan plan, double *DMnzvalLocal, double *EDMnzvalLocal, double *FDMnzvalLocal, double *totalEnergyH, double *totalEnergyS, double *totalFreeEnergy, int *info)
Retrieve the output matrices after running PPEXSIDFTDriver for complex input matrices.
Definition: interface.cpp:1142
int isSymbolicFactorize
Whether to perform symbolic factorization.
Definition: c_pexsi_interface.h:247
int matrixType
matrixType (global) Type of input H and S matrices.
Definition: c_pexsi_interface.h:243
void PPEXSISelInvRealUnsymmetricMatrix(PPEXSIPlan plan, PPEXSIOptions options, double *AnzvalLocal, double *AinvnzvalLocal, int *info)
Simplified driver interface for computing the selected elements of a real unsymmetric matrix...
Definition: interface.cpp:896
void PPEXSISymbolicFactorizeComplexUnsymmetricMatrix(PPEXSIPlan plan, PPEXSIOptions options, double *AnzvalLocal, int *info)
Separately perform symbolic factorization to prepare factorization and selected inversion for complex...
Definition: interface.cpp:631
double temperature
Temperature, in the same unit as H.
Definition: c_pexsi_interface.h:184
int solver
Solver used to do the factorization prior to the selected inversion.
Definition: c_pexsi_interface.h:259
double gap
Spectral gap. Note This can be set to be 0 in most cases.
Definition: c_pexsi_interface.h:188
void PPEXSISymbolicFactorizeRealUnsymmetricMatrix(PPEXSIPlan plan, PPEXSIOptions options, double *AnzvalLocal, int *info)
Separately perform symbolic factorization to prepare factorization and selected inversion for real ar...
Definition: interface.cpp:486
double muPEXSISafeGuard
Safe guard criterion in terms of the chemical potential to reinvoke the inertia counting procedure...
Definition: c_pexsi_interface.h:232
void PPEXSIDFTDriver2(PPEXSIPlan plan, PPEXSIOptions options, double numElectronExact, double *muPEXSI, double *numElectronPEXSI, double *muMinInertia, double *muMaxInertia, int *numTotalInertiaIter, int *info)
Simplified driver for solving Kohn-Sham DFT. Version 2. This is still in test phase.
Definition: interface.cpp:1044
void PPEXSIGetPoleFDM(double *zshift, double *zweight, int Npole, double temp, double gap, double deltaE, double mu)
Pole expansion for free energy density matrix (FDM).
Definition: interface.cpp:1261
int verbosity
The level of output information.
Definition: c_pexsi_interface.h:304
int numPole
Number of terms in the pole expansion.
Definition: c_pexsi_interface.h:196