[petsc-dev] Very Useful Description of MAT Types in Petsc Index

[Dave May]

On Thu 26. Mar 2020 at 21:19, Jacob Faibussowitsch <jacob.fai at gmail.com>
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 <dave.mayhem23 at gmail.com> wrote:
>
>
>
> On Thu, 26 Mar 2020 at 19:26, Jacob Faibussowitsch <jacob.fai at gmail.com>
> 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
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20200326/7eb56013/attachment-0001.html>