On Thu 26. Mar 2020 at 21:19, Jacob Faibussowitsch <[email protected]> wrote:
> Actually, the man pages for specific constructors actually yields more > useful information (in nearly all cases) about the formats. > Take a look at these pages > > > https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateSELL.html#MatCreateSELL > > > https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJCRL.html#MatCreateMPIAIJCRL > > > https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL > > > https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM > > Is that more informative? > > > Yes this is pretty much what I had in mind! > Cool. But I think it needs to moved away from the create calls and to the all > upper-case impls sections. > Totally agree. Just wanted to pointed some useful info is in fact there - albeit in a slightly non obvious place. It’s definitely a better situation than no useful info at all and instead just the same old generic description cut-and-pasted all over the place :D Currently the work-flow of the mat examples I have seen are as follows: > > MatCreate(); > MatSetSizes(); > MatSetType(); > > Which means new users will likely never look at the individual > MatCreateXXX() routines and never see any of the useful information. They > are far more likely to click on the links on the MatSetType calls to the > various implementations, and be frustrated when there’s nothing useful > there... > Sure - I agree with you. > Also as Junchao noted: > > Even better, with examples showing a small matrix. > > > I think this should be on every informative MAT page (wherever that ends > up being). For example for the “base” MatCreateAIJ you have nice diagrams > showing in broad strokes how things are internally structured. Say a user > eventually implements MATMPIAIJMKL, given the above it isn’t guaranteed > that they see the MatCreateAIJ which actually has the useful diagram, > leading to headaches trying to figure out how to properly feed petsc the > matrix. > > It’s certainly a bit of bloat, but every MAT impls should have a section > with the diagram about its “base” implementation. Maybe we can be smart > about it and “link” the text from another part of the src, but I don’t know > much about how much you can do with the current documentation generation. > > Best regards, > > Jacob Faibussowitsch > (Jacob Fai - booss - oh - vitch) > Cell: (312) 694-3391 > > On Mar 26, 2020, at 3:00 PM, Dave May <[email protected]> wrote: > > > > On Thu, 26 Mar 2020 at 19:26, Jacob Faibussowitsch <[email protected]> > wrote: > >> Hello, >> >> In keeping with PETSc design it would be nice to have *more* detail for >> all MAT implementations explaining in what the letters stand for, and >> use-cases it might be useful for. For example: >> >> MATAIJSELL >> <https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MATAIJSELL.html#MATAIJSELL> >> = "AIJSELL" - A matrix type to be used for sparse matrices. This matrix >> type is identical to MATSEQAIJSELL when constructed with a single process >> communicator, and MATMPIAIJSELL otherwise. As a result, for single process >> communicators, MatSeqAIJSetPreallocation >> <https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MatSeqAIJSetPreallocation.html#MatSeqAIJSetPreallocation>() >> is supported, and similarly MatMPIAIJSetPreallocation >> <https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MatMPIAIJSetPreallocation.html#MatMPIAIJSetPreallocation>() >> is supported for communicators controlling multiple processes. It is >> recommended that you call both of the above preallocation routines for >> simplicity. >> >> >> > Agreed that is not particularly informative. > > >> I am no complete beginner but I am no computational matrix expert either. >> I have no idea what “SELL” is. Obviously googling "mat sell format” gives >> less than useful results. Other such types are MATAIJCRL, MATAIJMKL, >> MATAIJPERM, MATADJ. >> > > Actually, the man pages for specific constructors actually yields more > useful information (in nearly all cases) about the formats. > Take a look at these pages > > > https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateSELL.html#MatCreateSELL > > > https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJCRL.html#MatCreateMPIAIJCRL > > > https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL > > > https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM > > Is that more informative? > > Admittedly the SELL man page should include references to the papers which > introduced the sliced ELLPACK stuff. > Possibly there are other matrix man pages which could also benefit from > references. > Similarly the source code for these matrix types should ideally also use > the function PetscCitationsRegister() to log / report these papers. > > > >> >> Smallest change could be as simple as mirroring MATSBAIJ, which is clear >> and concise: >> >> MATMPISBAIJ >> <https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MATMPISBAIJ.html#MATMPISBAIJ> >> = "mpisbaij" - A matrix type to be used for distributed symmetric sparse >> block matrices, based on block compressed sparse row format. Only the upper >> triangular portion of the "diagonal" portion of the matrix is stored. For >> complex numbers by default this matrix is symmetric, NOT Hermitian >> symmetric. To make it Hermitian symmetric you can call MatSetOption >> <https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MatSetOption.html#MatSetOption> >> (Mat >> <https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/Mat.html#Mat>, >> MAT_HERMITIAN >> <https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MatOption.html#MatOption> >> ); >> >> >> Clearest case would be: >> >> MATMPISBAIJ = "mpisbaij" - *MATrix MPI Symmetric Block AIJ.* A matrix >> type to be used for distributed symmetric sparse block matrices, based on >> block compressed sparse row format. >> >> Only the upper triangular portion of the "diagonal" portion of the matrix >> is stored. For complex numbers by default this matrix is symmetric, NOT >> Hermitian symmetric. To make it Hermitian symmetric you >> can call MatSetOption(Mat, MAT_HERMITIAN); >> >> >> Each format is useful in its own case, but people can’t use things if >> they don’t know what it is! >> >> Best regards, >> >> Jacob Faibussowitsch >> (Jacob Fai - booss - oh - vitch) >> Cell: (312) 694-3391 >> >> >
