[petsc-dev] MatDuplicate documentation needs clarification

[Barry Smith]

> On Jul 19, 2017, at 2:59 PM, Richard Tran Mills <rtmills at anl.gov> wrote:
> 
> Folks,
> 
> Looking at the MatDuplicate documentation, I think we could use some clarification. For the second argument, what this currently says is
> 
> "op - either MAT_DO_NOT_COPY_VALUES or MAT_COPY_VALUES, cause it to copy the numerical values in the matrix MAT_SHARE_NONZERO_PATTERN to share the nonzero patterns with the previous matrix and not copy them."
> 
> What? Either A or B -- but C is also a possibility? That is not normal English usage. Should it say something instead like
> 
> "op - If MAT_DO_NOT_COPY_VALUES, create an empty matrix using the same nonzero pattern as the original matrix; if MAT_COPY_VALUES, copy the numerical values in the matrix as well. If MAT_SHARE_NONZERO_PATTERN, then both parent and child matrices will have the same nonzero pattern and share the same index (I and J) arrays"

  Richard,

  Maybe better as three bullets on different lines

$  MAT_DO_NOT_COPY_VALUES - create a matrix with the same nonzero pattern as the original matrix with zeros for the numerical values
$  MAT_COPY_VALUES - create a matrix with the same nonzero pattern as the original matrix  and with the same numerical values
$  MAT_SHARE_NONZERO_PATTERN - create a matrix that shares the nonzero structure with the previous matrix and does not copy it, uses zeros for the numerical values. Note that you cannot insert new nonzero entries into this matrix or the matrix it is duplicated from.

   Note that  it would be better to only have the text in MatDuplicateOption manual page and have MatDuplicate() manual page say see MatDuplicateOption for the meaning of the values. Otherwise the two pages will get out of sync.

   I also etaged the code for MAT_SHARE_NONZERO_PATTERN  and see that SeqAIJ does not support this option and will make a copy of the nonzero structure in the new matrix, maybe this should be documented. I don't think it is a "bug" it is just that AIJ doesn't have this memory optimization.

   Barry



> 
> --Richard