Difference between revisions of "Creating a Custom Imperfect Interface Law"

From OSUPDOCS
Jump to navigation Jump to search
Line 89: Line 89:
; <tt>const char *MaterialType(void)</tt>
; <tt>const char *MaterialType(void)</tt>
: Return a short name to describe the imperfect interface law. This string is printed with contact law properties in the output of simulations.
: Return a short name to describe the imperfect interface law. This string is printed with contact law properties in the output of simulations.


== MPM Step Calculations ==
== MPM Step Calculations ==
Line 95: Line 94:
The remaining source code is to use the law in MPM calculations. Much of the work is done in the parent <tt>NonlinearInterface</tt> class. Your custom subclass only needs to return details about the contact law it self. The current implementation assumes a decoupled law that the normal and tangential forces are given by:
The remaining source code is to use the law in MPM calculations. Much of the work is done in the parent <tt>NonlinearInterface</tt> class. Your custom subclass only needs to return details about the contact law it self. The current implementation assumes a decoupled law that the normal and tangential forces are given by:


=== Check for Stability ===
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<math>T_n = f_n([u_n]) \qquad {\rm and } \qquad T_t = f_t([u_t])</math>


These methods are called prior to constitutive law methods to allow update of material properties when those material properties depend on the current state of the particle (e.g., properties that depend on temperature, moisture, orientation, or current particle's stress or stain) and to support parallel code for strain updates.
or where normal traction <math>T_n</math> is a function only of normal interfacial discontinuity <math>[u_n]</math> and tangential traction <math>T_t</math> is a function only of tangential interfacial discontinuity <math>[u_t]</math>. This limitation may change in the future. As a result, each method defined below has two version - one for normal tractions and one for tangential tractions.


Need to explain particle-dependent variables
=== Check for Stability ===


; <tt>int SizeOfMechanicalProperties(int &altBufferSize) const</tt>
; <tt>int CheckDnStability(double d,double m,double delta) const</tt><br><tt>int CheckDtStability(double d,double m,double delta) const</tt>
: The size
: The size


; <tt>void *GetCopyOfMechanicalProps(MPMBase *mptr,int np,void *matBuffer,void *altBuffer) const</tt>
=== Interface Law Properties ===
: This method is called just before the constitutive law on each time step. You can set any parameters for the material that depend on the current state of the particle. Things that never change (''i.e.'', properties that are independent of particle state) should be calculated in <tt>VerifyAndLoadProperties()<tt> instead. Some materials also used in FEA make use of <tt>LoadMechProps()</tt> in this task, but that method is limited to 2D because it only inputs a single rotation about the z axis.
 
; <tt>void GetTransportProps(MPMBase *,int,TransportProperties *)</tt> const (optional)
: This method is called when looping over material points to store parameters needed in transport calculations (''i.e.'', diffusion and conductivity tensors). It is called prior to the transport task to <tt>AddForces()</tt>. It is only needed for anistropic materials or for materials whose transport properties change depending on particle state. This method should load the required values into <tt>diffusionTensor</tt> and <tt>kCondTensor</tt> variables. It is automatically handled for subclasses of <tt>TRANSISO1(2)</tt> if the only effect is the current orientation. Transport properties that never change (''i.e.'', independent of particle state) should be calculated in <tt>FillTransportProperties()</tt> instead.
 
; <tt>double GetHeatCapacity(MPMBase *)</tt> (optional)
: Return current constant-strain heat capacity in the material (and code should always call this method when heat capacity is needed rather then directly using the heat capacity variable). This call allows materials to implement a state-dependent heat capacity. Return current heat capacity [[ConsistentUnits Command#Legacy and Consistent Units|heat capacity units]]  or in of nJ/(g-K) of using Legacy units. This method can be omitted if heat capacity is a constant.
 
; <tt>double GetCpMinusCv(MPMBase *mptr)</tt> (optional)
: Return the difference between constant-stress ( C<sub>p</sub>) and constant-strain ( C<sub>v</sub>) heat capacities (and code should always call this method when heat capacity is needed rather then directly using the heat capacity variable). Return the difference in[[ConsistentUnits Command#Legacy and Consistent Units|heat capacity units]]  or in of nJ/(g-K) of using Legacy units. This call is only used by conduction calculations because heat flow is based on C<sub>p</sub> instead of on C<sub>v</sub>. For an elastic material, this difference is given by -'''M'''.'''&alpha;'''T/&rho;, where '''M''' is stress-temperature tensor and '''&alpha;''' is thermal expansion tensor. For an isotropic material, this reduces to 3K&alpha;<sup>2</sup>T/&rho; where K is bulk modulus and &alpha; is linear thermal expansion coefficient. For an ideal gas, it reduces to nR/&rho;. If this method is omitted, the difference defaults to zero (which is often close enough for most solid materials).
 
=== Constitutive Law Methods ===


Once the properties are set (from previous section), the most important method is the one that implements the constitutive law:
; <tt>double GetFn(double delta,double area) const</tt><br><tt>double GetFt(double delta,double area) const</tt>
: Get force


; <tt>void MPMConstitutiveLaw(MPMBase *mptr,Matrix3 du,double delTime,int np)</tt>
; <tt>double GetFnPrime(double delta,double area) const</tt><br><tt>double GetFtPrime(double delta,double area) const</tt>
: This method applies constitutive law for the material and updates all needed particle properties. The required updates include stress (should be a specific stress), strain, plastic strain, rotational strain, work energy, residual energy, plastic energy, heat energy and any history dependent variables defined for the material. To support thermal and solvent expansion, include their effect on the constitutive law. The input '''<tt>du</tt>''' is the velocity gradient times the time step, which gives displacement gradient for this time step. See note below on particle temperature updates.
: Get derivative


The update should never change particle temperature, because that would invalidate some thermodynamics calculations in [[NairnMPM]]. To cause a particle temperature change, call <tt>IncrementHeatEnergy()</tt> with a temperature or energy increment. The code will take care of translating this result into particle temperature rise when appropriate. The particle temperature will rise during adiabatic calculations. For isothermal calculations, the temperature will not rise, but the corresponding energy that was released will be reflected in heat energy. See [[Thermal Calculations#Thermodynamics Modes in MPM|thermodynamics modes]] for more details.
; <tt>double GetFnEnergy(double dun,double trn) const</tt><br><tt>double GetFtPrime(double dun,double trn) const</tt>
: Get derivative

Revision as of 10:31, 14 April 2018

This section explains how to write C++ code create a custom imperfect interface for use in NairnMPM along with available imperfect interface contact laws..

Getting Started

The first steps are to create source files for the new interface law class, to give the law a unique name, and to allow the main NairnMPM code to instantiate the contact law to be used on cracks or in multimaterial mode.

Class Source Code

Custom imperfect interface should start by duplicating NonlinearInterface.cpp and NonlinearInterface.hpp files (or the files for one of its subclasses). All custom lows should inherit from the NonlinearInterface class. The new contact law will be used along with other Contact Laws and therefore will need a unique name and ID (an integer). In the new contact law's header file, replace NONLINEARINTERFACELAW copies above with a defined constant representing the new contact law's ID (which by convention is in UPPERCASE) and replace the number in the new constant's definition with the new ID. For example:

#define MYINTERFACE 201

All documented materials use numbers below 100. 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 contact law class files, but for that law 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 contact law's class files.

  1. Include the new contact law's header file at the top of Common/Read_XML/MaterialController.cpp:
     #include "Materials/MyInterface.hpp"
    

    or the appropriate relative path to the new contact law'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 contact law when matID matches the new contact law's constant defined above.
    case MYINTERFACE:
       newMaterial = new MyInterface(matName,matID);
       break;
    

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

Compiling with make Command

If you want to be able to do command-line compile using the make command, the new contact law source files need to be added to the file NairnMPM/build/makefile. The steps are best done by comparing to the NonlinearInterface entries in that makefile. The main makeFile editing steps are:

  1. Define an alias for relative path from makefile to the new material class files (in the list d)
    MyMaterial = $(src)/Materials/MyInterface
    
  2. Add an object file to the list of "all compiled objects" in the form Myintefacel.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 $(MyInterfacel).hpp.
  4. Compile the new contact law's source file with lines such as
    MyInterfacl.o : $(MyInterface).cpp $(dprefix) $(MyInterface).hpp $(MaterialBase).hpp $(MPMBase).hpp \
    			$(CommonException).hpp
    	$(CC) $(CFLAGS) $(headers) -include $(prefix) $(MyInterface).cpp
    

    The list of headers must include all headers explicitly (or implicitly) included in the new contact law'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 Contact Law Class Source Code

The remaining steps can usually all be done by editing only the contact law's source code file. The requirements and optional methods are described in the following sections. This stage usually starts by keeping by deleting all methods in the copied file that are not listed below and then changing the class name in each definition (e.g., change NonlinearInterface:: to MyInterface:: in each method). Any methods deleted from the cpp file should have its template deleted from the hpp file as well.

Creating Material Properties

Usually a newly-created contact law will have additional material properties than the parent law's (although reuse parent law properties when possible). To create such properties, you need to define them, allow them in input command files (i.e., update the DTD file), set them in the contact law's class file, and use them in calculations. The following steps are needed:

  1. Define a class variable for the property in the .hpp file (usually int or double). It is best to define these properties in the protected section of the class, although public properties are sometimes needed (and are allowed).
  2. To allow the property in input files, select a unique property name (the name may or may not be same as variable in previous step). Define that property by name in the DTD file, usually as a simple XML element such as:
    <!ELEMENT prop (#PCDATA)>
    

    where prop is the new property name.

  3. Add that property's name to the list of allowed elements within the Material element definition (beginning in <!ELEMENT Material in the DTD file.
  4. Set some default value for the new property variable in the new material's constructor method.

One properties are signed, they are initialized and printed with the following methods:

Required Initialization Methods

MyInterface::MyInterface(char *matName,int matID) : NonlinearInterface(matName,matID)
This method is the default constructor. It can initialize any custom interface properties to default values. It should als call constructor for the parent contact law class. If no defaults are needed, this method can be omitted. The MyInterface::: is the custom class name. This term is omitted from subsequent methods names (but is needed).
char * InputContactProperty(char *xName,int &input,double &gScaling)
If xName string matches a property name for this material, set input to DOUBLE_NUM or INT_NUM (depending on the type of variable) and return a pointer to the class variable for that property. If gScaling is set, the input value will be multiplied by gScaling after it is read. If xName is not a recognized property return NonlinearInterface::InputMat(xName,input) to allow the super class to look for their valid property types (replace <tt NonlinearInterface with different name if you subclassed some other contact law).
void PrintContactLaw(void) const
This method should print all properties or call a super class and then print just the new law properties. Use a style similar to other contact laws. To help in formatting, you can use the MaterialBase class method PrintProperty(label,prop,units) to print a label, a property numeric value, and units within one column. You can use several calls in sequence to get several properties on the same line. You can also call PrintProperty(text,right) to print text in a column and right or left justified if right is true or false.

Required Accessors

const char *MaterialType(void)
Return a short name to describe the imperfect interface law. This string is printed with contact law properties in the output of simulations.

MPM Step Calculations

The remaining source code is to use the law in MPM calculations. Much of the work is done in the parent NonlinearInterface class. Your custom subclass only needs to return details about the contact law it self. The current implementation assumes a decoupled law that the normal and tangential forces are given by:

      [math]\displaystyle{ T_n = f_n([u_n]) \qquad {\rm and } \qquad T_t = f_t([u_t]) }[/math]

or where normal traction [math]\displaystyle{ T_n }[/math] is a function only of normal interfacial discontinuity [math]\displaystyle{ [u_n] }[/math] and tangential traction [math]\displaystyle{ T_t }[/math] is a function only of tangential interfacial discontinuity [math]\displaystyle{ [u_t] }[/math]. This limitation may change in the future. As a result, each method defined below has two version - one for normal tractions and one for tangential tractions.

Check for Stability

int CheckDnStability(double d,double m,double delta) const
int CheckDtStability(double d,double m,double delta) const
The size

Interface Law Properties

double GetFn(double delta,double area) const
double GetFt(double delta,double area) const
Get force
double GetFnPrime(double delta,double area) const
double GetFtPrime(double delta,double area) const
Get derivative
double GetFnEnergy(double dun,double trn) const
double GetFtPrime(double dun,double trn) const
Get derivative