User-Defined Constitutive Models in FLAC3D

Introduction

FLAC3D includes the ability to create your own customized material behavior via user-defined constitutive models. These models are compiled using the C++ programming language into plugins that can be loaded into FLAC3D on startup. They are treated exactly like one of the program's built-in constitutive models. 

This page details the advantages of using FLAC3D to create custom material behavior, and gives a simple example of the process required.

Note that while there is no restriction on the creation of models, solving a model larger than 600 zones that uses a constitutive model plugin requires the Plugin Option.

The material here provides an overview and highlights; full reference documentation is available in the FLAC3D Help.

 
Explicit Scheme and Incremental Formulation

FLAC3D uses an explicit, incremental formulation for constitutive models.  Given the stress state at time t, and the total strain increment for a timestep, Δt, the purpose is to determine the corresponding stress increment and the new stress state at time t + Δt.  Often models calculate a perfectly elastic trial stress and then compare the results against whatever nonlinear criteria are being considered. If necessary, a correction is made to the trial stress in order to determine the actual stress state.

No stress/strain matrix is needed—the constitutive relations are used directly. Explicit schemes can follow arbitrary path-dependent behavior in stress/strain laws in almost the same computer time as path-independent laws. FLAC3D is robust in the sense that it can handle any constitutive model with no adjustment to the solution algorithm.

All models in FLAC3D operate on effective stresses only, and all stress increments in the constitutive model are corotational. The conversions to effective and corotational stress increment in the constitutive models are conducted by FLAC3D internally.

Each constitutive model instance is specific to a single zone. State variables and properties are stored separately for each zone. The properties of a constitutive model are saved automatically, but arbitrary data associated with each instance may also be saved and restored with the model.

 

Built-in Constitutive Models

FLAC3D's built-in constitutive models include 20 mechanical, nine creep, and one special hydration model. The source code used for all of these models is provided as part of the installation. This means that they are all available for use as examples of how to implement specific behavior, or to serve as a basis for alteration or extension.

 

User-Defined Model Library

Itasca’s User-Defined Constitutive Model Library (Itasca UDM Library) provides a collection of selected user-defined models (UDMs) for Itasca continuum software, including FLAC3D . The Library provides the facility for users to share and exchange custom models; UDMs available in the Library are free and unrestricted.

Please note that the UDMs are provided for your convenience, as is, and Itasca takes no responsibility for their correctness or your usage of the UDMs (see UDM Liability).

 

Creating Your Own Constitutive Model

You must have a compatible version of Microsoft Visual Studio C++ in order to create a constitutive model plugin.  Currently, FLAC3D 5.0 and the upcoming version 6.0 require compatibility with the Visual Studio 2010 runtime library.  You can either use Visual Studio 2010, or you can use Visual Studio 2015 (including the Community Edition) after also installing the files necessary for it to compile against the 2010 version runtime. Instructions and installation files for the latter are provided as part of a FLAC3D installation.

While it is not necessary that the user have an advanced knowledge of C++, a basic working knowledge is assumed.   

To get started quickly and provide a project for examination, in the material that follows we show all the steps necessary to extend the Mohr-Coulomb model with a residual cohesion that replaces the intact cohesion upon shear failure.

  • Assuming Visual Studio 2010 has already been installed, find the file “FLAC3D600VS2010Addin.msi” in the installation directory. If for Visual Studio 2015, choose file “FLAC3D600VS2015Addin.msi” instead.
  • Execute this installation file by double-clicking it. (You may need to have administrator’s rights to the machine to do this.)
  • Launch Visual Studio and select File/New/Project from the menu.
  • Select the “Visual C++” category from the “Installed Templates” section.
  • Scroll down to the right, where “Win32 Console Application” appears at the top. You should see the “FLAC3D600 Constitutive Model” option (as in the image below).

  • Assign a name to the project below. You also have the option to choose a new location in which to place the new project and solution.
  • A dialog will appear, asking you to name your new constitutive model. This will be the name of the class, and the name used to refer to the model in the code. This name can be changed later by directly editing the source. We choose the name “RCMohr”.

  • Click “Finish”, and a project is created for you. This project includes the necessary project files and two C++ source files called “modelRCMohr.h” and “modelRCMohr.cpp”, which are copied from the FLAC3D Version 6.0 built-in Mohr-Coulomb model, except that the model class and model name are “RCMohr”.

  • In the C++ header file “modelRCMohr.h”, we add a new double type member called  rcohesion_  , which stands for the new material parameter of residual cohesion, into the model class  ModelRCMohr .

  • In the C++ source file “modelRCMohr.cpp”, initialize  rcohesion_  to be zero in the construction function.

  • We add a material parameter name  cohesion-residual  in the function  getProperties():

  • We make corresponding changes in  getProperty() / setProperty() , used when properties are saved, restored, queried, or assigned.  This is done here,

     and here.

  • We add this new parameter in the copy() function.

  • At this point, it is important to understand something about how FLAC3D implements mixed-discretization in hexahedral zones. Each such zone is actually two overlays of five tetrahedra covering the hexahedron volume, called subzones. The constitutive relations are called on each tetrahedra separately. Properties and state variables are stored for the zone as a whole. Normally, state variables are assumed to be based on volume-averaged quantities over the entire zone. The constitutive model can access both the total number of subzones and which subzone is being calculated.
  • In the run() function, we use a working value s->working_[0] to store the averaged shear failure state value in the zone weighted by the subzone volumes (in the subzones, the shear failure state is assumed 1 if shear failed; 0 if not). We update the cohesion to the value of residual cohesion once the volume averaged shear failure value is greater than 0.5. Related variables need to be updated correspondingly.

  • Change the Visual Studio Compile/Build mode to be “Release” and “x64”. Build the project from the menu Build/Build Solution or press the F7 key. In the project directory, you will find a new created folder “x64Release”. A DLL file called “cmodelRCMohr006_64.dll” is created in the “x64Release” folder.
  • Copy the DLL file to “\exe64\plugins\cmodel”, which is under your FLAC3D Version 6.0 installation directory. You may need administrator privileges to copy files to this folder. You can also use the LOAD CMODEL command to load the plugin from an arbitrary location.
  • You can test the user-defined model by adding a command model configure plugin, in a data file. Below is a simple triaxial test data file (note the highlighted parts).

The graph below is the result of executing this model, showing the residual effect.