Site definition#

There are a number of site definition files which must be configured to make the Z-mat program additions work with ABAQUS. These will most likely be configured by NW Numerics during the installation.

The location of the abaqus executable to use is adjustable. There are two possibilities for defining the path. The first is to edit the file $Z7PATH/lib/Zmat/ABAQUS_ROOT and make an entry for the machine name (the name given via hostname) and the path to the ABAQUS installation directory. The second method is to define the environment variable ABAQUS_ROOT to point to the abaqus directory.

When launching the script will automatically link the Z-mat library and all plugins with the libZmat (unix) or zmat (win32 DLL) prefixes found in the standard search path (see the Zmaster/release manual reference section on search paths).

Unix configuration#

The most important issue for the Z-mat programs to work is the definition of an environment variable Z7PATH to point to the root directory of the Z-mat distribution (see release notes). The next important thing is to source the $Z7PATH/lib/Z7_cshrc file to set up additional environment variables. These two definitions can be put in a users .cshrc file for the C-shell.

The second most important environment variable is the Z7MACHINE variable. All the scripts which access binary executables use the Z7MACHINE variable to determine where and which binary to run. By default (if the variable is not set before sourcing the $Z7PATH/lib/Z7_cshrc file) the machine type will be set as setenv Z7MACHINE `uname`. Sometimes this is not sufficient to distinguish an architecture, so the user may add additional machine types. Additional architectures may be defined for different machines in the $Z7PATH/lib/MACHINE_TYPES file. This file is also used to define different compilers to be used. The Release Notes/Zmaster manual has more information in the Configuration chapter.

Windows configuration#

Aside from specifying the ABAQUS_ROOT position, no special work is needed for running Zmat on windows platforms. Only a command line interface is available however.

Interface files#

The fact that Z-mat is developed for use in Z-set (Zebulon FEA) natively, and that the interface with codes like ABAQUS is based on a Fortran subroutine implies that a certain amount of translation back and forth is required. Also, there are additional inputs required to control Z-mat outside of ABAQUS. The following figure outlines The interaction of different programs, and the use of input files.

The ABAQUS `.inp` file#

The use of an externally defined material behavior in ABAQUS requires a number of special entries to be made in the ABAQUS .inp file. Some of these entries are superfluous given the structure of the Z-mat library, but are nevertheless required to satisfy ABAQUS’s umat interface. The entries are:

*MATERIAL command to define the different materials of the problem. The name given to this command (using /*NAME=/) will be the name of an external file containing a Z-mat behavior definition (see previous section).
*DEPVAR command which establishes the storage per integration point for the material variables. This value must be greater or equal (best case) of the size determined by Z-mat for the behavior. There is no way except for user intervention to size this value, so the line must be included. If the value is too small for the behavior, an error message is printed in the .log file, and the calculation terminates.
*USER MATERIAL this defines that there is a user behavior. As as parameter to this command, one must give a CONSTANTS option, with at least one coefficient. This coefficient is not used in the Z-mat behavior however.

ABAQUS commands for initializing the state variables, giving a material orientation, and material coefficients are not used with Z-mat. There are instead alternatives which may be defined in the separate Z-mat material file (see the commands starting at page).

Output variables#

All the material variables should be available for output in ABAQUS calculations if the **external_storage option is not used. This should include the GRAD, FLUX, VINT and VAUX variables as shown with the Zpreload utility. The variables will all be stored as SDV variables.

There are some tricky spots which remain in the Z-mat output which may not be obvious to the new user. These are summarized below:

The shear components of symmetric tensional variables are natively stored with a factor of $\sqrt{2}$, which is removed by default at each exit of the z-mat routine. This operation takes up some CPU however, so it can be suppressed by using the ***state_var_shear_alter command. Also the default transformation for state variables is to change them to the real tensorial shear component. Engineering output is available by using the ***state_var_engineering_shear option. This is true for variables in the integrated vector and the auxiliary variables (VINT and VAUX variables). The GRAD and FLUX variables always have the factor removed however.
The integrated and auxiliary variables (VINT and VAUX) are stored sequentially in the vector prefixed sdv in ABAQUS.
For mechanical problems, the stress variable is named S and the strain E with all behavior as in ABAQUS standard.
Some extra variables such as the energy output variables are not yet calculated.

Extra files#

The compilation and linking of UMAT routines (Z-mat included) are controlled by parameters in the abaqus_v6.env file (located in the Site directory of the ABAQUS distribution.

Alterations must therefore exist in the active abaqus_v6.env file to link with the Z-mat library. An abaqus_v6.env to do this is supplied in the $Z7PATH/lib/Zmat/ directories. There is a default abaqus_v6.env file, and the option to have specific files for different machines (example files exist and it should be obvious how to manipulate these). The abaqus_v6.env file which is needed will be copied into the calculation directory in order to be the first read configuration file, and can thus be verified by looking at that file after an execution (possibly add comments to make the env file creation clearer).

The user can add configuration options in their customized personal files also. The standard abaqus_v6.env file will not be used in this case, replacing that with the file named zebaba_v6.env (replaced only for Zmat jobs). The Zmat program will search first in a users home directory, followed by the local execution directory.

The environment file shipped in the Z-mat for HP-UX is for example:

link_sl="Zmat -link_v6 /usr/ccs/lbin/ld64 -b -ashared_archive +k +n
     +FPD +vnocompatwarnings +pd L +pi D +s -c%E +h%U -o %U %F %A %B %L
     -lpthread -lcps -lcl"

compile_cpp="Zmat -compile_v6"
compile_fortran="Zmat -compile_v6"

In the standard Z-mat validation tests in the directory test/Z-mat/umat_v61 we have the custom file zebaba_v6.env with the following:

ask_delete=OFF
split_dat=ON

For personal files one may wish to remove the ask_delete parameter.

User additions#

Extensions to Z-mat#

User functions and classes may be added to the Z-mat library without limit. This is one of the advantages of working with Z-mat, as a site can create a library of user functionality in combination with Z-mat, and use it repeated without distributing the source files for each problem run. Also, the user classes will be automatically available to the simulation and optimization methods, creating a coherent extensible modeling environment.

In order to make user-additions to Z-mat, a custom shared library must be compiled and installed into the proper location with the proper name. For running Z-mat with other ABAQUS, the shared library must be named libZmat*.so where * is replaced by a user designated character filename. On HP-UX systems the suffix is .sa and on AIX it is .a. Files fitting the above wildcard name will be automatically loaded using the system dlopen command (or equivalent). The search path is:

the current working directory.
the path pointed to by the environment variable ZEBU_PATH
the default binary location $Z7PATH/PUBLIC/lib-$Z7MACHINE

More detail about the compiling process is given in the developer handbook, and there is always a pre-configured user-project in the installation directory $Z7PATH/User-project .

ABAQUS user routines#

The Z-mat package uses the ABAQUS UMAT function to interface with that FEA solver. This does not prevent one from programming extra user routines to run along with Z-mat. If the user routines are unrelated to the material (such as user loads or MPCs), an extra Fortran file can simply be appended to the Z-mat interface by using the Zmat option -uf. An example is provided in the +$Z7PATHtest/Z-mat/UMAT+ directory as problem 4020201. The execution is for example:

Zmat -fg -uf mpc.f 4020201

which will link in the user routines in mpc.f.

The user can override the default UMAT interface as well, by modifying the file +$Z7PATHlib/Zmat/mech-sd.c+ and using the -UF command switch.

Example#

This is an example material file which can be used with Z-mat. Note that all input is case sensitive!

This example has the material definition in the file e3danis. The following lines are the material related entries for the ABAQUS .inp input file:

*MATERIAL,NAME=e3danis
*DEPVAR
   20
*USER MATERIAL,CONSTANTS=1
0.0
*SOLID SECTION,MATERIAL=e3danis,ELSET=A1

Note that this syntax is very sensitive to positions, and connectivity. Commands are not case sensitive, but filenames may be. The command *DEPVAR allocates in ABAQUS storage for the material variables at each Gauss point. There is no way to dimension this quantity from the UMAT routine, so the user is obliged to enter the correct number corresponding to the material model used. Information concerning this quantity will be printed to the .log file generated by the ABAQUS output.

***material
  *integration runge_kutta 1.e-3 1.e-3
***behavior gen_evp
 **thermal_strain isotropic
    alpha  temperature
      2.0e-06    -0.1
      1.0e-06  1000.1
**elasticity isotropic
    young 200000.
    poisson 0.25
**potential gen_evp ev
   *criterion mises
   *flow norton
     n 4.0
     K 500.
   *kinematic nonlinear % x1
     C 10000.0
     D 100.0
   *isotropic constant
     R0 100.e+00
***return

For this material file, the output of the Zpreload program shows the material variables and their associated ABAQUS output variables.

============================================
Flux Name:
  sig11  sig22  sig33  sig12  sig23
  sig31

Grad Name:
  eto11  eto22  eto33  eto12  eto23
  eto31

var_int Name:
  eel11(sdv1) eel22(sdv2) eel33(sdv3) eel12(sdv4) eel23(sdv5)
  eel31(sdv6)
  evcum(sdv7)
  al111(sdv8) al122(sdv9) al133(sdv10) al112(sdv11) al123(sdv12)
  al131(sdv13)

var_aux Name:
  evi11(sdv14) evi22(sdv15) evi33(sdv16) evi12(sdv17) evi23(sdv18)
  evi31(sdv19)
============================================

Site definition

On this page