User Subroutine Extensions¶

FrontISTR provides a set of user subroutines for extending functionality without modifying the main source code. They cover user implementations of constitutive laws and integration of user-defined external loads. This chapter lists the available extension points and the keywords in the analysis control file used to invoke each one. For detailed subroutine arguments and rebuild procedures, see User Subroutines (Coding Guide).

Overview of Functions¶

User-subroutine extension points are divided into two categories: material constitutive laws and external loads. On the constitutive-law side, there are four invocation paths—linear elasticity, hyperelasticity, elastoplasticity, and a general-purpose constitutive law—each activated by an independent keyword. On the external-load side, a path is provided that reads load information from an external file prepared by the user and adds it to the global load vector and residual vector. Each extension becomes available after editing the template file included with the FrontISTR distribution and rebuilding the main program.

Extension Category	Analysis Control Keyword	Main User Subroutines	Template to Edit
User linear elasticity	`!ELASTIC, TYPE=USER`	`uElasticMatrix`, `uElasticUpdate`	`fistr1/src/lib/user/uelastic.f90`
User hyperelasticity	`!HYPERELASTIC, TYPE=USER`	`uElasticMatrix`, `uElasticUpdate`	`fistr1/src/lib/user/uelastic.f90`
User elastoplasticity (yield function and return mapping)	`!PLASTIC, YIELD=USER`	`uElastoPlasticMatrix`, `uBackwardEuler`, `uElastoPlasticNumStatus`	`fistr1/src/lib/user/uyield.f90`
General-purpose user constitutive law	`!USER_MATERIAL`	`uMatlMatrix`, `uUpdate`	`fistr1/src/lib/user/umat.f90`
User-defined external load	`!ULOAD, FILE=<fname>`	`ureadload`, `uloading`, `uResidual`	`fistr1/src/lib/user/uload.f90`

User-defined hardening laws (a path that retains the built-in yield function while replacing only the hardening curve with a user implementation) are not supported. If a user-defined hardening curve is required, select !PLASTIC, YIELD=USER and replace the entire elastoplastic constitutive law with a user implementation. User boundary conditions and extension points for user processing during restart are not supported.

!CREEP with TYPE=USER is not supported. Use !USER_MATERIAL to implement a time-dependent constitutive law as a user extension.

User Constitutive Laws¶

User constitutive laws provide an entry point for implementing stress-strain relationships that cannot be represented by the built-in material models in an external subroutine. Four paths are available according to the framework of the corresponding built-in constitutive law: user linear elasticity, user hyperelasticity, user elastoplasticity, and a general-purpose user constitutive law. In each path, within the !MATERIAL block of the analysis control data, specify TYPE=USER or YIELD=USER on the corresponding keyword. Up to 100 user constants can be specified and are passed to the subroutine.

User Linear Elasticity¶

User linear elasticity is the path in which the user calculates the elastic matrix within the infinitesimal-deformation framework. When !ELASTIC, TYPE=USER is specified in the analysis control data, FrontISTR treats it as an infinitesimal-deformation constitutive law and calls uElasticMatrix (which returns elastic matrix \(D\)) during element stiffness calculation and uElasticUpdate (which returns stress) during stress update. Do not use it together with an existing hyperelastic or elastoplastic model.

User Hyperelasticity¶

User hyperelasticity is the path for calculating stress and tangent stiffness from derivatives of a strain-energy function within a large-deformation (Total Lagrange) framework. Specify !HYPERELASTIC, TYPE=USER in the analysis control data. The called subroutines are the same uElasticMatrix and uElasticUpdate as for user linear elasticity, and the same fistr1/src/lib/user/uelastic.f90 template is shared. Because the keyword specification switches whether FrontISTR treats the implementation as infinitesimal deformation or Total Lagrange, the same template cannot be used simultaneously for both infinitesimal- and large-deformation implementations. Implement it as one of the two constitutive laws.

User Elastoplasticity¶

User elastoplasticity is the path in which the user implements the yield function and the return-mapping procedure. Specify !PLASTIC, YIELD=USER in the analysis control data. This enters a branch independent of the built-in Mises, Mohr-Coulomb, and Drucker-Prager yield functions. uElastoPlasticMatrix (which returns elastoplastic tangent stiffness \(D\)) is called during element stiffness calculation, uBackwardEuler (which maps trial stress to true stress and updates state variables) during stress update, and uElastoPlasticNumStatus (which returns the number of real-valued state variables to retain) during Gauss-point initialization. A path that replaces only the hardening curve with a user implementation is not supported. Even when only a user-defined hardening curve is needed, use this path to replace the entire elastoplastic constitutive law with a user implementation.

General-Purpose User Constitutive Law¶

The general-purpose user constitutive law is a path for implementing constitutive laws that do not fit within the elastic, hyperelastic, or elastoplastic frameworks. Specify !USER_MATERIAL in the analysis control data. By default it is handled within the Updated Lagrange framework; when KIRCHHOFF is specified, it is handled as Total Lagrange. The number of state variables is specified by NSTATUS. uMatlMatrix (which returns tangent stiffness \(D\)) is called during element stiffness calculation, and uUpdate (which updates stress and state variables) during stress update.

Passing User Constants and State Variables¶

For each of the !ELASTIC, TYPE=USER, !HYPERELASTIC, TYPE=USER, and !USER_MATERIAL paths, the user constants written on data lines in the analysis control data (up to 100) are passed directly to the subroutine through the matl argument. For !PLASTIC, YIELD=USER, the elastic constants specified by !ELASTIC and the user constants supplied through the !PLASTIC data lines are passed.

For the general-purpose user constitutive law and !PLASTIC, YIELD=USER, history information from the previous step (such as plastic strain, back stress, and damage) can be passed to the user implementation through the state variable fstat and written back at the end of the step. The number of state variables is determined, for the general-purpose user constitutive law, by !USER_MATERIAL and its NSTATUS, and for !PLASTIC, YIELD=USER, by the return value of uElastoPlasticNumStatus.

User-Defined External Loads¶

User-defined external loads provide a path for defining external forces that cannot be represented by the built-in concentrated loads, distributed loads, or body forces. When !ULOAD, FILE=<fname> is written in the analysis control data, FrontISTR passes the specified file name to ureadload, and the information read by the user implementation is retained as module data.

The following three subroutines correspond to invocation of !ULOAD.

ureadload: At the start of the analysis, reads user-defined loads from the external file specified in the control file. The user implementation opens the file and stores the required data in module variables.
uloading: Called while assembling the external load vector for each step and adds the user load to the global load vector. The current step number and load factor are passed as arguments.
uResidual: Called while assembling the residual vector at each iteration and adds the contribution of the user load to the global residual vector. It is called from both nonlinear iterations and equilibrium calculations.

No extension point is provided for user boundary conditions (user extensions of prescribed displacement or contact conditions). If a user extension other than an external force is required, use the corresponding built-in keyword or a user constitutive-law path.

Procedure for Implementing User Subroutines¶

To use a user subroutine, edit the template file included with the FrontISTR source distribution and then rebuild FrontISTR. User subroutines cannot be replaced in distributed binaries, so using a user extension requires an environment in which FrontISTR can be built from source.

User-subroutine templates are located under fistr1/src/lib/user/, with a specific file to edit for each extension category (see the table in Overview of Functions for file names). In their initial state, the files contain either empty subroutine bodies or a sample linear-elastic implementation; users add their own constitutive law or load definition there. After editing the template, rebuild FrontISTR normally with CMake and run the analysis with the resulting fistr1 executable.

Details such as the meaning of subroutine arguments, handling of state-variable arrays, and precautions when rebuilding are provided on the corresponding pages of the coding guide.