Improve MultiMat Sphinx documentation #1476
Conversation
BradWhitlock
requested review from
kennyweiss,
rhornung67,
publixsubfan,
Arlie-Capps,
white238,
nselliott,
gunney1 and
bmhan12
…/LLNL/axom into feature/whitlock/multimat_documentation
|
FYI, Here's the link to the generated ReadTheDocs for this PR: https://axom.readthedocs.io/en/feature-whitlock-multimat_documentation/axom/multimat/docs/sphinx/index.html |
| The CMR determines how materials are allocated to each cell but it does not determine | ||
| how much of each material is present in the cell. Volume fractions determine how much of each material | ||
| exists in each cell and is given as a percentage. If a cell contains materials A and B |
There was a problem hiding this comment.
Please consider rephrasing to "The CMR determines which materials are present in each cell; volume fractions determine how much of each material is present in each cell." This shortens the first two sentences to one sentence with two parallel phrases: to me, this helps with clarity. Also, I don't think you need "given as a percentage," since the next sentence gives an example.
| cell are: *0.2* and *0.8*. Note that the sum of volume fractions in a cell must equal 1 | ||
| to account for all of the cell. Volume fractions must be provided for every valid |
There was a problem hiding this comment.
Will multimat itself object if the volume fractions don't sum to 1? Is there a consistency check for this error mode, or will it just wait until it bites your algorithm?
There was a problem hiding this comment.
It doesn't enforce it really, but it will flag the error if MultiMat::isValid() is called. I added a statement to this effect.
| called a dense field. Dense fields are easy to understand since they have values for | ||
| every cell/material pair and they take more memory since zeroes must be provided even | ||
| for invalid cell/material pairs. Fields can also be sparse, which eliminates the zeroes | ||
| where a material does not exist. |
There was a problem hiding this comment.
Suggestion: rephrase to "Dense fields are easy to understand: they have values for every cell/material pair. Dense fields store zeros for cells where a material is not present. Fields can also be sparse, saving memory by eliminating the zeros where a material does not exist."
(I think both "zeros" and "zeroes" are correct. Not sure on that.)
| .. code-block:: cpp | ||
|
|
||
| constexpr int nComponents = 1; | ||
| double data[] = {0., | ||
| 1., | ||
| 2., | ||
| // more values ... | ||
| }; | ||
| axom::ArrayView<double> dataAV(data, sizeof(data) / sizeof(double)); | ||
| mm.addField("x2", | ||
| axom::multimat::FieldMapping::PER_CELL, | ||
| axom::multimat::DataLayout::CELL_DOM, | ||
| axom::multimat::SparsityLayout::SPARSE, | ||
| dataAV, | ||
| nComponents); |
There was a problem hiding this comment.
It would be very helpful to me if you could expand this example to have a diagram of (say) a 2x3 mesh with maybe two materials. Perhaps you could skip the call to setCellMatRel() and setVolfracField(). But it would help if you had three calls to addField(), one with PER_CELL, one with PER_MAT, and one with PER_CELL_MAT and CELL_DOM. These could all be DENSE, because you haven't gotten to the discussion of index sets yet. I think seeing everything fully written out would help readers learn these concepts.
There was a problem hiding this comment.
I moved code snippets into a basic.cpp example that compiles and added more examples of adding fields.
| For algorithms where sparse data traversal is desired, there are multiple options. The | ||
| MultiMat indexing sets can be used directly. Cells are iterated first in this example |
There was a problem hiding this comment.
Suggest condensing these two sentences to something like "For algorithms where sparse data traversal is desired, the MultiMat indexing sets can be used directly as an alternative to dense traversal patterns." I dunno. Maybe it's just a style question.
| API Documentation | ||
| ----------------- | ||
|
|
||
| Doxygen generated API documentation can be found here: `API documentation <../../../../doxygen/html/coretop.html>`_ |
There was a problem hiding this comment.
This links to the top of core instead of multimat. Maybe the last bit needs to be multimattop.html?
Doxygen multimat page: https://axom.readthedocs.io/en/feature-whitlock-multimat_documentation/doxygen/html/multimattop.html
| +--------------------+----------------------------------------------------------+ | ||
| | FieldMapping | Meaning | | ||
| +====================+==========================================================+ | ||
| | PER_CELL | The field contains up to ncells*ncomponents values (for | |
There was a problem hiding this comment.
Minor: A space before and after the * in this table and elsewhere may make the sizing dimensions more clear.
(ncells * ncomponents versus ncells*ncomponents).
This PR adds Sphinx documentation for Axom's MultiMat component. A couple of missing methods were also added that help the user query field properties.
Resolves #1362.