AbaqusUserElement

Coupling UserObject to use Abaqus UEL plugins in MOOSE

Description

The AbaqusUserElement user object is used to execute Abaqus UEL plugins that users code with the purpose of building finite element kinematics (i.e. interpolation functions), numerical treatments (e.g. locking correction), Jacobian of the forces with respect to the displacements and the forces themselves. These plug-ins can be coded in Fortran (.f and .f90 file extensions) or C/C++ (.c and .C file extensions) and can be located in the plugins directory of the app or another appropriate directory such as examples.

Note that one can combine a UEL routine with UMAT routines such that the UEL coder is responsible for calling a UMAT routine compiled within the same plugin.

note

When state variables are needed, the user is responsible for prescribing them in the input files via num_state_vars = in the AbaqusUserElement user object.

Various forms of verification of this interface have been carried out. The most general is that defined by a beam subjected to external loading. The internal forces are a function of strain-dependent state variables and two external fields that vary spatially. Results between a UEL of triangular elements and the corresponding model set up in MOOSE with a call to an equivalent UMAT routine match to a relative tolerance of $var element = document.getElementById("moose-equation-02b1fa2f-3671-4411-9bb4-a74d57e86764");katex.render("10^{-6}", element, {displayMode:false,throwOnError:false});$ .

The input file that calls the UEL does so from the AbaqusUserElement block:

[UserObjects]
  [uel]
    type = AbaqusUserElement
    variables = 'disp_x disp_y'
    plugin = ../../../examples/uel_tri_states_tests/uel
    use_displaced_mesh = false
    num_state_vars = 8
    constant_properties = '100 0.3' # E nu
    external_fields = 'temperature voltage'
    extra_vector_tags = 'kernel_residual'
  []
[]

The equivalent input file that performs all the setup in MOOSE, except the computation of internal forces, uses the AbaqusUMATStress plugin.

[umat]
  type = AbaqusUMATStress
  constant_properties = '100 0.3'
  plugin = '../../plugins/small_elastic_tri_states'
  num_state_vars = 2
  use_one_based_indexing = true
  temperature = 'temperature'
  external_fields = 'voltage'
[]

Interface

The UEL plugin entry function signature is defined in the AbaqusUserElement.h header file

  typedef void (*uel_t)(
      Real RHS[],    // (MLVARX,*)      Residual vector contribution for the current element
      Real AMATRX[], // (NDOFEL,NDOFEL) Jacobian contribution for the current element
      Real SVARS[],  // (NSVARS)        Persistent state variable values for the current element
      Real ENERGY[], // (8)             Energy quantities at the start of the current
                     //                 increment (to be updated by the UEL routine)
      int * NDOFEL,  // Number of degrees of freedom (DOFs) for the current element
      int * NRHS,    // NRHS=1: RHS should contain the residual vector,
                     // NRHS=2: not implemented (modified Riks static procedure)
      int * NSVARS,  // Number of persistent state variables for the element
      Real PROPS[],  // (NPROPS) Static property values (parameters) defined for use with this
                     // element.
      int * NPROPS,  //
      Real COORDS[], // (MCRD,NNODE) Undisplaced coordinates of the element nodes
                     //              COORDS(K1,K2) is the K1th coordinate of the
                     //              K2th node of the element
      int * MCRD,  // Maximum number of coordinates needed at any node point (COORDINATES keyword -
                   // unsupported)
      int * NNODE, // Number of nodes in the current element
      Real U[],    // (NDOFEL)   Total values of the variables
      Real DU[],   // (MLVARX,*) Incremental values of the variables for the current increment
                   //            for right-hand-side
      Real V[],    // (NDOFEL) Time rate of change of the variables (velocities,
                   //          rates of rotation). Defined for implicit dynamics only (LFLAGS(1)
                   //          11 or 12)
      Real A[],    // (NDOFEL) Accelerations of the variables. Defined for implicit dynamics
                   //          only (LFLAGS(1) 11 or 12).
      int * JTYPE, // Integer defining the element type. This is the user-defined integer value n in
                   // element type Un
      Real TIME[], // (2) step time and total time
      Real * DTIME,  // Time increment
      int * KSTEP,   // Step number (as per Abaqus definition) can be set by the user
      int * KINC,    // Increment number (MOOSE time step)
      int * JELEM,   // User-defined element number
      Real PRAMS[],  // (*) parameters associated with the solution procedure
      int * NDLOAD,  // Number of applied loads to the element (unused)
      int JDLTYP[],  // (MDLOAD, *) array containing the integers used to define distributed load
                     //             types for the element
      Real ADLMAG[], // (MDLOAD,*)
      Real PREDEF[], // (2,NPREDF,NNODE) predefined field variables, such as temperature in an
                     //                  uncoupled stress/displacement analysis
      int * NPREDF,  // Number of predefined field (auxiliary) variables, including temperature
      int LFLAGS[],  // (*) flags that define the current solution procedure
      int * MLVARX,  // used when several displacement or right-hand-side vectors are used
      Real DDLMAG[], // (MDLOAD,*)
      int * MDLOAD,  // Total number of distributed loads and/or fluxes defined on this element
      Real * PNEWDT, // Recommended new timestep (unused)
      int JPROPS[],  // (NJPROP) NJPROP integer property values defined for the current element
      int * NJPROP,  // Number of user defined integer properties
      Real * PERIOD  // Current step time period (unused)
  );

Output parameters

The UEL routine sets RHS, AMATRX, SVARS, ENERGY, and PNEWDT

RHS is the residual contribution for the DOFs associated with the current element
AMATRIX are the Jacobian contributions for the DOFs associated with the current element
SVARS are stateful properties (persistent across timesteps) that are managed by the user object similar to stateful material properties in MOOSE
ENERGY array of 6 energy quantities (currently not used by MOOSE)
1. Kinetic energy.
2. Elastic strain energy.
3. Creep dissipation.
4. Plastic dissipation.
5. Viscous dissipation.
6. Artificial strain energy stemming from e.g. artificial stiffness to control singular modes
7. Electroststic energy
8. Incremental work done by loads applied through the UEL routine
PNEWDT is a new recommended simulation time step (currently not used by MOOSE)

Input parameters

Please consult the Abaqus user manual for more documentation on the UEL plugin parameters.

Input Parameters

constant_propertiesConstant mechanical and thermal material properties (PROPS)
C++ Type:std::vector<double>
Controllable:No
Description:Constant mechanical and thermal material properties (PROPS)
num_state_varsThe number of state variables this UMAT is going to use
C++ Type:unsigned int
Controllable:No
Description:The number of state variables this UMAT is going to use
pluginUEL plugin file
C++ Type:FileName
Controllable:No
Description:UEL plugin file

Required Parameters

blockThe list of blocks (ids or names) that this object will be applied
C++ Type:std::vector<SubdomainName>
Controllable:No
Description:The list of blocks (ids or names) that this object will be applied
external_fieldsAuxiliary field variables (or 'predifined field variables') passed to the UEL plugin. Some plugins may assume that the first field is temperature when there are multiple external fields.
C++ Type:std::vector<AuxVariableName>
Controllable:No
Description:Auxiliary field variables (or 'predifined field variables') passed to the UEL plugin. Some plugins may assume that the first field is temperature when there are multiple external fields.
jtype0Abaqus element type integer
Default:0
C++ Type:int
Controllable:No
Description:Abaqus element type integer
prop_getter_suffixAn optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.
C++ Type:MaterialPropertyName
Controllable:No
Description:An optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.
variablesNonlinear coupled variables
C++ Type:std::vector<NonlinearVariableName>
Controllable:No
Description:Nonlinear coupled variables

Optional Parameters

absolute_value_vector_tagsThe tags for the vectors this residual object should fill with the absolute value of the residual contribution
C++ Type:std::vector<TagName>
Controllable:No
Description:The tags for the vectors this residual object should fill with the absolute value of the residual contribution
extra_matrix_tagsThe extra tags for the matrices this Kernel should fill
C++ Type:std::vector<TagName>
Controllable:No
Description:The extra tags for the matrices this Kernel should fill
extra_vector_tagsThe extra tags for the vectors this Kernel should fill
C++ Type:std::vector<TagName>
Controllable:No
Description:The extra tags for the vectors this Kernel should fill
matrix_tagssystemThe tag for the matrices this Kernel should fill
Default:system
C++ Type:MultiMooseEnum
Options:nontime, system
Controllable:No
Description:The tag for the matrices this Kernel should fill
vector_tagsnontimeThe tag for the vectors this Kernel should fill
Default:nontime
C++ Type:MultiMooseEnum
Options:nontime, time
Controllable:No
Description:The tag for the vectors this Kernel should fill

Tagging Parameters

allow_duplicate_execution_on_initialFalseIn the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).
Default:False
C++ Type:bool
Controllable:No
Description:In the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).
control_tagsAdds user-defined labels for accessing object parameters via control logic.
C++ Type:std::vector<std::string>
Controllable:No
Description:Adds user-defined labels for accessing object parameters via control logic.
enableTrueSet the enabled status of the MooseObject.
Default:True
C++ Type:bool
Controllable:Yes
Description:Set the enabled status of the MooseObject.
execution_order_group0Execution order groups are executed in increasing order (e.g., the lowest number is executed first). Note that negative group numbers may be used to execute groups before the default (0) group. Please refer to the user object documentation for ordering of user object execution within a group.
Default:0
C++ Type:int
Controllable:No
Description:Execution order groups are executed in increasing order (e.g., the lowest number is executed first). Note that negative group numbers may be used to execute groups before the default (0) group. Please refer to the user object documentation for ordering of user object execution within a group.
force_postauxFalseForces the UserObject to be executed in POSTAUX
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in POSTAUX
force_preauxFalseForces the UserObject to be executed in PREAUX
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in PREAUX
use_displaced_meshFalseWhether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.
Default:False
C++ Type:bool
Controllable:No
Description:Whether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.

Advanced Parameters

(moose/modules/tensor_mechanics/test/tests/uel/small_test_uel_states_fields_gradient.i)

[Mesh]
  [gen]
    type = GeneratedMeshGenerator
    dim = 2
    nx = 20
    ny = 10
    xmax = 10
    ymax = 3
    elem_type = TRI3
  []
  [pin]
    type = ExtraNodesetGenerator
    nodes = 106
    new_boundary = pin
    input = gen
  []
  displacements = 'disp_x disp_y'
[]

[Variables]
  [disp_x]
  []
  [disp_y]
  []
[]

[AuxVariables]
  [temperature]
    initial_condition = 400
  []
  [voltage]
    initial_condition = 210
  []
[]

[AuxKernels]
  [temperature]
    type = FunctionAux
    function = '25* x + 40 * y + 400'
    variable = temperature
  []
  [voltage]
    type = FunctionAux
    function = '10 * x + 4 * y + 210'
    variable = voltage
  []
[]

[BCs]
  [left_x]
    type = DirichletBC
    variable = disp_x
    boundary = left
    value = 0
  []
  [left_y]
    type = DirichletBC
    variable = disp_y
    boundary = pin
    value = 0
  []

  inactive = 'right_dirichlet'
  [right_neumann]
    type = FunctionNeumannBC
    variable = disp_x
    function = t/10
    boundary = right
  []
  [right_dirichlet]
    type = FunctionDirichletBC
    variable = disp_x
    function = t/10
    boundary = right
  []
[]

[UserObjects]
  [uel]
    type = AbaqusUserElement
    variables = 'disp_x disp_y'
    plugin = ../../../examples/uel_tri_states_tests/uel
    use_displaced_mesh = false
    num_state_vars = 8
    constant_properties = '100 0.3' # E nu
    external_fields = 'temperature voltage'
    extra_vector_tags = 'kernel_residual'
  []
[]

[Problem]
  kernel_coverage_check = false
  extra_tag_vectors = 'kernel_residual'
[]

[AuxVariables]
  [res_x]
  []
  [res_y]
  []
[]

[AuxKernels]
  [res_x]
    type = TagVectorAux
    variable = res_x
    v = disp_x
    vector_tag = kernel_residual
  []
  [res_y]
    type = TagVectorAux
    variable = res_y
    v = disp_y
    vector_tag = kernel_residual
  []
[]

[Executioner]
  type = Transient
  solve_type = NEWTON
  petsc_options_iname = '-pc_type'
  petsc_options_value = 'lu'
  dt = 1
  num_steps = 15
[]

[Postprocessors]
  [delta_l]
    type = SideAverageValue
    variable = disp_x
    boundary = right
    execute_on = 'INITIAL TIMESTEP_END'
  []
  [V]
    type = ElementIntegralMaterialProperty
    mat_prop = 1
    use_displaced_mesh = true
    execute_on = 'INITIAL TIMESTEP_END'
  []
[]

[Outputs]
  exodus = true
  csv = true
[]

(moose/modules/tensor_mechanics/test/tests/uel/small_test_umat_states_fields_gradient.i)

[GlobalParams]
  displacements = 'disp_x disp_y'
[]

[Mesh]
  [gen]
    type = GeneratedMeshGenerator
    dim = 2
    nx = 20
    ny = 10
    xmax = 10
    ymax = 3
    elem_type = TRI3
  []
  [pin]
    type = ExtraNodesetGenerator
    nodes = 106
    new_boundary = pin
    input = gen
  []
  displacements = 'disp_x disp_y'
[]

[AuxVariables]
  [temperature]
    initial_condition = 400
  []
  [voltage]
    initial_condition = 210
  []
[]

[AuxKernels]
  [temperature]
    type = FunctionAux
    function = '25* x + 40 * y + 400'
    variable = temperature
  []
  [voltage]
    type = FunctionAux
    function = '10 * x + 4 * y + 210'
    variable = voltage
  []
[]

[BCs]
  [left_x]
    type = DirichletBC
    variable = disp_x
    boundary = left
    value = 0
  []
  [left_y]
    type = DirichletBC
    variable = disp_y
    boundary = pin
    value = 0
  []

  inactive = 'right_dirichlet'
  [right_neumann]
    type = FunctionNeumannBC
    variable = disp_x
    function = t/10
    boundary = right
  []
  [right_dirichlet]
    type = FunctionDirichletBC
    variable = disp_x
    function = t/10
    boundary = right
  []
[]

[Modules/TensorMechanics/Master]
  [all]
    add_variables = true
    strain = SMALL
    incremental = true
    extra_vector_tags = 'kernel_residual'
  []
[]

[Materials]
  [umat]
    type = AbaqusUMATStress
    constant_properties = '100 0.3'
    plugin = '../../plugins/small_elastic_tri_states'
    num_state_vars = 2
    use_one_based_indexing = true
    temperature = 'temperature'
    external_fields = 'voltage'
  []
[]

[Problem]
  kernel_coverage_check = false
  extra_tag_vectors = 'kernel_residual'
[]

[AuxVariables]
  [res_x]
  []
  [res_y]
  []
[]

[AuxKernels]
  [res_x]
    type = TagVectorAux
    variable = res_x
    v = disp_x
    vector_tag = kernel_residual
  []
  [res_y]
    type = TagVectorAux
    variable = res_y
    v = disp_y
    vector_tag = kernel_residual
  []
[]

[Executioner]
  type = Transient
  solve_type = NEWTON
  petsc_options_iname = '-pc_type'
  petsc_options_value = 'lu'
  dt = 1
  num_steps = 15
  [Quadrature]
   type = GAUSS
   order = CONSTANT
  []
[]

[Postprocessors]
  [delta_l]
    type = SideAverageValue
    variable = disp_x
    boundary = right
    execute_on = 'INITIAL TIMESTEP_END'
  []
  [V]
    type = ElementIntegralMaterialProperty
    mat_prop = 1
    use_displaced_mesh = true
    execute_on = 'INITIAL TIMESTEP_END'
  []
[]

[Outputs]
  exodus = true
  csv = true
[]

(moose/modules/tensor_mechanics/include/userobjects/AbaqusUserElement.h)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#pragma once

#include "GeneralUserObject.h"
#include "BlockRestrictable.h"
#include "TaggingInterface.h"
#include "DynamicLibraryLoader.h"

class MooseMesh;
namespace libMesh
{
class Elem;
class MeshBase;
}

/**
 * This user-object is a testbed for implementing a custom element.
 */
class AbaqusUserElement : public GeneralUserObject,
                          public BlockRestrictable,
                          public TaggingInterface
{
public:
  /// function type for the external UMAT function
  typedef void (*uel_t)(
      Real RHS[],    // (MLVARX,*)      Residual vector contribution for the current element
      Real AMATRX[], // (NDOFEL,NDOFEL) Jacobian contribution for the current element
      Real SVARS[],  // (NSVARS)        Persistent state variable values for the current element
      Real ENERGY[], // (8)             Energy quantities at the start of the current
                     //                 increment (to be updated by the UEL routine)
      int * NDOFEL,  // Number of degrees of freedom (DOFs) for the current element
      int * NRHS,    // NRHS=1: RHS should contain the residual vector,
                     // NRHS=2: not implemented (modified Riks static procedure)
      int * NSVARS,  // Number of persistent state variables for the element
      Real PROPS[],  // (NPROPS) Static property values (parameters) defined for use with this
                     // element.
      int * NPROPS,  //
      Real COORDS[], // (MCRD,NNODE) Undisplaced coordinates of the element nodes
                     //              COORDS(K1,K2) is the K1th coordinate of the
                     //              K2th node of the element
      int * MCRD,  // Maximum number of coordinates needed at any node point (COORDINATES keyword -
                   // unsupported)
      int * NNODE, // Number of nodes in the current element
      Real U[],    // (NDOFEL)   Total values of the variables
      Real DU[],   // (MLVARX,*) Incremental values of the variables for the current increment
                   //            for right-hand-side
      Real V[],    // (NDOFEL) Time rate of change of the variables (velocities,
                   //          rates of rotation). Defined for implicit dynamics only (LFLAGS(1)
                   //          11 or 12)
      Real A[],    // (NDOFEL) Accelerations of the variables. Defined for implicit dynamics
                   //          only (LFLAGS(1) 11 or 12).
      int * JTYPE, // Integer defining the element type. This is the user-defined integer value n in
                   // element type Un
      Real TIME[], // (2) step time and total time
      Real * DTIME,  // Time increment
      int * KSTEP,   // Step number (as per Abaqus definition) can be set by the user
      int * KINC,    // Increment number (MOOSE time step)
      int * JELEM,   // User-defined element number
      Real PRAMS[],  // (*) parameters associated with the solution procedure
      int * NDLOAD,  // Number of applied loads to the element (unused)
      int JDLTYP[],  // (MDLOAD, *) array containing the integers used to define distributed load
                     //             types for the element
      Real ADLMAG[], // (MDLOAD,*)
      Real PREDEF[], // (2,NPREDF,NNODE) predefined field variables, such as temperature in an
                     //                  uncoupled stress/displacement analysis
      int * NPREDF,  // Number of predefined field (auxiliary) variables, including temperature
      int LFLAGS[],  // (*) flags that define the current solution procedure
      int * MLVARX,  // used when several displacement or right-hand-side vectors are used
      Real DDLMAG[], // (MDLOAD,*)
      int * MDLOAD,  // Total number of distributed loads and/or fluxes defined on this element
      Real * PNEWDT, // Recommended new timestep (unused)
      int JPROPS[],  // (NJPROP) NJPROP integer property values defined for the current element
      int * NJPROP,  // Number of user defined integer properties
      Real * PERIOD  // Current step time period (unused)
  );

  static InputParameters validParams();
  AbaqusUserElement(const InputParameters & params);

  virtual void initialSetup() override;
  virtual void meshChanged() override;

  virtual void initialize() override final;
  virtual void execute() override;
  virtual void finalize() override final {}

  /// getters for the loop class
  const std::vector<const MooseVariableFieldBase *> & getVariables() const { return _variables; }
  const std::vector<const MooseVariableFieldBase *> & getAuxVariables() const
  {
    return _aux_variables;
  }

  const uel_t & getPlugin() const { return _uel; }

protected:
  /// setup the range of elements this object operates on
  void setupElemRange();

  /// The plugin file name
  FileName _plugin;

  /// The plugin library wrapper
  DynamicLibraryLoader _library;

  /// Function pointer to the dynamically loaded function
  const uel_t _uel;

  /// The \p MooseMesh that this user object operates on
  MooseMesh & _moose_mesh;

  /// The \p libMesh mesh that this object acts on
  const libMesh::MeshBase & _mesh;

  /// The dimension of the mesh, e.g. 3 for hexes and tets, 2 for quads and tris
  const unsigned int _dim;

  /// coupled variables to provide the DOF values
  std::vector<NonlinearVariableName> _variable_names;

  /// Auxiliary variable names
  std::vector<AuxVariableName> _aux_variable_names;

  /// pointers to the variable objects
  std::vector<const MooseVariableFieldBase *> _variables;

  /// pointers to the auxiliary variable objects
  std::vector<const MooseVariableFieldBase *> _aux_variables;

  /// The subdomain ids this object operates on
  const std::set<SubdomainID> _sub_ids;

  /// All the active and elements local to this process that exist on this object's subdomains
  std::unique_ptr<ConstElemRange> _elem_range;

  /// props
  std::vector<Real> _props;
  int _nprops;

  /// stateful data
  int _nstatev;
  std::array<std::map<dof_id_type, std::vector<Real>>, 2> _statev;
  std::size_t _statev_index_current;
  std::size_t _statev_index_old;

  /// Abaqus element type
  const int _jtype;

  friend class UELThread;
};