generic-parallel material properties: load, check and describe the libraries generated by TFEL 5.2

CMakeLists.txt

@@ -223,6 +223,7 @@ if(NOT disable-tfel)
   if(TFEL_FOUND)
     include(tfel)
     include(material-properties)
+    include(generic-parallel)
     include(behaviours)
   endif(TFEL_FOUND)
 endif(NOT disable-tfel)

cmake/modules/generic-parallel.cmake

@@ -0,0 +1,53 @@
+# Libraries of material properties generated by the `generic-parallel`
+# interface of `MFront` (`TFEL` 5.2 or later), compiled by the C++ compiler
+# of `MGIS`. Only the backends whose sources are standard C++ sources are
+# supported (`stlpar`). The sources are generated in a directory of their
+# own.
+#
+# usage: mfront_generic_parallel_material_properties_check_library(name
+#                                                    backend properties...)
+function(mfront_generic_parallel_material_properties_check_library name
+                                                                 backend)
+  set(_directory
+    "${CMAKE_CURRENT_BINARY_DIR}/generic-parallel-material-properties-${backend}")
+  file(MAKE_DIRECTORY "${_directory}")
+  set(_configuration "${_directory}/configuration.json")
+  file(WRITE "${_configuration}"
+    "interfaces_options: {\n"
+    "  generic-parallel: {\n"
+    "    backend: \"${backend}\"\n"
+    "  }\n"
+    "}\n")
+  set(_sources)
+  foreach(source ${ARGN})
+    set(_file "${CMAKE_CURRENT_SOURCE_DIR}/${source}.mfront")
+    set(_output "${_directory}/src/${source}-generic-parallel-${backend}.cxx")
+    add_custom_command(
+      OUTPUT "${_output}"
+      COMMAND "${MFRONT}"
+      ARGS "--interface=generic-parallel"
+      ARGS "--configuration-file=${_configuration}"
+      ARGS "${_file}"
+      DEPENDS "${_file}" "${MFRONT}" "${_configuration}"
+      WORKING_DIRECTORY "${_directory}"
+      COMMENT "mfront source ${_file} (generic-parallel interface)")
+    list(APPEND _sources "${_output}")
+  endforeach(source ${ARGN})
+  add_library(${name} SHARED EXCLUDE_FROM_ALL ${_sources})
+  add_dependencies(build-tests ${name})
+  target_include_directories(${name}
+    PRIVATE "${_directory}/include"
+    PRIVATE "${TFEL_INCLUDE_PATH}")
+  target_compile_definitions(${name} PRIVATE MFRONT_COMPILING)
+  if(backend STREQUAL "stlpar")
+    # libraries required by the parallel algorithms of the standard library
+    # (see the `enable-parallel-stl-algorithms` option)
+    target_link_libraries(${name} PRIVATE ${MGIS_ADDITIONAL_LIBRARIES})
+    if(UNIX AND NOT APPLE)
+      # the library stays loaded until the end of the process: the threads
+      # of TBB may still run when the libraries are unloaded at exit (as in
+      # the configuration files of the stlpar backend of TFEL)
+      target_link_libraries(${name} PRIVATE "-Wl,-z,nodelete")
+    endif(UNIX AND NOT APPLE)
+  endif(backend STREQUAL "stlpar")
+endfunction(mfront_generic_parallel_material_properties_check_library)

docs/web/release-notes-3.2.md

@@ -232,6 +232,63 @@ setExternalStateVariable(m.s1, "Temperature", T1,
                          MaterialStateManager::UPDATE);
 ~~~~
 
+# New features of the `MGIS/MaterialProperty` library
+
+## Material properties generated by the `generic-parallel` interface
+
+The `generic-parallel` interface of `MFront` (`TFEL` 5.2 or later)
+generates functions evaluating a material property on a batch of points,
+on CPUs or on GPUs. The `load` function recognizes those libraries by the
+version of their functions (`<name>_generic_parallel_api_version`
+symbol) and fills the new members of the `MaterialProperty` structure:
+
+- `mfront_interface`: interface of `MFront` used to generate the
+  material property;
+- `batch_api_version`: version of the functions of batches of points;
+- `backend`: backend of the library (`cuda`, `hip`, `stlpar` or `sycl`);
+- `memory_space`: memory space of the computations (`host`, `device` or
+  `any`);
+- `execution_policy`: identifier of the execution policy expected by the
+  library;
+- `batch_fct` and `batch_report_fct`: functions evaluating the material
+  property on a batch of points and analysing the statistics of an
+  evaluation.
+
+A library exporting another version of those functions, an invalid memory
+space, or generated by a version of the `generic-parallel` interface which
+does not export the version of its functions, is refused. The
+`isGenericParallelMaterialProperty` function tells if a material property
+provides the functions of batches of points.
+
+The types of those functions (`mgis_mp_BatchData`,
+`mgis_mp_BatchStatistics`, `mgis_mp_BatchOutputStatus`, etc.), declared in
+`MGIS/MaterialProperty/BatchMaterialPropertyFctPtr.hxx`, are copies of the
+ones of `TFEL`: `MGIS` does not depend on `TFEL`. The execution policies of
+the backends are defined by `TFEL`: `MGIS` only declares their type
+(`MGIS/BackendExecutionPolicy.h`), and a code creating a policy includes the
+headers of `TFEL` and links the `MFrontGenericParallelRuntime` library.
+
+### Example of usage
+
+~~~~{.cxx}
+using namespace mgis::material_property;
+const auto mp = load("libGenericParallelMaterial-stlpar.so", "YoungModulus");
+const auto T = std::array<mgis::real, 4u>{300, 400, 500, 600};
+auto E = std::array<mgis::real, 4u>{};
+const auto args = std::array<BatchConstField, 1u>{
+    BatchConstField{.values = T.data(), .point_stride = 1}};
+const auto d = BatchData{.number_of_points = 4,
+                         .output = BatchField{.values = E.data(), .point_stride = 1},
+                         .arguments = args.data(),
+                         .number_of_arguments = 1,
+                         .out_of_bounds_policy = MGIS_MATERIALPROPERTY_NONE_POLICY,
+                         .statuses = nullptr,
+                         .statistics = nullptr,
+                         .execution_policy = nullptr};
+auto s = BatchOutputStatus{};
+const auto r = mp.batch_fct(&s, &d);
+~~~~
+
 # New features of the `MGIS/Function` library
 
 ## Support for quantities
@@ -412,6 +469,10 @@ For more details, see <https://github.com/thelfer/MFrontGenericInterfaceSupport/
 
 For more details, see <https://github.com/thelfer/MFrontGenericInterfaceSupport/issues/322>
 
+## Issue 320: generic-parallel material properties: the libraries generated by TFEL 5.2 can't be loaded nor checked
+
+For more details, see <https://github.com/thelfer/MFrontGenericInterfaceSupport/issues/320>
+
 ## Issue 308: Wrong statements and typos in the documentation and error messages
 
 For more details, see <https://github.com/thelfer/MFrontGenericInterfaceSupport/issues/308>

include/CMakeLists.txt

@@ -1,4 +1,5 @@
 mgis_header(MGIS Config-c.h)
+mgis_header(MGIS BackendExecutionPolicy.h)
 mgis_header(MGIS Config.hxx)
 mgis_header(MGIS LogStream.hxx)
 mgis_header(MGIS LogStream.ixx)
@@ -32,6 +33,7 @@ mgis_header(MGIS LibrariesManager.hxx)
 mgis_header(MGIS/MaterialProperty OutputStatus.hxx)
 mgis_header(MGIS/MaterialProperty OutOfBoundsPolicy.hxx)
 mgis_header(MGIS/MaterialProperty MaterialPropertyFctPtr.hxx)
+mgis_header(MGIS/MaterialProperty BatchMaterialPropertyFctPtr.hxx)
 mgis_header(MGIS/MaterialProperty MaterialProperty.hxx)
 mgis_header(MGIS/Behaviour Hypothesis.hxx)
 mgis_header(MGIS/Behaviour TimeStepStage.hxx)

include/MGIS/BackendExecutionPolicy.h

@@ -0,0 +1,46 @@
+/*!
+ * \file   include/MGIS/BackendExecutionPolicy.h
+ * \brief  This file declares the type of the execution policies of the
+ * backends of the `generic-parallel` interfaces of `MFront`. Those policies
+ * are defined by `TFEL` (`MFront/GenericParallel/` headers, base class
+ * `mfront::generic_parallel::AbstractBackendExecutionPolicy`): `MGIS` only
+ * gives them to the generated functions, so that a declaration is enough and
+ * `MGIS` does not depend on `TFEL` at compile time. In `C`, the policies are
+ * opaque and can only be given as null pointers (default policy of the
+ * backend).
+ * \date   22/10/2026
+ * \copyright Use, modification and distribution are subject
+ * to one of the following licences:
+ * - GNU Lesser General Public License (LGPL), Version 3.0. (See accompanying
+ *   file LGPL-3.0.txt)
+ * - CECILL-C,  Version 1.0 (See accompanying files
+ *   CeCILL-C_V1-en.txt and CeCILL-C_V1-fr.txt).
+ */
+
+#ifndef LIB_MGIS_BACKENDEXECUTIONPOLICY_H
+#define LIB_MGIS_BACKENDEXECUTIONPOLICY_H
+
+// NOLINTBEGIN(modernize-use-using)
+#ifdef __cplusplus
+
+namespace mfront::generic_parallel {
+
+  //! \brief base class of the execution policies of the backends
+  struct AbstractBackendExecutionPolicy;
+
+}  // end of namespace mfront::generic_parallel
+
+//! \brief a simple alias
+typedef mfront::generic_parallel::AbstractBackendExecutionPolicy
+    mgis_gp_AbstractBackendExecutionPolicy;
+
+#else /* __cplusplus */
+
+//! \brief opaque structure
+typedef struct mgis_gp_AbstractBackendExecutionPolicy
+    mgis_gp_AbstractBackendExecutionPolicy;
+
+#endif /* __cplusplus */
+// NOLINTEND(modernize-use-using)
+
+#endif /* LIB_MGIS_BACKENDEXECUTIONPOLICY_H */

include/MGIS/LibrariesManager.hxx

@@ -27,7 +27,7 @@
 #endif /* (defined _WIN32 || defined _WIN64) && (!defined __CYGWIN__) */
 
 #include "MGIS/Config.hxx"
-#include "MGIS/MaterialProperty/MaterialPropertyFctPtr.hxx"
+#include "MGIS/MaterialProperty/BatchMaterialPropertyFctPtr.hxx"
 #include "MGIS/Behaviour/FiniteStrainBehaviourOptions.hxx"
 #include "MGIS/Behaviour/BehaviourFctPtr.hxx"
 #include "MGIS/Behaviour/Hypothesis.hxx"
@@ -91,6 +91,49 @@ namespace mgis {
      * \param[in] n: entry point name
      */
     std::string getInterface(const std::string &, const std::string &);
+    /*!
+     * \return true if the given entry point provides the functions of
+     * batches of points of the `generic-parallel` interface, i.e. if the
+     * library exports the version of those functions
+     * (`<n>_generic_parallel_api_version` symbol)
+     * \param[in] l: library name
+     * \param[in] n: entry point name
+     */
+    bool hasGenericParallelFunctions(const std::string &, const std::string &);
+    /*!
+     * \return the version of the functions of batches of points
+     * (`<n>_generic_parallel_api_version` symbol)
+     * \param[in] l: library name
+     * \param[in] n: entry point name
+     */
+    unsigned short getGenericParallelAPIVersion(const std::string &,
+                                                const std::string &);
+    /*!
+     * \return the backend of a library generated by the `generic-parallel`
+     * interface (`<n>_generic_parallel_backend` symbol)
+     * \param[in] l: library name
+     * \param[in] n: entry point name
+     */
+    std::string getGenericParallelBackend(const std::string &,
+                                          const std::string &);
+    /*!
+     * \return the memory space of the computations of a library generated by
+     * the `generic-parallel` interface: `host`, `device` or `any`
+     * (`<n>_generic_parallel_memory_space` symbol)
+     * \param[in] l: library name
+     * \param[in] n: entry point name
+     */
+    std::string getGenericParallelMemorySpace(const std::string &,
+                                              const std::string &);
+    /*!
+     * \return the identifier of the execution policy expected by a library
+     * generated by the `generic-parallel` interface
+     * (`<n>_generic_parallel_execution_policy` symbol)
+     * \param[in] l: library name
+     * \param[in] n: entry point name
+     */
+    std::string getGenericParallelExecutionPolicy(const std::string &,
+                                                  const std::string &);
     /*!
      * \return the author of the `MFront` file
      * \param[in] l: library name
@@ -129,6 +172,26 @@ namespace mgis {
      */
     mgis::material_property::MaterialPropertyFctPtr getMaterialProperty(
         const std::string &, const std::string &);
+    /*!
+     * \return the function evaluating a material property on a batch of
+     * points (`<mp>_generic_parallel` symbol of a library generated by the
+     * `generic-parallel` interface)
+     * \param[in] l: library name
+     * \param[in] mp: material property name
+     */
+    mgis::material_property::BatchMaterialPropertyFctPtr
+    getBatchMaterialProperty(const std::string &, const std::string &);
+    /*!
+     * \return the function analysing the statistics of an evaluation of a
+     * material property on a batch of points
+     * (`<mp>_generic_parallel_report` symbol of a library generated by the
+     * `generic-parallel` interface)
+     * \param[in] l: library name
+     * \param[in] mp: material property name
+     */
+    mgis::material_property::BatchReportFctPtr
+    getBatchMaterialPropertyReportFunction(const std::string &,
+                                           const std::string &);
     /*!
      * \return the name of the output of the given material property
      * \param[in] l: library name
@@ -833,6 +896,16 @@ namespace mgis {
      * \param[in] n: symbol name
      */
     bool contains(const std::string &, const std::string &);
+    /*!
+     * \brief throw an exception if the given entry point does not provide
+     * the functions of batches of points of the `generic-parallel` interface
+     * \param[in] m: calling method
+     * \param[in] l: library name
+     * \param[in] n: entry point name
+     */
+    void checkGenericParallelFunctions(const char *const,
+                                       const std::string &,
+                                       const std::string &);
     /*!
      * \return the adress of the given symbol. If no symbol is found, a
      * null pointer is returned.