1 Known incompatibilities

The native Europlexus interface has been removed, as Europlexus now uses the generic interface through MGIS (see https://github.com/thelfer/tfel/issues/739 for details).

When compiling with option TFEL_APPEND_VERSION set to ON or when defining the string variable TFEL_VERSION_FLAVOUR, the python modules are now modified to reflect those information. This old behaviour can be restored by setting the unversioned-python-module-names option to ON.

1.1 Internal API changes

IsotropicHardeningRule::computeElasticLimitAndDerivative now returns the derivative of the elastic limit (computed at the middle of the time step) with respect to the equivalent plastic strain at the middle of the time step rather than the derivative with respect to the increment of the equivalent plastic strain.

2 New features in the TFEL libraries

2.1 Environment

This version now supports a new environment variable to specify the TFEL installation directory that always supersedes the TFELHOME environment variable. The name of this variable depends on the version of the project, the fact that a development version has been compiled and the flavour (optionally specified with the cmake variable TFEL_VERSION_FLAVOUR). The name of this variable can be retrieved with the --tfel-home option of tfel-config described below.

2.2 tfel-config

2.2.1 --registry-key option

On Windows, the --registry-key option returns the registry key which is used to determine the TFEL’s installation path.

2.2.2 --tfel-home option

The --tfel-home option returns the environment variable in which the TFEL’s installation path shall be defined.

2.2.2.1 Example of usage

$ tfel-config-5.1.0-dev-release --tfel-home
TFELHOME_5_1_0_dev_release

2.2.3 --python-module-suffix option

This option return the suffix of the python module. Such suffix is not empty only the following conditions are met:

• TFEL has been compiled with option TFEL_APPEND_VERSION set to ON and or with the string variable TFEL_VERSION_FLAVOUR defined,
• the unversioned-python-module-names option has been set to ON (the default value if OFF).

The option --python-module-suffix is only available if the python bindings is available.

2.2.4 --config

This option requests flags associated with the TFELConfig library.

2.2.5 --mfront-log-stream

This option requests flags associated with the MFrontLogStream library.

2.2.6 --mfront

This option requests flags associated with the TFELMFront library.

2.2.7 --mtest

This option requests flags associated with the TFELMTest library.

2.2.7.1 Example of usage

$ tfel-config-5.1.0-release --python-module-suffix
5_1_0_release

3 New TFEL/Math features

3.1 A zero method to create tensorial objects

A static method named zero is now available to create fixed-size tensorial objects.

3.1.1 Example of usage

constexpr auto s = stensor<2u, double>::zero();

4 New TFEL/Material features

4.1 Homogenization

4.1.1 Ellipsoidal inclusion embedded in anisotropic matrix

When \(\tenseuq{C}_0\) is anisotropic, the Eshelby tensor can be computed with computeAnisotropicEshelbyTensor in 3D and computePlainStrainAnisotropicEshelbyTensor in 2D. There are also computeAnisotropicHillTensor, computePlainStrainAnisotropicHillTensor, and also computeAnisotropicLocalisationTensor and computePlainStrainAnisotropicLocalisationTensor.

4.1.2 Homogenization bounds

Different homogenization bounds are implemented. The available functions are computeVoigtStiffness, computeReussStiffness, computeIsotropicHashinShtrikmanBounds.

4.2 Python bindings

Python bindings are now generated using the pybind11 library.

5 New features in MFront

This version introduces the following main features in MFront:

• warnings on potential misuses or known bad practices,
• the ability to call other behaviour from a behaviour.

5.1 Warnings

Many warnings have been added to detect potential misuses of MFront or known bad practices.

5.1.1 Activating and desactivating warnings

Reporting warnings is activated by default and can be disabled by passing the command line argument --report-warnings=false to MFront.

Warnings are associated with keywords and code blocks. Warnings can be disabled by appending the safe option to them. For instance, in an implicit DSL, specifying a convergence threshold greater than \(10^{-10}\) is considered to loose in most cases and thus triggers a warning. This warning can be disabled as follows:

@Epsilon<safe> 1;

This safe option can be ignored by passing the --ignore-safe command line argument to MFront. This argument is useful when analysing an existing file (written by another person) to question implementation choices.

5.1.2 Warnings added to all DSLs

• check that the consistent tangentor operator of all the relevant blocks are used in @TangentOperator.

5.1.3 Warnings added to the DSLs of the Default family

• check that the increments of all gradients are used in the @Integrator code block.
• check that the all thermodynamic forces are used in the @Integrator code block.
• check that the increment of all state variables are used in the @Integrator code block.
• check that all auxiliary state variables are used in the @Integrator code block or in UpdateAuxiliaryStateVariable code block.
• check that the consistent tangent operator Dt or all the tangent operator blocks are used in the @PredictionOperator code block, if defined.
• check that the consistent tangent operator Dt or all the tangent operator blocks are used in the @TangentOperator code block, if defined.
• check that the consistent tangent operator Dt or all the tangent operator blocks are used in the @Integrator code block if the implementation declares that the @Integrator computes it (using any of the @ProvidesTangentOperator and @ProvidesSymmetricTangentOperator) keywords).
• check that neither the consistent tangent operator Dt and any of the tangent operator blocks are used in the @Integrator code block if a @TangentOperator code block has been declared or if the implementation has not stated that it shall compute the consistent tangent operator.

5.1.4 Warnings added to isotropic DSLs

5.1.4.1 Warnings related to the convergence threshold

• using the default value of the convergence threshold
• specifying a value of the convergence threshold too low
• specifying a value of the convergence threshold too high

5.1.4.2 Warnings related to the implementation of the flow rule(s)

A warning is reported if the implementation of the flow rule(s) contains:

• the time increment dt,
• the strain eto at the beginning of the time step,
• the strain increment deto,
• the stress sig,
• the theta parameter,
• the increment of the external state variable,
• an auxiliary state variable not computed by an external point-wise model (see the @Model keyword).

Note

Using the increment of the external state variable and the time increment to compute the rate of an external state variable can be legitimate, but it is better to compute this rate in [InitLocalVariables?] and take into account the fact that the Cast3M solver may set the time increment to zero when activating is forced convergence algorithm.

A warning is reported if the implementation of the flow rule(s) does not contain:

• f and its derivative df_dseq,
• df_dp when required,
• R and dR_dp is an isotropic harderning rule has been defined for this flow rule.

5.1.4.3 Warnings related to the convergence threshold

• using the default value of the convergence threshold
• specifying a value of the convergence threshold too low
• specifying a value of the convergence threshold too high

5.1.5 Warnings added to implicit DSLs

5.1.5.1 Warnings related to the convergence threshold

• using the default value of the convergence threshold
• specifying a value of the convergence threshold too low
• specifying a value of the convergence threshold too high

5.1.5.2 Warnings related to the computation of the thermodynamic forces

• using the \(\theta\) (i.e. theta) or the iterMax parameter.
• using the time increment \(\Delta\, t\).
• using the increment of a gradient, integration variable or external state variable, or the increment of an auxiliary state variable computed by a point-wise model (see the @Model keyword).
• using an auxiliary state variable which is not computed by a point-wise model.

5.1.5.3 Warnings to @InitializeLocalVariables

• using the increment of an integration variable.

5.1.6 Warnings added to interfaces

5.1.6.1 Warnings added to the Cast3M interface

• using a maximum number of substepping greater than 3.
• not restricting the following keywords to the Cast3M interface, which is a portability issue as the behaviour can’t be compiled with other interfaces: @CastemGenerateMTestFileOnFailure, @UMATGenerateMTestFileOnFailure, @CastemUseTimeSubStepping, @UMATUseTimeSubStepping, @CastemMaximumSubStepping, @UMATMaximumSubStepping, @CastemDoSubSteppingOnInvalidResults, @UMATDoSubSteppingOnInvalidResults, @CastemFiniteStrainStrategy, @UMATFiniteStrainStrategy, @CastemFiniteStrainStrategies and @UMATFiniteStrainStrategies.

5.1.6.2 Warnings added to the generic interface

• not restricting the keyword @GenericInterfaceGenerateMTestFileOnFailure to the generic interface, which is a portability issue as the behaviour can’t be compiled with other interfaces.

5.1.6.3 Warnings related to the perturbation value used to compute a numerical approximation of the jacobian

5.1.6.4 Warnings related to the convergence threshold

• using the default value
• specifying a value too low
• specifying a value too high

5.2 Calling an external behaviour: the @BehaviourVariable keyword

@BehaviourVariable first_phase_plastic_behaviour {
  file: "Plasticity.mfront",
  variables_suffix: "1",
  external_names_prefix: "FirstPhase",
  store_gradients: true,
  store_thermodynamic_forces: true,
  shared_material_properties: {".+"},
  shared_external_state_variables: {".+"}
};

5.2.1 Behaviour variable factories

5.2.2 Extension of the @Model keyword

In previous versions, the @Model keyword allowed to call from a behaviour point-wise models using the historical Model DSL.

The @Model keyword now allows to use point-wise models implemented using the following DSLs: DefaultModel, RungeKuttaModel and ImplicitModel. In this case, a behaviour variable factory is automatically associated with the point-wise models which shares all its material properties and external state variables with the calling behaviour. Every persistent variables of the point-wise model are declared as auxiliary state variables. For each persistent variable of the point-wise model, a local variable meant to contain the increment of this variable over the time step is declared.

Point-wise models are called at the initialization stage of the behaviour. The auxiliary state variables associated with the point-wise models are updated at beginning of the updateAuxiliarySateVariables method before any user defined code (see the @UpdateAuxiliaryStateVariables keyword).

5.3 New command line arguments

The following command line arguments are now supported:

• --report-warnings: this command line argument enables or disables the reporting of warnings:
  • --report-warnings or --report-warnings=true enable the reporting of warnings (which is the default behaviour of MFront).
  • --report-warnings=false disables the reporting of warnings.
• --warning-error: this command line argument allows to treat warnings as errors.
  • --warning-error or --warning-error=true turns warnings into errors.
  • --warning-error=false does not turn warnings into errors (which is the default behaviour of MFront).
• -Werror is equivalent to --warning-error=true.
• -ignore-safe allows to ignore the safe option of keywords and code blocks.

5.4 New features in isotropic DSLs

5.4.1 Stress update algorithm

Isotropic DSLs all introduced the elastic strain as a state variable. When the elastic material properties are now to be constant in time, then the Hooke law can be written in an incremental form \[ {\left.\underline{\sigma}\right|_{t+\Delta\,t}}={\left.\underline{\sigma}\right|_{t}}+\lambda\,{\mathrm{tr}{\left(\Delta\,\underline{\varepsilon}^{\mathrm{to}}\right)}}+2\,\mu\,{\left(\Delta\,\underline{\varepsilon}^{\mathrm{to}}-\Delta\,p\,{\left.n\right|_{t+\theta\,\Delta\,t}}\right)} \] where \(\lambda\) and \(\mu\) are the first Lamé’s coefficient and the shear modulus, \(\Delta\,p\) is the increment of the equivalent plastic strain and \({\left.n\right|_{t+\theta\,\Delta\,t}}\) the flow direction at the middle of the time step.

The use_stress_update_algorithm DSL option prevents the declaration of the elastic strain and switches to this incremental form to compute the stress.

5.4.1.1 Example of usage

@DSL IsotropicStrainHardeningMisesCreep{
  use_stress_update_algorithm : true
};

5.4.2 Predefined isotropic hardening rules

The @IsotropicHardeningRule and @IsotropicHardeningRules allow to use the isotropic hardening rules available in the StandardElastoViscoPlasticity brick.

5.4.2.1 Example of usage

@IsotropicHardeningRule "Voce" {flow_id : 0, R0 : 125e6, Rinf : 500e6, b : 20};

@IsotropicHardeningRules{
  flow_id : 0,
  isotropic_hardening : "Voce" {R0 : 125e6, Rinf : 500e6, b : 20},
  isotropic_hardening : "Linear" {R0 : 50e6}
};

5.4.2.2 Automatic declaration of the flow rule in the IsotropicPlasticMisesFlow DSL

If an isotropic hardening rule is defined in the IsotropicPlasticMisesFlow DSL, and if no flow rule is defined, the following flow rule is automatically defined:

@FlowRule {
  f = seq - R;
  df_dseq = 1;
  df_dp = -dR_dp;
}

5.4.2.3 Available isotropic hardening rules

The following flow rules are currently available: Data, Linear, Power, StrainRateSensitive, Swift, UserDefined, and Voce.

This list can be retrieved as follows:

$ mfront --list-isotropic-hardening-rules

6 New features in mfront-query

6.1 New command line arguments

The following command line arguments are now supported:

• --report-warnings: this command line argument enables or disables the reporting of warnings:
  • --report-warnings or --report-warnings=true enable the reporting of warnings (which is the default behaviour of mfront-query).
  • --report-warnings=false disables the reporting of warnings.
• --warning-error: this command line argument allows to treat warnings as errors.
  • --warning-error or --warning-error=true turns warnings into errors.
  • --warning-error=false does not turn warnings into errors (which is the default behaviour of mfront-query).
• -Werror is equivalent to --warning-error=true.

6.2 New keywords

6.2.1 @TFELLibraries

The @TFELLibraries keyword let the user specify TFEL libraries to link with. This keyword must be followed by an array of strings.

The following libraries are available: Config, Exception, Glossary, Tests, UnicodeSupport, Utilities, System, Math, MathCubicSpline, MathKriging, MathParser, NUMODIS, Material, MFront, MTest.

6.2.1.1 Example of usage

@TFELLibraries {"MathParser"};

6.3 New tutorials

New tutorials on implementation of homogenization schemes for biphasic linear elastic media are available in the gallery.

New tutorials on implementation of homogenization schemes in non-linear elasticity are available in the gallery: Taylor scheme, Sachs scheme, \(\beta\)-rule. These tutorials use the keyword @BehaviourVariable for the integration and the computation of tangent operator of the local behaviours. The implementation shows how to use any behaviour law on each phase.

7 Issues fixed

7.1 Issue 739: [mfront] Depreciation of europlexus interface

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

7.2 Issue 708: Add support for hardening modes when libc++ is used

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

7.3 Issue 724: [mfront] Add support for non constant elastic properties in the stress update algorithm of the isotropic DSLs

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

7.4 Issue 721: [tfel-math] Add a zero method to create tensorial objects

This feature is described in Section 3.1.

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

7.5 Issue 717: [mfront] Add warning if the increment of a state variable is not used in [Integrator?] for the Implicit DSLs and the Default DSLs



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

7.6 Issue 698: [mfront] Add a stress update option which would not use the elastic strain as a state variable in Isotropic DSLs

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

7.7 Issue 661: [mfront] Allow to use isotropic hardening rules in isotropic DSLs

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

7.8 Issue 702: [mfront] Add a warning if an auxiliary state variable not computed by an external point-wise model is used in a @FlowRule block in isotropic DSLs

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

 ## Issue #697: [cyrano] Add a warning when the maximum number of sub steppings is too high

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

7.9 Issue #696: [calculix-interface] add support for the @GenerateMTestFileOnFailure keyword

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

7.10 Issue #695: [aster-interface] add support for the @GenerateMTestFileOnFailure keyword

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

7.11 Issue #694: [ansys-interface] add support for the @GenerateMTestFileOnFailure keyword

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

7.12 Issue #692: [mfront] add warning when interface specific keywords are not restricted to the corresponding interface

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

7.13 Issue #690: [castem] Add a warning when the maximum number of sub steppings is too high

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

7.14 Issue #689: [implicit-dsl] Add warning when using auxiliary state variables (not computed by external point-wise models) in @ComputeStress and @ComputeFinalStress

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

7.15 Issue 685: [tfel-config] Add support for TFELConfig, TFELMFront and TFELMTest

This feature is described in Section 2.2.

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

7.16 Issue 684: [mfront] Add support for @Includes, @Link and @TFELLibraries to the `Model DSL

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

7.17 Issue 683: Using TFEL librairies in material properties

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

7.18 Issue 677:[tfel-config] add a python-module-suffix option

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

7.19 Issue 676: Always prefer the versioned TFELHOME environment variable

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

7.20 Issue 674: [python-bindings] Add option to disable the modication of the names of python modules by the TFEL_APPEND_VERSION and TFEL_VERSION_FLAVOUR

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

7.21 Issue 673: [tfel-config] Add the ability to define an environment variable associated with the TFEL’s version and flavour

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

7.22 Issue 672: python bindings fix python modules names when TFEL_APPEND_VERSION or TFEL_VERSION_FLAVOUR is defined

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

7.23 Issue 667: Reduce the size of files paths in sources to fit in Windows’s MAX_PATH limit

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

7.24 Issue 666: [doc] Add CONTRIBUTING file, remove devel.md

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

7.25 Issue 654: Add PowerShell environment script

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

7.26 Issue 640: [mfront] Only point-wise models defined by Model DSL can be embedded in behaviours using the @Model keyword

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

7.27 Issue 294: [python-bindings] Evaluate port to pybind

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