User interface

Prior definitions

A heterogeneous Unit-cell consists of one (or more) Material, and each Material consists of one (or more) Zone. They are defined based on the following properties:

  • All the voxels of the 3D uniform grid define the Unit-cell.
  • Within a Material, all the voxels have the same behaviour law.
  • Within a Zone of a Material, all the voxels have the same material properties (coefficients of the behavior law).

How to launch AMITEX_FFTP

Within a batch script for the job manager available on your machine, a simulation is launched with one of the following command lines

1. mpirun ./amitex_fftp  -nm materialID.vtk -nz zoneID.vtk -m material.xml -c loading.xml -a algorithm.xml -s out_file

        or

2. mpirun ./amitex_fftp  -nm materialID.vtk -m material.xml -c loading.xml -a algorithm.xml -s out_file

        or

3. mpirun ./amitex_fftp  -nz zoneID.vtk -m material.xml -c loading.xml -a algorithm.xml -s out_file

Depending on the environment, you may have to specify the number of processes and replace mpirun by mpirun -np number_of_processes. This can be the case if the code is installed and launched directly on a standard PC (with several processors).

The three possible command lines listed above correspond to the three following cases :

  1. The unit-cell, the materials and their corresponding zones are defined by materialID.vtk and zoneID.vtk.
  2. All the materials defined by materialID.vtk have only one zone (all the voxel within a material have the same properties).
  3. The unit-cell consists of a single material with different zones defined in zoneID.vtk.

The material properties, the loading and the algorithm parameters are defined in the xml files : material.xml, loading.xml and algorithm.xml.

The rootname for the output file is given by out_file.


Geometry

The input file(s) materialID.vtk and/or zoneID.vtk are integer fields defined on a uniform grid according to the vtk simple legacy format (http://www.vtk.org/VTK/img/file-formats.pdf).

All the voxels with a common materialID value define a Material domain. Within a given material, all the voxels with a common zoneID value define a Zone.

CONSTRAINTS FOR THE GENERATION OF VTK FILES

Data definition The materialID field must contain integers starting from 0 or 1, and increasing without any skipping value.

The zoneID field must contain, within each Material domain, integers starting from 0 or 1, and increasing without any skipping value.

VTK file headers

The VTK file header must strictly contain the following 10 lines:

# vtk DataFile Version 4.5
Materiau
BINARY
DATASET STRUCTURED_POINTS
DIMENSIONS    66   66   66
ORIGIN    0.000   0.000   0.000
SPACING    1.000000    1.000000   1.000000
CELL_DATA   274625
SCALARS MaterialId unsigned_short
LOOKUP_TABLE default

DIMENSIONS defines the number of voxels per side plus 1. Here, the grid consists of 65x65x65 voxels.

SPACING defines the voxel size and especially the voxel shape. Here voxels are cubic.

CELL_DATA is the number of voxels, it must be in agreement with DIMENSIONS, here 274625=65x65x65.

SCALARS defines the data type (char, short, int, long, unsigned_char, unsigned_short, unsigned_int, unsigned_long, respectively coded on 1, 2, 4 and 8 bytes), here the type is unsigned_short.

Binary data

Binary data, given just after the header, must satisfy the following constraints:

  • byte ordering used to write the binary data is big endian
  • the data type when writing binaries must be consistent with the data type given in the header
  • the maximum field value (especially for zoneID) must be less than the limit value corresponding to the data type
  • BE CAREFUL, in case of unsigned data types, the limit value used by AMITEX_FFTP is the limit value for corresponding signed data types (~ 0.5 x limit value for unsigned). For example, the maximum value for both char and unsigned_char data types (coded on 1 byte) is 127.

XML files

Of course, XML files must follow the XML syntax (use a XML editor with syntax coloring).

A comment is written like this:

<!-- A comment -->

There is no need to follow any specific order for the various inputs given in XML files.

Remark

XML is a case sensitive language. As a consequence, case must be respected for the name of the nodes. However, the name of the string variables that can be input between quotation marks are case insensitive. For example, in the following XML command

<Coeff Index="1" Type="Constant_Zone">

Here, Coeff, Index and Type require the uppercase “C”, “I” and “T”. However, the type Constant_Zone can be written with or without uppercases.


Material properties

WARNING

The number of materials and the number of zones (per material), provided in the “material.xml” file described below, must be consistent with the description given by the vtk file(s).

EXAMPLE This material.xml file provides in a single example different ways to associate the geometry to material properties, detailed explanations are given after this example

<?xml version="1.0" encoding="UTF-8"?>
<Materials>

    <!-- REFERENCE MATERIAL -->
    <Reference_Material Lambda0="2.0952e+10" Mu0="1.5014e+10"/>


    <!-- MATERIAL "2", elastic isotropic behavior ("1") -->
    <Material numM="2" Law_Number="1" >
        <!-- Two constant coefficients (Lamé coefficients Lambda and Mu) -->
        <Coeff Index="1" Type="Constant" Value="4.0385e+10"/>
        <Coeff Index="2" Type="Constant" Value="2.6923e+10"/>
    </Material>


    <!-- MATERIAL "1", linear viscoelastic behavior ("40")-->
    <Material numM="1" Law_Number="40">

        <!-- coefficient 1: constant per zone -->
        <Coeff Index="1" Type="Constant_Zone">
            <!-- value within zone 1 -->
            <Zone numZ="1" Value="5.235e+10" />
            <!-- value within zone 2 -->
            <Zone numZ="2" Value="3.912e+10" />
        </Coeff>

        <!-- coefficient 2: constant per zone, values defined in the ASCII file "Coeff2" -->
        <Coeff Index="2" Type="Constant_Zone " File="Coeff2" Format="ASCII" />

        <!-- coefficient 3: constant per zone, values defined in the binary file "Coeff3.bin" -->
        <Coeff Index="3" Type="Constant_Zone " File="Coeff3.bin" Format="binary" />

        <!-- for sake of clarity, other coefficients for law "40" are omitted -->

        <!-- Internal variables are defined similarly-->
        <IntVar Index="1" Type="Constant" Value="0."/>

        <IntVar Index="2" Type="Constant_Zone">

            <Zone numZ="1" Value="0." />
            <Zone numZ="2" Value="10." />

        </IntVar>

        <IntVar Index="3" Type="Constant_Zone " File="Var3"/>

        <!-- for sake of clarity, other internal variables for law "40" are omitted -->

    </Material>

</Materials>

The file must begin and end with

<?xml version="1.0" encoding="UTF-8"?>
<Materials>
        .
        .
</Materials>

REFERENCE MATERIAL is defined by its Lamé coefficients. For an optimal choice with the basic scheme, see [Moulinec1998]. If convergence acceleration is used (see Algorithm parameters), the same choice can be used but the influence of this choice on the convergence is much less significant

<Reference_Material Lambda0="2.0952e+10" Mu0="1.5014e+10"/>

MATERIALS are defined by their material number numM and their corresponding Law_number

<Material numM="2" Law_Number="1" >
    .
    .
</Material>

The material numbers numM directly correspond the material domains described in materialID.vtk. Note that the numM values, defined between 1 and N (N=number of materials), directly correspond to the integer values distributed in the file materialID.vtk, defined between 1 and N or 0 and N-1 (see Geometry).

The Law_Number is related to the UMAT procedure in which a number is assigned to a behavior law. By default, the value “1” is for an isotropic behavior and “40” for a viscoelastic behavior.

To introduce a new behavior law, see User behavior law and user output.

MATERIAL COEFFICIENT‘s index is the position of each coefficient within the vector COEFF (used as an input of the UMAT procedure, see User behavior law and user output). For an isotropic behavior (Law_Number = “1”), the coefficients COEFF(1) and COEFF(2) are the Lamé coefficients \(\lambda\) and \(\mu\), respectively.

In the example above, four different ways are used to define these values

1. <Coeff Index="1" Type="Constant" Value="4.0385e+10"/>

2. <Coeff Index="1" Type="Constant_Zone">
       <Zone numZ="1" Value="5.235e+10" />
       <Zone numZ="2" Value="3.912e+10" />
   </Coeff>

3. <Coeff Index="2" Type="Constant_Zone " File="Coeff2" Format="ASCII"/>

4. <Coeff Index="3" Type="Constant_Zone " File="Coeff3.bin" Format="binary"/>
  1. is used if the coefficient is constant within the Material

    1. and 4. are used if the coefficient is constant within each Zone defining the Material
  2. is used to import coefficients from a text file, which can be useful when considering a relatively large number of zones (see Example: polyx_mfront). To define a coefficient for two zones, the file must contain at least two lines (one value per line) see an example of the file Coeff2:

    1.429430417
    3.905850691
    

    If the Format tag is not specified, the program will assume that the file given is written in the ASCII format.

  3. is used to import coefficients from a binary file. This is very useful when there is a very large number of zones. The header must contain the following 2 lines:

    2
    double
    

    The first line is the number of zones in the material, it must greater or equal to the number of zones defined in the VTK file.

    The second line defines the data type (char, short, int, long, unsigned_short, unsigned_int, unsigned_long, respectively coded on 1, 2, 4 and 8 bytes), here the type is double. The rest of the file should be binary data satisfying the constraints defined in Binary data (big endian ordering and maximum values).

INITIAL INTERNAL VARIABLES are assigned according to the same procedure. Here, the index is the position of each internal variable within the vector STATEV (used as an input/output of the UMAT procedure, see User behavior law and user output).


Loading and outputs: pure mechanical loading

Here is an example of a loading.xml file where the loading and the stress-strain fields output are defined. This loading reproduces an experimental creep procedure : at first the load is applied proportionnaly (tensile test) and then the macroscopic stress is kept constant (creep test):

<?xml version="1.0" encoding="UTF-8"?>
<Loading_Output>

    <!-- ADDITIONNAL OUPUT QUANTITIES (optionnal) -->
    <Output>

        <!-- Stress output (stress= "1") -->
        <vtk_StressStrain Strain = "0" Stress = "1"/>
        <vtk_IntVarList numM="1">
          1
        </vtk_IntVarList>
        <Zone numM="1">
            <VarIntList>  1  </VarIntList>
        </Zone>

    </Output>

    <!-- SUCCESSIVE LOADINGS AND OUTPUT TIMES -->

    <!-- Partial loading 1 -->
    <Loading Tag="1">

        <!-- User defined time discretization, 10 increments -->
        <Time_Discretization Discretization="User" Nincr="10" />
        <!-- Increment times (user definition) -->
        <Time_List>
        32832 83808 143424 211680 289440 380160 483840 604800 738720 898560
        </Time_List>
        <Output_zone Number ="10"/>
        <!--  No field output required -->
        <!-- Strain driven on xx component -->
        <xx Driving="Strain" Evolution="Linear" Value="-5e-4"/>
        <yy Driving="Stress" Evolution="Constant"  />
        <zz Driving="Stress" Evolution="Constant"  />
        <xy Driving="Stress" Evolution="Constant"  />
        <xz Driving="Stress" Evolution="Constant"  />
        <yz Driving="Stress" Evolution="Constant"  />
        <yx Driving="Strain" Evolution="Constant"  />
        <zx Driving="Strain" Evolution="Constant"  />
        <zy Driving="Strain" Evolution="Constant"  />
    </Loading>

    <!-- Partial loading 2 -->
    <Loading Tag="2">

        <!-- Linear time discretization -->
        <Time_Discretization Discretization="Linear" Nincr="22" Tfinal="25920000" />
        <Output_zone Number ="5"/>
        <!-- Field output for the last increment (22)  -->
        <Output_vtkList>
          22
        </Output_vtkList>
        <!-- Full stress driving -->
        <xx Driving="Stress" Evolution="Constant" />
        <yy Driving="Stress" Evolution="Constant" />
        <zz Driving="Stress" Evolution="Constant" />
        <xy Driving="Stress" Evolution="Constant" />
        <xz Driving="Stress" Evolution="Constant" />
        <yz Driving="Stress" Evolution="Constant" />
        <yx Driving="Strain" Evolution="Constant" />
        <zx Driving="Strain" Evolution="Constant" />
        <zy Driving="Strain" Evolution="Constant" />

    </Loading>

</Loading_Output>

The file must begin and end with

<?xml version="1.0" encoding="UTF-8"?>
<Loading_Output>
.
.
</Loading_Output>

DEFAULT OUTPUT - The section <output> ... </Output> is optionnal. If omitted the output reduces to three ouput files :

.std file : stress and strains average and standard deviations within the whole unit-cell.

.mstd file : per material stress and strains average and standard deviations.

.log file : informations on the simulation (number of iterations, criterion values, computation times etc...).

These quantities are output for each loading increment.

SPECIFIC OUTPUT - The section <output> ... </Output> allows to specify the two types of additionnal output : fields (vtk files) and per zone statistical quantities (zstd). Because these files can be very heavy (and time consuming) the number of outputs must be limited and chosen carefully. This is done in the section <Loading> ... </Loading>.

.vtk files - Strain and/or stress fields (VTK files) can be chosen through the vtk_StressStrain node. If no field are required, simply complete “0” and “0” for Strain and Stress. Similarly, the vtk_IntVarList node, gives the possibility to write in a VTK file the value of a list of internal variables in the material numM. Of course, if internal variables of different materials need to be printed, other vtk_IntVarList nodes, with appropriate numM and lists, can be inserted.

.zstd files - If the Zone node is present, per zone average and standard deviatiations of the stress, strain and requested internal variables, are printed for the material associated to the numM value. If nothing else is precised, only the means and standard deviations of the stress and strain tensors will be printed. However, in this node, a VarIntList node can be added to choose the list of internal variables to be output.

The .std, .mstd and .zstd files are written so that the value of each variable is given in column. Comments at the beginning of these files describe the variable associated to each column. More details about how to plot these results are given in the Plotting results section.

LOADING is defined by successive partial loadings, tagged 1, 2, 3, etc...

Time_Discretization within each partial loading can be chosen:

  • linear (loading 1 in the example): the user gives the final time and the number of increments,
  • user defined (loading 2): the user gives a time list, excluding the initial time.

In both cases, the initial time is the final time of the previous loading or equal to 0 for the first partial loading (i.e. Tag=”1”).

Output_vtkList is the list of increments, within the partial loading, for which stress, strain and/or internal variable fields (.vtk files) will be output.

Output_zone gives the number of loading steps in the partial loading for which per zone quantities (.zstd files) will be output. For each loading, if this number is positive, the output increments are equally distributed among the increasing increments, including the final increment.

Driving allows to define the loading, for each partial loading, and each component xx, yy, zz, xy, xz, yz (and yx, zx, yz in finite strain) :

  • Driving=”Stress” or “Strain” if average stress or strain component is applied
  • Evolution=”Linear” Value=”xx”: the component evolves linearly as a function of the time from the initial value until “xx”
  • Evolution=”Constant”: the component is constant and equal to its initial value.

In both cases, the initial value is the final value of the previous partial loading or equal to 0 for the first partial loading i.e. Tag=”1”.

Warning

With the small perturbation hypothesis (see Algorithm parameters) - In that case the “Strain” and “Stress” components are related to the component of :

  • the average linearized strain tensor,
  • the average Cauchy stress tensor.

Since the Voigt notation is used (in the inputs, the outputs and within the code itself), the value given for xy, xz or yz must be the double of the xy, xz or yz strain components.

Without the small perturbation hypothesis (see Algorithm parameters) - In that case corresponding to the finite strain framework, the “Strain” and “Stress” components are related to the components of :

  • the average first Piola-Kirchoff stress tensor,
  • the average displacement gradient (which is not strictly speaking a measure of the strain).

Mechanical and external loading

If the user wishes to use a material model depending on the temperature and/or external parameters it has to be implemented in the UMAT law (see here). It is then possible to impose these external parameters, constants on the whole unit-cell, during the loading. The temperature corresponds to the scalar UMAT variable TEMP. The other external parameters are gathered within the vector UMAT variable PREDEF. These external parameters must be indexed continuously starting from 1.

Here is an example of a loading.xml file where the temperature and two other external parameters are imposed:

<?xml version="1.0" encoding="UTF-8"?>
<Loading_Output>

    <!-- ADDITIONNAL OUPUT QUANTITIES (optionnal) -->
    <!-- <Output>
         </Output> -->

    <!-- Initialization of the temperature and the external parameters -->
    <InitLoadExt>
      <T Value="20" />
      <Param Index ="1" Value="0" />
      <Param Index ="2" Value="10" />
    </InitLoadExt>
    <!-- SUCCESSIVE LOADINGS AND OUTPUT TIMES -->

    <!-- Partial loading 1 -->
    <Loading Tag="1">
        <!-- User defined time discretization, 10 increments -->
        <Time_Discretization Discretization="User" Nincr="10" />
        <!-- Increment times (user definition) -->
        <Time_List>
        32832 83808 143424 211680 289440 380160 483840 604800 738720 898560
        </Time_List>
        <!--  No field output required -->
        <!-- Strain driven on xx component -->
        <xx Driving="Strain" Evolution="Linear" Value="-5e-4"/>
        <yy Driving="Stress" Evolution="Linear" Value="0." />
        <zz Driving="Stress" Evolution="Linear" Value="0." />
        <xy Driving="Stress" Evolution="Linear" Value="0" />
        <xz Driving="Stress" Evolution="Linear" Value="0" />
        <yz Driving="Stress" Evolution="Linear" Value="0" />
        <!-- Temperature is constant, equal to the initial value -->
        <T Evolution="Constant" />
        <!-- External parameters 1 and 2 have a linear evolution -->
        <Param Index="1" Evolution="Linear" Value ="50"/>
        <Param Index="2" Evolution="Linear" Value ="0"/>

    </Loading>

</Loading_Output>

In order to be imposed during the loading the temperature and each external parameter must :

  1. be initialized inside the section <InitLoadExt> ... </InitLoadExt>

    <InitLoadExt>
          <T Value="20" />
          <Param Index ="1" Value="0" />
          <Param Index ="2" Value="10" />
    </InitLoadExt>
    
  2. be described within each <Loading Tag=”i”> section as described in the example. The Evolution can be linear or constant as a function of time. In both cases, the initial value is the final value of the previous partial loading or equal to the value defined in the InitLoadExt tag for the first partial loading (i.e. Tag=”1”).

    <!-- Temperature is constant, equal to the initial value -->
    <T Evolution="Constant" />
    <!-- External parameters 1 and 2 have a linear evolution -->
    <Param Index="1" Evolution="Linear" Value ="50"/>
    <Param Index="2" Evolution="Linear" Value ="0"/>
    

Algorithm parameters

This section describes the algorithm parameters that can be chosen in the corresponding in the file algorithm.xml (see How to launch AMITEX_FFTP):

<?xml version="1.0" encoding="UTF-8"?>
<Algorithm_Parameters>
    <Filter Type="Default"/>                            <!-- "Default" ("hexa") or "no_filter" or "hexa" or "octa" -->
    <Small_Perturbations Value="true"/>                 <!-- "True" or "False" -->
    <Algorithm Type="Basic_Scheme">                     <!-- "Default" ("Basic_Scheme") -->
        <Convergence_Criterion Value="default"/>        <!-- "Default" (1e-4) or positive real value < 1e-3 -->
        <Convergence_Acceleration Value="true"/>        <!-- "True" or "False" -->
    </Algorithm>
</Algorithm_Parameters>

Filter - Different discrete Green operators are implemented in the code :

  • the classical one [Moulinec1998]
  • the hexaedral and octaedral filtered Green operators (to be published)

The hexaedral filtered Green Operator is the “Default”. It is:

  • very efficient to reduce the sensitivity to the mechanical contrast,
  • efficient to reduce spurious oscillations

Small_Perturbation - The user can choose to perform the simulation with or without the small perturbation assumption. Of course, the loading file must be consistent with this choice (see Warning).

Algorithm - Here, the basic scheme [Moulinec1998] is implemented with an additionnal convergence acceleration procedure which can be used or not. This convergence acceleration procedure (see procedure ACT3 in the finite element code CAST3M) is:

  • very efficient to reduce the sensitivity to the mechanical contrast,
  • very efficient to reduce the sensitivity to the reference material choice,
  • more memory consuming.

The convergence criterion is given by an equilibrium condition (i.e. \(div(\sigma) = 0\)) together with an average condition on the applied load. The default value is \(10^{-4}\) (a maximum value is set to \(10^{-3}\)).

If memory is not a problem, do not hesitate and use the convergence acceleration!


User behavior law and user output

General case

The AMITEX_FFTP offers the possibility to introduce user material behaviors through the UMAT procedure.

In the program, a standard output file output.std is printed after each loading increment. However, the user has also the possibility to modify this output through the sortie_std procedure. The purpose of this section is to show how to build the executable program AMITEX_FFTP incorporating a new user material behavior and/or a new user standard output.

A complete example, with both a user behavior law and a user output (which is, here, a copy of the original one), is available in (amitex_fftp)/cas_tests/comportements/polyxCC. The user can copy-paste this directory on his home directory (denoted here as home) and follow the procedure below.

The user material files (at least the umat file) and an additionnal Makefile to compile files are located in home/polyxCC/comportement_umat. The Fortran file umat is used to define a “law number”, assigned in the material.xml file (see Material properties), to call the corresponding behavior.

The user output files (at least the sortie_std file) and an additionnal Makefile to compile files are located in home/polyxCC/sortie_std.

The Makefile located in home/polyxCC launch the compilation within the two directories and build the executable.

  1. Adjust the following first lines of the Makefile located in home/polyxCC:

    # Path towards libraries
    lDecomp  = (amitex_fftp)/lib_extern/2decomp_fft-1.5.847
    lFox     = (amitex_fftp)/lib_extern/FoX-4.1.2
    lAmitex  = (amitex_fftp)/libAmitex
    
    # Directory where are the user material files (if exists)
    behavior = comportement_umat
    
    # Directory where are the user output files (if exists)
    output = sortie_std
    
    # Executable name
    MAIN = amitex_fftp
    
  2. In home/polyxCC:

    make clean
    make
    

The executable amitex_fftp should be created.

Remark

Setting “behavior” and “output” to blank values will build a non-modified amitex_fftp.

Using MFront

Interfacing AMITEX_FFTP with MFront libraries is quite similar.

An example with a dynamic library created by MFront, specifying the umat interface , is given in (amitex_fftp)/cas_tests/mazars.

The dynamic library was given as an output of MFront using the command:

mfront --obuild --interface=umat mazars.mfront

where mazars.mfront is the Mazars behavior law [Mazars1990] defined in MFront (see http://tfel.sourceforge.net/documentations.html for more information).

The Fortran file umat is used to define a “law number”, assigned in the material.xml file (see Material properties), to call the corresponding behavior generated by MFront within the library libUmatBehaviour.so.

It assumes that you have installed MFront on your machine and that the LD_LIBRARY_PATH contains the MFront library path.