ABAQUS User subroutines Overview

User subroutines:

• • •

• •

are provided to increase the functionality of several ABAQUS capabilities for which the usual data input methods alone may be too restrictive; provide an extremely powerful and flexible tool for analysis; are typically written as FORTRAN code and must be included in a model when you execute the analysis, as discussed below; must be included and, if desired, can be revised in a restarted run, since they are not saved to the restart files (see “Restarting an analysis,” Section 7.1.1); cannot be called one from another; and can in some cases call utility routines that are also available in ABAQUS (see “Utility routines: overview,” Section 26.1.1).

Including user subroutines in a model

You can include one or more user subroutines in a model by specifying the name of a FORTRAN source or object file that contains the subroutines. Details are provided in “Execution procedure for ABAQUS/Standard and ABAQUS/Explicit,” Section 3.2.2. Input File Usage: Enter the following input on the command line:

abaqus job=job-name user={source-file | object-file} ABAQUS/CAE Usage: Job module: job editor: General: User subroutine file

Managing external databases in ABAQUS/Standard and exchanging information with other software

In ABAQUS/Standard it is sometimes desirable to set up the FORTRAN environment and manage interactions with external data files that are used in conjunction with user subroutines. For example, there may be

inc and vaba_param. which compiles and links the user subroutine with the rest of ABAQUS.inc' as the first statement after the argument list. Such operations can be performed with user subroutine UEXTERNALDB (“UEXTERNALDB. the rules and guidelines below should be followed. This user interface can potentially be used to exchange data with another code. the user should specify the above include statement in all the subroutines to preserve precision. It is not necessary to find the file and copy it to any particular directory. If variables are exchanged between the main user subroutine and subsequent subroutines. Every ABAQUS/Explicit user subroutine must include the statement include 'vaba_param. Naming convention . to include the aba_param. Writing a user subroutine User subroutines should be written with great care.inc or vaba_param. Required INCLUDE statement Every ABAQUS/Standard user subroutine must include the statement include 'aba_param.inc are installed on the system by the ABAQUS installation procedure and contain important installation parameters. allowing for “stagger” between ABAQUS/Standard and another code.history-dependent quantities to be computed externally. The files aba_param. ABAQUS will know where to find it.inc file automatically.2.21). or output quantities that are accumulated over multiple elements in COMMON block variables within user subroutines may need to be written to external files at the end of a converged increment for postprocessing. To ensure their successful implementation. These statements tell the ABAQUS execution procedure. once per increment.inc' as the first statement after the argument list. for use during the analysis.” Section 25.

You must open these FORTRAN units. Compilation and linking problems If problems are encountered during compilation or linking of the subroutine. debug output can be written to the ABAQUS/Standard message (.If user subroutines call other subroutines or use COMMON blocks to pass information. Mismatches in type or number of arguments may lead to platform-dependent linking or runtime errors. Testing and debugging When developing user subroutines.1. These commands should have been set up by the ABAQUS site manager during installation. and because of the use of scratch directories. test them thoroughly on smaller examples in which the user subroutine is the only complicated aspect of the model before attempting to use them in production analysis work. make sure that the ABAQUS environment file (the default location for this file is the site subdirectory of the ABAQUS installation) contains the correct compile and link commands as specified in the ABAQUS Installation and Licensing Guide. Redefining variables User subroutines must perform their intended function without overwriting other parts of ABAQUS. the full pathname for the file must be used in the OPEN statement. The use of other FORTRAN units may interfere with ABAQUS file operations. If needed. In particular.sta) file using FORTRAN unit 6. FORTRAN units 15 through 18 or units greater than 100 can be used to read or write other user-specified information. these units should not be opened by your routines since they are already opened by ABAQUS.” Redefining “variables passed in for information” will have unpredictable effects. you should redefine only those variables identified in this chapter as “variables to be defined.7. The number and type of arguments must correspond to what is specified in the documentation. such subroutines or COMMON blocks should begin with the letter K since this letter is never used to start the name of any subroutine or COMMON block in ABAQUS.” Section 3.dat) file or the ABAQUS/Explicit status (. Terminating an analysis . see “FORTRAN unit numbers used by ABAQUS.msg) file using FORTRAN unit 7 or to the ABAQUS/Standard data (.

2. These numbers are global in nature.5).9. If the original number and the part instance name are required. not in a part-local coordinate system. or “Transformed coordinate systems. Another utility subroutine. a new local coordinate system was created relative to the assembly (global) coordinate system.5. As a result. all variables (such as current coordinates) are passed to a user subroutine in the global coordinate system.(CALL XIT or CALL XPLB_EXIT) Models defined in terms of an assembly of part instances An ABAQUS model can be defined in terms of an assembly of part instances (see “Defining an assembly. This new coordinate system definition is the one used for local orientations in user subroutines.2. can be used to retrieve the internal node or element number corresponding to a given part instance name and local number.4).1. . call the utility subroutine GETPARTINFO (ABAQUS/Standard) or VGETPARTINFO (ABAQUS/Explicit) from within your user subroutine (see “Obtaining part information.” Section 26.” Section 26. all internal node and element numbers are unique. This will ensure that all files associated with the analysis are closed properly (“Terminating an analysis. but it was transformed according to the positioning data given for the part instance.” Section 2.” Section 2.” Section 2.12). The only exception to this rule is when the user subroutine interface specifically indicates that a variable is in a user-defined local coordinate system (“Orientations.1). The local coordinate system originally may have been defined relative to a part coordinate system. so minimal use of them is recommended.Utility routine XIT (ABAQUS/Standard) or XPLB_EXIT (ABAQUS/Explicit) should be used instead of STOP when terminating an analysis from within a user subroutine. The expense of calling these routines is not trivial. Node and element numbers The node and element numbers passed to a user subroutine are internal numbers generated by ABAQUS.2. GETINTERNAL (ABAQUS/Standard) or VGETINTERNAL (ABAQUS/Explicit). Reference coordinate system Although a local coordinate system can be defined for each part instance.

” Section 25.” Section 25.” Section 25.2.2.39 “UTRS.2.” Section 25. which may also be needed in the constitutive routines and can vary with .8 “HETVAL.12 “UEL.28 “UMAT.3.” Section 25.2.” Section 25.30 “UMATHT.2.4 The state variables can be defined as a function of any other variables appearing in these subroutines and can be updated accordingly.31 “UMULLINS.” Section 25.” Section 25.” Section 25.2 “VUINTER. Defining and updating Any number of solution-dependent state variables can be used in the following user subroutines: • • • • • • • • • • • • • • • • • “CREEP. a surface named surf1 belonging to part instance Part1-1 in assembly Assembly1 will be passed to a user subroutine as Assembly1_Part1-1_surf1 Solution-dependent state variables Solution-dependent state variables are values that can be defined to evolve with the solution of an analysis.” Section 25.34 “USDFLD.2. Solutiondependent state variables should not be confused with field variables.27 “UINTER.20 “UGENS.” Section 25.” Section 25.42 “VFRIC.2.2.2.19 “UEXPAN.3.” Section 25.” Section 25.24 “UHARD.1 “FRIC.2.2.25 “UHYPER.2.Set and surface names Set and surface names passed to user subroutines are always prefixed by the assembly and part instance names.2.” Section 25.” Section 25.” Section 25. separated by underscores.3 “VUMAT. For example.3.2.

VARIABLES=number of variables For subroutines FRIC and VFRIC: *FRICTION. Solution-dependent state variables used in VFRIC and VUINTER are defined as state variables at slave nodes and are updated with other contact variables. the *DEPVAR option is not used. Solution-dependent state variables can be shared by subroutines within the same group.time. they cannot be shared between subroutines belonging to different groups. VARIABLES=number of variables For subroutine UGENS: *SHELL GENERAL SECTION. Input File Usage: For most subroutines the number of such variables required at the points or nodes is entered as the only value on the data line of the *DEPVAR option. field variables are discussed in detail in “Predefined fields. Separate user subroutine groups have been identified that differ in the way the number of solution-dependent state variables is defined.6.1. which should be included as part of the material definition for every material in which solution-dependent state variables are to be considered: *DEPVAR For subroutines that do not use the material behavior defined with the *MATERIAL option. Allocating space You must allocate space for each of the solution-dependent state variables at every applicable integration point or contact slave node. For subroutine UEL: *USER ELEMENT. DEPVAR=number of variables . USER. USER.” Section 19. These groups are described below.

USER . See “SDVINI.For subroutines UINTER and VUINTER: *SURFACE INTERACTION.” Section *INITIAL CONDITIONS. for additional details.2.fil). the output database file (. USER. Defining initial values directly You can define the initial values in a tabular format for elements and/or element sets.1. DEPVAR=number of variables ABAQUS/CAE Us For most subroutines the number of such variables age: required at the points or nodes is entered as part of the material definition for every material in which solutiondependent state variables are to be considered: Property module: material editor: General Depvar: Number of solution-dependent state variables Defining initial values You can define the initial values of solution-dependent state variable fields directly or in ABAQUS/Standard through a user subroutine.16.dat). can be used in the definition of the variable field. and the results file (. See “Initial conditions. Input File Usage: Output User-defined.” Section 19. TYPE=SOLUTION. The initial values of solution-dependent state variables for contact in ABAQUS/Explicit are assigned as zero internally.2. etc.” Section 25. TYPE=SOLUTION Defining initial values in a user subroutine in ABAQUS/Standard For complicated cases in ABAQUS/Standard you can call user subroutine SDVINI so that dependencies on coordinates. solution-dependent state variables can be written to the data file (. the output identifiers SDV and SDVn are available as element integration variables (see “ABAQUS/Standard output variable identifiers.odb). element numbers. for additional details. Input File Usage: *INITIAL CONDITIONS.

which means that blocks of data are passed to the user subroutines.” Section 3.” Section 25. the maximum block size. state variables. and “ABAQUS/Explicit output variable identifiers. Alphanumeric data Alphanumeric data. If the user subroutine requires the dimensioning of temporary arrays. Upper case must be used for all such comparisons.2).4. For example. The variable CMNAME is compared against MAT1 and MAT2 (even in situations where the material names may have been defined as mat1 and mat2. respectively. such as labels (names) of surfaces or materials. for nblock material points.30. All variables in the user subroutines that start with the letters a to h and o to z will automatically be defined in the precision of the executable that you run. An example of such a comparison can be found in “UMAT. ABAQUS/Explicit is run in the native precision of the machine.) Precision in ABAQUS/Explicit ABAQUS/Explicit is installed on all 32-bit floating point word systems with both single precision and double precision executables and on 64-bit floating point word systems as a single precision executable. the vectorized user material routine (VUMAT) is passed stresses. etc.2. These variables are not available for user subroutines VFRIC and VUINTER. The precision of the executable is defined in the vaba_param. and it is not necessary to define the precision of the variables explicitly.1.2. they can be dimensioned by maxblk.2). .inc is maxblk. One of the parameters defined by vaba_param. you must specify double precision when you run the analysis (see “Execution procedure for ABAQUS/Standard and ABAQUS/Explicit. Vectorization in ABAQUS/Explicit ABAQUS/Explicit user subroutines are written with a vector interface. To use the double precision executable on 32-bit machines.” Section 4. By default. As a result.2. strains. direct comparison of these labels with corresponding lower-case characters will fail. are always passed into user subroutines in the upper case. It illustrates the code setup inside user subroutine UMAT when more than one userdefined material model needs to be defined.inc file.2.

the use of common block statements in the user subroutines or in subroutines called by the user subroutines must be avoided since it will result in unpredictable behavior of the executable.3. or slave surface node at the end of each increment. or interface behavior two extra times for each material point. or slave surface node prior to the zero increment. However. . However. ABAQUS/Standard must call these user subroutines one extra time for each material point. when used in plane stress analyses. UHYPER. in transient implicit dynamic analyses (“Implicit dynamic analysis using direct integration. or slave surface node in the first iteration of every increment such that the model's initial stiffness matrix can be formulated appropriately for the step procedure chosen. element. The extra calls to the user subroutines are not made if the initial acceleration calculations are suppressed. By default.” Section 6. The subroutines are called only once per material point. User subroutine calls Most of the user subroutines available in ABAQUS are called at least once for each increment during an analysis step. element. User subroutines UHARD. ABAQUS/Standard must call user subroutines that are used to define material. the extra call to the user subroutines is not made. are called more often. and UMULLINS.2) ABAQUS/Standard calculates accelerations at the beginning of each dynamic step. element. many subroutines are called more or less often. Subroutines that define material.Parallelization in ABAQUS/Explicit User subroutines can be used when running ABAQUS/Explicit in parallel. element. UHYPEL. If the calculation of the half-step residual is suppressed. element. element. If the half-step residual tolerances are being checked in a transient implicit dynamic step. or interface behavior Most user subroutines that are used to define material. element. or slave surface node in each succeeding iteration within the increment. or interface behavior are called twice per material point. as discussed below.

2.2. 附 1:用户子程序 ABAQUS/Standard subroutines • • • • • • • • • • • “CREEP.” Section 25.” Section 25.2. this information can be obtained upon testing the subroutine on a small example. and they can be printed out as debug output (also discussed earlier).1. as suggested earlier.Subroutines that define initial conditions or orientations User subroutines that are used to define initial conditions or orientations are called before the first iteration of the first step's initial increment within an analysis.2 “DFLUX.2. The current step and increment numbers are commonly passed into these subroutines.2.2.” Section 4.msg) file (“Output. Subroutines that define predefined fields User subroutines that are used to define predefined fields are called prior to the first iteration of the relevant step's first increment for all iterations of all increments whenever the current field variable is needed.2.” Section 25.2.” Section 25. provided that the output to the message file is written at every increment.3 “DISP.” Section 25.4 “DLOAD. the location of the output within this file will give the iteration number. however.1).” Section 25.” Section 25. Verification of subroutine calls If there is any doubt as to how often a user subroutine is called.2.10 “HARDINI.7 “FRIC.8 “GAPCON.2.” Section 25.1 “DFLOW.11 .” Section 25. if printed output is sent from the subroutine to the message (.” Section 25.2.5 “FILM.9 “GAPELECTR.” Section 25.6 “FLOW. The iteration number for which the subroutine is called may not be passed into the user subroutine.

” Section 25.2.” Section 25.2.28 “UMASFL.2.2 “VUINTER.” Section 25.2.36 “UPSD.22 “UFLUID.3.• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • “HETVAL.” Section 25.” Section 25.2.2.” Section 25.” Section 25.2.” Section 25.32 “UMOTION.” Section 25.2.” Section 25.18 “UEL.” Section 25.” Section 25.35 “UPRESS.2.38 “USDFLD.” Section 25.16 “SIGINI.2.2.33 “UMULLINS.37 “URDFIL.44 “VOIDRI.” Section 25.12 “MPC.24 “UHARD.” Section 25.” Section 25.” Section 25.2.” Section 25.3.2.2.” Section 25.40 “UTRACLOAD.20 “UEXTERNALDB.45 ABAQUS/Explicit subroutines • • • • “VDLOAD.42 “UVARM.” Section 25.” Section 25.41 “UTRS.” Section 25.” Section 25.2.” Section 25.39 “UTEMP.23 “UGENS.” Section 25.2.2.29 “UMAT.4 .31 “UMESHMOTION.13 “ORIENT.27 “UINTER.” Section 25.21 “UFIELD.” Section 25.2.15 “SDVINI.2.2.26 “UHYPER.2.30 “UMATHT.” Section 25.2.” Section 25.2.2.3.” Section 25.34 “UPOREP.” Section 25.2.2.” Section 25.2.3 “VUMAT.” Section 25.” Section 25.2.” Section 25.” Section 25.3.19 “UEXPAN.2.” Section 25.2.2.43 “UWAVE.2.1 “VFRIC.14 “RSURFU.2.25 “UHYPEL.17 “UCORR.” Section 25.2.

log or .dat) file (You can write output to this file. You should specify unit numbers 15–18 or unit numbers greater than 100.msg) file (You can write output to this file.附 2:程序内部文件号 FORTRAN unit numbers used by ABAQUS ABAQUS uses the FORTRAN unit numbers outlined in the table below.res) file 19–30 Internal databases (scratch files).sel) file Message (. FORTRAN unit numbers Code ABAQUS/Stand ard Unit Description Number 1 2 6 7 8 10 12 Internal database Solver file Printed output (.bsp) Code ABAQUS/Explicit Analysis Unit Description Number 6 60 61 62 63 64 Printed output (.) Package (.) Message (.msg) file .fil) file Internal database Restart (. Unit numbers 21 and 22 are always written to disk.abq) file Temporary file Selected results (.pac) file State (.sta) file (You can write output to the . 73 Text file containing meshed beam cross-section properties (. Unless noted otherwise.sta file.) Results (. you should not try to write to these FORTRAN units from user subroutines.

temporary file Restart (.sel) file Internal database.023) file Package (.pac) file State (.abq) file Temporary file Selected results (. temporary file 12 23 60 61 62 63 69 ABAQUS/Explicit Packager .Code Unit Description Number 69 Internal database.res) file Communications (.

Sign up to vote on this title
UsefulNot useful