Introduction#

This manual covers the interfaces for developing material laws and FEA methods in Zebulon/Z-mat. Unlike other FEA codes which provide specific user routines to be re-defined, Z-mat and Z-set come with full featured application programming interfaces API, and a custom build environment. On unix machines makefiles are generated automatically, and on windows platforms a Microsoft Visual Studio project is generated, with all appropriate options set.

The API allows the user to make developments which span the whole range of analysis, adding for example new material behaviors, elements, post calculations, and even meshing and visualization options in the Zmaster program (without knowing GUI programming). The code is supplemented with many example additions in the form of our plug-in source repository, and ZebFront example files.

If there are specific issues of interest which are not documented, please feel free to inquire about them through the technical support hotline or e-mail.

Code Changes#

Zebulon/Z-mat are products under intensive development, and the code reflects this. All programs and utilities within Zebulon are done in C++ and use the same base classes. We emphasis modularity in design, but are not currently making any attempt to provide a static (fixed) interface design. This means that we will feel free to modify class implementations and interfaces as seen fit to allow rapid advancement of the code. The best way to avoid this constant change is to use ZebFront where ever it is implemented.

Environment#

The most classical error with Zebulon is the incorrect setting of environment variables, or mixing versions (a script from one version trying to run with a different $Z7PATH. Please make sure that you change versions cleanly:

setenv Z7PATH `pwd`
source $Z7PATH/lib/Z7_cshrc

Make sure that the desired version is listed before others in your path and LD_LIBRARY_PATH variable (or SHLIB_PATH on HP-UX or LIBPATH on AIX).

Compiler options#

Compiler options can be set in a variety of ways. First, when compiling (using Zmake) the script looks for an entry in $Z7PATH/lib/MACHINE_TYPES headed by the hostname. If so found, it will take the compiler and associated options from there. This file lets any computer use any options as required. If the file is not there, or the current machine is not listed, the script will look through the compilers listed in $Z7PATH/lib/COMPILER_DEFS, and use the first one found.

Additional options and link libraries can be found in files named $Z7PATHlib/Makefile.XXX/ The exact file of interest is indicated in your project library_files file. These Makefile headers may in turn include additional files, such as $Z7PATH/lib/Motif_lib_$(Z7MACHINE).

Why libraries#

The use of shared libraries allows different configurations of Zebulon/Z-mat to be built, and user additions to be made. For use with other codes such as in Z-mat for ABAQUS, the libraries alleviate the need for a compiler when running ABAQUS. The following summarizes the different component libraries in Zebulon.

The libraries are found in $Z7PATH/PUBLIC/lib-$Z7MACHINE. Static libraries end with .a (except on AIX, where these are shared) and shared libraries ending in .so (or .sl on HP-UX or .a on AIX). For windows platforms the libraries are called Dynamic linked libraries or DLLs. They are found in the $Z7PATH\win32 directory.

Foundations#

library of just the tools items. Not used for Z-set, but useful for making utility programs. Utility Library of items used in the Z-mat product, including optimization and simulation. Library of items used in Z-set, and the Zmaster interface. Not used when executing Z-mat.

User plug-ins#

Plug in functionality is added by making extra libraries which are loaded dynamically. The libraries will be searched in for first in the $Z7PATH/PUBLIC/lib-$Z7MACHINE directory on unix systems, or in $Z7PATH/win32 for windows systems, followed by any libraries in the directory pointed to by $ZEBU_PATH and finally in the current working directory of the problem.

User library plug-ins which will be loaded for Z-mat and Z-set applications. Any other library in the search path not included

Running Zmat will cause only shared libraries named Zmat*.so (or Zmat*.dll, etc) to be loaded. Otherwise the software will load all extra libraries found (not part of the standard distribution), if possible. If the library causes an undefined symbol or other error, it will not be loaded. There are messages issued at the beginning of the program launch indicating what is getting loaded.

Example project#

There is an example project in the test directory $Z7PATH/User_project/ Please note that the format of the projects in this directory may change from version to version. Each time you upgrade, you should at least look for differences in the configuration and source, and possibly re-build your personal project using the new User_project directory of interest.

In these projects, there are different ways of making user additions. The most common (recommended) way is to build shared libraries, which will be loaded dynamically as plug-ins (see above).

An example unix configuration file for 2 libraries, one for Z-mat use and one for general Z-set use follows (from the example directory). The file name by default is library_files but one can use any file by executing Zsetup -ffile.

%
% User-project/library_files
%
!MESSAGE User Z7 project

% !TOP Makefile.top
!TOP Makefile.Motif.c++

!DYNAMIC
!CFLAGS -I${Z7PATH}/include
!BFLAGS -L${Z7PATH}/PUBLIC/lib-${Z7MACHINE}

!MAKE target: lib

!INC   material
!SRC   material material
!INC   finite_element
!SRC   finite_element finite_element
!DEBUG material finite_element

!LIB Zmat_utest material
!LIB Zfem_utest finite_element

!!RETURN

Any time a new file is added, the makefile should be re-generated using the Zsetup command.

The file for Win32 development is different. Unfortunately the options and linking libraries are somewhat complicated here, but the standard default file should work as-is for most cases.

%
% User-project/proj.zpr
%
% !ALLOW_DEBUG
!VCPP  6.00
!OPT   CPP /D "ZEXCEPTIONS" /Tp /D "DLL2" /D "_WIN32" /I "include"
!O_OPT CPP /O2 /D "NDEBUG"
!D_OPT CPP /D "ZCHECK" /Od /D "NDEBUG" /Zi

!OPT LINK32 /NODEFAULTLIB kernel32.lib user32.lib gdi32.lib winspool.lib
comdlg32.lib advapi32.lib shell32.lib rpcrt4.lib ole32.lib oleaut32.lib
uuid.lib odbc32.lib odbccp32.lib   libcimt.lib LIBCMT.lib OLDNAMES.lib
libcpmt.lib msvcrt.lib /INCREMENTAL:YES /debug

!DLL zmat_test_models
!GROUPS
   material
!USE
   zmat_base

!OPT LINK32 /NODEFAULTLIB kernel32.lib user32.lib gdi32.lib winspool.lib
comdlg32.lib advapi32.lib shell32.lib rpcrt4.lib ole32.lib oleaut32.lib
uuid.lib odbc32.lib odbccp32.lib   libcimt.lib LIBCMT.lib OLDNAMES.lib
libcpmt.lib msvcrt.lib MFC42.LIB /INCREMENTAL:YES /debug

!DLL zfem_test_models
!GROUPS
   finite_element
!USE
   zmat_base
   zfem_base
!!RETURN

Patching Auto-loaded Classes#

Plug-in additions to the code are interfaced with the standard libraries through the Object-factory interface (see page ). This interface loads keyword to class creation mappings, and will look for existing entries before adding a new one. If a keyword exists beforehand, it will be replaced by the new one. It is important however that the class name (the C++ name) be different. Since the shared libraries are loaded after the program starts executing, this allows patches to be very easily made.

Introduction

On this page