Commits

BarryFSmith committed 1f817a2

completed initial implementation of PetscCitationsRegister() and added proper cites for hypre, ml, mumps

Comments (5)

  1. Jed Brown

    What about the other direction: make it possible to run a trivial PETSc program (or script) that extracts all citations from the code into a .bib file? Then we could take those citations out of the petsc.bib in the repository (but include them in release tarballs and on the website).

  2. Jed Brown

    Do you really want to place the full citations in the code? The duplication with respect to petsc.bib and petscapp.bib seems bound to become out of date.

  3. BarryFSmith author

    ABSOFREAKINGLUTELY. We are not going to have 1) the executable going off to try to find some database it cannot actually find to get the citation or 2) the executable printing out a statement "go look here for the bibtext entry".

    Remember this is going to work for PLUGINS also where the application code is just given another shared library to use and the plugin author who deserves credit does not have write access to petsc.bib and petscapp.bib

    Plus it is not duplication because though petsc.bib and petscapp.bib might have the citations it doesn't say in the *.bib that "these" are the ones you want to cite.

    I am pretty sure this is the right compromise. As we start to use it we'll get more experience and may decide to change it. Note also that specific implemented algorithms (for example some of the stuff Peter has implemented) can themselves directly register additional bibtex items such as ngmres .... (we could even have all the gmres implementations pop out the "original" Saad and Schultz paper :-)

  4. BarryFSmith author

    I am also inserting the bibtex item for the paper I'm writing on automatically generating bibtex items based on algorithms/code your application used so that will get cited everytime the automatically generated bibtex item -citations option is used :-)

Files changed (5)

include/petscsys.h

 PETSC_STATIC_INLINE PetscErrorCode PetscSegBufferGetInts(PetscSegBuffer seg,PetscInt count,PetscInt *PETSC_RESTRICT *slot) {return PetscSegBufferGet(seg,count,(void**)slot);}
 
 extern PetscSegBuffer PetscCitationsList;
+#undef __FUNCT__
+#define __FUNCT__ "PetscCitationsRegister"
+/*@C
+      PetscCitationsRegister - Register a bibtex item to obtain credit for an implemented algorithm used in the code.
+
+     Not Collective - only what is registered on rank 0 of PETSC_COMM_WORLD will be printed
+
+     Input Parameters:
++      cite - the bibtex item, formated to displayed on multiple lines nicely
+-      set - a boolean variable initially set to PETSC_FALSE; this is used to insure only a single registration of the citation
+
+     Options Database:
+.     -citations [filenmae]   - print out the bibtex entries for the given computation
+@*/
 PETSC_STATIC_INLINE PetscErrorCode PetscCitationsRegister(const char cit[],PetscBool *set)
 {
   size_t         len;
   char           *vstring;
   PetscErrorCode ierr;
 
+  PetscFunctionBegin;
   if (set && *set) return 0;
   ierr = PetscStrlen(cit,&len);CHKERRQ(ierr);
   ierr = PetscSegBufferGet(PetscCitationsList,(PetscInt)len,&vstring);CHKERRQ(ierr);
   ierr = PetscMemcpy(vstring,cit,len);CHKERRQ(ierr);
   if (set) *set = PETSC_TRUE;
-  return 0;
+  PetscFunctionReturn(0);
 }
 
 

src/ksp/pc/impls/hypre/hypre.c

 #include <../src/dm/impls/da/hypre/mhyp.h>
 
 static PetscBool cite = PETSC_FALSE;
-static const char *hypreCitation = "Hypre\n";
+static const char hypreCitation[] = "@manual{hypre-web-page,\n  title  = {{\\sl hypre}: High Performance Preconditioners},\n  organization = {Lawrence Livermore National Laboratory},\n  note  = {\\url{http://www.llnl.gov/CASC/hypre/}}\n}\n";
+
 /*
    Private context (data structure) for the  preconditioner.
 */

src/ksp/pc/impls/ml/ml.c

 #define __FUNCT__ "PCSetUp_ML"
 PetscErrorCode PCSetUp_ML(PC pc)
 {
-  PetscErrorCode ierr;
-  PetscMPIInt    size;
-  FineGridCtx    *PetscMLdata;
-  ML             *ml_object;
-  ML_Aggregate   *agg_object;
-  ML_Operator    *mlmat;
-  PetscInt       nlocal_allcols,Nlevels,mllevel,level,level1,m,fine_level,bs;
-  Mat            A,Aloc;
-  GridCtx        *gridctx;
-  PC_MG          *mg    = (PC_MG*)pc->data;
-  PC_ML          *pc_ml = (PC_ML*)mg->innerctx;
-  PetscBool      isSeq, isMPI;
-  KSP            smoother;
-  PC             subpc;
-  PetscInt       mesh_level, old_mesh_level;
-  MatInfo        info;
+  PetscErrorCode   ierr;
+  PetscMPIInt      size;
+  FineGridCtx      *PetscMLdata;
+  ML               *ml_object;
+  ML_Aggregate     *agg_object;
+  ML_Operator      *mlmat;
+  PetscInt         nlocal_allcols,Nlevels,mllevel,level,level1,m,fine_level,bs;
+  Mat              A,Aloc;
+  GridCtx          *gridctx;
+  PC_MG            *mg    = (PC_MG*)pc->data;
+  PC_ML            *pc_ml = (PC_ML*)mg->innerctx;
+  PetscBool        isSeq, isMPI;
+  KSP              smoother;
+  PC               subpc;
+  PetscInt         mesh_level, old_mesh_level;
+  MatInfo          info;
+  static PetscBool cite = PETSC_FALSE;
 
   PetscFunctionBegin;
+  ierr = PetscCitationsRegister("@TechReport{ml_users_guide,\n  author = {M. Sala and J.J. Hu and R.S. Tuminaro},\n  title = {{ML}3.1 {S}moothed {A}ggregation {U}ser's {G}uide},\n  institution =  {Sandia National Laboratories},\n  number = {SAND2004-4821},\n  year = 2004\n}\n",&cite);CHKERRQ(ierr);
   A    = pc->pmat;
   ierr = MPI_Comm_size(PetscObjectComm((PetscObject)A),&size);CHKERRQ(ierr);
 

src/mat/impls/aij/mpi/mumps/mumps.c

   static PetscBool cite = PETSC_FALSE;
 
   PetscFunctionBegin;
-  ierr = PetscCitationsRegister("MUMPS\n",&cite);CHKERRQ(ierr);
+  ierr = PetscCitationsRegister("@article{MUMPS01,\n  author = {P.~R. Amestoy and I.~S. Duff and J.-Y. L'Excellent and J. Koster},\n  title = {A fully asynchronous multifrontal solver using distributed dynamic scheduling},\n  journal = {SIAM Journal on Matrix Analysis and Applications},\n  volume = {23},\n  number = {1},\n  pages = {15--41},\n  year = {2001}\n}\n",&cite);CHKERRQ(ierr);
   mumps->id.nrhs = 1;
   b_seq          = mumps->b_seq;
   if (mumps->size > 1) {

src/sys/objects/pinit.c

   }
   ierr = PetscInfo(NULL,"PetscFinalize() called\n");CHKERRQ(ierr);
 
-  ierr = PetscOptionsGetBool(NULL,"-citations",&flg,NULL);CHKERRQ(ierr);
+  ierr = MPI_Comm_rank(PETSC_COMM_WORLD,&rank);CHKERRQ(ierr);
+
+  ierr = PetscOptionsHasName(NULL,"-citations",&flg);CHKERRQ(ierr);
   if (flg) {
-    char *cits;
+    char  *cits, filename[PETSC_MAX_PATH_LEN];
+    FILE  *fd = PETSC_STDOUT;
+
+    ierr = PetscOptionsGetString(NULL,"-citations",filename,PETSC_MAX_PATH_LEN,NULL);CHKERRQ(ierr);
+    if (filename[0]) {
+      ierr = PetscFOpen(PETSC_COMM_WORLD,filename,"w",&fd);CHKERRQ(ierr);
+    }
     ierr = PetscSegBufferGet(PetscCitationsList,1,&cits);CHKERRQ(ierr);
     cits[0] = 0;
     ierr = PetscSegBufferExtractAlloc(PetscCitationsList,&cits);CHKERRQ(ierr);
-    ierr = PetscPrintf(PETSC_COMM_WORLD,"If you publish results based on this computation please cite the following:\n");CHKERRQ(ierr);
-    ierr = PetscPrintf(PETSC_COMM_WORLD,"%s",cits);CHKERRQ(ierr);
+    ierr = PetscFPrintf(PETSC_COMM_WORLD,fd,"If you publish results based on this computation please cite the following:\n");CHKERRQ(ierr);
+    ierr = PetscFPrintf(PETSC_COMM_WORLD,fd,"===========================================================================\n");CHKERRQ(ierr);
+    ierr = PetscFPrintf(PETSC_COMM_WORLD,fd,"%s",cits);CHKERRQ(ierr);
+    ierr = PetscFPrintf(PETSC_COMM_WORLD,fd,"===========================================================================\n");CHKERRQ(ierr);
+    ierr = PetscFClose(PETSC_COMM_WORLD,fd);CHKERRQ(ierr);
     ierr = PetscFree(cits);CHKERRQ(ierr);
   }
   ierr = PetscSegBufferDestroy(&PetscCitationsList);CHKERRQ(ierr);
 
   ierr = PetscHMPIFinalize();CHKERRQ(ierr);
 
-  ierr = MPI_Comm_rank(PETSC_COMM_WORLD,&rank);CHKERRQ(ierr);
   ierr = PetscOptionsGetBool(NULL,"-malloc_info",&flg2,NULL);CHKERRQ(ierr);
   if (!flg2) {
     flg2 = PETSC_FALSE;