Function materials describe a family of MOOSE material classes that are derived from the FunctionMaterialBase base class. A function material provides a Real material property that hold the value of an arbitrary function expression. A derivative function material in addition provides further material properties that hold the value of the derivatives of the function expression with respect to each coupled variable up to a defined derivative_order.

Available function materials are

Material Description
ParsedMaterial Sets up a single material property that is computed using a parsed function expression
DerivativeParsedMaterial Extends ParsedMaterial and provides the automatically generated derivatives of the function expression w.r.t. all coupled variables.
DerivativeSumMaterial Create new material properties that contain the sum of multiple function material properties (including the sums of the derivatives)
ElasticEnergyMaterial Generates an elastic free energy function material from the current stress/strain state including necessary derivatives
SwitchingFunctionMaterial A convenience material to generate a soft switching function used in multiphase modeling
BarrierFunctionMaterial A convenience material to generate a barrier function used in multiphase modeling
MathFreeEnergy A simple double-well free energy $$$F = \frac14(1 + c)^2(1 - c)^2$$$ (and its concentration derivatives)



A ParsedMaterial object takes the function expression as an input parameter in the form of a Function Parser expression. Parsed materials (unlike ParsedFunctions) can couple to non-linear variables and material properties. In its configuration block all non-linear variables the free energy depends on (args), as well as constants (constant_names and constant_expressions) and other material properties (material_property_names) are declared. Constants can be declared as parsed expressions (which can depend on previously defined constants). One application would be the definition of a temperature $$$T$$$, the Boltzmann constant $$$k_B$$$, a defect formation energy $$$E_F$$$, and then an equilibrium defect concentration defined using a Boltzmann factor $$$exp(-\frac{E_d}{k_BT})$$$.

  # This parsed material creates a single property for visualization purposes.
  # It will be 0 for phase 1, -1 for phase 2, and 1 for phase 3
    type = ParsedMaterial
    block = 0
    f_name = phase
    args = 'eta2 eta3'
    function = 'if(eta3>0.5,1,0)-if(eta2>0.5,1,0)'
    outputs = exodus



This material class does everything the ParsedMaterial does, plus automatic symbolic differentiation of the function expression. The function material property derivatives follow a naming scheme defined in DerivativeMaterialPropertyNameInterface. The maximum order of derivatives generated is set using the derivative_order parameter.

    type = DerivativeParsedMaterial
    block = 0

    # name of the free energy function (and base name for the generated material properties)
    f_name = F

    # vector of non-linear variable names used in the function expression
    args = 'cv'

    # Either define constants here...
    #constant_names  = 'barr_height  cv_eq'
    #constant_expressions = '0.1         1.0e-2'

    # ...or use material properties declared here.
    material_property_names = 'barr_height cv_eq'

    # Equivalent to CHPoly with order=4
    function = 16*barr_height*(cv-cv_eq)^2*(1-cv_eq-cv)^2

    derivative_order = 2

Only required derivatives will be evaluated (e.g. the split operator kernel does not require third order derivatives. Second-order derivatives are only required for the Jacobian, as discussed here).

Non linear and auxiliary variables declared in the args parameter, constants declared in constant_names and constant_expressions and material properties declared in material_property_names may be used in the parsed function expression. Note that the constants can be defined using parsed expressions as long as these expressions only use numbers and/or constants already defined to the left of the current constant, line in this example:

    constant_names       = 'T    kB         E'
    constant_expressions = '300  8.6173e-5  T*kB'

where E can be defined in terms of T and kB, as those constants are to the left of E.

If a material property M is listed in material_property_names a special syntax (M(c1,c2) where c1 and c2 are variables) can be used to declare variable dependences as well as selecting derivatives of material properties (for example, d2M:=D[M(c1,c2),c2,c2] would make the second derivative of M with respect to c2 available as d2M in the parsed function expression). If variable dependencies are declared, the necessary derivatives of the coupled material properties will be automatically pulled in when constructing the derivatives of the parsed function.

In phase field, an application would be the definition of a mobility term $$$$M = \frac D{\frac{\partial^2 F}{\partial c^2}}$$$$ containing the second derivative of a free energy F as

    type = DerivativeParsedMaterial
    args = c
    f_name = M
    material_property_names = 'd2F:=D[F(c),c,c]'
    constant_names = D
    constant_expressions = 1e-3
    function = D/d2F

The mobility M defined above would have accurately constructed automatic derivatives w.r.t. c, which contain third and higher derivatives of F (make sure to set the derivative_order of F high enough!).

The material_property_names are parsed by the FunctionMaterialPropertyDescriptor class, which understands the following syntax:

Expression Description
F A material property called F with no declared variable dependencies (i.e. vanishing derivatives)
F(c,phi) A material property called F with declared dependence on 'c' and 'phi' (uses DerivativeFunctionMaterial rules to look up the derivatives) using the round-bracket-notation
d3x:=D[x(a,b),a,a,b] The third derivative $$$\frac{\partial^3x}{\partial^2a\partial b}$$$ of the a,b-dependent material property x, which will be referred to as d3x in the function expression
dF:=D[F,c] Derivative of F w.r.t. c. Although the c-dependence of F is not explicitly declared using the round-bracket-notation it is implicitly assumed as a derivative w.r.t. c is requested

Add outputs=exodus to the material block to automatically write all derivatives and the free energy to the exodus output.



This material generates new material properties that sum up the values and derivatives of a specified set of function materials. Using args argument the union of all sets of dependent variables has to be specified so that the DerivativeSumMaterial can gather the necessary derivatives to sum up.

  # material subblocks that define Fa, Fb, and Fc are omitted 

    type = DerivativeSumMaterial
    block = 0
    f_name = F
    sum_materials = 'Fa Fb Fb'
    args = 'c'
    outputs = exodus



This material generates an elastic free energy contribution consistent with the TensorMechanics stress divergence kernels. This allows for proper coupling of the phase field problem and the mechanics problem. The contribution of the ElasticEnergyMaterial and the chemical free energy (possibly defined using a DerivativeParsedMaterial) are then summed up using a DerivativeSumMaterial to form a total free energy which is passed to the phase field kernels.

  # material subblocks that define stress and elasticity tensor properties (and necessary derivatives) are omitted 

    type = ElasticEnergyMaterial
    block = 0
    args = 'c'