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

[Dave May]

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/b5527b3e/attachment-0001.html>