Methodology

Base Class for Constitutive Models

The object-oriented programming approach described in the Introduction is exploited in FLAC3D’s support for user-written constitutive models. A base class provides a framework for actual constitutive models, which are classes derived from the base class. The base class, called ConstitutiveModel, is an “abstract” class. It declares a number of “pure virtual” member functions (signified by the =0 syntax appended to the function prototypes). This means that no object of this base class can be created, and any derived-class object must supply real member functions to replace every one of the pure virtual functions of ConstitutiveModel.

Full documentation of ConstitutiveModel is provided in Programmer’s Interface. See the models namespace.

Member Functions

Any derived constitutive-model class must provide actual functions to replace the virtual member-functions in ConstitutiveModel.

The model class definition should also contain a constructor that must invoke the base constructor. In all cases, the derived-class constructor should be called with no parameters, as in the clone member function. Initialization of data members may be performed by the constructor, as illustrated here. In this example, the symbols bulk_, shear_, etc. are the data members for the derived model.

Typical Model Constructor

    ModelExample::ModelExample(unsigned short option) : ModelElastic(option) {
    }

Registration of Models

Each user-written constitutive model is compiled into a DLL that must be instantiated in the FLAC3D process. By convention, there are four exported functions in a DLL used as a plugin to FLAC3D: getName(), getMajorVersion(), getMinorVersion() and createInstance(). You must also provide a stub function called DllMain(), which is called when the library is loaded and unloaded from the system. For example, this is how these functions appear for the Example model:

int __stdcall DllMain(void *,unsigned, void *) {
    return 1;
}

extern "C" EXPORT_TAG const char *getName() {
#ifdef MODELDEBUG
    return "cmodelexampled";
#else
    return "cmodelexample";
#endif
}

extern "C" EXPORT_TAG unsigned getMajorVersion() {
    return MAJOR_VERSION;
}

extern "C" EXPORT_TAG unsigned getMinorVersion() {
    return UPDATE_VERSION;
}

extern "C" EXPORT_TAG void *createInstance() {
    models::ModelExample *m = new models::ModelExample();
    return (void *)m;
}

The EXPORT_TAG macro indicates that these functions should be exported from the DLL.

The DllMain() function is always the same.

The exported DLL function getName() should always return a string that begins with the word “cmodel”. This indicates that the DLL is a constitutive model plugin. In the above example, the string “cmodelexample” is returned by the exported DLL function getName(). The getName() method of the ConstitutiveModel class returns the string “example” (without “cmodel” prefixed to the name as in the getName() function that is exported). This convention of prefixing the exported name with “cmodel” should be followed. The ConstitutiveModel’s getName() function must return a unique string (this is the method used to distinguish constitutive models from each other).

The getMajorVersion() function should not be altered. The major version is determined by the base constitutive model DLL, and indicates binary compatibility. By convention, this number will also be indicated in the file name of the DLL you produce.

The getMinorVersion() function indicates the minor version update of your constitutive model. If new properties are added to a constitutive model, for example, it might not be save file-compatible with an older version. In this case, the minor version number (defined in file “version.txt”) would be incremented by 1.

The createInstance() function actually creates and returns an instance of your class. This is stored in a registry and used (via the clone() function) to create all other instances.

Information Passed between Model and Program during Cycling

The most important link between FLAC3D and a user-written model is the member-function run(UByte d, State *ps), which computes the mechanical response of the model during cycling. A structure, State (defined in “state.h”), is used to transfer information to and from the model.

Full documentation of State is also provided in the models namespace of the programmer’s interface documentation (available in the on-screen Help menu).

The main task of member-function run() is to compute new stresses from strain increments. In a nonlinear model, it is also useful to communicate the internal state of the model, so that the state may be plotted and printed. For example, the supplied models indicate whether they are currently yielding or have yielded in the past. Each subzone may set the variable state_, which records the state of a model as a series of bits that can be on or off (1 or 0). Each bit can be associated with a message that is displayed on the screen. The string returned by member function States contains sub-strings corresponding to bit positions that the model may set in state_. The first sub-string refers to bit 1, the second to bit 2, and so on. Several bits may be set simultaneously. For example, both shear and tensile yield may occur together. The bit assignment is described below. The operation of the state logic may be appreciated by consulting any of the nonlinear model files (e.g., “modelexample.cpp”).

Since all tetra in a zone share the same ConstitutiveModel instance, per-zone state information in the model should only be updated after the last tetra is processed. The State structure contains information designed to help the model determine this. The member variable sub_zone_ contains which tetra is being processed (starting at 0). The member variable total_sub_zones_ contains the total number of tetra in this zone from all overlays. The member variable overlay_ will be 1 or 2 indicating how many overlays are present in this zone.

In addition data can be stored across calls to tetra within a zone for use on the last. The arrays working_ and iworking_ allow data to be safely stored in the State structure across calls to a given zone. Note that the user should not assume that these arrays are initialized to zero on the first call to the first tetra, and detect and initialize this storage themselves.

State Indicators of Zones

A zone in FLAC3D is composed of tetrahedral subzones - two overlays of 5 tetra for 10 total tetrahdron in a normal hexahedral zone. Each tetra shares a ConstitutiveModel class instance, but keeps it’s own separate state indicator. The member variable has 32 bits that can be used to represent a maximum of 16 distinct states (assuming you are keeping track of “now” and “in past” separately). The state indicator bits are used by built-in constitutive models to denote plastic failure of tetrahedra in a zone. See Table 1 for bit assignment and the corresponding failure state for built-in constitutive models. Note that this is a convention and is not actually required for all constitutive models.


Table 1: Failure states and bit assignments
    Hex Decimal Binary
shear_now = 0x0001 1 0000 0000 0000 0001
tension_now = 0x0002 2 0000 0000 0000 0010
shear_past = 0x0004 4 0000 0000 0000 0100
tension_past = 0x0008 8 0000 0000 0000 1000
joint_shear_now = 0x0010 16 0000 0000 0001 0000
joint_tension_now = 0x0020 32 0000 0000 0010 0000
joint_shear_past = 0x0040 64 0000 0000 0100 0000
joint_tension_past = 0x0080 128 0000 0000 1000 0000
volume_now = 0x0100 256 0000 0001 0000 0000
volume_past = 0x0200 512 0000 0010 0000 0000
unused = 0x0400 1024 0000 0100 0000 0000
unused = 0x0800 2048 0000 1000 0000 0000
unused = 0x1000 4096 0001 0000 0000 0000
unused = 0x2000 8192 0010 0000 0000 0000
unused = 0x4000 16384 0100 0000 0000 0000
unused = 0x8000 32768 1000 0000 0000 0000

For user-defined constitutive models, the user can create a named state and assign any particular bit for that state, and subsequently update the tetrahedral state indicator variable. The named states in Table 1 are used by built-in constitutive models to update the failure states of tetrahedral subzones, and show one particular use of the state indicator variable.

The named states in Table 1 are used by many built-in models to update the tetrahedral subzone state indicator.

FLAC3D calls the constitutive model function run() for each tetrahedron that makes up the zone, to update its stress values. Typically, the state indicator is also updated in this process by the constitutive model. For built-in models, the state indicator denotes the failure state of the tetrahedron. This is updated by the constitutive model using the logical “or” (|) operation with the tetrahedron state indicator variable and the current failure state calculated by the constitutive model. The user should take care to appropriately set or un-set all previous states updated prior to the current state calculated by the constitutive model. The state of a tetrahedron can then be checked using the logical “and” (&) operator with the state variable and desired user-defined state.

Suppose a tetrahedron is undergoing failure in tension and shear. This failure state is stored in the state indicator of the tetrahedron. The built-in constitutive model updates the state variable:

  1. Initially, check the current state and set/un-set state indicator, appropriately. For example,
        if (s->state_ & shear_now) s->state_ |= shear_past;
        s->state_ &= ~shear_now;
        if (s->state_ & tension_now) s->state_ |= tension_past;
        s->state_ &= ~tension_now;
  1. Calculate the current state of the tetrahedron.
  2. Update the state if necessary. For example,
        s->state_ |= shear_now;

The result of the preceding operations is that the first and second bits are set for that particular tetrahedron. Additionally, during initialization (step a), the third and the fourth bits are also set. The FISH function zone.state returns a value of 15, the decimal equivalent of the first four bits being set.

Users can use the FISH logical zone.state to find out the failure state at any point in the analysis. Users can also split the output into additive powers of two, and find out all distinct failure states. For example, if zone.state returns 15, then 15 can be written as 15 = 1 + 2 + 4 + 8 (additive powers of two), and from Table 1, the zone is in shear and tensile failure, and had shear and tensile failure in the past.