The page declares the new functionalities of the 3.3 version of the TFEL project.

This version was released along with the following bug-fix releases:

Version 3.3 inherits the fixes of all those versions.

Version 3.3 includes \(15\,427\) unit tests and has been successfully tested on:

More tests are available in the MFrontGallery project.

1 Documentation and talks

New entries were added to the gallery:

1.2 Talks of the fifth MFront User Day

Some of the talks of the fifth MFront User Day are available online:

2 Improvements to MFront

2.1 Unicode Support

Some recent scientific programming languages like Julia or \(\nabla\) allow the usage of (a subset of) unicode characters [1, 2]. This allows a much more readable code, very close to the mathematical expressions.

Here is an example of the implementation of a Norton behaviour:

  const auto σᵉ = sigmaeq(σ);
  const auto iσᵉ = 1 / (max(σᵉ, real(1.e-12) ⋅ E));
  const auto vᵖ = A ⋅ pow(σᵉ, nn);
  const auto ∂vᵖ∕∂σᵉ = nn ⋅ vᵖ ⋅ iσᵉ;
  const auto n = 3 ⋅ deviator(σ) ⋅ (iσᵉ / 2);
  // Implicit system
  fεᵉˡ += Δp ⋅ n;
  fp -= vᵖ ⋅ Δt;
  // jacobian
  ∂fεᵉˡ∕∂Δεᵉˡ += 2 ⋅ μ ⋅ θ ⋅ dp ⋅ iσᵉ ⋅ (Mᵉ - (n ⊗ n));
  ∂fεᵉˡ∕∂Δp = n;
  ∂fp∕∂Δεᵉˡ = -2 ⋅ μ ⋅ θ ⋅ ∂vᵖ∕∂σᵉ ⋅ Δt ⋅ n;
} // end of @Integrator

The supported subset of unicode characters is fully detailed here.

2.2 Initial support for generalised behaviours

Generalised behaviours relate a set of gradients to their conjugated fluxes.

The following example shows how the linear Fourier law can be implemented:

@DSL DefaultGenericBehaviour;
@Behaviour StationaryHeatTransfer;
@Author Thomas Helfer;
@Date 15/02/2019;

@Gradient TemperatureGradient gT;

@Flux HeatFlux j;

@MaterialProperty thermalconductivity k;

  j = -k * (gT + dgT);
} // end of @Integrator

@TangentOperator {
  Dt = -k * tmatrix<N, N, real>::Id();

The non linear case is much more interesting as the consistent tangent operator can be split in two blocks:

The latter is introduced by the @AdditionalTangentOperatorBlock code block.

@DSL DefaultGenericBehaviour;
@Behaviour StationaryNonLinearHeatTransfer;
@Author Thomas Helfer;
@Date 15/02/2019;

@Gradient TemperatureGradient gT;

@Flux HeatFlux j;

@AdditionalTangentOperatorBlock dj_ddT;

@Parameter real A = 0.0375;
@Parameter real B = 2.165e-4;

@LocalVariable thermalconductivity k;

  const auto T_ = T + dT;
  k = 1 / (A + B * T_);
  j = -k * (gT + dgT);
} // end of @Integrator

@TangentOperator {
  dj_ddgT = -k * tmatrix<N, N, real>::Id();
  dj_ddT  =  B * k * k * (gT + dgT);
} // end of @TangentOperator 

The last example deals with solid-liquid phase change in transient heat-transfer. The enthalpy is treated in as a state variable. Its derivative with respect to temperature is yet another block in the tangent operator:

@DSL DefaultGenericBehaviour;
@Behaviour HeatTransfer;
@Author Thomas Helfer;
@Date 15 / 02 / 2019;

@Gradient TemperatureGradient gT;

@Flux HeatFlux j;

@StateVariable real H;

@AdditionalTangentOperatorBlock dj_ddT;
@AdditionalTangentOperatorBlock dH_ddT;

@Parameter Tm = 933.15;  
@Parameter ks = 210;
@Parameter Cs = 3.e6;
@Parameter kl = 95;
@Parameter Cl = 2.58e6;
@Parameter dHsl = 1.08048e9;

@LocalVariable thermalconductivity k;
// @LocalVariable real H0;
@LocalVariable real Ce;

@Integrator {
  const auto T_ = T + dT;
  // const auto Te = temperature(0.01);
  // const auto Ts = Tm-Te;
  // const auto Tl = Tm+Te;
  // heat flux
  k = (T_<Tm) ? ks : kl;
  j = -k*(gT+dgT);
  // enthalpy
    Ce = Cs;
    H = Cs*T_;
  } else {
    Ce = Cl;
    H = Cl*(T_-Tm)+dHsl+Cs*Tm;
}  // end of @Integrator

@TangentOperator {
  dj_ddgT = -k * tmatrix<N, N, real>::Id();
  dj_ddT = tvector<N, real>(real(0));
  dH_ddT = Ce;
}  // end of @TangentOperator

All those examples have been tested in the FEniCS platform and validated against analytical results or test cases extracted from the Cast3M or Code_Aster codes.

2.2.1 Limitations

Generalised behaviours are currently limited by the tensorial objects provided by the TFEL/Math library.

Only the generic interface handles generalised behaviours.

2.3 A new stress potential in the StandardElastoViscoPlasticity brick

A regularised Mohr-Coulomb stress potential is now available. This stress potential is fully described here.

2.4 Specifying a build identifier

As defined by Wikipedia, Quality assurance (QA) is a way of preventing mistakes and defects in manufactured products and avoiding problems when delivering products.

Fuel performance codes are developed under stringent Quality Assurance requirements that make their developers reluctant to rely on shared libraries to deliver material knowledge they are responsible for. A risk that must be mitigated as much as possible is the replacement of a shared library by another one, either intentionally to modify the results of the code or by accident (conflict with a previous version for example).

Specifying a build identifier proposes a solution for this issue. During building the shared libraries, developers may now specify a build identifier using the TFEL_BUILD_ID environment variable. This identifier is meant to be only known by the developers of the code and is hidden to end users. At runtime, when calling a shared library, the code can retrieve its build identifier, if any, and can check if it matches the identifier defined by the developers. If not, it may indicate a conflict exists with a previous versions of the shared library or that the end user wants to test a new material property or a new mechanical behaviour. In both cases, the code will report that results are unreliable and not coverered by the code specifications.

2.5 Parameters can now be declared with a type

In previous versions, parameters had the implicit type real. The user can now specify any scalar type. This makes the declaration of parameters consistent with the declaration of the other variables.

@Parameter strainrate de0 = 1e-4;

2.6 New material property interface for the Cyrano fuel performance code

For the Cyrano fuel performance code to call external material properties, a dedicated interface has been built.

The prototype of the generated functions is as follows:

CyranoRealType (*)(CyranoOutputStatus* const,
                   const CyranoRealType* const,
                   const CyranoIntegerType,
                   const CyranoOutOfBoundsPolicy);

This new interface is fully documented here.

2.7 Improvements to the Cast3M’ behaviour interface

Cast3M users have to deal with two a priori incompatible requirements:

Possible workarounds so far include:

Both workarounds have their drawbacks:

This release introduces a better solution. When elastic properties are defined internally, the Cast3M interface for behaviours now automatically generates the elastic material properties using the Cast3M interface for material properties.

The generated functions: have a name built with the name of the behaviour, followed by the underscore, and the name of the material property and are built in the same shared library than the behaviour.

At this stage, one gets something very similar with the second solution we just discussed. However, we now have the following advantages:

2.7.1 Example

Consider the following minimal example:

@DSL Implicit;
@Behaviour Test;
@ElasticMaterialProperties{"127.8e9*(1-7.825e-5*(T-293.15))", 0.3};
 σ = λ ⋅ trace(εᵉˡ) ⋅ I₂ + 2 ⋅ μ ⋅ εᵉˡ;
@Integrator {
  fεᵉˡ += Δεᵗᵒ;

Compiling this behaviour with the Cast3M interface generates the following output:

Treating target : all
The following library has been built :
- :  umattest Test_YoungModulus Test_PoissonRatio

In addition of the behaviour, this output highlights that two functions associated respectively with the YoungModulus and the PoissonRatio were generated.

In the generated example of usage, the material properties are declared as follows:

xyoun = 'TABLE';
xyoun . 'MODELE' = 'Test_YoungModulus';
xyoun . 'LIBRAIRIE' = '';
xyoun . 'VARIABLES' = 'MOTS'  'T';

xnu = 0.3;

2.8 Improvements to the Cyrano’ behaviour interface

2.8.1 Generation of elastic material properties from the behaviour

For post-processing reasons, the Cyrano fuel performance code must access the elastic material properties used by the behaviour. To ensure consistency, the behaviour now automatically exports the elastic material properties when they are defined internally.

2.9 Various API improvements

The MFront API was greatly improved to allow the implementation of the tfel-editor’ behaviour wizard.

2.10 New experimental interfaces for COMSOL Multiphysics and DIANA FEA

This release introduces two new experimental interfaces for the COMSOL Multiphysics and DIANA FEA solvers.

Experimental means that those interfaces have been build using the solvers specifications but have not been tested in those solvers.

There are 125 unit tests associated with the DIANA FEA solver through MTest.

Users of those solvers willing to test those new interfaces are welcomed.

3 Improvements to MTest

3.1 Ability to choose the stress measure used in input/output and the consistent tangent operator returned for finite strain behaviours through the generic interface

The following options can be passed to the behaviour:

@Behaviour<generic> 'src/' 'LogarithmicStrainElasticity2' {
  stress_measure : PK2,
  tangent_operator : DPK1_DF

The output of the behaviour is still the Cauchy stress. The stress measure on input and input are converted from or to the Cauchy stress.

The non linear algorithm still relies on the derivative of the Cauchy stress with respect to the deformation gradient: the tangent operator returned by the behaviour is automatically converted to this derivative.

3.2 Automatically load exported elastic properties for Cast3M behaviours

As detailed in Section 2.7, behaviours generated by the Cast3M interface may export their elastic properties. If so, those elastic properties are automatically loaded by MTest (if not declared by the user).

3.3 New methods (python bindings)

Various methods have been added to the MTest and PipeTest class in python:

4 mfm-test-generator

mfm-test-generator provides a way to generate input files for various solvers for specific cases. See the dedicated page for details.

5 TFEL’ core libraries

5.1 Improvements and new features of TFEL/Material library

5.1.1 Support for \({\displaystyle \frac{\displaystyle \partial {\underset{\tilde{}}{\mathbf{\Pi}}}}{\displaystyle \partial {\underset{\tilde{}}{\mathbf{F}}}}}\)

The derivative of the first Piola-Kirchhoff stress with respect to the deformation gradient is now available as a tangent operator for finite strain behaviour.

5.1.2 The Mohr-Coulomb yield criterion

Various functions allowing the computation of the Mohr-Coulomb yield criterion, its first and second derivatives are now available. See this page for details.

5.2 New library: TFELUnicodeSupport

This release introduces a new library called TFELUnicodeSupport. The purpose of this library is mainly to provide some mangling mechanisms that convert names based a subset of UTF-8 characters into valid C++ identifiers.

5.3 Improvements and new features of TFEL/System library

5.3.1 Improvements to ExternalLibraryManager

ExternalLibraryManager’ new features includes:

5.3.2 Improvements to the ExternalBehaviourData structure

The ExternalBehaviourData class now contains three new fields associated respectively with the build identifier see Section 2.4), the interface used to generate the behaviour, and the exported elastic material properties.

The later is empty if the behaviour does not export elastic material properties.

See the doxygen documentation for details.

5.3.3 The ExternalMaterialPropertyData and ExternalMaterialPropertyDescription structures

The ExternalMaterialPropertyData and ExternalMaterialPropertyDescription structures provides metadata about a material property. See the doxygen documentation for details.

6 Known incompatibilities

6.1 API changes in the class TargetsDescription

In previous versions, the class TargetsDescription was mainly designed to handle libraries. Version 3.3 provides a better support for executables.

The following changes were made:

7 Tickets solved during the development of this version

7.1 Ticket #183: Calling an MFront function (material properties) with the ‘cyrano’ interface

This feature is detailled in Section 2.8.1. See also Section 2.6.

For more details, see:

7.2 Ticket #172: Support for dynamic choice of the consistent tangent operator of finite strain behaviours using the generic interface

The generic interface now allows to specify, for finite strain behaviours (including the behaviours based on the Green-Lagrange and the Hencky strain measure):

If K is the array used to store the consistent tangent operator, K[0] still represent the kind of integration to be performed.

For finite strain behaviours K[1] must now hold the stress measure used:

K[2] must hold the consitent tangent operator returned by the behaviour:

For more details, see:

7.3 Ticket #171: Add the derivative of the first Piola-Kirchoff stress as a possible consistent tangentor for finite strain behaviours

For more details, see:

7.4 Ticket #169: Determinant of a fourth-order tensor

For more details, see:


Camier, Jean-Sylvain. Improving performance portability and exascale software productivity with the ∇ numerical programming language. In : Proceedings of the 3rd international conference on exascale applications and software. Edinburgh, Scotland, UK : University of Edinburgh, 2015. p. 126–131. EASC ’15. ISBN 978-0-9926615-1-9. Available from:
event-place: Edinburgh, UK
Bezanson, Jeff, Edelman, Alan, Karpinski, Stefan and Shah, Viral B. Julia: A fresh approach to numerical computing. SIAM review. 2017. Vol. 59, no. 1, p. 65–98. Available from:

  1. Elastic properties may be defined in various ways. One way is to use either the @ElasticMaterialProperties keyword or the @ComputeStiffnessTensor keyword. Another way is to define them inside the options of bricks.↩︎