\documentclass[doktyp=unbekannt,hausschrift=true,sprache=english]{TUBAFarbeiten}

\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{amsmath}
\usepackage{listings}
\lstset{language=[90]Fortran}
\usepackage{supertabular} %tables over several pages
\usepackage{hyperref}


%\bibliography{abaquser}
\lstset{extendedchars=true,basicstyle=\small}

%\makeatletter
%  \renewcommand{\TUBAFarbeiten@typ}{Documentation}
%\makeatother

\addto\captionsenglish{\renewcommand{\TUBAFBetreuername}{Contact:}}

\TUBAFFakultaet{Faculty of Mechanical, Process and Energy Engineering}
\TUBAFInstitut{Institute for Mechanics and Fluid Dynamics (IMFD)}
\TUBAFLehrstuhl{Chair Applied Mechanics -- Solid Mechanics}



\TUBAFTitel[\UELlib]{\UELlib \\ A library for user-defined elements in Abaqus}%
\TUBAFBetreuer{Geralf Hütter \newline TU Bergakademie Freiberg \newline Institute of Mechanics and Fluid Dynamics \newline Lampadiusstr.~4 \newline 09596 Freiberg, Germany \newline Geralf.Huetter@imfd.tu-freiberg.de}
% hier Bearbeiter eintragen
\TUBAFAutor[Hütter/Roth/Skrypnyk]{Geralf Hütter, Stephan Roth, Rostyslav Skrypnyk}

% own commands:
\newcommand{\UELlib}{\textsc{UELlib}\;}
\newcommand{\UEL}{UEL\;}
\newcommand{\file}[1]{\texttt{#1}}
\newcommand{\fileuellib}{\file{UEL\_lib.f90}}
\newcommand{\fileabqinterface}{\file{ABQinterface.f90}}


\begin{document}

\maketitle

%\KOMAoptions{%
%	abstract=true	% schaltet die "Uberschrift "`Zusammenfassung"' ein
%}

%\begin{abstract}
%
%\end{abstract}

\tableofcontents
%\listoffigures
%\listoftables

\newpage
\section{General}\label{sec:intension}

The commercial finite element code Abaqus/standard provides the \UEL interface to implement user-defined elements. Implementing different problems as \UEL often requires the same ingredients like particular shape functions, quadrature rules and mathematical utility routines.
The present library UELlib provides a library with modular structure for the implementation of elements via the UEL interface. UELlib distributed under a \href{https://creativecommons.org/licenses/by-nc-sa/4.0/}{CC BY-NC-SA 4.0 license}. UELlib has been used by the authors in \cite{Roth2014,Huetter2016,Huetter2017,Lange2021}. Please refer to any of these publications when using UELlib.

\vspace{-0.8em}
\paragraph{Requirements to the program:}
\begin{enumerate}
  \vspace{-0.5em}
  \setlength{\itemsep}{-0.3em}
	\item It shall be possible to create elements with different different dimensionality (2D/3D), material routines, shape functions, and different quadrature rules without modifying the source code of the actual \UEL routine but by changing only the loaded modules.
	\item It shall be possible to use elements with different shape functions, quadrature rule etc.\ in a single simulation.
	\item The library shall be easily serviceable, i.e.\ it shall contain as few dublicate information and subroutines as possible.
	\item The modular structure shall not influence the runtime speed if possible. For this purpose the libraries are procedurally programmed and it is envisaged that as much information on dimensions of arrays are accessible at compile time in order to allow vectorization.
	\item However, in order to achieve the desired flexibility the library implements static polymorphism features and modules in FORTRAN 90/95.
%	\item A smooth integration in Abaqus is desired making nevertheless : execution on multiple CPUs
\end{enumerate}

The source code has been developed and extensively tested using versions 6.10EF1 and 6.12-3 of ABAQUS with version 11.0 of the Intel Fortran compiler. Later, it was used succesfully with Abaqus versions 6.14, 2018 and 2020 and Intel Fortran compiler 2017.

\section{Installation}\label{sec_Installation}

\subsection{Files}
\label{sec:files}

In folder \file{lib/}:
\begin{itemize}
	\item \fileabqinterface: provides data types of Abaqus variables and explicit interfaces to Abaqus utility routines
	\item \file{Math.f90}: mathematical utility routines e.g.\ for inversion of matrices
	\item \fileuellib: shape functions, quadrature rules and B matrices
\end{itemize}

\subsection{Example elements}

In folder \file{examples/}:
\begin{itemize}
	\item \file{elastic}: standard small displacement element, material routines for isotropic elastic 3D and 2D plane stress and plain strain analysis by Rostyslav Skrypnyk
	\item \file{empty\_element\_framework}: framework for building new elements
\end{itemize}

\subsection{Usage}

\UELlib can either be used by including its source files (as listed in section~\ref{sec:files}) or by linking the compiled \UELlib to the desired library.  Both scenarios are demonstrated with the example elements for which respective \file{Makefile}s are provided to build \file{libstandardU} in subfolders \file{bin/} of the example elements. They are implemented as make targets \lstinline|buildlibsrc| and  \lstinline|buildlibbin|, respectively. In the latter case the files of \UELlib have to be compiled first. A further \file{Makefile} ist provided in the root directory for this task to build the object files in folder \file{bin/}.

If \UELlib shall be used for building a new element, copy one of the content of one folders of the example elements to another folder and start editing it. The variable \lstinline|UELlibpath| in the copied \file{Makefile} has to be set to the directory where \UELlib is located.

\section{Implementation}

\subsection{Structure}
\label{sec:routines}

\subsubsection{Interface to Abaqus}

The module \lstinline|ABQINTERFACE| in \fileabqinterface provides an explicit interface to some utility provided by Abaqus. Another important point is the precision of integer and float variables in the UEL interface. Abaqus offers only an implicit type declaration over the file \file{ABA\_PARAM.INC}. However, implicit type declaration is prone to errors and thus outdated. For this reason private variables are defined implicitly in \lstinline|ABQINTERFACE|. Their "kinds" are picked and provided as \lstinline|AbqRK| and \lstinline|AbqIK| for explicit type declarations in all following modules and routines.

\subsubsection{Shape Functions}

The shape functions are provided over the modules \lstinline|ShapeFunc*| in \fileuellib. Each of this modules contains
\begin{itemize}
	\item \lstinline|ShapeFunc(chi)| which returns the vector (of size \lstinline|NNODES|) of values of the shape functions at a given position \lstinline|chi| in the unit domain.   \lstinline|chi| is a column vector of suitable dimension \lstinline|NDIM|. According to the concept of the libraries, the values \lstinline|NNODES| and \lstinline|NDIM| are provided as paremeters and can be used for defining fixed-size arrays.
	\item \lstinline|ShapeFuncDeriv(chi)| returns the values of the derivative of the shape functions w.r.t.\ the unit coordinates \lstinline|chi| as array of dimension \lstinline|DIMENSION(NNODES,NDIM)|.
\end{itemize}

\subsubsection{Quadrature Rules}

The modules \lstinline|Integr*_*| contain the quadrature rules. Their names like \lstinline|Integr2D_Square9GP| indicate that they refer to a plane square unit domain with nine Gauss points. Each of this modules provides:
\begin{itemize}
	\item the number of Gauss points \lstinline|NGP|
	\item the dimension of unit domain \lstinline|NDIMGP|
	\item a column vector \lstinline|GPWeight| with weights of the Gauss points
	\item a matrix \lstinline|GPPos(NGP,NDIMGP)| containing the positions of the points in the unit domain
\end{itemize}
All these values are defined as parameters and are thus available at compile time.

\subsubsection{B-matrices}

The modules \lstinline|BMatrices*| contain functions to derive the B-matrices for different szenarios
\begin{itemize}
	\item \lstinline|BMatTensSym| for symmetric tensors in Voigt notation like e.g.\ the strain tensor
	\item \lstinline|BMatTensUnsym| for unsymmetric tensors in Voigt notation like e.g.\ the deformation
\end{itemize}
by default the B-matrices are computed from the inverse of Jacobian of the isoparametric mapping and from the derivative matrix of the shape functions w.r.t.\ the unit coordinates. Alternative versions of the function with suffix \lstinline|_SFG| are available indicating that the B-matrices are computed from the already computed gradient of the shape functions w.r.t.\ the physical coordinates. This option may save computational time in multi-field problems if the same shape functions are used for the different fields.

\subsection{Applications}

\subsubsection{Elements with Different Shape Function, Quadrature Rules etc.}

If only a single element shall be developed the aforementioned modules can just be loaded in the UEL routine.
However, one main goal of the present library is to allow to develop elements with different shape function, quadrature rules, dimensions etc.\ with a single source code, i.e.\ without the necessity of maintaining different almost identical source codes for similar elements. If they shall be used in a single simulation (or compiled into a single universal shared library) this can be achieved via modules as demonstrated in the examples:
\begin{lstlisting}
MODULE CXU2D4PlaneStrain
  USE  ShapeFunc2D_Square_Lin
  USE  BMatrices2DPlaneStrain
  USE Integr2D_Square4GP
  USE UMAT1
  IMPLICIT NONE
  PUBLIC::UEL
  CONTAINS
    INCLUDE "UelCXU.f90"
END MODULE
\end{lstlisting}
Then the file \file{UelCXU.f90} contains the actual UEL that makes use of the generally named routines and variables defined in the modules as described in section~\ref{sec:routines} (like \lstinline|ShapeFunc(chi)|, \lstinline|NNODES| etc.). Several of such modules with different combinations of shape function, quadrature rules, dimensions etc.\ can be created. This means that the actual element routine from \file{UelCXU.f90} is compiled individually for each combination allowing the respective optimzations since information like the size of the arrays are available at compile time.
Finally, the modules with different element routines are managed by the "global" UEL routine provided to Abaqus. This routine loads the modules and calls the respective module element routine depending on the  \lstinline|JTYPE| parameter. The latter contains the number of the user element defined in the Abaqus input file, e.g.\ a definition \lstinline|*USER ELEMENT, TYPE=U2001, ...| would correspond to \lstinline|JTYPE=2001|.
\begin{lstlisting}
SUBROUTINE UEL(...Parameters according to Abaqus UEL interface...)
  USE CXU2D4PlaneStrain, ONLY: UEL1 => UEL
  USE CXU3D20, ONLY: UEL2 => UEL

!  Type declarations ...

  SELECT CASE( JTYPE )
    CASE (2001)
      CALL UEL1(Parameters)
    CASE (2002)
      CALL UEL2(Parameters)
  END SELECT
END SUBROUTINE
\end{lstlisting}
Note that the local renaming operator \lstinline|=>| is used here to distinguish the originally equally named module element routines. It may be remarked here that the interface of the module element routines has not inevitably to coincide with the Abaqus UEL interface. For instance module element routines may use assumed-shape arrays or may drop some irrelevant parameters.

\subsubsection{Multi-field problems}

Using the possibilities of Fortran 90/95 also multi-field problems may be implemented easily. For this purpose the shape function modules are loaded several times and the needed subroutines are renamed correspondingly. For instance for a coupled temperature-displacement element with quadratic shape functions for the displacements and linear ones for the temperature the frame could look like this:
\begin{lstlisting}
MODULE CXUT2D8M1
  USE  ShapeFunc2D_Square_Quad,&
    ONLY: ShapeFuncDispl => ShapeFunc, &
    ShapeFunDerivcDispl => ShapeFuncDeriv, &
    NNODESDISPL=>NNODES, NDIM
  USE  BMatrices2DPlaneStrain,&
    ONLY: BmatStrain => BMatTensSym, NDI, NSHR, NTENS
  USE  ShapeFunc2D_Square_Lin,&
    ONLY: ShapeFuncTemp => ShapeFunc, &
    ShapeFunDerivcTemp => ShapeFuncDeriv, NNODESTEMP=>NNODES
  USE  BMatricesScalar,  ONLY: BmatTemp => BMatScal
  IMPLICIT NONE
  PUBLIC::UEL
  CONTAINS
    INCLUDE "UelCXUT.f90"
END MODULE
\end{lstlisting}
Now the actual element routine in \file{UelCXUT.f90} can use the loaded routines like \lstinline|ShapeFuncDispl| and \lstinline|ShapeFuncTemp| which may be although identical if the same modules are loaded for temperature and displacement.

\section{Perspective and Problems}\label{sec:problems}

\subsection{Known problems}
\begin{itemize}
	\item For an unknown reason the UEL interface of Abaqus reserves arrays of different sizes for the generalized vectors of displacements and internal forces, namely \lstinline|U(NDOFEL)| and \lstinline|DIMENSION RHS(MLVARX,NRHS)| with \lstinline|NDOFEL| \emph{not} being equal to \lstinline|MLVARX| (actually, the latter is larger). If the implementation is done in Fortran 77 with all vector and matrix operations implemented via DO loops one does not need to care about this matter. However, if use of vector and matrix capabilities of Fortran 90/95 shall be made allowing a vectorization for an improved performance one has to take care. We recommend to introduce an additional array of suitable \lstinline|DIMENSION RHS_TEMP(NDOFEL,NRHS)| and finally copy the respective entries to the original array \lstinline|RHS| as it is done in the provided example.
\item
The provided subroutines should support complete parallelization since they do not use critical features like COMMON blocks, module variables or variables with SAVE attribute. However, at least under the tested environments the compiler options used by default by Abaqus do not permit parallelization. The compiler options are stored in the file "\file{ABQDIR/site/abaqus\_v6.env}". It has to be copied to the job directory. Within this file, the line \file{compile\_fortran="... -auto ..."} has to be changed to \file{compile\_fortran="... -openmp ..."}.
With this modification the computations can be run completely in parallel, i.e.\ for computing the element matrices and solving the final system of equations.
%Note that with \file{*Dynamic} step definitions only the global system of equations is solved in parallel by default.
\item Abaqus versions 2016 and later  employ the compiler option \lstinline|-fpp| by default. However, the Intel Fortran preprocessor \lstinline|fpp| does not recognize the compiler directive \lstinline|!DEC$ FREEFORM| which switches to free-form Fortran. In order to overcome this problem, either the switch \lstinline|-fpp| has to be removed in the line \file{compile\_fortran="..."} of the Abaqus environment \file{abaqus\_v6.env} or the compiler option \lstinline|-free| has to be set therein explicitly.
	\item The B-matrices for unsymmetric tensors are not verified yet.
\end{itemize}

\subsection{Future developments:}
\begin{itemize}
 \item second derivatives of shape functions as necessary e.g.\ for Euler-Bernoulli beam elements or Kirchhoff plate elements
 \item B-matrices for higher order tensors
 \item utilities for surface loads for implementing DLOAD routine with UELlib
 \item performance improvements
 \begin{itemize}
    \item usage of libraries like Intel MKL or LAPACK for mathematical utility routines
    \item hard coded derivatives of shape functions with respect to unit coordinates to improve the performance
    \item inline compilation of smaller utility routines
 \end{itemize}
 \item testing and verification with other compilers and under MS Windows
\end{itemize}

\section{Version History}

\tablehead{\hline Date        & SVN/GIT version	& editor &remarks\\ \hline}
\tabletail{\hline}
\begin{supertabular}{|l|p{0.10\textwidth}|p{0.06\textwidth}|p{0.6\textwidth}|}
2014/05/06  & 1           & GH     & framework with interfaces of routines only \\ \hline
2014/05/06  & 3           & GH     & first working version with example element by R.~Skrypnyk \\ \hline
2014/05/07  & 5           & GH     & added: Gauss point numbering as in Abaqus, separated B-matrices based on shape function gradient; modifications: changed naming of some modules and routines \\ \hline
2014/05/08  & 6           & GH     & elimination of minor bugs \\ \hline
2014/06/24  & 8           & GH     & added: shape functions and integration scheme for linear triangle element + example \\ \hline
2014/10/27  & 9           & GH     & added: shape functions and integration scheme for tetrahedra by RS \\ \hline
2015/04/22  &10           & GH     & added: quadratic shape functions for triangle element incl. integration schemes and shape functions and integration schemes for line elements by S.~Roth \\ \hline
2015/10/23  &18           & GH     & added: \file{Makefile}s for compiling \UELlib and the provided example elements (requiring some restructuring of the folders of the latter) \\ \hline
2015/10/26  &19           & GH     & changed: Use of Abaqus utility routine \lstinline|STDB_ABQERR()| for reporting errors in submitted material parameters for example element instead of \lstinline|WRITE()| \\ \hline
2015/11/06  &24           & GH     & \file{Makefile} now builds single object file \file{UEL\_lib-std.o}, which contains all modules, in folder \file{/bin} \\ \hline
2015/12/04  &27           & GH     & added some direct integration rules for quadrilateron (5,7,8 point) and hexahedron (14 points) \\ \hline
2017/02/17  &31           & GH     & removed: bug when calling \lstinline|inverse()| without optional argument \lstinline|det|; added: generic interface \lstinline|inverse| which can be called also as function \\ \hline
2017/10/23  &33           & SR     & B-matrices for axi- and spheri-symmetric elements \\ \hline
2018/02/07  &35           & GH     & added: "SFG" variant of B-matrices for axi-symmetric elements; few minor modifications and optimisations \\ \hline
2018/03/06  & 04dd530     & GH     & added: interface to \lstinline|PreFactor| to be accessible as function or subroutine, the latter providing the derivative w.~r.~t. \lstinline|radius| for large displacement analyses \\ \hline
2018/06/27  &             & GH     & added to documentation: hint regarding compiler options for Abaqus 2016 and later \\ \hline
\end{supertabular}

%\newpage
%\printbibliography[heading=bibintoc]

%%=========================================================================
\begin{thebibliography}{[10]}
%%=========================================================================
\bibitem{Roth2014}
\textsc{S.~Roth}, \textsc{G.~Hütter}, \textsc{M.~Kuna}: Simulation of fatigue crack growth with a cyclic cohesive zone model, International Journal of Fracture, 188 (2014), 23-45.

\bibitem{Huetter2016}
\textsc{G.~Hütter}, \textsc{R. Skrypnyk}: Micromorphic Homogenisation of a Porous Medium: Application to Size Effects and Quasi-Brittle Damage, Proceedings of Applied Mathematics and Mechanics 16 (2016), 347-348.

\bibitem{Huetter2017}
\textsc{G.~Hütter}: Micromorphic homogenisation and its application to a model of ductile damage, Proceedings of Applied Mathematics and Mechanics 17 (2017), 599-600.

\bibitem{Lange2021}% article
\textsc{N.~Lange}, \textsc{G.~Hütter}, \textsc{B.~Kiefer}: An efficient monolithic solution scheme for FE\textsuperscript{2} problems, \href{https://arxiv.org/abs/2101.01802}{arxiv.org/2101.01802}.

\end{thebibliography}

\end{document}