Creating MPM Materials

This section explains how to write C++ code create a new material class for use in NairnMPM.

Getting Started

The first steps are to create source files for the new material class, to give the material a unique name, and to allow the main NairnMPM code to instantiate the material class when it is needed for a particle.

Class Source Code

The best way to create the source code is to duplicate the NewMaterial.cpp and NewMaterial.hpp files, which are templates for a new material class. Edit the files and change NewMaterial to the new material's class name (e.g., MyMaterial). The NewMaterial template is a subclass of MaterialBase. Normally the new material will be a subclass of another class. If so, change MaterialBase references, as needed, to the actual parent class. These changes are needed whenever a method in the new material class needs to pass control to its immediate super class.

Material Class Hierarchy

The new material should be inserted into the NairnMPM material class hierarchy with its name (from previous step) and a unique ID (an integer). In the new material's header files, replace NEWMATERIAL with a defined constant representing the new material's ID (which by convention is in UPPERCASE) and replace the number in the new constant's definition with the new material's ID. For example:

#define MYMATERIAL 102

All documented materials use low numbers (starting with 1). To avoid conflicts, those working on custom materials should use large numbers (>100).

Editing Required in Core Code

Almost all coding will be done in the new material class files, but for that material to be recognized as an option in NairnMPM, two places in the core code have to be edited first. These should be the only changes needed outside the new material's class files.

1. Include the new material's header file at the top of Common/Read_XML/MaterialController.cpp:

    #include "Materials/MyMaterial.hpp"
   

   or the appropriate relative path to the new material's header file.

2. In MaterialController::AddMaterial(int matID,char *matName), add a new case in the switch(matID) section to call the default constructor of the new material when matID matches the new material's constant defined above.

   case MYMATERIAL:
      newMaterial=new MyMaterial(matName);
      break;
   

   If needed you can define a custom constructor and use that in this code (this need is very rare).

Compiling with make Command

If you want to be able to do command-line compile using the make command, the new material source files needed to add to the file NairnMPM/build/makefile. The steps are best done by comparing to a similar material's files in that makefile. The main makeFile editing stepsare:

1. Define an alias for relative path from makefile to the new material class files (in the list d)

   MyMaterial = $(src)/Materials/MyMaterial
   

2. Add an object file to the list of "all compiled objects" in the form MyMaterial.o.
3. Add the new material's header file to the header file's needed to compile MaterialController.hpp. Using the alias defined in step 1, the added text will be $(MyMaterial).hpp.
4. Compile the new material's source file with lines such as

   MyMaterial.o : $(MyMaterial).cpp $(dprefix) $(MyMaterial).hpp $(MaterialBase).hpp $(MPMBase).hpp \
   			$(CommonException).hpp
   	$(CC) $(CFLAGS) $(headers) -include $(prefix) $(MyMaterial).cpp
   

   The list of headers must include all headers explicitly (or implicitly included in the new material's source code. The leading white space for lines 2 (and on) must use only tabs and only one tab for the final compilation line.

Writing the Material Class Source Code

The remaining steps can usually all be done by editing only the material's source code file. The requirements and optional methods are described in the following sections. This stage involves editing the template file created above and customizing the listed methods and/or deleting optional methods that are not needed.

Basic Class Accessors

These methods (required unless specified as optional) return basic facts about the material:

const char *MaterialType(void)

Return a short name to describe the material. This string is printed with material properties in the output of simulations.

int MaterialTag()

Return the constant defined above.

double WaveSpeed(bool,MPMBase *)

Return the maximum wave speed for material in mm/sec. This method is called once for each material point at start of calculation and after material properties have been defined. If the wave speed might change during the simulation, be conservative and return the maximum possible save speed. The first parameter is true for 3D calculations or false for 2D. This speed is needed to pick the time step for explicit calculations. The second parameter is pointer to a material point in case the wave speed depends on the initial particle state. This method is also used in some crack propagation methods. If the material supports crack propagation, make sure it gives good results for these uses.

double MaterialBase::CurrentWaveSpeed(bool,MPMBase *) (optiona) - Return the current wave speed, which might depend on particle state. This method is used by the AdjustTimeStep task to change time step as needed; without this method, the time step will not adjust for the material. double ShearWaveSpeed(bool) (optional) - Return the shear wave speed for the material. This method is only used by silent boundary conditions. The MaterialBase class returns WaveSpeed()/sqrt(3). You only need to override this method if you want a better value. Also note that silent boundary conditions only work for isotropic materials. double MaximumDiffusion(void) (optional) - return maximum diffusion constant in cm2/sec. This method is called once for each material at the start of the calculation and after material properties are defined. The MaterialBase class returns the appropriate result for isotropic materials. You only need to override if you need a different result. double MaximumDiffusivity(void) (optional) - return maximum thermal diffusivity in cm2/sec = k/(100 rho Cp). This method is called once for each material at the start of the calculation and after material properties are defined. The MaterialBase class returns the appropriate result for isotropic materials. You only need to override if you need a different result. double GetCurrentRelativeVolume(MPMBase *) (optional) - Return current relative volume to be used to convert tracked stress to true stress. Low strain materials track stress/initial density and they should return 1 (which is what base material class returns). Large deformation materials should be tracking specific Cauchy stress (= Kirchoff stress/initial density) and therefore should return relative volume (i.e., initial density/current density). Tensor GetStress(Tensor *sp,double pressure) (optional) - Return current stress. Most materials just return the contents of sp which is the particle stress. Materials that track pressure and deviatoric stress separately (or use some other stress tracking scheme), should reconstruct and return the full stress in this method. bool PartitionsElasticAndPlasticStrain(void) (optional) - Materials that separated elastic and plastic strain should override and return TRUE. Otherwise the strain tensor on the particle is assumed to have the total strain and plastic strain can be used for anything else (e.g., hyperelastic materials track the elastic Left-Cauchy Green strain in the particle's plastic strain). bool SupportsArtificialViscosity(void) (optional) - Materials that implement artificial viscosity must override this method to return TRUE and then implement the calculations in the constitutive law methods.