There are various ways of getting help, including this FAQ.
The main source is the
TFEL website: https://thelfer.github.io/tfel/web/. In particular, one may want to read the pages dedicated to:
If none of the resources available is satisfying, one may want to use:
TFEL forums: https://github.com/thelfer/tfel/discussions
TFEL bug report: https://github.com/thelfer/tfel/issues
TFEL official mail adress to contact the developpers: firstname.lastname@example.org.
We recommend using the forums for general questions, as our answers can hopefully also be of any help to other users.
There are various kind of documents available, covering a wide range of questions. This section describes some of them, but documentation about specific part of the
TFEL project, such as
MFront, is described in the associated sections.
Available operations on tensors are described here. This page is not complete, so you may want to read the
doxygen documentation of the project.
This section deals with installing
MFront from sources. Consider using binary packages of your distribution, when available, if those versions were compiled with the appropriate interfaces for your specific needs.
The installation process is fully described in the following pages:
TFEL from the sources on posix-compliant systems. Please note that the main systems on which
TFEL was developed is
Linux. Extensive testing on other posix-compliant operating systems, notably
FreeBSD, is lacking, although compilation and unit testing is known to work.
FreeBSD is available here.
MinGW (as packaged with
2017). This tutorial can easily be adapted to other versions of
MinGW, without requiring
Cast3M to be installed.
We strongly recommend using the
cmake build system, which is actively in the development process used for various reasons and which enables many tests that are not present when using
autotools build system is barely maintained in a functional state under
LinuX. This can be used when
cmake is not available.
By default, the compilation of
mfront takes advantage of the specific CPU of the host system (using flags such as
-xHost with the
intel compiler). However, the binaries generated can not:
In both cases, the execution can fail with an
illegal instruction message.
To solve this issue, the
-Denable-portable-build=ON option (this option is valid for
cmake, when using the
autotools, consider the
--enable-portable-build option) has been introduced.
With this option, the
mfront binary and all the
TFEL shared libraries will be “portable” (will not include CPU specific instructions).
However, most of the times, the shared libraries produced by
MFront will be executed on the machine on which they will be used. For this reasons, the default behaviour of
mfront is to use flags like
-march=native when compiling the libraries (This can be disabled by selecting
Thus, we test the availability of this flag whether or not
-Denable-portable-build=ON is used. Thus, a message such as
--enabling flag 'march=native' barely states that this option is supported by the compiler.
The best way to know if this option was taken into account is check the flags used to compile TFEL, as follows:
# when using cmake
$ make VERBOSE=1
# when using autotools
$ make V=1
-Denable-portable-build=ON, you shall see the
--march=native flag twice: one time as a compiler flag, one time as part of the definition of the
OPTIMISATION_FLAGS macro. With
-Denable-portable-build=ON, you will see it only once, in the definition of the
MFront treats various kind of material knowledge:
For mechanical behaviours, various algorithms are available.
In all cases,
MFront strives to provide the most natural way of implementing the material knowledge under consideration. In technical terms,
MFront provides for each case a domain specific language which is meant to be simple and expressive.
MFront already supports many interfaces to:
Most solvers offers entry points to add user defined mechanical behaviours. The most common one is
UMAT, which is part of the
Abaqus/Standard solver. In this case, the process of supporting new a solver is fairly easy and we are ready to help setting it up. However, extensive testing can be a long and tedious task: again, we are ready to help by providing advice, test cases and reference solutions.
If no such entry point exist, then one may need to modify the solver. Again, we can provide valuable advice of how to do add support for user defined behaviours and even provide tight integration with
MFront (which can really ease user’s life).
To get the list of all the keywords associated with a given
Implicit keyword for example, just type:
$ mfront --help-keywords-list=Implicit
To get help on a specific keyword, the
@StrainMeasure keyword from the
Implicit DSL for example, just type:
$ mfront --help-keyword=Implicit:@StrainMeasure
The help is written using
The following command will display the description of all the keywords provided by the
$ mfront --help-keywords=Implicit
pandoc, this can be turned into an web page or a
$ mfront --help-keywords=Implicit | pandoc -f markdown-markdown_in_html_blocks+tex_math_single_backslash --mathjax -o Implicit.html
$ mfront --help-keywords=Implicit | pandoc -f markdown-markdown_in_html_blocks+tex_math_single_backslash --mathjax -s --toc --toc-depth=1 -o Implicit.pdf
The gallery has been created for that purpose. Various implementations of mechanical behaviour are covered in depth, including the description of the algorithm used. See this page for details.
Let us point that, there is no general guidelines, most troubles are behaviour specific. However, here are some advises to may help you. Note that those advises are worth considered during the behaviour implementation, before “real-world tests.”
The first thing to do is to identify the trouble.
If your computations are very CPU intensive and if the divergence appends after a noticeable amount of time, it is worth enabling the generation of a
MTest file on failure. This feature is for example supported by the
I thus assume that your are using
You can use
--debug command line option when compiling the
MFront file. This will print some information about convergence at runtime. For example, it may show:
In this case, you may want to print some of your variables to see what is happening. If the large values appears due to unrealistic prediction of the stresses, in particular at the second iteration, the
Implicit scheme allows you to limit the
Newton steps or use more robust algorithms (
LevenbergMarquardt). Otherwise, you must check your units.
In the second case, the trouble may be related to your implementation of the Jacobian matrix (assuming you are using an
Implicit scheme with analytical jacobian). In this case, it is worth comparing your jacobian to a numericall one (see
@CompareToNumericalJaobian). As this comparison is CPU intensive, please consider specifying this keyword in the command line rather than in your implementation to avoid forgetting removing it in your real-world tests:
$ mfront --obuild --interface=castem --@CompareToNumericalJacobian=true norton.mfront
Spurious oscillations may also be caused by an ill-conditioned system, see the
In this case, you may want to build your
MFront libraries with debugging symbols. This can be done by defining the
CXXFLAGS environment variable before the behaviour compilation. For example:
$ export CXXFLAGS="-g"
$ mfront --obuild --interface=castem norton.mfront
or even better
$ CXXFLAGS="-g" mfront --obuild --interface=castem norton.mfront
c-shell, you must use the following lines:
$ setenv CXXFLAGS "-g"
$ mfront --obuild --interface=castem norton.mfront
You can then launch
MTest in the
gdb debugger like this:
$ gdb --args mtest -fpe norton.mtest
You must type
gdb to start the computations. The
-fpe command line option will cause the program to fail a the invalid operation and
gdb will show you which line causes the trouble. Beware that this line may be in the generated code. In this case, this information will not be useful and you shall return to manual search of the problem.
For all domain specific languages,
MFront defines the real
typedef which is used to abstract to floating-point type used by the calling solver. For example, if the calling solver works in double precision, real will be a
double. If the calling solver works in quadruple precision, real will be a
Thus, we do recommend not to use the numerical types defined by the
C++ language directly.
For scalar values,
MFront introduces many different aliases to be able to express the nature of the variable:
For vector values,
MFront introduces these
For symmetric tensor values,
MFront also introduces many different
Finally, for tensor values,
MFront introduces these
An up-to-date list of all aliases automatically defined by
MFront is available on the following page.
You can also directly use to types provided by the
TFEL library. The most interesting ones for the end user are:
tvector<N,Type> (fixed sized vector)
stensor<N,Type> (symmetric tensor)
tensor<N,Type> (non symmetric tensor)
tmatrix<N,M,Type> (fixed sized matrix)
st2tost2<N,Type> (linear application changing a symmetric tensor to a symmetric tensor)
st2tot2<N,Type> (linear application changing a symmetric tensor to a non symmetric tensor)
t2tost2<N,Type> (linear application changing a non symmetric tensor to a symmetric tensor)
t2tot2<N,Type> (linear application changing a non symmetric tensor to a non symmetric tensor)
N is the size for vectors, the number of rows for matrices and the spatial dimension for the other types.
M is the number of columns for the matrices.
Type is the underlying numeric type.
The difference between those types is currently purely informative: the user can use these types to improve the readability of their code which is strongly encouraged.
TFEL library has support for quantities (number associated with units) which allows to checks for the consistency of operations at compile-time (no cost at runtime). However, support for this feature has not been enabled in
MFront yet: for the moment, we only have introduced the associated types.
Most finite element solver can’t have a uniq definition of the orthotropic axes for all the modelling hypotheses.
For example, one can define a pipe using the following axes definition:
With those conventions, the axial direction is either the second or the third material axis, a fact that must be taken into account when defining the stiffness tensor, the Hill tensor(s), the thermal expansion, etc.
This convention is valid for all modelling hypotheses.
If we were to model plates, an appropriate convention is the following:
By definition, this convention is only valid for \(3D\), \(2D\) plane stress, strain and generalized plane strain modelling hypotheses.
The following figure shows how the various blocks defined by the user may be used when using the
Implicit domain specific language: