Loops over material and environment entities

This page describes the management of loops over material and environment entities.

In the rest of this page, the generic term component is used to describe a material or an environment.

A component's entities can be divided into two parts: pure entities and impure entities. By definition, entities that are not pure are impure. The notion of purity varies depending on the component type:

• for an environment, an entity is pure if there is only one environment in that entity.
• for a material, an entity is pure if there is only one material AND only one environment.

At the memory storage level for a given variable, accessing a pure entity is equivalent to accessing the global value of that variable.

Loop Generalization

Since version 2.7.0 of Arcane, the generic macro ENUMERATE_COMPONENTITEM() allows iteration over a component's entities globally or by part (pure/impure). It can replace the macros ENUMERATE_COMPONENTCELL(), ENUMERATE_MATCELL(), and ENUMERATE_ENVCELL().

The following values are available for iteration:

ENUMERATE_COMPONENTITEM(MatCell,icell,container) with container of type IMeshMaterial* or MatCellVector.

It is possible to iterate only over the pure or impure part of a component.

Note

Currently, the traversal order of loops by pure or impure part is not defined and may evolve later. This means that if there are dependencies between loop iterations, the result may vary from one execution to another.

The following examples show the different variants of the ENUMERATE_COMPONENTITEM() macro

Loops over environments

      Arcane::CellGroup test_env_group;
      Arcane::Materials::IMeshEnvironment* env = env1;
      Arcane::Materials::EnvCellVector env_vector(test_env_group, env);
 
      // Loop over the environment cells \a env
      ENUMERATE_COMPONENTITEM (Arcane::Materials::EnvCell, ienvcell, env) {
        Arcane::Materials::EnvCell c = *ienvcell;
        mat_pressure[c] = mat_temperature[ienvcell];
      }
 
      // Loop over the environment cells \a env_vector
      ENUMERATE_COMPONENTITEM (Arcane::Materials::EnvCell, ienvcell, env_vector) {
        Arcane::Materials::EnvCell c = *ienvcell;
        mat_pressure[c] = mat_temperature[ienvcell];
      }
 
      // Loop over the pure environment cells \a env
      ENUMERATE_COMPONENTITEM (Arcane::Materials::EnvPartCell, ienvcell, env->pureEnvItems()) {
        Arcane::Materials::EnvCell c = *ienvcell;
        mat_pressure[c] = mat_temperature[ienvcell];
      }
 
      // Loop over the pure environment cells \a env
      ENUMERATE_COMPONENTITEM (Arcane::Materials::EnvPartCell, ienvcell, env, Arcane::Materials::eMatPart::Pure) {
        Arcane::Materials::EnvCell c = *ienvcell;
        mat_pressure[c] = mat_temperature[ienvcell];
      }
 
      // Loop over the impure environment cells \a env
      ENUMERATE_COMPONENTITEM (Arcane::Materials::EnvPartCell, ienvcell, env->impureEnvItems()) {
        Arcane::Materials::EnvCell c = *ienvcell;
        mat_pressure[c] = mat_temperature[ienvcell];
      }
 
      // Loop over the impure environment cells \a env
      ENUMERATE_COMPONENTITEM (Arcane::Materials::EnvPartCell, ienvcell, env, Arcane::Materials::eMatPart::Impure) {
        Arcane::Materials::EnvCell c = *ienvcell;
        mat_pressure[c] = mat_temperature[ienvcell];
      }
 

Loops over materials

      Arcane::CellGroup test_mat_group;
      Arcane::Materials::IMeshMaterial* mat = env1->materials()[0];
      Arcane::Materials::MatCellVector mat_vector(test_mat_group, mat);
 
      // Loop over the material cells \a mat
      ENUMERATE_COMPONENTITEM (Arcane::Materials::MatCell, imatcell, mat) {
        Arcane::Materials::MatCell c = *imatcell;
        mat_pressure[c] = mat_temperature[imatcell];
      }
 
      // Loop over the material cells \a mat_vector
      ENUMERATE_COMPONENTITEM (Arcane::Materials::MatCell, imatcell, mat_vector) {
        Arcane::Materials::MatCell c = *imatcell;
        mat_pressure[c] = mat_temperature[imatcell];
      }
 
      // Loop over the pure material cells \a mat
      ENUMERATE_COMPONENTITEM (Arcane::Materials::MatPartCell, imatcell, mat->pureMatItems()) {
        Arcane::Materials::MatCell c = *imatcell;
        mat_pressure[c] = mat_temperature[imatcell];
      }
 
      // Loop over the pure material cells \a mat
      ENUMERATE_COMPONENTITEM (Arcane::MatPartCell, imatcell, mat, Arcane::Materials::eMatPart::Pure) {
        Arcane::MatCell c = *imatcell;
        mat_pressure[c] = mat_temperature[imatcell];
      }
 
      // Loop over the impure material cells \a mat
      ENUMERATE_COMPONENTITEM (Arcane::Materials::MatPartCell, imatcell, mat->impureMatItems()) {
        Arcane::Materials::MatCell c = *imatcell;
        mat_pressure[c] = mat_temperature[imatcell];
      }
 
      // Loop over the impure material cells \a mat
      ENUMERATE_COMPONENTITEM (Arcane::Materials::MatPartCell, imatcell, mat, Arcane::Materials::eMatPart::Impure) {
        Arcane::Materials::MatCell c = *imatcell;
        mat_pressure[c] = mat_temperature[imatcell];
      }

Generic loops over components

      // Generic loop over the material cells \a mat
      ENUMERATE_COMPONENTITEM (Arcane::Materials::ComponentCell, iccell, mat) {
        Arcane::Materials::ComponentCell c = *iccell;
        mat_pressure[c] = mat_temperature[iccell];
      }
 
      // Generic loop over the material cells \a mat_vector
      ENUMERATE_COMPONENTITEM (Arcane::Materials::ComponentCell, iccell, mat_vector) {
        Arcane::Materials::ComponentCell c = *iccell;
        mat_pressure[c] = mat_temperature[iccell];
      }
 
      // Generic loop over the pure material cells \a mat
      ENUMERATE_COMPONENTITEM (Arcane::Materials::ComponentPartCell, iccell, mat->pureItems()) {
        Arcane::Materials::ComponentCell c = *iccell;
        mat_pressure[c] = mat_temperature[iccell];
      }
 
      // Generic loop over the pure material cells \a mat
      ENUMERATE_COMPONENTITEM (Arcane::Materials::ComponentPartCell, iccell, mat, Arcane::eMatPart::Pure) {
        Arcane::Materials::ComponentCell c = *iccell;
        mat_pressure[c] = mat_temperature[iccell];
      }
 
      // Generic loop over the impure material cells \a mat
      ENUMERATE_COMPONENTITEM (Arcane::Materials::ComponentPartCell, iccell, mat->impureItems()) {
        Arcane::Materials::ComponentCell c = *iccell;
        mat_pressure[c] = mat_temperature[iccell];
      }
 
      // Generic loop over the impure material cells \a mat
      ENUMERATE_COMPONENTITEM (Arcane::Materials::ComponentPartCell, iccell, mat, Arcane::eMatPart::Impure) {
        Arcane::Materials::ComponentCell c = *iccell;
        mat_pressure[c] = mat_temperature[iccell];
      }

Vector loops over components

Note

In the current version of Arcane (2.7.0), vector loops are only supported for environments (but not yet for materials).

To be able to use vectorization on components, you must include the following file:

#include <arcane/materials/ComponentSimd.h>
 
using namespace Arcane::Materials;

It is necessary to use the C++11 lambda mechanism to iterate over components via vector iterators. This is done using the following macro:

ENUMERATE_COMPONENTITEM_LAMBDA(){
};

Warning

Do not forget the final semicolon ';'. For more information, refer to the documentation for this macro.

Note

This mechanism is experimental and may evolve later.

For example, with the following variable declarations:

      Arcane::Materials::MaterialVariableCellReal mat_pressure(Arcane::VariableBuildInfo(mesh, "Pressure"));
      Arcane::Materials::MaterialVariableCellReal mat_volume(Arcane::VariableBuildInfo(mesh, "Volume"));
      Arcane::Materials::MaterialVariableCellReal mat_temperature(Arcane::VariableBuildInfo(mesh, "Temperature"));

It is possible to use vector loops as follows:

      Arcane::Real nr = 1.0;
      // Temperature and volume are read-only
      auto in_volume = viewIn(mat_volume);
      auto in_temperature = viewIn(mat_temperature);
      // Pressure is writable
      auto out_pressure = viewOut(mat_pressure);
 
      ENUMERATE_COMPONENTITEM_LAMBDA(EnvPartSimdCell, scell, env)
      {
        out_pressure[scell] = nr * in_temperature[scell] / in_volume[scell];
      };

Warning

For performance reasons, the order of iterations may be arbitrary. It is therefore essential that there are no relationships between the iterations. In particular, if non-associative operations such as sums on real numbers are used, the result may vary between two executions.

Note

The current implementation has several limitations:

• It is not yet possible to use these enumerators with concurrent loops (see page Parallelization of Loops on Materials and Environments).
• For SIMD, views must be used.
• For now, views are only available for scalar variables.

---

Material and Environment Management.