> 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/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/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/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL> > > https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM > > <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! But I think it needs to moved away from the create calls and to the all upper-case impls sections. 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... 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] > <mailto:[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/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/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/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL> > > https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM > > <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 >
