<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class=""><blockquote type="cite" class=""><div dir="ltr" class=""><div class="gmail_quote"><div class="">Actually, the man pages for specific constructors actually yields more useful information (in nearly all cases) about the formats.</div><div class="">Take a look at these pages<br class=""></div><div class=""><br class=""></div><div class=""><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateSELL.html#MatCreateSELL" class="">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateSELL.html#MatCreateSELL</a></div><div class=""><br class=""></div><div class=""><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJCRL.html#MatCreateMPIAIJCRL" class="">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJCRL.html#MatCreateMPIAIJCRL</a></div><div class=""><br class=""></div><div class=""><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL" class="">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL</a></div><div class=""><br class=""></div><div class=""><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM" class="">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM</a></div><div class=""><br class=""></div><div class="">Is that more informative?</div></div></div></blockquote><div class=""><br class=""></div>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:<div class=""><br class=""></div><div class="">MatCreate();</div><div class="">MatSetSizes();</div><div class="">MatSetType();</div><div class=""><br class=""></div><div class="">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...</div><div class=""><div class=""><br class=""></div><div class="">Also as Junchao noted:<div class=""><br class=""></div><div class=""><blockquote type="cite" class=""><span style="caret-color: rgb(0, 0, 0); color: rgb(0, 0, 0);" class="">Even better, with examples showing a small matrix.</span></blockquote><div class=""><br class=""></div>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. </div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class=""><div class=""><div class="">
<div dir="auto" style="caret-color: rgb(0, 0, 0); color: rgb(0, 0, 0); letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none; word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class=""><div>Best regards,<br class=""><br class="">Jacob Faibussowitsch<br class="">(Jacob Fai - booss - oh - vitch)<br class="">Cell: (312) 694-3391</div></div>
</div>
<div><br class=""><blockquote type="cite" class=""><div class="">On Mar 26, 2020, at 3:00 PM, Dave May <<a href="mailto:dave.mayhem23@gmail.com" class="">dave.mayhem23@gmail.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div dir="ltr" class=""><div dir="ltr" class=""><br class=""></div><br class=""><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, 26 Mar 2020 at 19:26, Jacob Faibussowitsch <<a href="mailto:jacob.fai@gmail.com" class="">jacob.fai@gmail.com</a>> wrote:<br class=""></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div style="overflow-wrap: break-word;" class="">Hello,<div class=""><br class=""></div><div class="">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:</div><div class=""><br class=""></div><div class=""><blockquote type="cite" class=""><a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MATAIJSELL.html#MATAIJSELL" target="_blank" class="">MATAIJSELL</a>
= "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,
<a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MatSeqAIJSetPreallocation.html#MatSeqAIJSetPreallocation" target="_blank" class="">MatSeqAIJSetPreallocation</a>() is supported, and similarly <a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MatMPIAIJSetPreallocation.html#MatMPIAIJSetPreallocation" target="_blank" class="">MatMPIAIJSetPreallocation</a>() is supported
for communicators controlling multiple processes. It is recommended that you call both of
the above preallocation routines for simplicity.</blockquote><div class=""><br class=""></div></div></div></blockquote><div class=""><br class=""></div><div class="">Agreed that is not particularly informative.<br class=""></div><div class=""> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div style="overflow-wrap: break-word;" class=""><div class=""><div class=""></div><div class="">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. </div></div></div></blockquote><div class=""><br class=""></div><div class="">Actually, the man pages for specific constructors actually yields more useful information (in nearly all cases) about the formats.</div><div class="">Take a look at these pages<br class=""></div><div class=""><br class=""></div><div class=""><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateSELL.html#MatCreateSELL" class="">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateSELL.html#MatCreateSELL</a></div><div class=""><br class=""></div><div class=""><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJCRL.html#MatCreateMPIAIJCRL" class="">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJCRL.html#MatCreateMPIAIJCRL</a></div><div class=""><br class=""></div><div class=""><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL" class="">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL</a></div><div class=""><br class=""></div><div class=""><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM" class="">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM</a></div><div class=""><br class=""></div><div class="">Is that more informative?<br class=""></div><div class=""><br class=""></div><div class="">Admittedly the SELL man page should include references to the papers which introduced the sliced ELLPACK stuff.</div><div class="">Possibly there are other matrix man pages which could also benefit from references.</div><div class="">Similarly the source code for these matrix types should ideally also use the function PetscCitationsRegister() to log / report these papers.<br class=""></div><div class=""><br class=""></div><div class=""> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div style="overflow-wrap: break-word;" class=""><div class=""><div class=""><br class=""></div><div class="">Smallest change could be as simple as mirroring MATSBAIJ, which is clear and concise:</div></div><div class=""><br class=""></div><div class=""></div><div class=""><blockquote type="cite" class=""><a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MATMPISBAIJ.html#MATMPISBAIJ" target="_blank" class="">MATMPISBAIJ</a>
= "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 <a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MatSetOption.html#MatSetOption" target="_blank" class="">MatSetOption</a>(<a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/Mat.html#Mat" target="_blank" class="">Mat</a>, <a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MatOption.html#MatOption" target="_blank" class="">MAT_HERMITIAN</a>); </blockquote><div class="">
<div dir="auto" style="text-align:start;text-indent:0px" class=""><div style="letter-spacing: normal; text-transform: none; white-space: normal; word-spacing: 0px; text-decoration: none;" class=""><br class=""></div><div style="letter-spacing: normal; text-transform: none; white-space: normal; word-spacing: 0px; text-decoration: none;" class="">Clearest case would be:</div><div style="letter-spacing: normal; text-transform: none; white-space: normal; word-spacing: 0px; text-decoration: none;" class=""><br class=""></div><div class=""><blockquote type="cite" class=""><font class=""><span class="">MATMPISBAIJ = "mpisbaij" - <u class="">MATrix MPI Symmetric Block AIJ.</u> A matrix type to be used for distributed symmetric sparse block matrices, based on block compressed sparse row format.</span></font></blockquote><blockquote type="cite" class=""><font class=""><span class="">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); </span></font></blockquote></div><div class=""><br class=""></div><div class="">Each format is useful in its own case, but people can’t use things if they don’t know what it is!</div><div class=""><br class=""></div><div style="letter-spacing: normal; text-transform: none; white-space: normal; word-spacing: 0px; text-decoration: none;" class="">Best regards,<br class=""><br class="">Jacob Faibussowitsch<br class="">(Jacob Fai - booss - oh - vitch)<br class="">Cell: (312) 694-3391</div></div>
</div>
<br class=""></div></div></blockquote></div></div>
</div></blockquote></div><br class=""></div></div></div></div></body></html>