Skip to content

Commit a73d429

Browse files
BradWhitlockBradWhitlock
authored
Merge pull request #1476 from LLNL/feature/whitlock/multimat_documentation
Improve MultiMat Sphinx documentation
2 parents 56c8787 + a78d2d3 commit a73d429

17 files changed

+1197
-8
lines changed

‎.gitlab/build_lassen.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,13 @@
2323
# Template
2424
.src_build_on_lassen:
2525
variables:
26-
ALLOC_TIME: "25"
26+
ALLOC_TIME: "40"
2727
extends: [.src_build_script, .on_lassen, .src_workflow]
2828
needs: []
2929

3030
.full_build_on_lassen:
3131
variables:
32-
ALLOC_TIME: "45"
32+
ALLOC_TIME: "60"
3333
extends: [.full_build_script, .on_lassen, .full_workflow]
3434
needs: []
3535

‎.gitlab/build_tioga.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
# Template
2323
.src_build_on_tioga:
2424
variables:
25-
ALLOC_TIME: "30"
25+
ALLOC_TIME: "40"
2626
extends: [.src_build_script, .on_tioga, .src_workflow]
2727
needs: []
2828

‎src/axom/multimat/docs/sphinx/figures/axom_multimat_diagrams.pptx

101 KB
Binary file not shown.

‎src/axom/multimat/docs/sphinx/figures/mapping.png

96.7 KB
Loading

‎src/axom/multimat/docs/sphinx/figures/relation.png

117 KB
Loading

‎src/axom/multimat/docs/sphinx/figures/sparsity.png

164 KB
Loading

‎src/axom/multimat/docs/sphinx/figures/volume_fractions.png

119 KB
Loading

‎src/axom/multimat/docs/sphinx/index.rst

+29-2
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,33 @@ Multimat User Guide
77
====================
88

99
Axom's MultiMat component is a data management library for multimaterial field data
10-
within multiphysics simulation codes.
10+
within multiphysics simulation codes. Simulation codes use materials to overlay extra
11+
parts and details onto a mesh without requiring those features to be modeled
12+
conformally. Instead of using cells to model the part geometry, the geometry is
13+
instead represented using materials and volume fractions. The method for adding
14+
such details is often called *"shaping"* and it is covered in Axom's
15+
:doc:`Klee <../../../../axom/klee/docs/sphinx/index>` and :doc:`Quest <../../../../axom/quest/docs/sphinx/index>`
16+
components.
1117

12-
We are working on documentation for this component.
18+
In addition to representing materials on a mesh, MultiMat is used to define
19+
fields on the mesh, and over material subsets. This enables fields to contain multiple
20+
values where needed for mixed-material cells. MultiMat supports flexible data mappings,
21+
layouts, and dense vs sparse field storage, allowing field data to occupy less memory
22+
than would otherwise be necessary.
23+
24+
25+
26+
API Documentation
27+
-----------------
28+
29+
Doxygen generated API documentation can be found here: `API documentation <../../../../doxygen/html/multimattop.html>`_
30+
31+
32+
.. toctree::
33+
:caption: Contents
34+
:maxdepth: 1
35+
36+
multimat_materials
37+
multimat_field_concepts
38+
multimat_using_fields
39+
multimat_dynamic_mode

‎src/axom/multimat/docs/sphinx/multimat_dynamic_mode.rst

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
.. ## Copyright (c) 2017-2024, Lawrence Livermore National Security, LLC and
2+
.. ## other Axom Project Developers. See the top-level LICENSE file for details.
3+
.. ##
4+
.. ## SPDX-License-Identifier: (BSD-3-Clause)
5+
6+
******************************************************
7+
Dynamic Mode
8+
******************************************************
9+
10+
The distribution of materials in MultiMat is controlled by the
11+
Cell-Material Relation (CMR). For many MultiMat use cases, this is set
12+
once (static mode) and then fields are defined on the MultiMat object. MultiMat
13+
also supports a dynamic mode that permits materials to move around in the mesh.
14+
15+
When creating a MultiMat object using the default constructor, it will default
16+
to static mode using ``CELL_DOM`` data layout with sparse data. The data layout
17+
argument later impacts the ``addEntry()`` and ``removeEntry()`` methods that modify
18+
the MultiMat object's CMR in dynamic mode. For those methods, when MultiMat is
19+
created with a ``CELL_DOM`` data layout, it means that the first argument to
20+
``addEntry()`` will be a cell number and the second will be a material number.
21+
22+
To convert the MultiMat object to dynamic mode, call the ``convertToDynamic()``
23+
method. This method changes some internal representations (including field
24+
organization) to better support dynamic modifications of the CMR. For example,
25+
when changing to dynamic mode, ``SPARSE`` fields are converted to ``DENSE``
26+
so further changes do not require field data to be reallocated/reorganized
27+
again. The CMR is modified using calls to the ``addEntry()`` and ``removeEntry()``
28+
methods.
29+
30+
.. literalinclude:: ../../examples/basic.cpp
31+
:start-after: _multimat_dynamic_mode_begin
32+
:end-before: _multimat_dynamic_mode_end
33+
:language: C++

‎src/axom/multimat/docs/sphinx/multimat_field_concepts.rst

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
.. ## Copyright (c) 2017-2024, Lawrence Livermore National Security, LLC and
2+
.. ## other Axom Project Developers. See the top-level LICENSE file for details.
3+
.. ##
4+
.. ## SPDX-License-Identifier: (BSD-3-Clause)
5+
6+
******************************************************
7+
Field Concepts
8+
******************************************************
9+
10+
Fields are data that are defined over a mesh, typically with one or more values
11+
per cell. Fields can be scalar, indicating 1-component per cell - or they can
12+
contain multiple components as with vector data (2+ components per cell). This
13+
section discusses important MultiMat field concepts that determine where fields
14+
live on the mesh and how their data are organized in memory.
15+
16+
#######################
17+
Field Mapping
18+
#######################
19+
20+
MultiMat associates materials with cells in a mesh, possibly subdividing cells.
21+
MultiMat includes the concept of field *mapping*, which is where on the mesh the
22+
field data live. Fields can be defined over the cells, which is how most simulations
23+
think about cell-centered fields. With MultiMat, fields can also be defined over
24+
the materials, allowing for compact storage of material-level data. Fields can
25+
also be defined over the cells/material pairs from the Cell-Material Relation (CMR),
26+
allowing fields to have data values for each material in a cell.
27+
28+
.. figure:: figures/mapping.png
29+
:figwidth: 700px
30+
31+
Diagram showing field mapping concept.
32+
33+
+--------------------+-----------------------------------------------------------+
34+
| FieldMapping | Meaning |
35+
+====================+===========================================================+
36+
| PER_CELL | The field contains up to ncells * ncomponents values (for |
37+
| | dense storage) and there are ncomponents values per cell. |
38+
| | For scalars *ncomponents* is 1 so the field length is |
39+
| | ncells. |
40+
+--------------------+-----------------------------------------------------------+
41+
| PER_MAT | The field contains nmats * ncomponents values and there |
42+
| | are ncomponents values per material. This mapping allows |
43+
| | fields to be defined over the entire material region and |
44+
| | any cell that uses the material inherits the per-material |
45+
| | field value, allowing for very compact storage of |
46+
| | material-level properties. |
47+
+--------------------+-----------------------------------------------------------+
48+
| PER_CELL_MAT | The field contains up to ncells * nmats * ncomponents (for|
49+
| | dense storage). This mapping allows materials within a |
50+
| | cell to have their own unique values, which makes them |
51+
| | useful for tracking data at a sub-cell level. |
52+
+--------------------+-----------------------------------------------------------+
53+
54+
#######################
55+
Data Layout
56+
#######################
57+
58+
Simulation codes contain a variety of algorithms that may have a preference for how
59+
data are arranged in memory to ensure good performance. MultiMat supports
60+
fields with a ``PER_CELL_MAT`` mapping and there are two ways to organize such data.
61+
Fields are said to be **Cell-Dominant** (``CELL_DOM``) if they are stored such that
62+
each cell stores all of its material data to memory before proceeding to data for
63+
the next cell. Fields are **Material-Dominant** (``MAT_DOM``) if the data for all
64+
cells that use the material is stored before proceeding to the next material.
65+
The data layout for multi-material data can be thought of as 2 nested for-loops where
66+
the outer loop is the dominant loop. For example, if iterating over materials and
67+
then cells, the data are stored using ``MAT_DOM`` layout.
68+
69+
+--------------------+----------------------------------------------------------+
70+
| DataLayout | Meaning |
71+
+====================+==========================================================+
72+
| CELL_DOM | Data are stored for each cell and then for each material |
73+
| | like this *(c=cell, m=material)*: |
74+
| | |
75+
| | ``{c0m0, c0m1, c0m2, ..., c1m0, c1m1, c1m2, ...}`` |
76+
+--------------------+----------------------------------------------------------+
77+
| MAT_DOM | Data are stored for each material and then for each cell |
78+
| | like this *(m=material, c=cell)*: |
79+
| | |
80+
| | ``{m0c0, m0c1, m0c2, m0c3, ... , m1c0, m1c1, m1c2, ...}``|
81+
+--------------------+----------------------------------------------------------+
82+
83+
#######################
84+
Sparsity Layout
85+
#######################
86+
87+
Sparsity primarily concerns fields with ``PER_CELL_MAT`` mapping. When initializing
88+
the MultiMat object, the CMR indicates how materials are distributed
89+
over the mesh. It is completely acceptable for materials to skip over certain cells,
90+
which makes sense if we think about materials as a way to divide up the mesh into
91+
various regions or parts. There are ncells * nmats pairs of data that could be entered
92+
for MultiMat fields. For ``DENSE`` fields, the field must contain ncells * nmats values,
93+
with values present for cell/material pairs whether materials are present or not.
94+
This is an easy way to specify the data but it wastes memory by including extra
95+
values whose only purpose is to keep the rectangular shape of the data array.
96+
97+
For large meshes, compressing out unnecessary values can save a lot of memory. MultiMat
98+
supports a ``SPARSE`` layout that does not include any unnecessary values. If we
99+
regard the CMR as a matrix of true/false values, a user must only provide field values
100+
for ``SPARSE`` data where the CMR contains true values.
101+
102+
103+
.. figure:: figures/sparsity.png
104+
:figwidth: 700px
105+
106+
Mixed-material volume fraction field with both DENSE and SPARSE representations.
107+
108+
109+
110+
+--------------------+----------------------------------------------------------+
111+
| SparsityLayout | Meaning |
112+
+====================+==========================================================+
113+
| DENSE | Data are provided for all ncells * nmats pairs, even if |
114+
| | there is no cell/material that is valid. |
115+
+--------------------+----------------------------------------------------------+
116+
| SPARSE | Data are provided for only the cell/material pairs that |
117+
| | are valid according to the CMR. |
118+
+--------------------+----------------------------------------------------------+

‎src/axom/multimat/docs/sphinx/multimat_materials.rst

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
.. ## Copyright (c) 2017-2024, Lawrence Livermore National Security, LLC and
2+
.. ## other Axom Project Developers. See the top-level LICENSE file for details.
3+
.. ##
4+
.. ## SPDX-License-Identifier: (BSD-3-Clause)
5+
6+
******************************************************
7+
Materials
8+
******************************************************
9+
10+
MultiMat defines materials over the cells in a mesh. This section describes how to
11+
use the MultiMat object to define materials.
12+
13+
#######################
14+
Cell Material Relation
15+
#######################
16+
17+
The distribution of materials over the mesh is determined using the **Cell-Material Relation** *(CMR)*.
18+
If a mesh has *N* cells and *M* materials, each cell can have up to *M* possible values.
19+
This means the mesh will hold N*M values if each cell contains all materials.
20+
There are multiple ways to specify the CMR to MultiMat. A static material decomposition
21+
is described here, though the CMR can also be built :doc:`dynamically <multimat_dynamic_mode>`.
22+
The easiest method for defining the CMR is to provide a bool vector containing
23+
true/false values for whether a cell/material combination is valid.
24+
25+
.. figure:: figures/relation.png
26+
:figwidth: 700px
27+
28+
Diagram showing mixed-material mesh with CELL_DOM and MAT_DOM ways of defining the Cell-Material Relation.
29+
30+
The following code shows how to initialize a MultiMat object with 9 cells and 3 materials
31+
and build the CMR by populating a bool vector that is given to the MultiMat object.
32+
In the following example, the relation is expressed using a **Cell-Dominant**
33+
data layout (``CELL_DOM``). This means that the data will be arranged such that all material
34+
values for cell 0 are given, followed by all of the material values for cell 1, until all
35+
cells have provided their flags. The bool vector contains *true* if a material is present
36+
in a cell and *false* if the material is not present. This CMR vector is essentially
37+
a mask for which cell/material combinations are valid. Data can also be transposed
38+
into a **Material-Dominant** data layout (``MAT_DOM``) in which the materials are
39+
iterated first, followed by cells that use the current material.
40+
41+
.. literalinclude:: ../../examples/basic.cpp
42+
:start-after: _multimat_materials_cmr_begin
43+
:end-before: _multimat_materials_cmr_end
44+
:language: C++
45+
46+
#######################
47+
Volume Fractions
48+
#######################
49+
50+
The CMR determines which materials are present in each cell; volume fractions determine
51+
how much material is in each cell. If a cell contains materials A and B
52+
at 20% and 80%, respectively, then the volume fractions for those materials in the
53+
cell are: *0.2* and *0.8*. Note that the sum of volume fractions in a cell should equal 1
54+
to account for all of the cell, though this is not enforced unless the ``isValid()``
55+
method is called. Volume fractions must be provided for every valid cell/material pair
56+
in the CMR and they must be specified using the same data layout as data in the CMR.
57+
58+
.. figure:: figures/volume_fractions.png
59+
:figwidth: 600px
60+
61+
Diagram showing mixed-material mesh with volume fractions shown in CELL_DOM table.
62+
63+
Volume fractions are stored in MultiMat as a field and fields have an added concept
64+
of sparsity. Fields can provide data for every possible cell/material pair; this is
65+
called a dense field. Dense fields are easy to understand: they have values for
66+
every cell/material pair, even for materials that are not actually present. Fields
67+
can also be sparse, saving memory by eliminating the zeroes where a material does not
68+
exist.
69+
70+
Volume fraction data are provided to MultiMat wrapped in an ``axom::ArrayView`` object,
71+
which provides the default values for the volume fractions. The *ArrayView* is passed
72+
to MultiMat using the ``setVolfracField()`` method. The following example shows how to
73+
pass a dense volume fraction field to MultiMat. Note the zeroes where the material is
74+
not present. After adding volume fractions, the MultiMat object is fully constructed
75+
and it can be used to store field data.
76+
77+
.. literalinclude:: ../../examples/basic.cpp
78+
:start-after: _multimat_materials_volfracs_begin
79+
:end-before: _multimat_materials_volfracs_end
80+
:language: C++
81+

0 commit comments

Comments
 (0)