Software Products

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 26 mechanical, nine creep, and one special hydration model. The source code used for most 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. For FLAC3D 7.0, either Visual Studio 2017 or Visual Studio 2019 can current be used. You must be able to install custom project templates.

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. The text following assumes you are using Visual Studio 2019. Note that all screenshots were taken using the “Dark” theme:

• Assuming Visual Studio 2019 has already been installed, find the file “ItascaProjectTemplates.vsix” in the PluginFiles folder of the installation directory. Execute this installation file by double-clicking it. (You may need to have administrator’s rights to the machine to do this.) Complete the installation as prompted.
• Launch Visual Studio 2019 and select “Create a new project”.

• Find the proper template by typing “itasca” into the “search for project templates” field.

• Select the “Itasca Constitutive Model” template and press “Next”.

• In the “Configure your new project” dialog, assign a project name. Here we use “RCMohr”. Then press Create.

• 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”. Then select “Accept and Close”, and a project is create 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 7.0 built-in Mohr-Coulomb model, except that the model class name is “ModelRcmohr” and the model keyword is “rcmohr”.

• First you should update the solution to use the latest version of the Windows SDK, and the latest version of the runtime libraries. These might have changed since the project template was created. Right click on the solution in the “Solution Explorer” window and select “Retarget Projects”. Use the default values and select OK.

• In the C++ header file “modelrcmohr.h”, we add a new double type member called rcohesion_ initialized to -1.0, which stands for the new material parameter of residual cohesion, into the model class ModelRcmohr. A value below zero will indicate that the residual value will be ignored.

• Next in the C++ file “modelrcmohr.cpp” 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). This is initialized to zero for the first sub zone.
  • We initialize the working value to zero for the first sub zone.
  • We check if the tet has failed in shear now or in the past, and if so add the tet volume to the working value.
  • On the last sub zone, we check to see if at least half of the volume-averaged tets have failed in shear, and if so we move from the origin to the residual cohesion value.

• Change the Visual Studio Compile/Build mode to be “Release” and “x64”. Build the project from the menu Build/Build Solution or press the Ctrl-Shift-B key. In the project directory, you will find a new created folder “Release”. A DLL file called “cmodelrcmohr007.dll” is created in the “Release” folder.

• Copy the DLL file to “\exe64\plugins\cmodel”, which is under your FLAC3D Version 7.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 outlined parts).

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