Writing New Constitutive Models

Introduction

Users may create their own constitutive model for use in FLAC3D (by default, applicable to FLAC2D as well). The model must be written in C++ and compiled as a DLL file (dynamic link library), and can be loaded whenever needed. The main function of the model is to return new stresses, given strain increments. However, the model must also provide other information (such as name of the model and material property names) and describe certain details about how the model interacts with the code.

In the C++ language, the emphasis is on an object-oriented approach to program structure, using classes to represent objects. The data associated with an object are encapsulated by the object and are invisible outside of the object. Communication with the object is by member functions that operate on the encapsulated data. In addition, there is strong support for a hierarchy of objects: new object types may be derived from a base object, and the base-object’s member functions may be superseded by similar functions provided by the derived objects. This arrangement confers a distinct benefit in terms of program modularity. For example, the main program may need access to many different varieties of derived objects in many different parts of the code, but it is only necessary to make reference to base objects, not to the derived objects. The runtime system automatically calls the member functions of the appropriate derived objects. A good introduction to programming in C++ is provided by Stevens (1994); it is assumed that the reader has a working knowledge of the language.

Discussion below regarding the mechanics of building DLLs of constitutive models is focused primarily on Windows. For Linux users, please copy the contents of “/opt/itascasoftware/v900/pluginfiles/models/example” to a working directory. Comments at the top of the “CMakeLists.txt” file from that directory outline the process of compiling the shared object file. Once created, please move the shared object file to “/opt/itascasoftware/v900/plugins/cmodel”.

The methodology of writing a constitutive model in C++ for operation in FLAC3D is described in Methodology. This includes descriptions of the base class, member functions, registration of models, information passed between the model and FLAC3D, and the model state indicators. The implementation of a DLL model is described and illustrated in Implementation. This includes descriptions of the support functions used by the model, the source code for an example model, FISH support for user-written models, and the mechanism for creating and loading a DLL. All of the files referenced in this section are contained in the “\pluginfiles\models\src” directory.

Note that a DLL must be compiled using Microsoft Visual Studio 2022 for operation in FLAC3D.

Using Project Template

To get started quickly and provide a project for examination, take the following steps.

  1. Assuming FLAC3D 9.0 and Visual Studio 2022 has been already installed, find the file “ItascaProjectTemplates.vsix” in the FLAC3D 9.00 installation PluginFiles directory.

  2. Execute this installation file “ItascaProjectTemplates.vsix” by double-clicking on it. (You may need to have administrator privileges on the machine to do this.) Complete the installation as prompted. Make sure checking VS 2022 when asking “Select the product you want to install the extension to”.

  3. Launch Visual Studio 2022.

    1. Select “Create a new project” from the options on the right of the startup dialog.

    2. Type ‘itasca’ in the “Search for project templates” field.

    3. Select the “Itasca Constitutive Model” option and Next.

    4. Assign a name to the “Project name” (e.g., “udm”). You also have the option to choose a new location in which to place the new project and solution. Then Create.

  4. A dialog will appear, asking you to name your “Model Keyword”. 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, You can use a name different from the project name, e.g., “test”, but we recommend just use the same name as the project, e.g., “udm”.

  5. A project will be created for you, using the source to the example Mohr-Coulomb model as a starting point. This can be freely modified by you to match your specific model behavior.

  6. You should update the solution to use the latest version of the Windows SDK and runtime libraries. Do this by right-clicking on the solution line in the “Solution Explorer” and selecting “Retarget Projects”.

  7. Change the build mode from “debug” to “release”, build the project (from VS 2022 menu Build ‣ Build Solution). If succeeded, a DLL file should be in the “Release” folder under the project directory. Close FLAC3D, copy that DLL file (e.g., “cmodeludm009.dll) to the folder of “ItascaSoftware900\exe64plugins\cmodel” under the FLAC3D installation directory, e.g., “C:\Program Files\Itasca”. Restart FLAC3D, if you find the information “cmodel plugin name (e.g., udm or test) loaded”, this user-defined model as been successfully loaded in FLAC3D. Type “zone cmodel list” in the FLAC3D console to double-check in the model list.

Using CMAKE Method

To use the CMAKE method, follow these steps.

  1. Assuming FLAC3D 9.0 and Visual Studio 2022 x64 version has been already installed, copy the folder of models\example in the FLAC3D 9.00 installation PluginFiles directory to your working folder.

  2. Within the folder of \models\example, delete the files “example.sln”, “example.vcxproj”, and “example.vcxproj.filters”.

  3. Rename the folder “example” into another project name, e.g., “mmc”, which is an abbreviation for “ModifiedMohrCoulomb”. You may choose a different name.

  4. Rename “modelexample.h” and “modelexample.cpp” to, e.g., “modelmmc.h” and “modelmmc.cpp”.

  1. Open “CMakelists.txt” in a text editor. Replace all instances of “example” with “mmc”.

  2. Launch Visual Studio 2022 and select “Open a local folder”, then open the “mmc” folder.

  3. In the “modelmmc.h” file, change all occurrences of the class name “ModelExample” to, e.g., “ModelMMC”.

  4. In the “modelmmc.cpp” file, replace the first line of “#include “modelexample.h”” in to “#include “modelemmc.h””. Also, update all occurrences of the class name “ModelExample” to “ModelMMC”.

  5. In the function of “extern “C” EXPORT_TAG const char *getName()”, change “example” to “mmc”.

  6. In the function of “string ModelMMC::getName() const”, change “example” to “modified-mohr-coulomb”. Please be aware that “modified-mohr-coulomb” will be the official model name which can be used in the “zone cmodel assign modified-mohr-coulomb” command.

  7. Similarly, in the function “string ModelMMC::getFullName() const”, change “Example” to “Modified-Mohr-Coulomb”.

  8. Set Visual Studio to the “x64-Release” mode and build the model from the menu “Build -> ReBuild All”.

  9. Review and revise the contents of “modelmmc.h” and “modelmmc.cpp” to ensure they conform to your UDM. Refer to the Methodology and Implementation sections for more details.

  10. Rebuild the model, once successful, a DLL of “modelmmc009.dll” will be in the sub-folder of \out\build\x64-Release\lib. copy that DLL file (e.g., “cmodelmmc009.dll) to the folder of “ItascaSoftware900\exe64plugins\cmodel” under the FLAC3D installation directory, e.g., “C:\Program Files\Itasca”. Restart FLAC3D, if you find the information “cmodel plugin name (e.g., mmc or test) loaded”, this user-defined model as been successfully loaded in FLAC3D. Type “zone cmodel list” in the FLAC3D console to double-check in the model list.

Manual Configuration

In order to create a DLL in Visual Studio 2022, it is first necessary to create a solution. The solution will contain projects that are essentially a collection of C++ source and header files and their dependencies.

An example solution and project have been provided. This collection of files can be found in the “PluginFiles\models\example” folder of the FLAC3D application data directory (“ProgramData\Itasca\ItascaSoftware900” by default). To create a custom DLL, the user may simply wish to modify the example provided. We do not, however, recommend this, since the original example will no longer be available for reference. Additionally, Visual Studio embeds a unique identifier (a GUID) in each solution and project file. Copying a project and renaming it can cause serious confusion within the IDE. Instead, we recommend you create a new project using the following steps and settings.

  1. Launch Visual Studio 2022, and select “Create a new project”.

  2. Filter “C++” under “All languages” and “Windows” under “All platform”. Select “Empty Project”. Then press Next.

  3. Assign a name to the “Project name” (e.g., “test”). You also have the option to choose a new location in which to place the new project and solution. Then press Create.

  4. In VS 2022. change build mode to “Release” and “x64”. Copy the files “modelexample.h”, “modelexample.cpp”, “version.rc” and “version.txt” from “pluginfiles\models\examples” into the directory created by Visual Studio for your solution and project. Rename the C++ source files to indicate your constitutive model (for example, “modeltest.h” and “modeltest.cpp”).

  5. In the Solution Explorer window of Visual Studio, right-click on the “Header Files” folder and add “modeltest.h”. Then right-click on the “Source Files” folder and add “modeltest.cpp”. Add the file “version.rc” to the “Resources” folder. Add the file “version.txt” as a project object. (“Add Existing Item” from the project context menu.) These files can now be edited to create your custom constitutive model.

  6. Right-click on the project entry and select “Properties”. Make certain that “Configuration:” reads “Active(Release)” and “Platform:” reads “Active(x64)”. You can create Debug and x64 versions of the project later by copying these steps with appropriate modifications.

  7. Under “Configuration Properties,” select the “General” entry. Change the “Configuration Type” entry to “Dynamic Library (.dll)”. Change the “Target Name” entry to “cmodel$(ProjectName)009”, or a specific name if it is not the same as the project name, e.g., “cmodeltest009” if the model name is called “test”. If the “Configuration:” reads “Active(Debug)” in step (6), Change the “Target Name” entry to “cmodel$(ProjectName)d009”, or a specific name if it is not the same as the project name, e.g., “cmodeltestd009” if the model name is called “test”. Change the “C++ Language Standard” entry to “ISO C++ 17 Standard”.

  8. Under “C/C++,” select the “General” entry. Add the directories “interface” and “cmodels\src”, both sub-directories of the “ProgramData\Itasca\ItascaSoftware900” directory, to “Additional Include Directories”. In a typical install, this entry might read “C:\ProgramData\Itasca\ItascaSoftware90\pluginfiles\interface”; “C:\ProgramData\Itasca\ItascaSoftware90\pluginfiles\models\src”. You should also change “Warning Level” to Level 4, and set “Treat Warnings As Errors” to Yes.

  9. Under “C/C++,” select the “Code Generation” entry. Change “Runtime Library” to “Multi-threaded DLL (/MD)”. If the “Configuration:” reads “Active(Debug)” in step (6), under “C/C++,” select the “Preprocessor” entry. Change “Preprocessor Definitions” so that “_NDEBUG” now reads “MODELDEBUG”.

  10. Select “Linker/General”. Make sure the “Output File” entry is as “$(OutDir)$(TargetName)$(TargetExt)”. Add “Additional Library Directories” with “C:\ProgramData\Itasca\ItascaSoftware90\pluginfiles\lib”.

  11. Select “Linker/Input”. The “Additional Dependencies” should add the files “base009_64.lib” and “conmodel009_64.lib”, For instance, in a typical install this would read “C:\ProgramData\Itasca\ItascaSoftware900\PluginFiles\lib\exe64\base009.lib” and “C:\ProgramData\Itasca\ItascaSoftware900\PluginFiles\lib\exe64\conmodel009.lib”.

  12. Build the project (from VS 2022 menu Build ‣ Build Solution). If succeeded, a DLL file should be in the “x64\Release” folder under the project directory. Close FLAC3D, copy that DLL file (e.g., “cmodeludm009.dll) to the folder of “ItascaSoftware900\exe64plugins\cmodel” under the FLAC3D installation directory, e.g., “C:\Program Files\Itasca”. Restart FLAC3D, if you find the information “cmodel plugin name (e.g., udm or test) loaded”, this user-defined model as been successfully loaded in FLAC3D. Type “zone cmodel list” in the FLAC3D console to double-check in the model list.

Reference

Stevens, A. Teach Yourself C++, 4th Ed. New York: MIS Press (1994).