1--- 2title: Parameters in `MFront` 3author: Thomas 4date: 6/10/2014 5lang: en-EN 6link-citations: true 7colorlinks: true 8figPrefixTemplate: "$$i$$" 9tabPrefixTemplate: "$$i$$" 10secPrefixTemplate: "$$i$$" 11eqnPrefixTemplate: "($$i$$)" 12--- 13 14# Rationale 15 16Being able to modify some coefficients of a behaviour without 17recompiling is a very handy feature for the end user and is mandatory 18for parametric studies. 19 20To achieve this, most mechanical solvers have introduced material 21properties, declared with the `@MaterialProperty` keyword in `MFront`, 22which are evaluated by the calling solver and then passed to the 23behaviour. The main idea behind material properties is to write 24generic behaviours that can be used to describe a wide range of 25materials. 26 27There are a important shortcomings associated with the use of material 28properties: 29 30- For Assurance Quality reasons, we consider that the usage of generic 31 behaviours shall be avoided, mainly because part of the definition 32 of the behaviour is put in the user input file: we do think that the 33 whole description of the behaviour shall be included in the `MFront` 34 implementation. This can not be achieved with material properties 35 since their is no easy cross-solver way to define their default 36 values from the behaviour implementation. 37- The use of material properties can have significant numerical impact 38 in some finite element solver: those costs are associated to the 39 evaluation and transfer of material properties values to the 40 behaviour. 41 42Parameters, defined through the `@Parameter` keyword, are meant to be 43an alternative solution: parameters are internal coefficients that can 44be modified by the end user at (almost) no cost. **A parameter must 45have a default value** which must be considered as the reference 46value. 47 48Parameters are global values shared by all instances of the 49behaviour. Parameters are thus associated to the behaviour and not to 50a material (or model in the `Cast3M` wording). Parameters thus have a 51few shortcomings (compared to material properties). 52 53# Defining a parameter 54 55Parameters are defined with the `@Parameter` keyword. The following 56syntax are allowed: 57 58~~~~~{#parameters .cpp} 59@Parameter real dmax1 = 0.98; // initialisation by assignment syntax 60@Parameter real dmax2(0.98); // constructor syntax 61@Parameter real dmax3{0.98}; // uniform initialisation syntax 62@Parameter real dmax4; // only syntax valid for tfel < 2.0 63dmax4.setDefaultValue(0.98); 64~~~~~ 65 66A glossary name or an entry name can be associated to a parameter 67through the `setGlossaryName` or the `setEntryName` method. 68 69> **Note** 70> 71> Historically, the type of the parameter was not required and was 72> implicitly assumed to be of the `real` type. Although deprecated, 73> the following syntax is still valid: 74> 75> ~~~~~{#parameters .cpp} 76> @Parameter dmax1 = 0.98; // initialisation by assignment syntax 77> ~~~~~ 78 79# Modifying a parameter at runtime 80 81There are two ways to modify a parameter at runtime: 82 83- through the calling solver input file; 84- through an external file 85 86From our point of view, the first method is preferable but is not 87always available. Some examples are provided below. 88 89## Examples of modify the calling solver input file 90 91### `MTest` 92 93The keyword `@Parameter` is available in [`MTest`](mtest.html). 94 95### `Code-Aster` 96 97### `Zebulon` 98 99The `***parameter` section can be used to define parameters from the 100input file. 101 102## External file {#sec:mfront:parameters:parameters_file} 103 104Let us take an example of a behaviour named `Mazars` (the behaviour 105name is defined by the value given to the `@Behaviour` keyword and 106prefixed by the material name, given by `@Material` keyword (if any)). 107We suppose that this behaviour defines a parameter whose entry name is 108`DamageThreshold` (entry names are defined through the `setEntryName` 109method). 110 111If a file named `Mazars-parameters.txt` is in the current directory, 112it is automatically read at the first behaviour call. This file must 113contain lines beginning with a parameter name and its value. No 114comments are allowed. 115 116If our case, this file may contain the following line: 117 118~~~~~~~~~{#external-file .txt} 119DamageThreshold 0.95 120~~~~~~~~~ 121 122If a parameter is not defined in this file, it will have its default 123value. 124 125This functionality is illustrated below: 126 127 129 130# Querying information about parameters in `mfront-query` 131 132## List of parameters 133 134The list of parameters in an `mfront` file can be retrieved as follows: 135 136~~~~{.bash} 137$ mfront-query --parameters Rousselier.mfront 138... 139- safety_factor_for_the_upper_bound_of_the_porosity: a safety factor for the porosity upper bound 140- safety_factor_for_the_upper_bound_of_the_porosity_for_fracture_detection: a safety factor for the porosity upper bound 141- staggered_scheme_porosity_criterion: stopping criterion value of the staggered scheme 142- staggered_scheme_maximum_number_of_iterations: maximum number of iterations of the staggered scheme allowed 143- minimal_time_step_scaling_factor: minimal value for the time step scaling factor 144- maximal_time_step_scaling_factor: maximal value for the time step scaling factor 145- numerical_jacobian_epsilon: perturbation value used to compute a numerical approximation of the jacobian 146- iterMax: maximum number of iterations allowed 147~~~~ 148 149## Querying the default value of a parameter 150 151The default value of a parameter can be retrieved using the 152`--parameter-default-value` query, as follows: 153 154~~~~{.bash} 155$ mfront-query --parameter-default-value=epsilon Rousselier.mfront 1561.e-14 157$ mfront-query --parameter-default-value=iterMax Rousselier.mfront 158100 159~~~~ 160 161## Querying the type of a parameter 162 163The type of a parameter can be retrieved through the `--parameter-type` 164query, as follows: 165 166~~~~{.bash} 167$ mfront-query --parameter-type=iterMax Rousselier.mfront 168ushort 169~~~~ 170 171Here `ushort` means that the `iterMax` parameter is stored as unsigned 172short integer. 173 174## Querying the name of the parameters' file through `mfront-query` 175 176The name of the file which can be used to modify the parameters' values 177(see Section @sec:mfront:parameters:parameters_file) can be retrieved 178with the `--parameters-file` query: 179 180~~~~{.bash} 181$ mfront-query --parameters-file Rousselier.mfront 182Rousseliertest-parameters.txt 183~~~~ 184 185<!-- Local IspellDict: english --> 186
