MaterialParameters.json file description

The material parameters json-file contains descriptions of several material models and their properties which can be adopted by a Kratos simulation. The user is responsible for providing a consistent set of material parameters.

By clicking on an annotation (1) the user is provided with more detailed information about a property.

Here more information about an annotation can be found.

The structural format of the MaterialParameters.json is as follows:

{
  "properties": [ //(1)!
    {
      "model_part_name": "PorousDomain.Material_1", //(2)!
      "properties_id": 1, //(3)!
      "Material": { //(4)!
        "constitutive_law": { //(5)!
          "name": "GeoLinearElasticPlaneStrain2DLaw" //(6)!
        },
        "Variables": { } //(7)!
      }
    }
  ]
}

Start of the properties list.
Name of the model part to which this material will be assigned. Type: string.
Unique ID of this material. Type: integer.
Start of the material description.
Definition of the constitutive law.
Name of the soil constitutive law. Type: string. Supported examples.
Material properties relevant for the current constitutive law. Details.

When a project needs various materials, multiple items can be added to the properties list, each having its own unique ID and possibly varying constitutive laws and/or material properties.

Supported constitutive laws

Incremental linear elastic law for plane strain models

GeoLinearElasticPlaneStrain2DLaw is an incremental linear elastic constitutive law that is to be used by plane strain models only. It does not require any additional input to the variables.

Mohr-Coulomb with tension cut-off for plane strain models

GeoMohrCoulombWithTensionCutOff2D is a Mohr-Coulomb plastic constitutive law that is to be used by plane strain models only. This model requires the following material specific input in the variables section:

{
    "GEO_COHESION": 3.0e+03, //(1)!
    "GEO_FRICTION_ANGLE": 22.5, //(2)!
    "GEO_DILATANCY_ANGLE": 0.0, //(3)!
    "GEO_TENSILE_STRENGTH": 7.24263e+03 //(4)!
}

Cohesion [Pa]. Type: float. Range: [0.0, ->).
Friction angle in degrees. Type: float. Range: [0.0, 90.0).
Dilatancy angle in degrees. Type: float. Range: [0.0, GEO_FRICTION_ANGLE].
Tension cut-off stress [Pa]. Type: float. Range: [0.0, GEO_COHESION / tan(GEO_FRICTION_ANGLE)]

User-defined soil model (UDSM) for plane strain models

SmallStrainUDSM2DPlaneStrainLaw is a user-defined material model for plane strain models only. This model requires the following material specific input in the variables section:

{
  "UDSM_NAME": "UDSM.dll", //(1)!
  "UDSM_NUMBER": 1, //(2)!
  "IS_FORTRAN_UDSM": true, //(3)!
  "UMAT_PARAMETERS": [ ] //(4)!
  "USE_HENCKY_STRAIN": false  //(5)!
}

Path to the UDSM file (.dll). For various commonly used soil models see Details. Type: string.
Material model ID in the UDSM. Type: integer.
Set to true if the UDSM file was written in FORTRAN. Type: boolean.
The UMAT parameters. Type: array of values. For various commonly used soil models see details.
Toggle to use the Hencky strain measure (natural/logarithmic strain). Type: boolean. Note: this should be used together with move_mesh_flag solver settings in ProjectParameters.json and have the same value.

UMAT parameters format

Here, the input parameters are described for some soil models that are commonly used within Deltares. See Soil Models for more background about how to obtain and use them.

abc-Isotache natural strain: `abc64.dll`

For abc-Isotache natural strain soil model, abc64.dll, the following parameters are expected:

Parameters	Description
`a`	modified natural swelling index
`b`	modified natural compression index
`c`	modified natural secondary compression constant
`t`	time = 1.0
`OCR`	overconsolidation ratio

Mohr-Coulomb model: `MohrCoulomb64.dll`

The Mohr-Coulomb model in MohrCoulomb64.dll expects the UMAT parameters to be an array with the following components:

Nr.	Description
1.	Young's modulus [Pa]
2.	Poisson's ratio [-]
3.	Cohesion [Pa]
4.	Friction angle [deg]
5.	Dilatancy angle [deg]
6.	Tension cut-off stress [Pa]
7.	Yield function selector [0: Matsuoka–Nakai Convex, 1: Mohr–Coulomb, 2: Drucker–Prager, 3: Matsuoka–Nakai]
8.	Undrained Poisson's ratio [-]

Mohr-Coulomb model: `example64.dll`

The Mohr-Coulomb model in example64.dll expects the UMAT parameters to be an array with the following components:

Nr.	Description
1.	Shear modulus [Pa]
2.	Poisson's ratio [-]
3.	Cohesion [Pa]
4.	Friction angle [deg]
5.	Dilatancy angle [deg]
6.	Tension cut-off stress [Pa]

Variables

For geomechanical materials, the "Variables" section consists of the following parts:

Drainage type
General material properties of the soil.
A description of the groundwater flow. This includes the permeability and a retention law.
K_0 procedure parameters. Only included if a horizontal stress state is initialised. K_0

Drainage types

The drainage type of your material is given by the parameter GEO_DRAINAGE_TYPE.

At present, the GeoMechanicsApplication supports two drainage types:

Fully coupled. With corresponding: "GEO_DRAINAGE_TYPE" = "FULLY_COUPLED".
When this type is selected, the simulation will solve for the displacement field as well as the pore water pressure field in a coupled manner. In other words, the displacement field affects the pore water pressure field and vice versa.
Keeping the pore water pressure field constant. With corresponding: "GEO_DRAINAGE_TYPE" = "CONSTANT_PW_FIELD"
When this type is selected, the simulation will solve for the displacement field only. The pore water pressure field is kept constant, i.e. the pore water pressure degrees of freedom remain unchanged. Only the effect of the pore water pressure field on the displacement field is taken into account for the coupling.

General material properties of the soil

{
    "YOUNG_MODULUS": 1.0E+05, //(1)!
    "POISSON_RATIO": 0.25, //(2)!
    "POROSITY": 0.45, //(3)!
    "DENSITY_SOLID": 1.83486e+03, //(4)!
    "DENSITY_WATER": 1.01937e+03, //(5)!
    "BULK_MODULUS_SOLID": 1.0e+10, //(6)!
    "BULK_MODULUS_FLUID": 2.2e+09 //(7)!

}

Young's modulus of the soil skeleton [Pa]. Type: float. Range: (0.0, ->).
Poisson's ratio of the soil skeleton [-]. Type: float. Range: (-1.0, 0.5).
Fraction of the unit volume that represents the pores. Type: float. Range: [0.0, 1.0].
Density of the grain material without the pores [kg/m^3]. Type: float. Range: (0.0, ->).
Density of the water [kg/m^3]. Type: float. Range: (0.0, ->).
Compression modulus of the grain material without pores [N/m^2]. Type: float. Range: (0.0, ->).
Compression modulus of water [N/m^2]. Type: float. Range: (0.0, ->).

Horizontal stress state initialization

For the initialization of an in-situ stress field, the \(K_0\) procedure derives the horizontal effective stresses from a field of vertical effective stresses. To distinguish between the vertical and horizontal stress fields, we need to know the direction of gravity. Furthermore, we need additional input that details how the horizontal stress field is calculated from the vertical one. This can be specified in one of several ways:

Direct input of \(K_{0}^{\mathrm{nc}}\) as described here.
Derivation of the \(K_{0}\) value from the friction angle as described here.
Direct specification of directional \(K_{0}\) values as described here.

Direct specification of \(K_0^{\mathrm{nc}}\)

{
    "K0_MAIN_DIRECTION": 1, //(1)!
    "K0_NC": 0.62 //(2)!
}

Direction of gravity. Type: integer. Allowed values: 0, 1, 2 which correspond to X, Y and Z, respectively.
\(K_{0}^{\mathrm{nc}}\): coefficient for normally consolidated soil. Type: float. Range: [0.0, ->).

Derivation of \(K_0^{\mathrm{nc}}\) from the friction angle

The \(K_0^{\mathrm{nc}}\) can be derived from the friction angle as follows:

\[K_0^{nc} = 1.0 - \sin \phi\]

{
    "K0_MAIN_DIRECTION": 1, //(1)!
    "GEO_FRICTION_ANGLE": 30.0 //(2)!
}

Direction of gravity. Type: integer. Allowed values: 0, 1, 2 which correspond to X, Y and Z, respectively.
Friction angle in degrees. Type: float. Range: [0.0, 90.0).

Direct specification of directional \(K_0\) coefficients

{
    "K0_MAIN_DIRECTION": 1, //(1)!
    "K0_VALUE_XX": 0.5, //(2)!
    "K0_VALUE_YY": 1.0, //(3)!
    "K0_VALUE_ZZ": 0.5 //(4)!
}

Direction of gravity. Type: integer. Allowed values: 0, 1, 2 which correspond to X, Y and Z, respectively.
\(K_0\) coefficient in X direction. Type: float. Range: [0.0, ->).
\(K_0\) coefficient in Y direction. Type: float. Range: [0.0, ->).
\(K_0\) coefficient in Z direction. Type: float. Range: [0.0, ->).

Permeability

The permeability describes the groundwater flow in the pores.

{
  "PERMEABILITY_XX": 7.0E-11, //(1)!
  "PERMEABILITY_YY": 7.0E-11, //(2)!
  "PERMEABILITY_XY": 0.0, //(3)!
  "PERMEABILITY_ZZ": 7.0E-11, //(4)!
  "PERMEABILITY_YZ": 0.0, //(5)!
  "PERMEABILITY_ZX": 0.0, //(6)!
  "DYNAMIC_VISCOSITY": 0.0013, //(7)!
  "PERMEABILITY_CHANGE_INVERSE_FACTOR": 0.0 //(8)!
}

Intrinsic permeability in the XX direction [m^2]. Type: float. Range: (0.0, ->).
Intrinsic permeability in the YY direction [m^2]. Type: float. Range: (0.0, ->).
Intrinsic cross permeability in the XY direction [m^2]. Type: float. Range: [0.0, ->).
Intrinsic permeability in the ZZ direction [m^2]. Relevant for three-dimensional models only. Type: float. Range: (0.0, ->).
Intrinsic cross permeability in the YZ direction [m^2]. Relevant for three-dimensional models only. Type: float. Range: [0.0, ->).
Intrinsic cross permeability in the ZX direction [m^2]. Relevant for three-dimensional models only. Type: float. Range: [0.0, ->).
Dynamic viscosity [Pa s]. Type: float. Range: (0.0, ->).
If greater than 0.0, the permeability will be updated depending on the volumetric strain. Type: float.

Retention laws

A retention law determines the pressure-dependent relative conductivity and storage capacity. The GeoMechanicsApplication supports several ways to describe this behavior by supplying one of the following strings for the setting "RETENTION_LAW":

"SaturatedLaw"
"SaturatedBelowPhreaticLevelLaw"
"VanGenuchtenLaw"

Fully saturated

For a fully saturated retention law, the relative permeability is always equal to 1.0, and the storage capacity equals 0.0. The saturation always equals the specified value.

{
    "RETENTION_LAW": "SaturatedLaw",
    "SATURATED_SATURATION": 1.0 //(1)!
}

Maximum water content in the pores. Type: float. Range: [0.0, 1.0].

Saturated below the phreatic level

Below the phreatic level, the pores are assumed to be fully saturated as for the case of a fully saturated retention law. Above the phreatic level, there remains some pore water content indicated by a residual saturation as well as a minimum relative permeability.

{
    "RETENTION_LAW": "SaturatedBelowPhreaticLevelLaw",
    "SATURATED_SATURATION": 1.0, //(1)!
    "RESIDUAL_SATURATION": 0.1, //(2)!
    "MINIMUM_RELATIVE_PERMEABILITY": 1.0E-04 //(3)!
}

Maximum water content in the pores. Type: float. Range: [RESIDUAL_SATURATION, 1.0].
Minimum water content in the pores. Type: float. Range: [0.0, SATURATED_SATURATION].
Minimum relative permeability. Type: float. Range: [0.0, 1.0].

Retention law according to Van Genuchten

This retention law adopts the formulation proposed by Van Genuchten.

{
    "RETENTION_LAW": "VanGenuchtenLaw",
    "SATURATED_SATURATION": 1.0, //(1)!
    "RESIDUAL_SATURATION": 0.1, //(2)!
    "MINIMUM_RELATIVE_PERMEABILITY": 1.0E-04, //(3)!
    "VAN_GENUCHTEN_AIR_ENTRY_PRESSURE": 2.561, //(4)!
    "VAN_GENUCHTEN_GN": 1.377, //(5)!
    "VAN_GENUCHTEN_GL": 1.25 //(6)!
}

Maximum water content in the pores. Type: float. Range: [RESIDUAL_SATURATION, 1.0].
Minimum water content in the pores. Type: float. Range: [0.0, SATURATED_SATURATION].
Minimum relative permeability. Type: float. Range: [0.0, 1.0].
Air entry pressure [Pa]. Type: float. Range: (0.0, ->).
Parameter GN. Type: float. Range: (0.0, ->).
Parameter GL. Type: float. Range: (0.0, ->).