Writing New Joint Constitutive Models


Users may create their own joint constitutive model for use in 3DEC. 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 normal and shear forces, given normal and shear displacements. 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.

The methodology of writing a joint constitutive model in C++ for operation in 3DEC is described in Methodology. This includes descriptions of the base class, member functions, registration of models, information passed between the model and 3DEC, 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\jmodels\src” directory.

Note that a DLL must be compiled using Microsoft Visual Studio 2017 or 2019 for operation in 3DEC.

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

  1. Assuming 3DEC 7.0 and Visual Studio 2017 or 2019 are already installed, find the file “ItascaProjectTemplates.vsix” in the 3DEC 7.00 installation PluginFiles directory.

  2. Execute this installation file by double-clicking on it. (You may need to have administrator privileges on the machine to do this.) Complete the installation as prompted.

  3. Launch Visual Studio 2017 or 2019.

    If using Visual Studio 2017:

    1. Select File ‣ New ‣ Project from the menu.
    2. Select the “Visual C++” category from the “Installed” section.
    3. You should see the “Itasca Constitutive Model” option.
    4. 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. Then press “OK”.

    If using Visual Studio 2019:

    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 “Itaca Constitutive Model” option and press “Next”.
    4. Assign a name to the project. You also have the option to choose a new location in which to place the new project and solution. Then press “Create”.
  4. 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. If you have more than one compatible version of an Itasca code installed, select the one you are planning on using the constitutive model with first. Press “Accept and Close”.

  5. A project will be created for you, using the source to the internal Mohr-Coulomb model 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”.


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

In this Section