% MTest keywords

The @AccelerationAlgorithm keyword

The @AccelerationAlgorithm keyword is used to give the name of the acceleration algorithm used to accelerate the convergence toward equilibrium.

The following algorithms are available:

The parameters of these algorithms are given by the @AccelerationAlgorithmParameter keyword:

Example:

@AccelerationAlgorithm 'Secant';

The @AccelerationAlgorithmParameter keyword

The @AccelerationAlgorithmParameter keyword allows the user to fine-tune the acceleration algorithm used to reach equilibrium. The parameter that can be defined depends on the acceleration algorithm used.

This keyword is followed by a string giving the name of the parameter and the value of this parameter, given without quotes.

Example

@AccelerationAlgorithmParameter 'AccelerationTrigger' 3;

The @Author keyword

The @Author keyword is used give the name of the person who wrote the mtest file.

All the following words are appended to the author’s name up to a final semicolon.

Example:

@Author Éric Brunon;

The @Behaviour keyword

The @Behaviour keyword declares the behaviour used for the test.

This keyword may be followed by two options:

Two strings are then expected:

Sometimes, additional parameters must be given, in particular for interfaces to behaviours not generated by MFront.

Available interfaces

The following interfaces are supported for MFront generated behaviours:

Some interfaces are also available for behaviours not generated by MFront:

Available behaviour wrappers

Currently, two behaviours wrappers are available:

Example

@Behaviour<castem> 'libMFrontCastemBehaviours.so' 'umatnorton';
@Behaviour<mistral> 'SOURCES/libumat.so' 'umat_' {
 'mistral_parameters_file' : 'M5CC_par.txt',
 'SENSIP1':1,
 'SENSIP2':3,
 'ICBASE' :0};
@Behaviour<castem_umat_small_strain> './libumat.so' 'umat_'{
 'NUME_LOI'   : 10,
 'SYMETRIE'   : 'ISOTROPE',
 'C_MATERIAU' : {'YOUN','NU'}
};

The @CastemAccelerationPeriod keyword

The keyword @CastemAccelerationPeriod specifies the number of iterations between two calls to the acceleration algorithm.

This keyword is followed by a positive number.

Example

@CastemAccelerationPeriod 3;

The @CastemAccelerationTrigger keyword

The keyword @CastemAccelerationTrigger specifies the number of iterations before the first call to the acceleration algorithm.

This keyword is followed by a positive number.

Example

@CastemAccelerationTrigger 4;

The @CohesiveForce keyword

The @CohesiveForce keyword let the user specify the initial value of the cohesive forces.

This keyword is followed by an array. The size of this array must be equal to the space dimension of the modelling hypothesis considered (one component per space dimension, see the @ModellingHypothesis keyword).

Example

@CohesiveForce {'T0', 0., 0.};

The @CohesiveForceEpsilon keyword

The global algorithm uses two criteria to check if a satisfying equilibrium has been found: one on opening displacements, the other on cohesive forces.

This criterion on cohesive forces checks that the residual of the Newton algorithm is low enough. By default, this value is equal to 1.e-3, which is a convenient value if cohesive force are expressed in Newton.

The @CohesiveForceEpsilon let the user specify the criterion value used for the criterion on cohesive force.

It is followed by the criterion value.

Example

@CohesiveForceEpsilon 1.e-3;

The @CompareToNumericalTangentOperator keyword

If the @CompareToNumericalTangentOperator is followed by true, a comparison of the tangent operator given by the behaviour to a numerical approximation computed by a centered finite difference is performed.

The value of the perturbation used to compute this numerical approximation can be adjusted by the @NumericalTangentOperatorPerturbationValue.

The value used for to compare the tangent operator given by the behaviour to a numerical approximation can be adjusted by the @TangentOperatorComparisonCriterion.

This comparison is a debugging tool: when it fails, the tangent operator given by the behaviour and its numerical approximation are printed in the output of MTest, but the test is not considered as failed.

Example

@CompareToNumericalTangentOperator true;

The @Date keyword

The @Date keyword allows the user to precise when the mtest file was written.

All the following words are appended to the date up to a final semicolon.

Example

@Date 2008-11-17;

The @DeformationGradient keyword

The @DeformationGradient let the user specify the initial value of the deformation gradient.

This keyword is followed by an array. The size of this array must be equal to the number of components of (non-symmetric) tensors for the modelling hypothesis considered (see the @ModellingHypothesis keyword).

Example

@DeformationGradient {1,1,1,0,0,0,0,0,0};

The @DeformationGradientEpsilon keyword

The global algorithm uses two criteria to check if a satisfying equilibrium has been found: one on deformation gradient, the other on stresses.

This criterion on the deformation gradient checks if two successive estimate of the strains are close enough. By default, the criterion value used is 1.e-12;

The @DeformationGradientEpsilon let the user specify the criterion value used for the criterion on strains.

It is followed by the criterion value.

Example

@DeformationGradientEpsilon 1.e-12;

The @Description keyword

The @Description keywords describes the test which is implemented in a mtest file.

This keyword is followed by a block containing all the relevant piece of information.

Example

@Description
{
  "Modélisation d'un tube sous pression"
};

The @DrivingVariable keyword

The @DrivingVariable keyword is a synonym of @Gradient.

The @DrivingVariableEpsilon keyword

The @DrivingVariableEpsilon keyword is a synonym of @GradientEpsilon.

The @DynamicTimeStepScaling keyword

The @DynamicTimeStepScaling keyword let the user enable or disable the dynamic time step adaptation.

This keyword is followed by a boolean.

Example

@DynamicTimeStepScaling true;

The @Event keyword

The @Event keyword allows the user to define event during the computations. Defining an event is a way to active/desactivate a constraint, (see @ImposedStrain, @ImposedCohesiveForce, @ImposedOpeningDisplacement, @ImposedStrain, @ImposedDeformationGradient, @NonLinearConstraint).

The @Event keyword is followed by the name of the event and a time or a list of times (given as an array of values).

Example

@Event 'Stop' '1';

Note

The times defining an event are not required to match a time of the discretisation of the computation, but this is highly recommended. An event is triggered at the end of a time step when the final time is greater or equal than the time associated with the event. This does not take into account sub-steppings.

The @Evolution keyword

The @Evolution specifies a function of time.

This keyword may have one option, which is the way the evolution will be defined. Four values are accepted: evolution, function, data and file. The data and file options are equivalent. If no option is specified, the evolution option is chosen.

After the option, the name of evolution, which shall be given as string, is expected.

evolution option

If the evolution option has been selected, the user may specify a constant evolution by simply giving its value. Otherwise, complex evolutions can be build using an associative array where the key is the time and the value of the evolution. Between two times, the values will be interpolated linearly. Prior to the first declared time given, the value corresponding to this first time is used. After the last time given, the value corresponding this last time is used.

function option

If the function option has been selected, a string is expected which will be interpreted as a function of time. The time is represented by the variable t.

data or file options

With the data or file options, one may define an evolution based on the values defined in a file. Those values will be interpolated linearly.

After the evolution name, one expects a file name as a string. This file name must be followed by:

This syntax has been choosen to mimic the gnuplot one.

A formula can use any constant or function defined in the input file, such a the ones defined by the @Real keyword. A variable prefixed by the $ followed by a positive integer holds for the value of a column.

Example (constant evolution):

@Evolution 'Pressure' 1.e5;

Example (linear evolution):

@Evolution 'Pressure' {0:0.,1.:1.e5};

Example (function):

@Real 'P0' 2.e5;
@Real 'P1' 4.e5;
@Evolution<function> 'Pressure' 'P0+(P1-P0)*t**2';

Example (data):

// times are converted to seconds
// pressure is converted to Pa
@Evolution<data> 'Pressure' 'data.txt' using '$1*3600':'$2*1e6';

The @ExternalStateVariable keyword

The @ExternalStateVariable keyword let the user specify the evolution of an external state variables, including the temperature which is generally defined by default by behaviour interfaces.

This keyword may have one option, which is the way the evolution will be defined. Four values are accepted: evolution, function, data or file. The data and file options are equivalent. If no option is specified, the evolution option is chosen.

After the option, the name of the external state variable, which shall be given as string, is expected.

The @ExternalStateVariable allows to define tensorial external state variables components by components (see example below).

evolution option

If the evolution option has been selected, the user may specify a constant evolution by simply giving its value. Otherwise, complex evolutions can be build using an associative array where the key is the time and the value of the evolution. Between two times, the values will be interpolated linearly. Prior to the first declared time given, the value corresponding to this first time is used. After the last time given, the value corresponding this last time is used.

function option

If the function option has been selected, a string is expected which will be interpreted as a function of time. The time is represented by the variable t.

data or file options

With the data or file options, one may define an evolution based on the values defined in a file. Those values will be interpolated linearly.

After the evolution name, one expects a file name as a string. This file name must be followed by:

This syntax has been choosen to mimic the gnuplot one.

A formula can use any constant or function defined in the input file, such a the ones defined by the @Real keyword. A variable prefixed by the $ followed by a positive integer holds for the value of a column.

Example (constant evolution)

@ExternalStateVariable 'Temperature' 293.15;

Example (linear evolution)

@ExternalStateVariable 'Temperature' {0:293.15,1.:800};

Example (function)

@Real 'T0' 293.15;
@Real 'T1' 400.15;
@ExternalStateVariable<function> 'Temperature' 'T0+(T1-T0)*t**2';
// Definition of an symmetric tensor external state variable
@ExternalStateVariable<function> 'g' {'0', '1', '2', '3 * t', '4', '5 * t'};
// Definition of an symmetric tensor external state variable components by components
@ExternalStateVariable<function> 'g2XX'  '0';
@ExternalStateVariable<function> 'g2YY'  '2';
@ExternalStateVariable<function> 'g2ZZ'  't';
@ExternalStateVariable<function> 'g2XY'  '3';
@ExternalStateVariable<function> 'g2XZ'  '4';
@ExternalStateVariable<function> 'g2YZ'  '5*t';

The @Gradient keyword

The @Gradient keyword specifies the initial values of the gradients of the behaviour.

This keyword is followed by an array. The size of this array must be equal to the total size of the gradients of the behaviour for the modelling hypothesis considered (see the @ModellingHypothesis keyword).

This keyword can be used with any behaviour. The @Strain, @DeformationGradient and @OpeningDisplacement keywords are the specialised versions of this keyword for small strain behaviours, finite strain behaviours and cohesive zone models respectively. The @DrivingVariable keyword is a synonym of @Gradient.

Example

@Gradient {0.13};

The @GradientEpsilon keyword

The global algorithm uses two criteria to check if a satisfying equilibrium has been found: one on the gradients, the other on the thermodynamic forces.

The criterion on the gradients checks if two successive estimates of the gradients are close enough. By default, the criterion value used is 1.e-12.

The @GradientEpsilon keyword specifies the criterion value used for the criterion on the gradients. It is followed by the criterion value.

The @StrainEpsilon, @DeformationGradientEpsilon and @OpeningDisplacementEpsilon keywords are the specialised versions of this keyword for small strain behaviours, finite strain behaviours and cohesive zone models respectively. The @DrivingVariableEpsilon keyword is a synonym of @GradientEpsilon.

Example

@GradientEpsilon 1.e-10;

The @HandleThermalExpansion keyword

The @HandleThermalExpansion keyword allow the activation or desactivation of the computation of thermal strain. The computation of the thermal strain is done by default if a material property named ThermalExpansion is defined (for isotropic materials).

This keyword is followed by a boolean. If true, the computation of the thermal strain is done.

Example

@HandleThermalExpansion false;

The @Import keyword

Depending of the option used (given between ‘<’ and ‘>’), the @Import keyword may have various meanings.

The castem option

The castem (or Castem or Cast3M) option let you import a function generated by MFront with the castem interface. This function can be used in every formula.

The keyword is followed by the library an function names.

Example

@Import<castem> 'CastemW' 'W_ThermalExpansion';
@Real 'h' '16e-3*(1+W_ThermalExpansion(1500)*(1500-293.15))';

The @ImposedCohesiveForce keyword

The @ImposedCohesiveForce keyword allows the user to impose the evolution of a component of the cohesive force of a cohesive zone model.

This keyword may have one option, which is the way the evolution will be defined. Four values are accepted: evolution, function, data or file. The data and file options are equivalent. If no option is specified, the evolution option is chosen.

After the option, the name of the component of the cohesive force, which shall be given as string, is expected.

The definition of the evolution and the options on the active state of the constraint are the same as for the @ImposedStrain keyword.

Name of the components of the cohesive force

According to the modelling hypothesis selected (see the @ModellingHypothesis keyword), the following components names are accepted:

Tn is the normal component and Tt, Tt1 and Tt2 are the tangential components.

Example

@ImposedCohesiveForce 'Tn' {0 : 0, 1 : 1.e6};

The @ImposedDeformationGradient keyword

The @ImposedDeformationGradient keyword allows the user to impose the evolution of a component of the deformation gradient.

This keyword may have one option, which is the way the evolution will be defined. Four values are accepted: evolution, function, data or file. The data and file options are equivalent. If no option is specified, the evolution option is chosen.

After the option, the name of the component of the deformation gradient, which shall be given as string, is expected.

Finally, one may optionnally set options on the active state of this contraint, the activating events and desactivating events using a JSON-like structure. See the @Event keyword to know how to define an event. This structure starts with an opening curly brace ({) and ends with a closing curly brace (}). An option is given by its name, an double-dot character (:) and the value of the option. Consecutive options are separated by a comma ,. The following options are available:

Name of the components of the deformation gradient

According to the modelling hypothesis selected (see the @ModellingHypothesis keyword), the following components names are accepted:

evolution option

If the evolution option has been selected, the user may specify a constant evolution by simply giving its value. Otherwise, complex evolutions can be build using an associative array where the key is the time and the value of the evolution. Between two times, the values will be interpolated linearly. Prior to the first declared time given, the value corresponding to this first time is used. After the last time given, the value corresponding this last time is used.

function option

If the function option has been selected, a string is expected which will be interpreted as a function of time. The time is represented by the variable t.

data or file options

With the data or file options, one may define an evolution based on the values defined in a file. Those values will be interpolated linearly.

After the evolution name, one expects a file name as a string. This file name must be followed by:

This syntax has been choosen to mimic the gnuplot one.

A formula can use any constant or function defined in the input file, such a the ones defined by the @Real keyword. A variable prefixed by the $ followed by a positive integer holds for the value of a column.

Example (constant evolution)

@ImposedDeformationGradient<evolution> 'FXX' 1e-3;

Example (linear evolution)

@ImposedDeformationGradient<evolution> 'FXX' {0.:0.,1:1e-3};

Example (function)

@ImposedDeformationGradient<function> 'FXX' 'e0*sin(t/900.)';

The @ImposedDrivingVariable keyword

The @ImposedDrivingVariable keyword is a synonym of @ImposedGradient.

The @ImposedGradient keyword

The @ImposedGradient keyword allows the user to impose the evolution of a component of the gradients of the behaviour.

This keyword may have one option, which is the way the evolution will be defined. Four values are accepted: evolution, function, data or file. The data and file options are equivalent. If no option is specified, the evolution option is chosen.

After the option, the name of the component of the gradients, which shall be given as string, is expected. A scalar gradient is designated by its name. A component of a tensorial gradient is designated by the name of the gradient followed by the suffix of the component, for instance StrainXX for a symmetric tensor named Strain. For small strain behaviours, finite strain behaviours and cohesive zone models, the names of the components are the ones given by the @ImposedStrain, @ImposedDeformationGradient and @ImposedOpeningDisplacement keywords.

The definition of the evolution and the options on the active state of the constraint are the same as for the @ImposedStrain keyword.

This keyword can be used with any behaviour. The @ImposedStrain, @ImposedDeformationGradient and @ImposedOpeningDisplacement keywords are the specialised versions of this keyword for small strain behaviours, finite strain behaviours and cohesive zone models respectively. The @ImposedDrivingVariable keyword is a synonym of @ImposedGradient.

Example

@ImposedGradient 'ChangeOfVolume' {0 : 0.13, 1 : 0.24};

The @ImposedOpeningDisplacement keyword

The @ImposedOpeningDisplacement keyword allows the user to impose the evolution of a component of the opening displacement of a cohesive zone model.

This keyword may have one option, which is the way the evolution will be defined. Four values are accepted: evolution, function, data or file. The data and file options are equivalent. If no option is specified, the evolution option is chosen.

After the option, the name of the component of the opening displacement, which shall be given as string, is expected.

The definition of the evolution and the options on the active state of the constraint are the same as for the @ImposedStrain keyword.

Name of the components of the opening displacement

According to the modelling hypothesis selected (see the @ModellingHypothesis keyword), the following components names are accepted:

Un is the normal component and Ut, Ut1 and Ut2 are the tangential components.

Example

@ImposedOpeningDisplacement 'Un' {0 : 0, 1 : 1.e-4};

The @ImposedStrain keyword

The @ImposedStrain keyword allows the user to impose the evolution of a component of the strains.

This keyword may have one option, which is the way the evolution will be defined. Four values are accepted: evolution, function, data or file. The data and file options are equivalent. If no option is specified, the evolution option is chosen.

After the option, the name of the component of the strains, which shall be given as string, is expected.

Finally, one may optionnally set options on the active state of this contraint, the activating events and desactivating events using a JSON-like structure. See the @Event keyword to know how to define an event. This structure starts with an opening curly brace ({) and ends with a closing curly brace (}). An option is given by its name, an double-dot character (:) and the value of the option. Consecutive options are separated by a comma , (see below for an example). The following options are available:

Name of the components of the strain

According to the modelling hypothesis selected (see the @ModellingHypothesis keyword), the following components names are accepted:

evolution option

If the evolution option has been selected, the user may specify a constant evolution by simply giving its value. Otherwise, complex evolutions can be build using an associative array where the key is the time and the value of the evolution. Between two times, the values will be interpolated linearly. Prior to the first declared time given, the value corresponding to this first time is used. After the last time given, the value corresponding this last time is used.

function option

If the function option has been selected, a string is expected which is interpreted as a function of time. The current time is represented by the variable t.

data or file options

With the data or file options, one may define an evolution based on the values defined in a file. Those values will be interpolated linearly.

After the evolution name, one expects a file name as a string. This file name must be followed by:

This syntax has been choosen to mimic the gnuplot one.

A formula can use any constant or function defined in the input file, such a the ones defined by the @Real keyword. A variable prefixed by the $ followed by a positive integer holds for the value of a column.

Example (constant evolution)

@ImposedStrain<evolution> 'EXX' 1e-3;

Example (linear evolution)

@ImposedStrain<evolution> 'EXX' {0.:0.,1:1e-3};

Example (function)

@ImposedStrain<function> 'EXX' 'e0*sin(t/900.)';

Example (event)

@ImposedStrain<evolution> 'EXX' {0.:0.,1:1e-3}{
    desactivating_event : 'Stop'
};

Note

The off-diagonal terms shall be multiplied by a factor \(\sqrt(2)\) with respect to standard conventions.

The @ImposedStress keyword

The @ImposedStress keyword allows the user to impose the evolution of a component of the stresses.

This keyword may have one option, which is the way the evolution will be defined. Four values are accepted: evolution, function, data or file. The data and file options are equivalent. If no option is specified, the evolution option is chosen.

After the option, the name of the component of the stresses, which shall be given as string, is expected.

Finally, one may optionnally set options on the active state of this contraint, the activating events and desactivating events using a JSON-like structure. See the @Event keyword to know how to define an event. This structure starts with an opening curly brace ({) and ends with a closing curly brace (}). An option is given by its name, an double-dot character (:) and the value of the option. Consecutive options are separated by a comma ,. The following options are available:

Name of the components of the stress

According to the modelling hypothesis selected (see the @ModellingHypothesis keyword), the following components names are accepted:

evolution option

If the evolution option has been selected, the user may specify a constant evolution by simply giving its value. Otherwise, complex evolutions can be build using an associative array where the key is the time and the value of the evolution. Between two times, the values will be interpolated linearly. Prior to the first declared time given, the value corresponding to this first time is used. After the last time given, the value corresponding this last time is used.

function option

If the function option has been selected, a string is expected which is interpreted as a function of time. The current time is represented by the variable t.

data or file options

With the data or file options, one may define an evolution based on the values defined in a file. Those values will be interpolated linearly.

After the evolution name, one expects a file name as a string. This file name must be followed by:

This syntax has been choosen to mimic the gnuplot one.

A formula can use any constant or function defined in the input file, such a the ones defined by the @Real keyword. A variable prefixed by the $ followed by a positive integer holds for the value of a column.

Example (constant evolution)

@ImposedStress 'SXX' 50.e6;

Example (linear evolution)

@ImposedStress<evolution> 'SXX' {0.:0.,1:50e6};

Example (function)

@ImposedStress<function>  'SXX' 's0*sin(t/900.)';

Note

The off-diagonal terms shall be multiplied by a factor \(\sqrt(2)\).

The @ImposedThermodynamicForce keyword

The @ImposedThermodynamicForce keyword allows the user to impose the evolution of a component of the thermodynamic forces of the behaviour.

This keyword may have one option, which is the way the evolution will be defined. Four values are accepted: evolution, function, data or file. The data and file options are equivalent. If no option is specified, the evolution option is chosen.

After the option, the name of the component of the thermodynamic forces, which shall be given as string, is expected. A scalar thermodynamic force is designated by its name. A component of a tensorial thermodynamic force is designated by the name of the thermodynamic force followed by the suffix of the component, for instance StressXX for a symmetric tensor named Stress. For small and finite strain behaviours and for cohesive zone models, the names of the components are the ones given by the @ImposedStress and @ImposedCohesiveForce keywords.

The definition of the evolution and the options on the active state of the constraint are the same as for the @ImposedStrain keyword.

This keyword can be used with any behaviour. The @ImposedStress and @ImposedCohesiveForce keywords are the specialised versions of this keyword for small and finite strain behaviours and for cohesive zone models respectively.

Example

@ImposedThermodynamicForce 'HydrostaticPressure' {0 : 0, 1 : 1.e6};

The @IntegerParameter keyword

The @IntegerParameter keyword specifies the value of an integer parameter of the behaviour.

Example

@IntegerParameter 'iter' 12;

The @InternalStateVariable keyword

The @InternalStateVariable keyword defines the initial value of a state variable.

This keyword must be followed by the name of the internal state variable considered, given as a string.

If this internal state variable is scalar, a real value is then expected.

If this internal state variable is a symmetric tensor, an array of real values of the appropriate size is expected. A symmetric tensor has 3 components in 1D, 4 components in 2D and 6 components in 3D (see the @ModellingHypothesis keyword). The off-diagonals components shall be declared with a \(\sqrt(2)\) factor.

Example

@InternalStateVariable 'ElasticStrain' {'EELRR0','EELZZ0','EELZZ0',0.};

The @MaterialProperty keyword

The @MaterialProperty keyword defines a material property. Only the mechanical properties defined by the behaviour for the modelling hypothesis considered may be used with the noticeable exception of the thermal expansions:

This keyword takes the type of the material property as an option. Three types of material properties are supported, constant or castem or function.

The name of the material property shall then be given.

If the material property is constant, its value is expected.

If the material property is of the castem type, the name of the library and the name of the function implementing the material property are expected.

If the material property is a function, the function definition is expected.

Example (constant)

@MaterialProperty<constant> 'YoungModulus' 150.e9;

Example (castem)

@MaterialProperty<castem> 'YoungModulus' 'libInconel600MaterialProperties.so' 'Inconel600_YoungModulus';

The @MaximalTimeStep keyword

The @MaximalTimeStep keyword let the user define the maximal time step allowed.

This keyword is followed by a value.

Example

@MaximalTimeStep 1.e-4;

The @MaximalTimeStepScalingFactor keyword

The @MaximalTimeStepScalingFactor keyword let the user define the maximal time step scaling factor allowed during automatic time step adaptation (see @DynamicTimeStepScaling for details).

This keyword is followed by a value. This value must be greater than one.

Example

@MaximalTimeStepScalingFactor 1.2;

The @MaximumNumberOfIterations keyword

The @MaximumNumberOfIterations keyword let the user specify the maximum number of iterations of the global algorithm to reach the equilibrium.

This keyword is followed by an integer.

If the number of iterations reaches the maximal authorized value, the time step is divided by two. The maximum number of sub-steps can be specified using the @MaximumNumberOfSubSteps keyword.

Example

@MaximumNumberOfIterations 10;

The @MaximumNumberOfSubSteps keyword

The @MaximumNumberOfSubSteps keyword let the user specify the maximum number of sub steps allowed.

This keyword is followed by an integer.

When the global algorithm fails to reach equilibrium (see the @MaximumNumberOfIterations keyword), the time step can be divided by two. The maximal number of times the time step is reduced if given by maximum number of sub steps.

Example

@MaximumNumberOfSubSteps 10;

The @Message keyword

The @Message keyword is used to display some informative message on the standard output.

This keyword is followed by floatting point values and/or strings.

Strings are first interpreted as formulae. If the interpretation is successfull, the result is printed. Otherwise, the string is display witout interpretation.

All the following tokens are appended to the message up to a final semi-colon.

Example:

@Message "12*5";

The @MinimalTimeStep keyword

The @MinimalTimeStep keyword let the user define the minimal time step allowed.

This keyword is followed by a value.

Example

@MinimalTimeStep 1.e-4;

The @MinimalTimeStepScalingFactor keyword

The @MinimalTimeStepScalingFactor keyword let the user define the minimal time step scaling factor allowed during automatic time step adaptation (see @DynamicTimeStepScaling for details).

This keyword is followed by a value. This value must be strictly positive and lower than one.

Example

@MinimalTimeStepScalingFactor 0.2;

The @Model keyword

The @Model keyword is mostly a synomymous of the @Behaviour. The only difference is that a check is done to see if the behaviour does not declare any gradient, thermodynamic force nor any tangent operator block.

Example

@Model<generic> 'src/libBehaviour.so' 'ode_rk54';

The @ModellingHypothesis keyword

The @ModellingHypothesis keyword allows the user to choose the modelling hypothesis to use. The keywords shall be one of the first keyword of the file: if not, some keywords, which requires the modelling hypothesis to be defined, may force the default modelling hypothesis to be used (Tridimensional).

This keyword is followed by the desired modelling hypothesis given as a string. The following values are currently supported:

The modelling hypothesis changes the name of the components of symmetric tensors and their numbers. For example, the components of the strains are:

The @NonLinearConstraint keyword

The @NonLinearConstraint keyword let the user introduce arbitrary constraints on driving variables and thermodynamic forces.

Note

This keyword can also be used to define linear constraints, although the numerical treatment of such a constraint will be sub-optimal. A special treatment of such a constraint is planned.

Note

A stress component whose value is imposed using @ImposedStress command shall not appear in a non linear constraint: the numerical treatment of those two constraints is incompatible.

Applications

Abritray non linear constraints can be used to:

On the physical meaning of a constraint

A constraint \(c\) is imposed by introducing a Lagrange multiplier \(\lambda\).

Consider a small strain elastic behaviour characterised by its free energy \(\Psi\). In the only loading is the constraint \(c\), the solution satisfies: \[ \underset{\underline{\varepsilon},\lambda}{\min}\Psi-\lambda\,c \]

In this case, the constraint \(c\) is equivalent to the following imposed stress:

\[ -\lambda\,{\displaystyle \frac{\displaystyle \partial c}{\displaystyle \partial \underline{\varepsilon}}} \]

If the constraint is \(\sigma_{xx}-\sigma_{0}\), where \(\sigma_{0}\) is a constant value, the previous equation shows that imposing this constraint is not equivalent to imposing an uniaxial stress state \(\left(\sigma_{xx}\,0\,0\,0\,0\,0\right)\).

Normalisation policy

This keyword must be followed by an option giving the normalisation policy. The normalisation policy can have one of the following values:

Example

// ensure that the loading is isochoric in 1D
@NonLinearConstraint<Strain> 'FRR*FTT*FZZ-1';
// impose the first piola kirchoff stress
// in an uniaxial compression test
@Real 'Pi0' -40e6;
@NonLinearConstraint<Stress> 'SXX*FYY*FZZ-Pi0';
@NonLinearConstraint<Stress> 'SYY';
@NonLinearConstraint<Stress> 'SZZ';
@NonLinearConstraint<Stress> 'SXY';
@NonLinearConstraint<Stress> 'SXZ';
@NonLinearConstraint<Stress> 'SYZ';

The @NumericalTangentOperatorPerturbationValue keyword

The @NumericalTangentOperatorPerturbationValue keyword can be used to adjust the value use to perform a numerical approximation of the tangent operator. This keyword followed by the value to be used.

Example

@NumericalTangentOperatorPerturbationValue 1.e-9;

The @OpeningDisplacement keyword

The @OpeningDisplacement keyword specifies the initial value of the opening displacement of a cohesive zone model.

This keyword is followed by an array. The size of this array must be equal to the space dimension of the modelling hypothesis considered (one component per space dimension, see the @ModellingHypothesis keyword).

Example

@OpeningDisplacement {1.e-4, 0., 0.};

The @OpeningDisplacementEpsilon keyword

The global algorithm uses two criteria to check if a satisfying equilibrium has been found: one on opening displacements, the other on cohesive forces.

This criterion on opening displacements checks if two successive estimates of the opening displacements are close enough. By default, the criterion value used is 1.e-12.

The @OpeningDisplacementEpsilon keyword specifies the criterion value used for the criterion on opening displacements.

It is followed by the criterion value.

Example

@OpeningDisplacementEpsilon 1.e-12;

The @OutOfBoundsPolicy keyword

The @OutOfBoundsPolicy let the user to precise the out of bounds policy. Three policies are available:

Example

@OutOfBoundsPolicy 'Strict';

The @OutputFile keyword

The @OutputFile keywords specifies the name of the output file. By default, the name of output file is equal to the name of the input file, minus the .mtest extension if present, plus .res.

Example

@OutputFile 'results.txt';

The @OutputFilePrecision keyword

The @OutputFilePrecision specify the number of digits used to print the results in the output file.

This keyword is followed by the number of digits wanted.

Example

@OutputFilePrecision 15;

The @OutputFrequency keyword

The OutputFrequency let the user specify at when results are written in the output files. This keyword is followed by a string. Two values are allowed:

This two options differs only in case of substepping.

Example

@OutputFrequency 'EveryPeriod';

The @Parameter keyword

The @Parameter keyword specifies the value of a parameter of the behaviour.

Example

@Parameter 'espilon' 1.e-8;

The @PredictionPolicy keyword

The @PredictionPolicy keyword let the user how the initial estimate of the solution shall be obtained.

This keyword is followed by a string. The following values are allowed:

Example

@PredictionPolicy 'ElasticPrediction';

Note

The ElasticPredictionFromMaterialProperties policy is only supported by the umat interface as the Cast3M finite element solver requires the stiffness matrix to be defined.

The @Print keyword

The @Print keyword is an alias to the @Message keyword.

Example:

@Print "12*5";

The @PrintLagrangeMultipliers keyword

The @PrintLagrangeMultipliers is followed by a boolean indicating if the Lagrange multipliers of the various constraints (see the @NonLinearConstraint for instance) shall be printed in the output file.

Example

@PrintLagrangeMultipliers true;

The @Real keyword

The @Real keyword let the user define a constant.

This keyword is followed by the name of the constant, as a string and by the value of the constant.

Example

@Real 'SXX0' 20.6;

The @ResidualFile keyword

The @ResidualFile let the user specify the name of a file where the residuals at each iteration will be printed.

Example

@ResidualFile 'residual.res';

The @ResidualFilePrecision keyword

The @ResidualFilePrecision let the user specify the number of significant digits used when printing residuals at each iteration.

This keyword is followed by the number of digits wanted.

Note

By default, the precision used for printing the residuals are the same than the one used for printing results (see the @OutputFilePrecision for details).

Example

@ResidualFilePrecision 14;

The @RotationMatrix keyword

The @RotationMatrix let the user specify a rotation matrix, so that the principal directions of the material are different from those used for the resolution and the boundary conditions.

The columns of the rotation matrix \(R\) are the material axes expressed in the global frame: the components of a symmetric tensor \(\underline{s}\) in the material frame are given by \(R^{T}\,.\,\underline{s}\,.\,R\).

This keywords accepts an option (given between left and right angles) named respectively Standard (default), Direction, Euler and Miller. Each option corresponds to a way of defining the rotation matrix:

Special case for the Abaqus/Standard and Abaqus/Explicit interface

The Abaqus/Standard and Abaqus/Explicit interfaces introduce the notion of othrothropy management policy (see the documentation of thoses interfaces). In particular, if the behaviour uses the MFront orthotropic management policy, the material orientation has to be given in the first internal state variables. Those internal state variables are not accessible by the end user.

MTest handles this specific case and extracts the appropriate information from the rotation matrix given with the @RotationMatrix keywords and copy them to the first internal state variables automatically.

Example

// standard way (rotate vectors by an angle θ about the z-axis)
@RotationMatrix {{cos,-sin, 0},
                 {sin, cos, 0},
                 { 0 ,  0 , 1}};
// using direction in 2D
@RotationMatrix<Direction> {0,1};
// using directions in 3D (rotate vectors by an angle θ about the z-axis)
@RotationMatrix<Direction> {{cos,sin,0},{-sin,cos,0}};
// using miller indices
@RotationMatrix<Miller> {1,5,9};

The @StateVariable keyword

The @StateVariable keyword is a synonym of @InternalStateVariable, which defines the initial value of a state variable. See @InternalStateVariable for details.

The @StiffnessMatrixType keyword

The @StiffnessMatrixType keyword let the user specify choose type of stiffness matrix that shall be given by the mechanical behaviour and that will be used by the resolution algorithm.

This keyword is followed by a string. The following values are allowed:

Example

@StiffnessMatrixType 'Elastic';

The @StiffnessUpdatePolicy keyword

This keyword is not yet implemented.

The @Strain keyword

The @Strain let the user specify the initial value of the strains.

This keyword is followed by an array. The size of this array must be equal to the number of components of symmetric tensors for the modelling hypothesis considered (see the @ModellingHypothesis keyword).

Note

The values must follow the TFEL conventions. In \(3D\), strains are stored in the following order: \[ \left( varepsilon_{xx},\varepsilon_{yy},\varepsilon_{zz},\sqrt{2}\,\varepsilon_{xy},\sqrt{2}\,\varepsilon_{xz},\sqrt{2}\,\varepsilon_{yz} \right) \]

Example

@Strain {0.000239466253465591,
         -7.18398760396772e-05,
         -7.18398760396772e-05,
         0.,0.,0.};

The @StrainEpsilon keyword

The global algorithm uses two criteria to check if a satisfying equilibrium has been found: one on strains, the other on stresses.

This criterion on strains checks if two successive estimate of the strains are close enough. By default, the criterion value used is 1.e-12;

The @StrainEpsilon let the user specify the criterion value used for the criterion on strains.

It is followed by the criterion value.

Example

@StrainEpsilon 1.e-12;

The @Stress keyword

The @Stress let the user specify the initial value of the stresses.

This keyword is followed by an array. The size of this array must be equal to the number of components of symmetric tensors for the modelling hypothesis considered (see the @ModellingHypothesis keyword).

Example

@Stress {'YoungModulus*EXX0',
         '-PoissonRatio*YoungModulus*EXX0',
         '-PoissonRatio*YoungModulus*EXX0',
         0.,0.,0.};

The @StressEpsilon keyword

The global algorithm uses two criteria to check if a satisfying equilibrium has been found: one on strains, the other on stresses.

This criterion on stresses checks that the residual of the Newton Algorithm is low enough. By default, this value is equal to 1.e-3, which is a convenient value if stresses are expressed in Pa.

The @StressEpsilon keyword let the user specify the criterion value used for the criterion on stresses.

It is followed by the criterion value.

Example

@StressEpsilon 1.e2;

The @TangentOperatorComparisonCriterion keyword

The @TangentOperatorComparisonCriterion keyword sets the criterion value used to compare the tangent operator given by the behaviour to its numerical approximation (see @CompareToNumericalTangentOperator). This keyword is followed by a positive value.

The @TangentOperatorComparisonCriterium keyword

The @TangentOperatorComparisonCriterium keyword is a synonym of @TangentOperatorComparisonCriterion.

The @Test keyword

The @Test keyword allows the user to add a test on the results. Two types of tests are supported, function or file. The tests are executed at the end of each time step.

This keyword is followed by the type of the test.

If the type of the test is function, two syntaxes are allowed. In the first one, three arguments are expected: the name of the tested variable, a function of time given the expected value, a criterion value used for the comparison. In the second syntax, two arguments are expected: a map which associates the name of a tested variable to a function of time given the expected value of this variable and a criterion value used for the comparison. The functions may explicitly depend on time through the variable t.

If the type of the test is file, the expected values are read in the columns of a text file. The name of the text file shall be given and then two syntaxes are allowed. In the first one, three arguments are expected: the name of the tested variable, a column number and a criterion value used for the comparison. In the second syntax, two arguments are expected: a map which associates the name of a tested variable to a column number and a criterion value used for the comparison. In each case, the values given by the n+1 line shall correspond to the values expected after the n period.

The comparisons are made using an absolute criterion. The names of the components of the strains begins with E. The name of the components of the stresses begins with S. The name of the components of symmetric tensor internal state variables begins with the name of the internal state variables. The name of the components of symmetric tensors are obtained by suffixing their name according to the modelling hypothesis used (see the @ModellingHypothesis keyword). For example, the components of the strains are:

Off-diagonals terms are affected by a factor \(\sqrt(2)\).

Example (function)

@Test<function> 'EXY' '0.' 1.e-12;

Example (function)

@Test<function> {'EXX':'SXX/YoungModulus',
                 'EYY':'-PoissonRatio*SXX/YoungModulus',
                 'EZZ':'-PoissonRatio*SXX/YoungModulus',
                 'EXY':'0.','EXZ':'0.','EYZ':'0.'} 1.e-12;

Example (file)

@Test<file> 'reference.txt' 'EXY' 1 1.e-12;

The @ThermodynamicForce keyword

The @ThermodynamicForce keyword specifies the initial values of the thermodynamic forces of the behaviour.

This keyword is followed by an array. The size of this array must be equal to the total size of the thermodynamic forces of the behaviour for the modelling hypothesis considered (see the @ModellingHypothesis keyword).

This keyword can be used with any behaviour. The @Stress and @CohesiveForce keywords are the specialised versions of this keyword for small and finite strain behaviours and for cohesive zone models respectively.

Example

@ThermodynamicForce {1.e6};

The @ThermodynamicForceEpsilon keyword

The global algorithm uses two criteria to check if a satisfying equilibrium has been found: one on the gradients, the other on the thermodynamic forces.

The criterion on the thermodynamic forces checks that the residual of the Newton algorithm is low enough. By default, the criterion value used is 1.e-3.

The @ThermodynamicForceEpsilon keyword specifies the criterion value used for the criterion on the thermodynamic forces. It is followed by the criterion value.

The @StressEpsilon and @CohesiveForceEpsilon keywords are the specialised versions of this keyword for small and finite strain behaviours and for cohesive zone models respectively.

Example

@ThermodynamicForceEpsilon 1.e-3;

The @Times keyword

The @Times keywords let the user specify a list of times used for the computations.

There are currently two ways of specifying this list of times:

The first one is selected by the array option. The second one is selected by one of the equivalent options data or file. This option is given between ‘<’ and ‘>’ brackets.

array option

In this case, one expects an array describing intervals of times. By default, one time step is used to go from a given time to the next one. The keyword ‘in’ allows the user to divide an interval into a given number of smaller intervals.

data or file option

In this case, one expects a file name followed by the keyword using. The user may then either specify a column number or a formula as a string. If a formula is given, one may use any constant or function defined in the input file, such a the ones defined by the @Real keyword. A variable prefixed by $ followed by a positive integer holds for the value of a column.

Note

The loadings and the external state variables evolutions are described in a totally independent manner (see the @ImposedStrain, the @ImposedStress and the @ExternalStateVariable keywords).

Note

In case of non convergence, the algorithm handles time sub stepping. See the @MaximumNumberOfSubSteps for details.

Example

@Times {0.,3600.};         // 1  time step of  3600. seconds

Example

@Times {0.,3600. in 10};   // 10 time steps of 360   seconds

Example

@Times<array> {0.,3600. in 10};   // 10 time steps of 360   seconds

Example

 // read from file and convert the values read from hours to seconds
@Times<file> 'data.txt' using '$1*3600';

#Example

 // read from file and convert the values read from hours to seconds
@Times<data> 'data.txt' using '$1*3600';

The @UnsignedIntegerParameter keyword

The @UnsignedIntegerParameter keyword specifies the value of a parameter of the behaviour.

Example

@UnsignedIntegerParameter 'iterMax' 12;

The @UseCastemAccelerationAlgorithm keyword

The @UseCastemAccelerationAlgorithm specifies if the acceleration algorithm introduced by the resolution procedures of the castem finite element shall be used.

This keyword is followed by true or false.

Example

@UseCastemAccelerationAlgorithm true;

The @UserDefinedPostProcessing keyword

The @UserDefinedPostProcessing lets the user define its own post-processings.

This keywords is followed by:

Example

@UserDefinedPostProcessing 'test.txt' '(SXX+SYY+SZZ)/3';
@UserDefinedPostProcessing 'myoutput.txt' {'SXX','EquivalentPlasticStrain'};

The @XMLOutputFile keyword

The @XMLOutputFile keyword specifies the name of the file in which the results of the tests are written in the XML format. This file is only written if the --xml-output command line option is given. The --xml-output-file command line option overrides this keyword. By default, the name of this file is the name of the input file, minus its extension, plus .xml.

Example

@XMLOutputFile 'results.xml';