[arcane,materials+doc] Ajoute documentation pour l'utilisation des ma…

…tériaux avec l'API accélérateur.

arcane/doc/doc_user/chap_acceleratorapi/0_acceleratorapi.md

@@ -11,10 +11,13 @@ Sommaire de ce chapitre :
   Présente les mécanismes disponibles dans %Arcane pour pouvoir utiliser
   les accélérateurs (GPU) dans %Arcane.
 
-2. \subpage arcanedoc_acceleratorapi_reduction <br>
+2. \subpage arcanedoc_acceleratorapi_materials <br>
+  Présente l'utilisation de l'API accélérateur pour les matériaux.
+
+3. \subpage arcanedoc_acceleratorapi_reduction <br>
   Présente les mécanismes disponibles pour effectuer des réductions.
 
-3. \subpage arcanedoc_acceleratorapi_memorypool <br>
+4. \subpage arcanedoc_acceleratorapi_memorypool <br>
   Présente le mécanisme de pool de mémoire.
 ____
 

arcane/doc/doc_user/chap_acceleratorapi/4_accelerator.md → arcane/doc/doc_user/chap_acceleratorapi/1_accelerator.md

@@ -667,4 +667,7 @@ ____
 <span class="back_section_button">
 \ref arcanedoc_acceleratorapi
 </span>
+<span class="next_section_button">
+\ref arcanedoc_accelerator_materials
+</span>
 </div>

arcane/doc/doc_user/chap_acceleratorapi/3_materials.md

@@ -0,0 +1,87 @@
+# Utilisation pour les matériaux {#arcanedoc_acceleratorapi_materials}
+
+[TOC]
+
+L'utilisation de l'API accélérateur pour les matériaux est similaire à
+l'utilisation sur les entités du maillage. La macro
+RUNCOMMAND_MAT_ENUMERATE() permet d'itérer sur un milieu
+\arcanemat{IMeshEnvironment} ou un matériau \arcanemat{IMeshMaterial}.
+
+Les valeurs possibles pour cette macro sont:
+
+<table>
+<tr>
+<th>Type d'itération</th><th>Valeur de l'itérateur</th>
+<th>Type du conteneur</th><th>Description</th>
+</tr>
+
+<tr>
+<td>EnvAndGlobalCell</td>
+<td>\arcanemat{EnvAndGlobalCellIteratorValue}</td>
+<td>\arcanemat{IMeshEnvironment} <br></br>
+\arcanemat{EnvCellVectorView}</td>
+<td>Itération sur un milieu permettant de récupérer pour chaque itération
+le numéro local de la maille milieu, l'index de l'itération et le
+numéro local de la maille globale associée</td>
+</tr>
+
+<tr>
+<td>MatAndGlobalCell</td>
+<td>\arcanemat{MatAndGlobalCellIteratorValue}</td>
+<td>\arcanemat{IMeshMaterial} <br></br> \arcanemat{MatCellVectorView}</td>
+<td>Itération sur un matériau permettant de récupérer pour chaque itération
+le numéro local de la maille matériau, l'index de l'itération et le
+numéro local de la maille globale associée</td>
+</tr>
+
+<tr>
+<td>AllEnvCell</td>
+<td>\arcanemat{AllEnvCell}</td>
+<td>\arcanemat{AllEnvCellVectorView}</td>
+<td>Itération sur les AllEnvCell</td>
+</tr>
+
+<tr>
+<td>EnvCell</td>
+<td>\arcanemat{EnvCellLocalId}</td>
+<td>\arcanemat{IMeshEnvironment} <br></br> \arcanemat{EnvCellVectorView}</td>
+<td>Itération sur un milieu permettant de récupérer pour chaque itération
+uniquement le numéro local de la maille milieu</td>
+</tr>
+
+<tr>
+<td>MatCell</td>
+<td>\arcanemat{MatCellLocalId}</td>
+<td>\arcanemat{IMeshMaterial} <br></br> \arcanemat{MatCellVectorView}</td>
+<td>Itération sur un matériau permettant de récupérer pour chaque itération
+uniquement le numéro local de la maille matériau</td>
+</tr>
+
+</table>
+
+Si on souhaite uniquement accéder aux numéros locaux des mailles
+matériaux ou milieux il est préférable pour des raisons de performance
+d'utiliser la version avec `EnvCell` ou `MatCell` comme type
+d'itérateur.
+
+Voici un exemple de code pour itérer sur une maille milieu avec
+l'information de l'index de l'itération et de la maille globale associée
+
+\snippet MeshMaterialAcceleratorUnitTest.cc SampleEnvAndGlobalCell
+
+Voici un autre exemple pour itérer sur les \arcanemat{AllEnvCell} et
+récupérer les informations sur les milieux et matériaux présents dans
+chaque \arcanemat{AllEnvCell}
+
+\snippet MeshMaterialAcceleratorUnitTest.cc SampleAllEnvCell
+
+____
+
+<div class="section_buttons">
+<span class="back_section_button">
+\ref arcanedoc_parallel_accelerator
+</span>
+<span class="next_section_button">
+\ref arcanedoc_acceleratorapi_reduction
+</span>
+</div>

arcane/doc/doc_user/chap_acceleratorapi/5_reduce.md

@@ -72,7 +72,7 @@ ____
 
 <div class="section_buttons">
 <span class="back_section_button">
-\ref arcanedoc_parallel_accelerator
+\ref arcanedoc_acceleratorapi_materials
 </span>
 <span class="next_section_button">
 \ref arcanedoc_acceleratorapi_memorypool

arcane/src/arcane/accelerator/RunCommandMaterialEnumerate.h

@@ -29,7 +29,7 @@
 /*---------------------------------------------------------------------------*/
 /*---------------------------------------------------------------------------*/
 
-namespace Arcane::Accelerator
+namespace Arcane::Materials
 {
 
 /*---------------------------------------------------------------------------*/
@@ -114,10 +114,16 @@ class ConstituentAndGlobalCellIteratorValue
   Int32 m_index = -1;
 };
 
+//! Type de la valeur de l'itérateur pour RUNCOMMAND_MAT_ENUMERATE(EnvAndGlobalCell,...)
+using EnvAndGlobalCellIteratorValue = ConstituentAndGlobalCellIteratorValue<EnvItemLocalId>;
+
+//! Type de la valeur de l'itérateur pour RUNCOMMAND_MAT_ENUMERATE(MatAndGlobalCell,...)
+using MatAndGlobalCellIteratorValue = ConstituentAndGlobalCellIteratorValue<MatItemLocalId>;
+
 /*---------------------------------------------------------------------------*/
 /*---------------------------------------------------------------------------*/
 
-} // namespace Arcane::Accelerator
+} // namespace Arcane::Materials
 
 /*---------------------------------------------------------------------------*/
 /*---------------------------------------------------------------------------*/
@@ -300,7 +306,7 @@ class ConstituentAndGlobalCellRunCommandBase
 
   using ThatClass = ConstituentAndGlobalCellRunCommandBase<ConstituentItemLocalIdType_, ContainerCreateViewType_>;
   using CommandType = ThatClass;
-  using IteratorValueType = ConstituentAndGlobalCellIteratorValue<ConstituentItemLocalIdType_>;
+  using IteratorValueType = Arcane::Materials::ConstituentAndGlobalCellIteratorValue<ConstituentItemLocalIdType_>;
   using ContainerCreateViewType = ContainerCreateViewType_;
 
  public:
@@ -767,7 +773,8 @@ operator<<(RunCommand& command, const impl::MatCellRunCommand::Container& view)
  * \param iter_name est le nom de l'itérateur
  * \param env_or_mat_container est le conteneur sur lequel on itère.
  *
- * Les paramètres supplémentaires sont utilisés pour les réductions.
+ * Les paramètres supplémentaires sont utilisés pour les réductions
+ * (voir \ref arcanedoc_acceleratorapi_reduction)
  *
  * \a ConstituentItemNameType doit être une des valeurs suivantes:
  *
@@ -777,7 +784,7 @@ operator<<(RunCommand& command, const impl::MatCellRunCommand::Container& view)
  * - MatCell
  * - AllEnvCell
  *
- * \sa arcanedoc_acceleratorapi_materials
+ * Voir \ref arcanedoc_acceleratorapi_materials pour plus d'informations.
  */
 #define RUNCOMMAND_MAT_ENUMERATE(ConstituentItemNameType, iter_name, env_or_mat_container, ...) \
   A_FUNCINFO << ::Arcane::Accelerator::impl::makeExtendedConstituentItemEnumeratorLoop<ConstituentItemNameType>(env_or_mat_container __VA_OPT__(, __VA_ARGS__)) \

arcane/src/arcane/core/materials/MaterialsCoreGlobal.h

@@ -173,6 +173,12 @@ using CellMatCellEnumerator = CellComponentCellEnumeratorT<MatCell>;
 //! Enumérateur sur les mailles milieux d'une maille.
 using CellEnvCellEnumerator = CellComponentCellEnumeratorT<EnvCell>;
 
+//! Index d'un MatItem dans une variable.
+using MatCellLocalId = MatItemLocalId;
+
+//! Index d'un EnvItem dans une variable.
+using EnvCellLocalId = EnvItemLocalId;
+
 /*---------------------------------------------------------------------------*/
 /*---------------------------------------------------------------------------*/
 

arcane/src/arcane/tests/accelerator/MeshMaterialAcceleratorUnitTest.cc

@@ -735,30 +735,33 @@ _executeTest4(Integer nb_z, bool use_new_impl)
 
     if (use_new_impl) {
       for (Integer z = 0, iz = nb_z; z < iz; ++z) {
-        AllEnvCellVectorView all_env_view = m_mm_mng->view(allCells());
+        //![SampleAllEnvCell]
+        Arcane::Materials::AllEnvCellVectorView all_env_view = m_mm_mng->view(allCells());
         auto cmd = makeCommand(queue);
         auto in_b = viewIn(cmd, m_mat_b);
         auto out_c = viewOut(cmd, m_mat_c);
         auto in_c_g = viewIn(cmd, m_mat_c.globalVariable());
         auto out_a_g = viewOut(cmd, m_mat_a);
-        cmd << RUNCOMMAND_MAT_ENUMERATE(AllEnvCell, all_env_cell, all_env_view)
+        cmd << RUNCOMMAND_MAT_ENUMERATE(AllEnvCell, all_env_cell_iter, all_env_view)
         {
-          CellLocalId cid = all_env_cell.globalCellId();
+          Arcane::Materials::AllEnvCell all_env_cell = all_env_cell_iter;
+          Arcane::CellLocalId cid = all_env_cell.globalCellId();
           Real sum2 = 0.0;
-          for (EnvCell ev : all_env_cell.subEnvItems()) {
+          for (Arcane::Materials::EnvCell ev : all_env_cell.subEnvItems()) {
             sum2 += in_b[ev] + in_b[cid];
           }
 
           Real sum3 = 0.0;
           if (all_env_cell.nbEnvironment() > 1) {
-            for (EnvCell ev : all_env_cell.subEnvItems()) {
+            for (Arcane::Materials::EnvCell ev : all_env_cell.subEnvItems()) {
               Real contrib2 = (in_b[ev] + in_b[all_env_cell]) - (sum2 + 1.);
               out_c[ev] = contrib2 * in_c_g[cid];
               sum3 += contrib2;
             }
           }
           out_a_g[cid] = sum3;
         };
+        //![SampleAllEnvCell]
       }
     }
     else {
@@ -910,19 +913,29 @@ _executeTest4(Integer nb_z, bool use_new_impl)
 void MeshMaterialAcceleratorUnitTest::
 _executeTest6()
 {
-  Int32 nb_cell = m_env1->cells().size();
-  NumArray<Int32, MDDim1> cells_local_id(nb_cell);
+  //![SampleEnvAndGlobalCell]
+  Arcane::Materials::IMeshEnvironment* env1 = m_env1;
+  Int32 nb_cell = env1->cells().size();
+  Arcane::NumArray<Int32, MDDim1> cells_local_id(nb_cell);
+  Arcane::Materials::MaterialVariableCellReal& mat_a = m_mat_a;
 
   {
     auto queue = makeQueue(m_runner);
     auto command = makeCommand(queue);
     auto cells_local_id_view = viewOut(command, cells_local_id);
-    command << RUNCOMMAND_MAT_ENUMERATE(EnvAndGlobalCell, evi, m_env1)
+    auto out_mat_a = viewOut(command, mat_a);
+    command << RUNCOMMAND_MAT_ENUMERATE(EnvAndGlobalCell, iter, m_env1)
     {
-      auto [mvi, cid] = evi();
-      cells_local_id_view[evi.index()] = cid;
+      EnvAndGlobalCellIteratorValue evi = iter; // Valeur de l'itérateur
+      auto [iter_mvi, iter_cid] = evi();
+      EnvCellLocalId mvi = iter_mvi; // Numéro local de la maille milieu
+      Arcane::CellLocalId cid = iter_cid; // Numéro de la maille globale de la maille milieu courante
+      Int32 iter_index = evi.index(); // Index de l'itération
+      cells_local_id_view[iter_index] = cid;
+      out_mat_a[mvi] = 1.2;
     };
   }
+  //![SampleEnvAndGlobalCell]
   {
     ENUMERATE_ENVCELL (ienvcell, m_env1) {
       EnvCell env_cell(*ienvcell);