Development of material models

For the definition of a material model, one has to put information at a number of places. A detailed description of the methods, attributes, files, and directories where new code is needed, is given in the following. The material model shall get a generic name myNewMaterial here.

Note

The following sections are focused on the development of solid materials. Few information is also given for other material models (fluid, electrochemical, etc.), but some methods may be different. There might be separate sections for the different material classes in the future.

Input reader for the material model

The main input read is located in src/inpar/inpar_validmaterials.cpp. Here, the input for the material including all mandatory and optional parameters, is defined. Parameters that do not appear here, are not recognized. A description and default values (for optional parameters) can (and should!) be defined here as well.

Definition of the material model as an enumeration item

The main purpose of the file src/inpar/inpar_material.H is to provide the Enum list MaterialType of all material laws existing in 4C within the namespace INPAT::MAT. Thus, for each new material model, one has to add a new item in the enum list. The name of the enum item starts with m_, followed by the material name in lowercase. It may be useful to add the physics in front, e.g. m_fluid_... or m_poro_... (this is not always the case, particularly not for solid mechanics). For the example mentioned above the enum item would be

m_mynewmaterial

The material models are in general in alphabetical order, so, please, put the new material model to the correct place.

Definition of the classes needed for the new material

A new file needs to be created: /src/mat/mat_<matname>.cpp (here: mat_mynewmaterial.cpp, again all lowercase), including the corresponding header file.

All material related classes are defined in this directory, within the namespace MAT.

Definition of a material parameter class

Define the class for Material Parameters in the namespace Mat::PAR as

class MyNewMaterial : public Core::Mat::PAR::Parameter

Here we need the methods

• Constructor MyNewMaterial(Core::Mat::PAR::Parameter::Data matdata)

• Teuchos::RCP<Core::Mat::Material> CreateMaterial()

Definition of the material type class

Here the material type class is generated within the namespace MAT as

class MyNewMaterialType : public Core::COMM::ParObjectType

This class is just to define the material itself, together with its respective parameter set.

This class does not even need a constructor, but only a single private static variable:

Mat::MyNewMaterial Mat::MyNewMaterial::instance_;

and a few public methods:

Core::COMM::ParObject* Mat::MyNewMaterialType::Create(const std::vector<char>& data)
{
  Mat::MyNewMaterial* mymaterial = new Mat::MyNewMaterial();
  mymaterial->unpack(data);
  return mymaterial;
}
std::string Name() const { return "MyNewMaterial"; }

static MyNewMaterialType& instance() { return instance_; };

Definition of the material class

The main work happens in the material class in the Mat namespace, which is derived from the parent class. This can be the class Material, which is independent from the underlying physics, but there are also classes for specific physical representations the material model happen. The base classes of the material models representing a single physics environment, are given in the following table:

Physics	base class
Structure (3D solid)	Mat::So3Material
Structure (Beams)	Mat::BeamMaterialTemplated
Thermo	Mat::ThermoMaterial
Fluid	Mat::Material
Electrochemistry	Mat::ElchSingleMat
Scalar transport	Mat::Material

Note that not all existing materials use a physics-specific base class, some materials are simply derived from Mat::Material even though a more specialized class exists.

It is probably a good idea to start with a clone of the material law given in the table above, and define a new class, e.g.:

class MyNewMaterial : public So3Material

Here we definitely need a number of methods, which are called from other places, and which have already a virtual representation in the parent class, e.g., here for solid materials:

• Constructor

• UniqueParObject()

• pack()

• unpack()

• setup() // -> initialize and allocate internal variables

• update() // -> update internal variables

• evaluate() // calculate stress and constitutive matrix

• VisNames() // For the names of variables to be visualized (optional; only if extra variables are to be visualized)

• VisData() // For the data of these variables (optional; only if extra variables are to be visualized)

Selection of the material model

The selection of the material model happens in the file mat/mat_material.cpp. Based on the enum Core::Materials::MaterialType, a switch creates the material and provides the parameters. Each case within the switch condition has a very similar layout, so for our material it looks like this:

case Core::Materials::m_mynewmaterial:
{
  if (curmat->Parameter() == nullptr)
    curmat->SetParameter(new Mat::PAR::MyNewMaterial(curmat));
  auto* params = static_cast<Mat::PAR::MyNewMaterial*>(curmat->Parameter());
  return params->CreateMaterial();
}

Unit test of the material model

One should also write a unit test for the new material routine. The respective source file should be located in /unittests/mat/unit_mynewmaterial.cpp. This file must also be included in the /unittests/mat/CMakeLists.txt file.

Remark on the dimensionality of the material model

All (solid) materials are defined for 3D elements. A reduction of the matrices is not used. Instead, additional assumptions of the restrictions for plane strain and plane stress are used for the respective 2D elements. The evaluation is then conducted in 3D. Finally, the stress and stiffness matrices are stored with the reduced component number.