This document gives an overview of the CMake infrastructure of the MFrontGallery and MFrontMaterials projects.

This infrastructure is fully contained in the cmake/modules directory, the file cmake/modules/mfm.cmake being the main entry point.

Section 1 describes the main cmake functions provided by this infrastructure from the point of view of the maintainer and developper of a material knowledge management project. It mostly convers:

• functions used to compile MFront files related to material properties, behaviours and models.
• functions related to documentation and website generation.

1 Main functions

1.1 The mfront_properties_library function

The mfront_behaviours_library function adds shared libraries to the project related to MFront’ behaviours. The number of added shared libraries depends on the number of (material properties) interfaces selected when the project is configured (see the install page for details).

1.1.1 Usage

The following example shows how to create libraries associated with a material called VanadiumAlloy from a single MFront source file named VanadiumAlloy_YoungModulus_SRMA.mfront:

mfront_properties_library(VanadiumAlloy
  VanadiumAlloy_YoungModulus_SRMA)

Note that the .mfront suffix has been omitted in this declaration.

Internally, the mfront_properties_library function forward is arguments to the parse_mfront_library_sources function and use its results to add the shared libraries properly. See Section 1.3 for the available options.

The output generated by this function during the cmake configuration process is similar to the following:

-- Treating interface cyrano
-- Adding library : VanadiumAlloyMaterialProperties-cyrano (/home/th202608/codes/MFrontGallery/master/src/build/materials/VanadiumAlloy/properties/cyrano/src/VanadiumAlloy_YoungModulus_SRMA-mfront.cxx)
-- Treating interface castem
-- Adding library : VanadiumAlloyMaterialProperties-castem (/home/th202608/codes/MFrontGallery/master/src/build/materials/VanadiumAlloy/properties/castem/src/VanadiumAlloy_YoungModulus_SRMA-mfront.cxx)
....

which lists the shared libraries that will be compiled and the sources that will be generated by MFront. One may notice that each shared library is compiled in its own directory.

Internally, the mfront_properties_library relies on the mfront-query to get the list generated sources and handle dependencies to other MFront files and so on.

Regarding dependencies to other MFront files, the current directory ${CMAKE_SOURCE_DIR}/materials/${mat}/properties is automatically added to the MFront search paths, where:

• ${CMAKE_SOURCE_DIR} denotes the top level directory of the project
• ${mat} is the name of the material passed as first argument to the mfront_properties_library.

Other search paths can be added by using any of the keywords SEARCH_PATH or SEARCH_PATHS, as described in Section 1.3.

1.2 The mfront_behaviours_library function

The mfront_behaviours_library function adds shared libraries to the project related to MFront’ behaviours. The number of added shared libraries depends on the number of (behaviour) interfaces selected when the project is configured (see the install page for details).

1.2.1 Usage

A typical usage of the mfront_behaviours_library is the following:

mfront_behaviours_library(Concrete
  ConcreteBurger_EDF_CIWAP_2021
  ConcreteBurger_EDF_CIWAP_2021_v2)

which declares a set of shared libraries associated with the Concrete material. Those shared libraries are generated using two MFront files named respectively ConcreteBurger_EDF_CIWAP_2021.mfront and ConcreteBurger_EDF_CIWAP_2021_v2.mfront (See Section 1.3.1 for details).

Note that the .mfront suffix has been omitted in this declaration.

-- ConcreteBurger_EDF_CIWAP_2021 has been discarded for interface calculix (behaviours with external state variable other  than the temperature are not supported)
-- ConcreteBurger_EDF_CIWAP_2021_v2 has been discarded for interface calculix (behaviours with external state variable other  than the temperature are not supported)
-- No sources selected for library CONCRETECALCULIXBEHAVIOURS for interface calculix
-- ConcreteBurger_EDF_CIWAP_2021 has been discarded for interface ansys (behaviours with external state variable other  than the temperature are not supported)
-- ConcreteBurger_EDF_CIWAP_2021_v2 has been discarded for interface ansys (behaviours with external state variable other  than the temperature are not supported)
-- No sources selected for library CONCRETEANSYSBEHAVIOURS for interface ansys
-- Adding library : CONCRETEABAQUSBEHAVIOURS (/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/abaqus/src/abaqusConcreteBurger_EDF_CIWAP_2021.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/abaqus/src/ConcreteBurger_EDF_CIWAP_2021.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/abaqus/src/abaqusConcreteBurger_EDF_CIWAP_2021_v2.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/abaqus/src/ConcreteBurger_EDF_CIWAP_2021_v2.cxx)
-- Adding library : ConcreteBehaviours-cyrano (/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/cyrano/src/cyranoConcreteBurger_EDF_CIWAP_2021.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/cyrano/src/ConcreteBurger_EDF_CIWAP_2021.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/cyrano/src/cyranoConcreteBurger_EDF_CIWAP_2021_v2.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/cyrano/src/ConcreteBurger_EDF_CIWAP_2021_v2.cxx)
-- ConcreteBurger_EDF_CIWAP_2021 has been discarded for interface epx (small strain behaviours are not supported)
-- ConcreteBurger_EDF_CIWAP_2021_v2 has been discarded for interface epx (small strain behaviours are not supported)
-- No sources selected for library ConcreteBehaviours-epx for interface epx
-- ConcreteBurger_EDF_CIWAP_2021 has been discarded for interface dianafea (behaviours with external state variable other  than the temperature are not supported)
-- ConcreteBurger_EDF_CIWAP_2021_v2 has been discarded for interface dianafea (behaviours with external state variable other  than the temperature are not supported)
-- No sources selected for library ConcreteDianaFEABehaviours for interface dianafea
-- Adding library : ConcreteBehaviours-aster (/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/aster/src/asterConcreteBurger_EDF_CIWAP_2021.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/aster/src/ConcreteBurger_EDF_CIWAP_2021.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/aster/src/asterConcreteBurger_EDF_CIWAP_2021_v2.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/aster/src/ConcreteBurger_EDF_CIWAP_2021_v2.cxx)
-- Adding library : ConcreteBehaviours (/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/castem/src/umatConcreteBurger_EDF_CIWAP_2021.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/castem/src/ConcreteBurger_EDF_CIWAP_2021.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/castem/src/umatConcreteBurger_EDF_CIWAP_2021_v2.cxx;/home/th202608/codes/MFrontGallery/master/src/build/materials/Concrete/behaviours/castem/src/ConcreteBurger_EDF_CIWAP_2021_v2.cxx)
....

which lists the shared libraries that will be compiled and the sources that will be generated by MFront. One may notice that each shared library is compiled in its own directory.

One may also notice that the behaviours considered are not compatible with some of the selected behaviour interfaces and are thus discarded:

• Those behaviours are not compatible with the dianafea, calculix and ansys interfaces because it declares an external state variable which is not the temperature and this is not supported by those interfaces.
• Those behaviours are not compatible with the epx (Europlexus) interface because this solver only supports finite strain behaviours.

In this example, no shared libraries for the Concrete material will be generated for the interfaces dianafea, calculix, ansys and epx interfaces since no MFront are compatible with them.

Internally, the mfront_behaviours_library function forward is arguments to the parse_mfront_library_sources function and use its results to add the shared libraries properly. See Section 1.3 for the available options.

1.3 The parse_mfront_library_sources function

The parse_mfront_library_sources function set the following variables on output:

• mfront_sources: list of sources to be processed (see below). In practice, this is the list of arguments which are not specifically introduced by a keyword (see below).
• mfront_search_paths: list of search paths, i.e. list of directories where MFront shall search for auxiliary files (imported files, external material properties, external models.).
• mfront_include_directories: list of include directories. The include directories are added the compiler include directories.
• mfront_link_libraries: list of link libraries. Those link libraries are meant to be linked to the generated shared libraries.

The parse_mfront_library_sources function allows the following keywords:

• SOURCES (the default): this option introduces new sources for the generated libraries. All subsequent arguments are treated as sources, up to the next option.
• LINK_LIBRARY: this option allows to define one link library by the next argument passed to the parse_mfront_library_sources function.
• LINK_LIBRARIES: all subsequent arguments are treated as link libraries, up to the next option.
• SEARCH_PATH: the next argument passed to the parse_mfront_library_sources function is added to the list of search paths.
• SEARCH_PATHS: all subsequent arguments are treated as MFront search path, up to the next option.
• INCLUDE_DIRECTORY: the next argument passed to the parse_mfront_library_sources function is added to the list of include directories.
• INCLUDE_DIRECTORIES: the next argument passed to the parse_mfront_library_sources function is added to the list of include directories.

1.3.1 Treatment of the sources

For each shared library to be added, each source returned in the mfront_sources variable by the parse_mfront_library_sources is treated as follows:

• If the considered source, denoted @source@ in the following, starts with the mdnx: prefix, it is considered as a path in a madnex file.
• If a file @source@.mdnx (or @source@.madnex) exists in the current source directory, then it is treated as an madnex source file. All the material knowledge of the considered kind (material property, behaviour, model) contained in this file is added to the library.
• If a file @source@.mfront exists in the current source directory or in the current source directory, this file is treated as an MFront source file.
• If a file @source@.mfront.in (where @source@ is the name of the considered source) exists in the current source directory, then it is automatically configured using ̀CMake’ configure_file command and the resulting file is treated as an MFront source file.
• If none of the previous cases applied, the file @source@ is added in the list of sources for the treated shared library. This file can be given by its full path, and is searched in the current source directory or the the current binary directory.

MFront source files are treated by the generate_mfront_doc function which will generate a web page for this source file using the mfront-doc utility if the enable-website option has been choosen at the CMake configuration stage (see the install page for details).

1.4 Functions related to tests based on MTest

1.4.1 The add_mtest function (defined in behaviours.cmake)

The add_mtest function allows to declare a test on behaviours based on the MTest solver. The add_mtest function is used by wrappers such as genericmtest (for tests associated with the generic interface) or castemmest (for tests associated with the Cast3M interface) and not used directly (see below).

This function takes two mandatory arguments:

• the name of the interface.
• the name of the library containing the behaviour to be tested.

This function may take optional arguments introduced by the following keywords:

• TEST_NAME (default): this keyword introduces the base name of one or several tests. The full test name is created by adding:
  • the configuration (Release, Debug, etc.) for build systems that support multiple configurations in the same build
  • the rounding mode (see below for details).
• MTEST_FILE: this keyword introduces one or several base names to declare MTest scripts (i.e. the name of a file without extension). For each base name, the add_mtest function proceeds as follows:
  • If a file, with this base name and the extension .mtest.in exists, the configure_file function is called to generate a script file in the current directory. This file will be called by MTest.
  • Otherwise, a file, with this base name and the extension .mtest is expected to exist in the current source directory.
• BEHAVIOUR: this keyword introduces the name of the behaviour. This name used to replace all occurences of @behaviour@ in the MTest scripts.
• LIBRARY: this keyword introduces the path to the library containing the behaviour to be tested. This name used to replace all occurences of @library@ in the MTest scripts. By default, this location is deduced from the name of the second argument of the function.
• INTERFACE: this keyword introduces the name of the interface used to generate the library. This name used to replace all occurences of @interface@ in the MTest scripts.
• REFERENCE_FILE: this keyword introduces the name of the file containing the reference results. This name used to replace all occurences of @reference_file@ in the MTest scripts.
• ACCELERATION_ALGORITHM: this keyword introduces the name of an acceleration algorithm (see the MTest documentation for a list of acceleration algorithms).
• STIFFNESS_MATRIX_TYPE: this keyword introduces the type of stiffness matrix type to be used for the test (see the MTest documentation for a list of available stiffness matrix types).
• MATERIAL_PROPERTIES_LIBRARIES: this keyword introduces a list of libraries whose locations are requested. This keyword is only meaningful if an mtest.in file is to be used.

Several test names and several MTest scripts can be declared through the TEST_NAME and MTEST_FILE keywords respectively. The number of test names must match the number of scripts.

A script is generally run several times with different rounding modes (see the MTest documentation for details).

1.4.2 Wrappers around the add_mtest functions

The add_mtest function does not check if the interface used by the test has been selected and is not able to deduce the name of the library associated with an interface from the name of a material (Bentonite for instance) or the name of the class of behaviours considered (Plasticity for instance).

MFrontGallery thus provides several wrappers, such as: castemmtest, astermtest, europlexusmtest abaqusmtest, abaqusexplicitmtest, ansysmtest, calculixmtest dianafeamtest, cyranomtest and genericmtest.

For instance, one can call the castemmtest function even if the Cast3M interface for behaviours has not been selected: in this case, the associated test is just not declared.

1.4.2.1 Example of usage

The following code declares a test based on the asteriwan.mtest script if the aster interface has been selected:

mfront_behaviours_library(Plasticity
  ${MFRONT_BEHAVIOURS_PLASTICITY_SOURCES})

astermtest(Plasticity asteriwan)

1.5 Tests based on tfel-check

The tfel_check function declares a test based on [tfel-check]](https://thelfer.github.io/tfel/web/tfel-check.html). This function takes one mandatory argument named file, which must contain the base name for the input file passed to tfel-check. A file named ${file}.check or ${file}.check.in must exist in the current source directory. If the ${file}.check.in exists, the configure_file function is called to generate a file named ${file}.check in the current directory.

The configuration file mfm-tfel-check.config is automatically used. This configuration file is generated at the top level directory of the build tree by the create_tfel_check_config_file. This configuration file declares a component for each interface selected. For an interface ${interface} associated with a material property, the component mfm::material_property_interface::${interface} is declared. A similar declaration is performed for interfaces associated with behaviours and models.

If a python interpreter is detected, the substitution variable python is automatically defined and contains the path to the python interpreter.

If the castem tests are enabled (see the enable-castem-tests option), the substitution variable castem is automatically defined and contains the path to the Cast3M executable.

Additional configuration files may be added by derived projects to the mfm-tfel-check-configuration-files list.

The following substitution variables are automatically defined:

• current_src_dir: points to the current source directory
• current_binary_dir: points to the current directory in the build tree

1.6 The pandoc_html function

The pandoc_html function can be used to generate an html page from a markdow file using pandoc. This function takes the name of a markdown file a argument. All the other options are passed verbatim to pandoc.

The following options are automatically passed to pandoc:

• --mathjax: This option forces the use of the MathJax library to display embedded (La)TeX formulae.
• --highlight-style=tango: This option selects the tango style to display code snippets.
• --email-obfuscation=javascript: This option modifies how emails are displayed.
• --default-image-extension=svg: This option chooses SVG as the default image extension.

1.6.1 HTML template

If a file named mfm-template.html is found in the directory docs/web (from the root of the sources of the project), this file is used as a template for generating the web pages (see pandoc’s --template option).

1.6.2 Bibliography

If a biblatex file named bibliography.bib is found in the directory docs/web (from the root of the sources of the project), the generation of a bibliography is automatically enabled (see pandoc’s --bibliography option).

1.6.3 Citation Style Language (CSL) file

If a file named iso690-numeric-en.csl is found in the directory docs/web (from the root of the sources of the project), this file is used to define the reference style used (see pandoc’s --csl option).