Symbolic MPM records

The symbolic mpm module lets a problem be defined by writing its weak form in terms of variables, terms and integrals. The counts of these records are declared by nvariables, nterms and nintegrals in the analysis record, and the records themselves follow the export module records; see Analysis record and Stationary symbolic MPM problem.

The three record kinds build on one another:

  • a Variable is an unknown field, or the test (weighting) function of one;

  • a Term is an integrand, written in terms of a variable and a test variable;

  • an Integral integrates one term over a set of elements.

Variable records

Describes a variable, that is a field appearing in the weak form.

Record syntax

Variable name (s) interpolation (s) type (et) quantity (et) size (in) dofs (ia) [dualto (s)]

Parameters

name (s)

Name of the variable. Terms refer to variables by this name.

interpolation (s)

Interpolation of the variable. The supported values are:

feiconst

Constant interpolation.

feilin

Linear interpolation.

feiquad

Quadratic interpolation.

fei1dlin_x, fei1dlin_y, fei1dlin_z

Linear interpolation on a 1D cell aligned with the given global axis.

type (et)

Rank of the variable: scalar (0) or vector (1). Either the name or the number may be written.

quantity (et)

What the variable physically is, as a FieldType value. Either the name or the number may be written, and the FT_ prefix may be dropped — so quantity "Temperature" and quantity 5 are the same thing. The values are defined in src/core/field.h:

Value

Name

Meaning

0

FT_Unknown

Unspecified

1

FT_Velocity

Velocity field

2

FT_Displacements

Displacement field

3

FT_VelocityPressure

Combined velocity and pressure field

4

FT_Pressure

Pressure field

5

FT_Temperature

Temperature field

6

FT_HumidityConcentration

Humidity or concentration field

7

FT_TransportProblemUnknowns

Generic transport problem unknowns

8

FT_TemperatureAmbient

Ambient temperature

9

FT_EigenStrain

Eigenstrain field

10

FT_VOF

Volume of fluid

11

FT_Pressure2

Pressure of the second phase

12

FT_Concentration1

Mass concentration of the first constituent

13

FT_Concentration2

Mass concentration of the second constituent
size (in)

Size, that is the dimension, of the variable.

dofs (ia)

Physical meaning of the variable’s DOFs, as DofIDItem values; see the table under Dof manager records. The size of the array should equal size.

[dualto (s)]

Name of the unknown field that this variable is the test (weighting) function of. This is the only thing that distinguishes an unknown from its weighting function: the two are declared as two Variable records that differ by name, and they may even carry different interpolations, which is what a non-symmetric Petrov-Galerkin formulation looks like.

Declaring it matters because assembly has to read the nodal unknowns through the unknown field’s interpolation rather than through its weighting function’s.

Example

Variable name "u" interpolation "feilin" type 1 quantity "Temperature" \
    size 1 dofs 1 10
Variable name "w" interpolation "feilin" type 1 quantity "Temperature" \
    size 1 dofs 1 10 dualto "u"

Here u is the temperature unknown and w its test function. See tests/regression/mpm/mpms06.in for a complete input file.

Term records

A term is what an integral in the weak form integrates.

Record syntax common to all terms

TermType num (in) variable (s) testvariable (s) mmode (et)

Parameters

variable (s)

Name of the unknown variable (field) of the term.

testvariable (s)

Name of the test variable (field) of the term.

mmode (et)

Material mode used to evaluate the term, as a MaterialMode value; see src/core/materialmode.h.

Individual term types may introduce further parameters of their own.

Notation

Symbol

Meaning

\(q\), \(p\)

Scalar valued functions

\(\mathbf{w}\), \(\mathbf{u}\)

Vector valued functions

Supported term types

BTSigmaTerm

\(\int_\Omega \nabla^s \mathbf{w}\ \mathbf{\sigma}(\nabla^s \mathbf{u})\), where \(\mathbf{\sigma}\) is the (nonlinear) operator evaluated by the constitutive model.

Supported material modes: _3dMat, _3dUP, _2dUP, _PlaneStress.

Optional parameter: [lhsmatmode (in)].

BTamNTerm

\(\int_\Omega \nabla^s \mathbf{w}\ a\mathbf{m}\ p\), where a is a material parameter defined by the constitutive model whose meaning is fixed by the atype parameter, and \(\mathbf{m}^T=[1,1,1,0,0,0]^T\).

Note that \(\mathbf{\sigma}_{D}=\mathbf{\sigma}-\mathbf{m}p\).

NTamTBTerm

The transposed version of BTamNTerm: \(\int_\Omega w\ \alpha\mathbf{m}\ \nabla^s \mathbf{u}\).

NTcN

\(\int_\Omega q c p\), where c is a constant defined by the material model whose meaning is fixed by the ctype parameter.

NTfTerm

\(\int_\Omega \mathbf{w}\cdot\bar{\mathbf{t}}\), where \(\bar{\mathbf{t}}\) is a given flux vector supplied by the flux (ra) parameter.

SymbolicTerm

A term whose integrand is written directly in the input file, in a symbolic mathematical language that is compiled to bytecode during initialization.

It adds two mandatory string parameters: lexpression (s), the left-hand side expression evaluated to the tangent/stiffness matrix contribution, and rexpression (s), the right-hand side expression evaluated to the internal force or residual vector contribution.

The expression language — its functions Grad_s, Grad, Div, N, Sig, Sig_dev, MDer, MVec, MProp and the rest, and the full list of attributes — is documented separately in doc/symbolic_term.md.

Integral records

An integral integrates one term over a set of elements.

Record syntax

Integral num (in) domain (in) set (in) term (in)

Parameters

domain (in)

Number of the domain in which the integral is defined.

set (in)

Number of the set of elements over which the integration is performed; see Set records.

Note

Boundary integrals require the boundary elements to be present.

term (in)

Number of the term to integrate.

The integrals contributing to the left- and right-hand sides of the problem are selected by the lhsterms and rhsterms arrays of the analysis record; see Stationary symbolic MPM problem.

Note

Despite their names, lhsterms and rhsterms list integral numbers, not term numbers.