<div><br></div><div><br><div class="gmail_quote"><div dir="ltr">On Thu 26. Mar 2020 at 21:19, Jacob Faibussowitsch <<a href="mailto:jacob.fai@gmail.com">jacob.fai@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word;line-break:after-white-space"><blockquote type="cite"><div dir="ltr"><div class="gmail_quote"><div>Actually, the man pages for specific constructors actually yields more useful information (in nearly all cases) about the formats.</div><div>Take a look at these pages<br></div><div><br></div><div><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateSELL.html#MatCreateSELL" target="_blank">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateSELL.html#MatCreateSELL</a></div><div><br></div><div><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJCRL.html#MatCreateMPIAIJCRL" target="_blank">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJCRL.html#MatCreateMPIAIJCRL</a></div><div><br></div><div><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL" target="_blank">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL</a></div><div><br></div><div><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM" target="_blank">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM</a></div><div><br></div><div>Is that more informative?</div></div></div></blockquote><div><br></div>Yes this is pretty much what I had in mind! </div></blockquote><div dir="auto"><br></div><div dir="auto">Cool.</div><div dir="auto"><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word;line-break:after-white-space">But I think it needs to moved away from the create calls and to the all upper-case impls sections. </div></blockquote><div dir="auto"><br></div><div dir="auto">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</div><div dir="auto"><br></div><div dir="auto"><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word;line-break:after-white-space">Currently the work-flow of the mat examples I have seen are as follows:<div><br></div><div>MatCreate();</div><div>MatSetSizes();</div><div>MatSetType();</div><div><br></div><div>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><div></div></div></div></blockquote><div dir="auto"><br></div><div dir="auto">Sure - I agree with you.</div><div dir="auto"><br></div><div dir="auto"><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word;line-break:after-white-space"><div><div><br></div><div>Also as Junchao noted:<div><br></div><div><blockquote type="cite"><span style="color:rgb(0,0,0)">Even better, with examples showing a small matrix.</span></blockquote><div><br></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><br></div><div>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><br></div><div><div></div></div></div></div></div><div style="word-wrap:break-word;line-break:after-white-space"><div><div><div><div><div>
<div dir="auto" style="color:rgb(0,0,0);letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none;word-wrap:break-word;line-break:after-white-space"><div>Best regards,<br><br>Jacob Faibussowitsch<br>(Jacob Fai - booss - oh - vitch)<br>Cell: (312) 694-3391</div></div>
</div>
<div><br><blockquote type="cite"><div>On Mar 26, 2020, at 3:00 PM, Dave May <<a href="mailto:dave.mayhem23@gmail.com" target="_blank">dave.mayhem23@gmail.com</a>> wrote:</div><br><div><div dir="ltr"><div dir="ltr"><br></div><br><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" target="_blank">jacob.fai@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div>Hello,<div><br></div><div>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><br></div><div><blockquote type="cite"><a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MATAIJSELL.html#MATAIJSELL" target="_blank">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">MatSeqAIJSetPreallocation</a>() is supported, and similarly <a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MatMPIAIJSetPreallocation.html#MatMPIAIJSetPreallocation" target="_blank">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><br></div></div></div></blockquote><div><br></div><div>Agreed that is not particularly informative.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div><div></div><div>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><br></div><div>Actually, the man pages for specific constructors actually yields more useful information (in nearly all cases) about the formats.</div><div>Take a look at these pages<br></div><div><br></div><div><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateSELL.html#MatCreateSELL" target="_blank">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateSELL.html#MatCreateSELL</a></div><div><br></div><div><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJCRL.html#MatCreateMPIAIJCRL" target="_blank">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJCRL.html#MatCreateMPIAIJCRL</a></div><div><br></div><div><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL" target="_blank">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJMKL.html#MatCreateMPIAIJMKL</a></div><div><br></div><div><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM" target="_blank">https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateMPIAIJPERM.html#MatCreateMPIAIJPERM</a></div><div><br></div><div>Is that more informative?<br></div><div><br></div><div>Admittedly the SELL man page should include references to the papers which introduced the sliced ELLPACK stuff.</div><div>Possibly there are other matrix man pages which could also benefit from references.</div><div>Similarly the source code for these matrix types should ideally also use the function PetscCitationsRegister() to log / report these papers.<br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div><div><br></div><div>Smallest change could be as simple as mirroring MATSBAIJ, which is clear and concise:</div></div><div><br></div><div></div><div><blockquote type="cite"><a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MATMPISBAIJ.html#MATMPISBAIJ" target="_blank">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">MatSetOption</a>(<a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/Mat.html#Mat" target="_blank">Mat</a>, <a href="https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/Mat/MatOption.html#MatOption" target="_blank">MAT_HERMITIAN</a>); </blockquote><div>
<div dir="auto" style="text-align:start;text-indent:0px"><div style="letter-spacing:normal;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><br></div><div style="letter-spacing:normal;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none">Clearest case would be:</div><div style="letter-spacing:normal;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none"><br></div><div><blockquote type="cite"><font><span>MATMPISBAIJ = "mpisbaij" - <u>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"><font><span>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><br></div><div>Each format is useful in its own case, but people can’t use things if they don’t know what it is!</div><div><br></div><div style="letter-spacing:normal;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none">Best regards,<br><br>Jacob Faibussowitsch<br>(Jacob Fai - booss - oh - vitch)<br>Cell: (312) 694-3391</div></div>
</div>
<br></div></div></blockquote></div></div>
</div></blockquote></div><br></div></div></div></div></div></blockquote></div></div>