The page describes the new functionalities of Version 5.2 of the TFEL project.

1 Highlights

1.1 Support for the TDLS library (Tiny Device-callable Linear Solvers)

The TDLS library provides direct linear solvers for small dense systems, callable on CPUs as well as inside GPU kernels, and designed for maximum GPU performance:

• https://github.com/trsxvz/tdls
• API reference

When compiling TFEL, one must explicitly enable support for the TDLS library, see below.

2 Known incompatibilities

• MFront’ interfaces have to implement a method named setOptions.

3 Improvements to the build system

3.1 New cmake options

• enable-tdls: add support for Tiny Device-callable Linear Solvers (TDLS) library. OFF by default.
• enable-tdls-as-default-linear-system-solver-in-mfront: use TDLS as the default linear solver. Requires enable-tdls to be ON. OFF by default.

3.2 User-defined cmake variables

• generic-parallel-configurations: list of configurations to be supported. See next paragraph for details and the list of supported configurations.
• TFEL_GXX_COMPILER: path to the g++ compiler.
• TFEL_CLANGXX_COMPILER: path to the clang++ compiler.
• TFEL_ICPX_COMPILER: path to INTEL’s icpx compiler.
• TFEL_NVHPC_COMPILER: path to NVIDIA’s nvhpc compiler.
• TFEL_ACPP_COMPILER: path to AdaptativeCpp’s acpp compiler.
• tdls_DIR: directory where to find the cmake files installed by the Tiny Device-callable Linear Solvers (TDLS) library.

3.3 Supported parallel configurations

The following configurations are supported for parallel computations:

• cuda-nvcc: configuration associated with the CUDA parallel programming model and NVIDIA’s nvcc compiler
• cuda-clang: configuration associated with the CUDA parallel programming model and LLVM’s clang compiler
• hip-hipcc: configuration associated with the HIP parallel programming model and AMD’s hipcc compiler
• hip-clang: configuration associated with the HIP parallel programming model and LLVM’s clang compiler
• stlpar-parunseq-gcc: configuration associated with C++ standard parallel algorithms using the parallel unsequenced execution policy and the gcc compiler.
• stlpar-parunseq-clang: configuration associated with C++ standard parallel algorithms using the parallel unsequenced execution policy and the clang compiler.
• stlpar-parunseq-icpx: configuration associated with C++ standard parallel algorithms using the parallel unsequenced execution policy and the icpx compiler.
• stlpar-parunseq-nvhpc-gpu: configuration associated with C++ standard parallel algorithms using the parallel unsequenced execution policy and NVIDIA’s nvhpc compiler with offloading on the GPU.
• sycl-default-icpx: configuration associated with SYCL programming model INTEL’s icpx compiler.

3.4 Add a build-tests target

In previous versions, tests were compiled and run using the check target, which internally calls ctest for running the test. One drawback of this approach is that ctest could not be run in parallel.

The build-tests target (which is a dependency of the check target) only compiles the tests. To run the tests, one may still call the check target or call directly ctest.

If the build-tests target has not been called, the check target works as in previous versions.

4 New TFEL/Config features

The TFEL/Config library is now documented on this page.

4.1 TFEL’s default substitutions

The getDefaultSubstitutions function returns some default substitutions used by MFront when reading configuration files and tfel-check when analysing .check files.

4.1.1 General substitutions

• TFEL_CXX_STANDARD: the C++ standard used by the project.

4.1.2 Supported compilers

• TFEL_GXX_COMPILER: path the g++ compiler. The value associated with this key is determined as follows, by order of priority:

  1. by passing the variable TFEL_GXX_COMPILER during the invocation of cmake.
  2. by using g++ as the main compiler to compile TFEL
  3. by searching g++ using cmake’s find_program function.

• TFEL_CLANGXX_COMPILER: path to LLVM clang++ compiler. The value associated with this key is determined as follows, by order of priority:

  1. by passing the variable TFEL_CLANGXX_COMPILER during the invocation of cmake,
  2. by using clang++ as the main compiler to compile TFEL,
  3. by searching clang++ using cmake’s find_program function.

• TFEL_ICPX_COMPILER: path to INTEL’s icpx compiler. The value associated with this key is determined as follows, by order of priority:

  1. by passing the variable TFEL_ICPX_COMPILER during the invocation of cmake,
  2. by using icpx as the main compiler to compile TFEL,
  3. by searching icpx using cmake’s find_program function.

• TFEL_ACPP_COMPILER: path to AdaptativeCpp acpp compiler. The value associated with this key is determined as follows, by order of priority:

  1. by passing the variable TFEL_ACPP_COMPILER during the invocation of cmake,
  2. by searching acpp using cmake’s find_program function.

• TFEL_NVHPC_COMPILER: path to NVIDIA’s nvhpc compiler. The value associated with this key is determined as follows, by order of priority:

  1. by passing the variable TFEL_NVHPC_COMPILER during the invocation of cmake,
  2. by using nvhpc as the main compiler to compile TFEL,
  3. by searching nvhpc using cmake’s find_program function.

• TFEL_NVCC_COMPILER: path to NVIDIA’s nvhcp as found by FindCUDAToolkit.

• TFEL_HIPCC_COMPILER: path to AMD’s hipcc compiler. The value associated with this key is determined as follows, by order of priority:

  1. by passing the variable TFEL_HIPCC_COMPILER during the invocation of cmake,
  2. by searching hipcc using cmake’s find_program function.

4.1.3 Substitutions related to the HIPCC compiler

• TFEL_HIPCC_FLAGS: additional flags to be passed to thehipcc` compiler.
• TFEL_HIP_INCLUDE_DIR: paths to HIP headers

4.1.4 Substitutions related to the CUDA platform

• TFEL_CUDA_PATH: path to NVIDIA’s CUDA toolkit as found by CMake’s FindCUDAToolkit module.
• TFEL_CUDA_LIBRARY_DIR: path to the libraries of the NVIDIA’s CUDA toolkit as found by CMake’s FindCUDAToolkit module.

5 New TFEL/Math features

5.1 Views of tensorial objects with coalescent memory access for data separated by a constant stride

In previous versions, the View class allows interpreting a contiguous memory area as a tensorial object. The CoalescedView class allows to create a tensorial object where each component is referred to by its own pointer.

The StridedCoalescedView assumes that each component is separated by a constant stride in memory, so that it only have to store one pointer and the value of the stride.

Such views are efficient on GPUs where coalescent memory access are preferable.

int values[8] = {1, 10, 2, 20, 3, 30, 4, 40};
auto s1 = map_strided<stensor<2u, int>>(values, 2);

5.2 Walpole basis

The Walpole basis relative to transverse isotropic fourth-order tensors (st2tost2) is introduced with the struct TransverseIsotropicWalpoleBasis, member of tfel::math.

5.3 Refactoring of quantities

Quantities were deeply refactored to:

• improve maintainability (code is much more compact),
• allow creating surrogate classes for quantities,
• improve error message,
• reduce size of the generated symbols.

6 New TFEL/Material features

6.1 Homogenization

The following methods of the ParticulateMicrostructure objects are able to modify the microstructure:

• changeElasticityOfMatrixPhase
• changeElasticityOfInclusionPhase
• changeFractionOfInclusionPhase

The UserDefinedDistributionOfSpheroids allows to define a distribution of spheroids defined by two orientation tensors. This distribution can be used in a ParticulateMicrostructure and the associated homogenization schemes can be used with these microstructures.

7 New features in tfel-check

7.1 Parallelization

The commands described in different .check files can now be run in distinct processes.

Note that the command described in a .check are still run sequentially.

By default, as in previous versions, only one process is used.

7.1.1 Specifying the number of jobs run simultaneously

The command line argument --jobs (-j) allow specifying the number of jobs run simultaneously.

If no option is given to --jobs, the number of available cores is used, if the system provide this information.

7.1.1.1 Limit on the number of jobs

By default, this number must be lower than the number of cores available. This limit can be discarded by passing--discard-jobs-limit=true to tfel-check.

7.1.2 Caution

The user must take care that the commands described in .check files can be run in parallel.

• the jobs shall no exhaust memory.
• the jobs shall not access concurrently to the same resources.

A typical example of conflict would be to have two .check files in the same directory that call mfront to build somes shared libraries: the two MFront’s processes may write concurrently files in the src and include directories, leading to an undefined behaviour.

Another example would be to use @CleanDirectories and @CleanFiles commands inappropriately and erase data used by commands of other .check files.

7.2 Defining environment variables in configuration files

Configuration files can now contain an environment_variables sections which can introduce a map defining a set of environment variables.

7.2.1 Example of usage

environment_variables: {"CXXFLAGS": "-Wall"};

7.2.2 Caution

• An environment variable can only be defined once in configuration files
• If an environment variable is defined in a configuration file and in a test file (through the @Environment keyword), the latter definition is used.

7.3 New features in TFEL/System

7.3.1 Improvements in ProcessManager

• New overloads of the createProcess and execute methods allow specifying the directory where a command shall be executed.
• ProcessManager shall now work properly in a multithreaded context.

7.3.2 Improvements in SignalManager

• SignalManager shall now work properly in a multithreaded context.

8 New TFEL/Material features

8.1 Homogenization

The second moments of strains considering a Hashin-Shtrikman scheme are available. A new tutorial shows how to use it in the implementation of Ponte-Castaneda variational bound (1992), within the framework of non-linear elasticity.

9 New features in MFront

9.1 The @LinearSystemSolver keyword

The @LinearSystemSolver keyword is used to select the linear system solver. It is followed by the name of the solver. Currently, two solvers are supported:

• Default. This uses the solvers provided natively by the TFEL/Math library. As implied by its name, this solver is used by default.
• TDLS (or equivalently TinyDeviceCallableLinearSolver). See https://trsxvz.github.io/TDLS/getting_started.html for details. If TFEL is not compiled with support for the TDLS library, selecting this solver falls back to the Default solver.

The name of the solver can optionally be followed by a dictionary allowing to parametrize the solver.

9.1.1 Supported Parameters

9.1.1.1 Parameters of the Default Linear Solver

The Default Linear Solver does not accept any parameter.

9.1.1.2 Parameters of the TDLS Linear Solver

The following options are supported:

• tile_size: the matrix is processed as a grid of tile_size x tile_size register tiles. This is the main performance axis of the solvers. Tune it per system dimension. The tile_size can be a strictly positive integer or a string. If tile_size is a string, it is interpreted as an integer formula whose variables can be any integer constant (see the @IntegerConstant keyword), N, TVectorSize, StensorSize or TensorSize. This formula must evaluate to a strictly positive integer for all hypotheses supported by the behaviour.
• schedule: expected values are either left_looking (or equivalently left, left-looking or LeftLooking) or right_looking (or equivalently right, right-looking or RightLooking). This parameter defines the elimination schedule of the tiled factorization.
• out_of_tile_search_strategy: expected values are either first_acceptable (or equivalently first-acceptable or FirstAcceptable) or full_scan (or equivalently full-scan or FullScan). With first_acceptable, the search below the tile stops at the first candidate whose corrected magnitude reaches the out-of-tile search threshold. With full_scan, all the rows below the tile are scanned and the best corrected candidate wins.
• unroll_inner_loop: expected values are either true or false. If true, loops indexing register tiles carry a forced-unroll pragma, the guard that keeps tiles in registers on GPU backends, where a rolled loop indexes the tile dynamically and demotes it to slow local memory. If false, no unroll pragma anywhere, for faster compiles, GPU performance not guaranteed.
• out_of_tile_search_threshold: acceptable-pivot threshold of the out-of-tile search. An in-tile pivot candidate whose magnitude reaches this value is accepted without looking outside the tile; below it, the search extends to the rows under the tile (out-of-tile pivoting) and the best candidate wins.
• singular_pivot_threshold: the factorization is declared singular when even the best candidate of the out-of-tile recovery stays below this threshold. This option must be set together with the out_of_tile_search_threshold option and must not exceed it.
• out_of_tile_search_diagnostics: expected values are either true or false. If true, an integer member mfront_tdls_oot_count, readable in user code blocks, reports the number of out-of-tile searches of the last linear solve. If false (the default), the generated code is unchanged.

If a parameter is not defined, the default values are inherited from the TiledLUppConfig class defined by the TDLS library. See the API reference for details. At the time of writing this documentation, those default values are:

• 3 for tile_size
• right_looking for schedule
• first_acceptable for out_of_tile_search_strategy
• true for unroll_inner_loop
• 1e-10 for out_of_tile_search_threshold (or 1e-4 for single precision)
• std::numeric_limits<double>::min() for singular_pivot_threshold (or std::numeric_limits<float>::min() for single precision)

9.1.2 Examples

@LinearSystemSolver TDLS{
  tile_size: 4,
  unroll_inner_loop: false
};

@LinearSystemSolver TDLS{
  tile_size: "StensorSize"
};

9.2 Configuration file

MFront now allows to define options in a configuration file define through the --configuration-file command line argument as follows:

~~{bash} $ mfront –configuration-file=config.json –interface=generic-parallel UO2_ShearModulus.mfront~~

Configuration file follows an extented JSON-like syntax. It contains the following sections:

• dsl_options
• material_property_dsl_options
• behaviour_dsl_options
• model_dsl_options
• interfaces_options
• compilation_options

None of those sections is required. All those sections must introduce a dictionary.

Note

The options given in sections dsl_options, material_property_dsl_options, behaviour_dsl_options and model_dsl_options may also be retrieved in dedicated configurations files, respectively specified by the --dsl-options-file, --material-property-dsl-options-file, --behaviour-dsl-options-file, and --model-dsl-options-file command line arguments introduced in Version 4.1.

9.2.1 Example of configuration file

interfaces_options: {
  generic-parallel: {
    backend: {"stlpar", execution_policy: "par_unseq"}
  }
}

9.2.2 The interfaces_options section

9.2.3 The compilation_options section

compilation_options : {
  cxx : {
    compiler: "nvc++",
    compilation_flags: "-O2 -stdpar=gpu -std=c++20 -march=native -gpu=sm_89" 
  }
}

9.2.3.1 The compiler option

9.2.3.2 The compilation_flags option

9.2.4 The linking_options section

9.2.4.1 The linker_flags option

9.3 Passing options to interfaces on the command line

9.3.1 First syntax

~~{bash} $ mfront –obuild –interface=‘generic-parallel{backend:{“stlpar”: {execution_policy:“par_unseq”}}}’ UO2_ShearModulus.mfront~~

9.3.2 Second syntax

~~{bash} $ mfront –obuild –interface=‘{generic-parallel:{backend:“stlpar”{execution_policy:“par_unseq”}}}’ UO2_ShearModulus.mfront~~

9.4 The generic-parallel interface for material properties

See this page for details.

9.4.1 Available backends

9.4.1.1 STLPar

9.4.1.2 CUDA

9.5 Improvements to the Cast3M interface

9.5.1 Improved generation of Gibiane input file

The Cast3M interface generates automatically an example of Gibiane input file to integrate which each MFront behaviour. This example is meant to be used a template and do not pretend to be usable without modification by the user. For instance, previous versions of MFront did not guarantee that the name of the variables (limited to 4 characters) were unique. Version 5.2 improves this. To illustrate this, one may compare the output of Version 5.1 and Version 5.2:

* Version prior to 5.2
statev = 'MOTS' 'EERR' 'EEZZ' 'EETT' 'EERZ' 'KHRR' 'KHZZ' 'KHTT' 'KHRZ' 'KHRR' 'KHZZ' 'KHTT' 'KHRZ' 'P';
* Version 5.2
statev = 'MOTS' 'EERR' 'EEZZ' 'EETT' 'EERZ' 'KHRR' 'KHZZ' 'KHTT' 'KHRZ' 'V0' 'V1' 'V2' 'V3' 'P';

In Version 5.1, the variable name KHRR is declared twice. Cast3M does not generate an error although duplicated names leads to erroneous results. Version 5.2 avoids this pitfall.

10 Continuous integration

10.1 Github actions

Github actions have been updated to supported a wider range of configurations, including testing based on Visual Studio 2024 and Visual Studio 2026.

11 Acknowledgements

The authors are grateful to the many contributors to the TFEL/MFront project. This research was conducted in the framework of the PLEIADES project, which was supported financially by the CEA (Commissariat à l’Énergie Atomique et aux Énergies Alternatives), EDF (Électricité de France) and Framatome. Homogenization developments were conducted within the framework of the AnoHonA ANR project (n° AAPG2023).

12 Issues fixed

12.1 Issue 1016: [mfront] Variables have the same name in the dgibi file generated by MFront, for using the FEM program Cast3M

For more details, see https://github.com/thelfer/tfel/issues/1016

12.2 Issue 1014: [cmake] Add a build-tests target

For more details, see https://github.com/thelfer/tfel/issues/1014

12.3 Issue 1013: [tfel-math] Refine QuantityConcept to take mutability into account

For more details, see https://github.com/thelfer/tfel/issues/1013 

12.4 Issue 1012: [github-actions] Add testing of TFEL with madnex

For more details, see https://github.com/thelfer/tfel/issues/1012 

12.5 Issue 1010: [clang-tidy] fix warnings related to the google-explicit-constructor check

For more details, see https://github.com/thelfer/tfel/issues/1010

 ## Issue 1007: [github-actions] Add continuous integration for the generic-parallel interface with CUDA backend

For more details, see https://github.com/thelfer/tfel/issues/1007

12.6 Issue 1006: [github-actions] Add tests based on tfel-check

For more details, see https://github.com/thelfer/tfel/issues/1006

12.7 Issue 1004: [github-actions] Add support actions based on Visual Studio

For more details, see https://github.com/thelfer/tfel/issues/1004

 ## Issue 1003:[tfel-math] Improve error messages when using quantities

For more details, see https://github.com/thelfer/tfel/issues/1003

12.8 Issue 1001: [tfel-math] Introduce the QuantityConcept class to allow surrogate classes to be treated as quantities

For more details, see https://github.com/thelfer/tfel/issues/1001

12.9 Issue 995: [tfel-check] Adding [Environment?] section in configuration file

For more details, see https://github.com/thelfer/tfel/issues/995

12.10 Issue 987: StridedCoalescedView has no exposed data pointer and stride

For more details, see https://github.com/thelfer/tfel/issues/987

12.11 Issue 926: [tfel-math] Add TFEL_HOST_DEVICE to LeftCauchyGreenTensorDerivativeExpr and RightCauchyGreenTensorDerivativeExpr classes

For more details, see https://github.com/thelfer/tfel/issues/926

12.12 Issue 925: [tfel-math] Introduce the StressStensorConcept and NoUnitStensorConcept concepts and siblings for orther tensorial objects

For more details, see https://github.com/thelfer/tfel/issues/925

12.13 Issue 922: [tfel-math] two functions have no GPU device support



For more details, see https://github.com/thelfer/tfel/issues/922

12.14 Issue 890: mfront Add Ponte Castaneda 1992 non linear scheme

For more details, see https://github.com/thelfer/tfel/issues/890

12.15 Issue 905: [TFEL/Math] Pointer-heavy CoalescedView

For more details, see https://github.com/thelfer/tfel/issues/905

12.16 Issue 853: [tfel-fcheck] Have the possibility to launch multiple call to tfel-check simultaenously in a CI context

For more details, see https://github.com/thelfer/tfel/issues/853