Technical Overview

This section provides general information about the CEETRON SAM SDKs distribution, how to build and link it, and valuable information on various programming topics.

Application Development Environment

Each library contains a set of object oriented modules which implement the functionality of a particular library. Modules are object-based in that they support the encapsulation of a set of functions and data within an object, so that the data is only accessible though a well defined interface. A module (also termed a “class” in object-oriented technology) also supports the instantiation of multiple objects, each with its own private data. An object may be destroyed at any time, freeing its private data and local memory resources.

The application programming interface (API) consists of a header file and a series of entry points defining the functional interface (also termed “methods” in object-oriented technology) for each module. The private data for each module is defined in a C language structure, struct, which is a defined type, typedef. In order to avoid naming conflicts, all function names and defined types of the modules delivered with CEETRON SAM begin with vut_, vml_, vsy_, vis_, vgl_, vfe_, vfs_, vdm_ or vfx_. The four character prefix is followed by the module and function name in initial capital letters. For example the function to draw contours on a curvilinear array of computational cells in VisTools is vis_ContourCurv(). All arguments to module functions are either simple variables, arrays or pointers to structures containing the private data of an object. Each module contains functions to begin and end an instance of the module. For example to create a Contour object use vis_ContourBegin(). This function allocates an instance (an object) of the module and returns a pointer (object handle) to a struct containing the private data of the object. If object creation fails, a NULL pointer is returned. The end function destroys the object and frees its memory resources. For example, use vis_ContourEnd() to destroy a Contour object.

Directory Structure

All CEETRON SAM component source libraries require the base source library as a foundation. The installation procedure for CEETRON SAM creates the following directory structure under the devtools directory. The libraries which appear are site dependent.

devtools - CEETRON SAM MAKEDEFS for built-in make system
devtools/lib - Empty directory for CEETRON SAM archives
devtools/src/base - CEETRON SAM base source and header files
devtools/src/base/ext - CEETRON SAM ZLIB source
devtools/src/base/exam - CEETRON SAM base examples
devtools/src/vgl - VglTools source and header files
devtools/src/vgl/exam - VglTools examples
devtools/src/vgl/ext - VglTools PNG, TIFF, JPEG source
devtools/src/vgl/fonts - VglTools FreeType font files
devtools/src/vgl/test - VglTools feature and performance tests
devtools/src/vis - VisTools source and header files
devtools/src/vis/exam - VisTools examples
devtools/src/vdm - VdmTools source and header files
devtools/src/vdm/exam - VdmTools examples
devtools/src/vfe - VfeTools source and header files
devtools/src/vfe/exam - VfeTools examples
devtools/src/vfs - VfsTools source and header files
devtools/src/vfs/exam - VfsTools examples
devtools/src/vfx - VfxTools source and header files
devtools/src/vfx/exam - VfxTools examples

In addition to the above directories, each toolkit directory contains subdirectories “fortran”, “cplusplus”, and “csharp” that contain the bindings for FORTRAN, C++, and C#, respectively.

Each CEETRON SAM module exists as a source file (.c or .cxx) and associated header file (.h) in the source directory. For example the Contour module source and header files are contour.c and contour.h respectively and reside in the VisTools src/vis directory. There are additional source and header files which contain internal utility procedures and CEETRON SAM-wide macro definitions.

The base directory contains all the foundation module source and header files for all CEETRON SAM components. Examples of foundation modules are Error, List and Stack.

The lib directory contains a set of subdirectories which are empty at initial installation. They may be used to place object or archive files resulting from compiling CEETRON SAM components on a specific platform.

The Built-in CMake System - CMake 

The built-in CEETRON SAM CMake system is the easiest way to compile and link with CEETRON SAM. To compile CEETRON SAM and its example programs, follow these steps:

Create a new directory named build using the command:

mkdir build

Change your current directory to the build directory you just created with the command:

cd build

Generate build files for your project. If you are on Windows, use the following command:

cmake --preset=Windows ..

If you are on Linux, use this instead:

cmake --preset=Linux ..

Build your project using the generated build files with the command:

cmake --build .

If you are on Linux, you’ll need to add the path of the dependencies in the thirdparty directory to the LD_LIBRARY_PATH environment variable. This allows the dynamic linker to find them at runtime. Here’s an example of how to do this:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/techsoft3d/CeetronSAM/thirdparty/abaqus-odb_api-2023-linux64/lib

Replace /home/techsoft3d/CeetronSAM/thirdparty/abaqus-odb_api-2023-linux64/lib with the actual path to your thirdparty directory.

The ThirdParty packages included in the distribution - CMakePreset 

There are a variety of C preprocessor definitions which are used to conditionally compile source code. The following definitions are set when using the predefined CMake Preset.

CEE_SAM_PROJECT_NAME	: “CeetronSAM”	Project Name
CMAKE_BUILD_TYPE	: “Release”	Build type
CEE_SAM_VERBOSE_LOGGING	: “OFF”	Verbose logging flag
CEE_SAM_BUILD_CONFIGURATION	: “Static”	Build configuration. Static, Shared for Windows available. Only Static for Linux
CEE_SAM_BASE	: “ON”	Add base src directory
CEE_SAM_VDM	: “ON”	Add vdm src directory (CEETRON Access)
CEE_SAM_VIS	: “ON”	Add vis src directory (CEETRON GlobalModules, MESH, legacy visualization)
CEE_SAM_VFE	: “ON”	Add vfe src directory (CEETRON Solve)
CEE_SAM_VFS	: “ON”	Add vfs src directory (CEETRON Solve)
CEE_SAM_VFX	: “ON”	Add vfx src directory (CEETRON Solve)
CEE_SAM_VGL	: “ON”	Add vgl src directory (VKI legacy visualization)
CEE_SAM_DATA_PROVIDER_FRAMEWORK	: “ON”	Link against the Data Provider Framework
CEE_SAM_EXAMPLES	: “ON”	Add Examples in the current project
CEE_SAM_INTERFACE_FORTRAN	: “OFF”	Generate Fortran interface
CEE_SAM_INTERFACE_CSHARP	: “OFF”	Generate C# interface
CEE_SAM_READER_ABAODB	: “ON”	Link against Abaqus ODB API external library
CEE_SAM_READER_ALTAIR_H3D	: “OFF”	Link against Altair H3D API external library
CEE_SAM_READER_ANSYS_DPF	: “ON”	Link against ANSYS DPF API external library
CEE_SAM_READER_OPENFOAM	: “ON”	Toggle support for OpenFOAM files. Requires linking with zlib.
CEE_SAM_READER_PERMASLIB	: “ON”	Toggle support for PERMAS files. Requires linking with zlib.
CEE_SAM_READER_CGNS	: “ON”	Link against CGNS API external library
CEE_SAM_READER_PAMLIBERF	: “OFF”	Link against PAM API external library
CEE_SAM_READER_SAMCEF	: “OFF”	Link against SAMCEF API external library
CEE_SAM_OPTION_BOOST	: “OFF”	Link against Boost (required for Autodyn library)
CEE_SAM_OPTION_CAPRI	: “OFF”	Link against CAPRI
CEE_SAM_OPTION_CHECK_ERRS	: “ON”	Include additional error checking
CEE_SAM_OPTION_CHECK_FPE	: “OFF”	Check floating-point exceptions
CEE_SAM_OPTION_CHECK_MEM	: “OFF”	Include memory checks
CEE_SAM_OPTION_FFMPEG	: “OFF”	Link against FFMPEG (required for vglTools)
CEE_SAM_OPTION_FREETYPE	: “OFF”	Link against FREETYPE (required for vglTools)
CEE_SAM_OPTION_GLEW	: “OFF”	Link against GLEW (required for VGL)
CEE_SAM_OPTION_HDF5	: “ON”	Link against HDF5 external library (required for CGNS reader)
CEE_SAM_OPTION_HOOPS	: “OFF”	Link against HOOPS Exchange (option for CEETRON MESH)
CEE_SAM_OPTION_INTEL_MKL	: “ON”	Link against MKL (required for the eigensolver)
CEE_SAM_OPTION_INTEL_MKL_MULTITHREAD	: “ON”	Link against MKL (required for the eigensolver)
CEE_SAM_OPTION_JTTK	: “OFF”
CEE_SAM_OPTION_MPI	: “OFF”
CEE_SAM_OPTION_MUMPS	: “OFF”
CEE_SAM_OPTION_OPENGL	: “OFF”
CEE_SAM_OPTION_OPENMP	: “ON”	Link against OPENMP
CEE_SAM_OPTION_OPENMP_VERSION	: “Intel”	OpenMP version: Intel or Default
CEE_SAM_OPTION_OPEN_CASCADE	: “OFF”
CEE_SAM_OPTION_PARASOLID	: “OFF”
CEE_SAM_OPTION_POLYGONICA	: “OFF”
CEE_SAM_OPTION_PROSOLVE	: “OFF”
CEE_SAM_OPTION_THIRD_PARTY_DIRECTORY_NAME	: “thirdparty”	Name of folder where the third-party libraries are located
CEE_SAM_OPTION_WIDECHAR	: “OFF”	Build with Unicode support
CEE_SAM_OPTION_ZLIB	: “Internal”	Link against zlib (required for OpenFOAM, Permas reader, and HDF5 link)

The ThirdParty packages included in the distribution - ThirdPartyDist 

The built-in CEETRON SAM CMake system is the easiest way to compile and link with CEETRON SAM. The delivered CMakeLists.txt is being instructed to use the thirdparty packages included in this distribution. To this date: Abaqus, Ansys-DPF, CGNS, HDF5 (including zlib) IntelMKL, IntelOpenMP, GKlib and METIS are delivered. Those libraries are being tested linked to CEETRON SAM to guarantee the best functionality.

The version of each of the included libraries is mentioned in the third-party directory.

We acknowledge those packages for granting a license that allow its distribution either by mutual agreement between Tech Soft 3D and the owners, or because of the license terms. Tech Soft 3D is not the author of those packages, the software is distributed as-is. Any distribution of those packages must be in agremeent to the license included for all of them.

[Deprecated] Compiling and Linking CEETRON Solve/Access/Mesh

This method is deprecated and will be removed. Please refer to the Built-in CMake System section.

CEETRON SAM libraries are delivered in obfuscated source code form. This means that the source code has been processed so that it is not readily understandable by human beings but compiles properly on any supported computer platform. As a result, a single CEETRON SAM source code deliverable is generally immune to operating system and compilation system changes. The general concepts of compiling and linking CEETRON SAM source is outlined below. The user may use this information to integrate the compilation of CEETRON SAM source into their custom development environment. As an option, a built-in compilation and linking system is provided which is described in the next section.

Each CEETRON SAM library has a different set of compilation options (C preprocessor directives) which are required for proper compilation on a particular platform, operating system, window system, etc. These options are documented in the “Compiling and Linking” section of each library. The base library must be compiled for all CEETRON SAM installations, along with each of the CEETRON SAM libraries delivered.

The recommended compilation method is the built-in CMake system.

There are a variety of C preprocessor definitions which are used to conditionally compile source code. The following definitions are common to all CEETRON SAM libraries. The primary category is machine architecture which is related to the overall computing platform. The machine architecture implies an operating system such as LINUX, Microsoft Windows and platform dependent varitions of UNIX. Possible architectures are the following,

VKI_ARCH_HP	Hewlett Packard HPUX systems
VKI_ARCH_IBM	IBM AIX systems
VKI_ARCH_LINUX	LINUX operating system
VKI_ARCH_MAC	Apple MAC OS X
VKI_ARCH_SGI	Silicon Graphics IRIX systems
VKI_ARCH_SUN	SUN Solaris systems
VKI_ARCH_WIN32	MicroSoft Windows

Publicly available external library support for compression. There are two options. The user may conditionally compile source to reference a user supplied installation of the external library or conditionally compile source to reference a modified version of the publicly available source which is delivered in the base/ext directory.

VKI_LIBAPI_ZLIB	ZLIB user installed external library
VKI_EXTAPI_ZLIB	ZLIB base/ext/zlib source

Enable Intel’s MKL BLAS functionality. These definitions must be used when compiling all objects in the base, vfs and vfx directories.

VKI_LIBAPI_BLASMKL_SEQUENTIAL	Enable MKL sequential BLAS functionality
VKI_LIBAPI_BLASMKL_THREAD	Enable MKL threaded BLAS functionality

Enable multi-threading functionality which uses OpenMP. These definitions must be used when compiling all objects in the base, vfs and vfx directories.

VKI_LIBAPI_OPENMP

Enable OpenMP Threading functionality

Enable sockets functionality. This definition must be used when compiling all objects in the base directory.

VKI_LIBAPI_SOCKETS

Enable sockets functionality

In general, most user input arguments to functions are checked for validity. In some cases where the error checking may degrade performance, a compile time option is available to conditionally compile the additional error checking code. This option also adds some memory integrity checking. The compile time definition related to error and memory checking is the following.

VKI_CHECK_ERRS

Include additional error checking

Once the CEETRON SAM source code is compiled, either the object files may be used directly or they may be installed in an object library archive so that the loader may selectively relocate only the objects which are required. CEETRON SAM is written in ANSI C. It is suggested to use the highest level of serial optimization options available on the C compiler.

For example, on LINUX systems, create a directory LINUX under lib to hold the final devtools.a archive file. Then from the devtools/src/base directory compile using

gcc -c -O2 -DVKI_ARCH_LINUX -DVKI_CHECK_ERRS -I.. *.c

creating .o files in the base directory. To place the object files in an archive file issue

ar rs ../../lib/LINUX/devtools.a *.o

The object files may be deleted after the devtools.a archive is successfully created. At this point the devtools.a archive contains all base objects. Place the devtools.a archive immediately after the application code libraries in the load line. A devtools.a archive must be built for each computer platform using the methodology outlined above.

To build a dynamic link library on LINUX systems, use the same LINUX directory under lib to hold the final devtools.so library file. Then from the devtools/src/base directory compile using

gcc -c -fPIC -O2 -DVKI_ARCH_LINUX -DVKI_CHECK_ERRS -I.. *.c

creating .o files in the base directory that are suitable for building a dynamic link library. The library itself may be created with

gcc -shared -Wl,-soname,devtools.so -o ../../lib/devtools.so *.o -lc

This will create the shared library devtools.so in the LINUX subdirectory. You can now link with this library, provided your environment variable LD_LIBRARY_PATH contains this subdirectory (separated by a colon).

On Microsoft Windows systems, compile from within a nmake file using:

!include <ntwin32.mak>
cl.exe $(cflags) $(cvars) /O2 -DVKI_ARCH_WIN32 -DVKI_CHECK_ERRS -I.. *.c

creating .obj files in the base directory. To place the object files in a library file issue

lib /out:../../lib/INTEL/devtools.lib *.obj

The object files may be deleted after the devtools.lib library is successfully created.

To build a dynamic link library (.dll) in Microsoft Windows rather than a static library, define the macro VKI_EXTERN to be __declspec(dllexport) when compiling CEETRON SAM source code as follows:

!include <ntwin32.mak>
cl.exe $(cflags) $(cvars) /O2 -DVKI_ARCH_WIN32 -DVKI_CHECK_ERRS \
        -DVKI_EXTERN=__declspec(dllexport) -I.. *.c

creating .obj files in the base directory. Then these .obj files must be linked into a dynamic link library using:

link /dll /implib:devtools.lib /out:devtools.dll /machine:i386 *.obj

When compiling user code referencing a CEETRON SAM function which has been placed in a dynamic link library, it is suggested to define the macro VKI_EXTERN to be __declspec(dllimport). Note that the devtools.dll must be placed in a directory that can be found by Microsoft Windows when the application is executed.

[Deprecated] The Built-in Make System

This method is deprecated and will be removed. Please refer to the Built-in CMake System section.

The built-in CEETRON SAM make system may be used to build a standalone object archive or library and link the supplied examples. The system consists of a Makefile and Makefile.win32 in each toolkit directory and exam subdirectory. The Makefile.win32 is used for Microsoft Windows platforms and Makefile is used for all other (UNIX-like and LINUX) platforms. These make files reference a MAKEDEFS.xxx file in the main devtools directory, in which the xxx is a “machine” type. The MAKEDEFS.xxx files contain the “machine” dependent compiler switches, etc. The machine type is set with the environment variable VKI_MACH. Currently recognized values for VKI_MACH are the following.

LINUX	LINUX 32 bit
LINUX64	LINUX 64 bit
MAC	Apple MAC OS X
WIN32	Microsoft Windows 32 bit
WIN64	Microsoft Windows 64 bit

In order to build the source code, first set the appropriate VKI_MACH value. Then change directory to the devtools/src/base directory and enter the following command for Microsoft Windows:

nmake /f Makefile.win32 build

or for all other systems enter

make build

The base directory contains an ext sub directory. This directory contains ZLIB source. If you already use a pre-installed version of ZLIB you do not need to compile this source, Otherwise build it using the following command for Microsoft Windows:

nmake /f Makefile.win32 buildext

or for all other systems enter

make buildext

Then visit each licensed toolkit source directory and repeat the procedure. An ext subdirectory only exists in the base and vgl source directories. If the C++ interfaces are desired in addition to the standard C interfaces, then substitute buildCC for build in the make commands above. Once all files have been compiled, a final library resides in the directory lib/$(VKI_MACH) for the platform used.

In order to build any one of the supplied examples after the object library or archive has been built using the procedure above, change directory to the exam directory in any of the toolkit source directories. Then issue the appropriate make command to build one of the examples. For example to build Example 1 as a console application in the base library on Microsoft Windows, change directory to devtools/src/base/exam and enter

nmake /f Makefile.win32 exam1

This will create exam1.exe

Include Files and Data Types

The first step in writing a CEETRON SAM application is to include the proper header files. All CEETRON SAM applications must include the base.h header file located in the base directory. This file includes typedefs for all basic data types and defined constants. The basic data types are listed below.

Vchar	character, a single byte
Vtchar	character, single byte or wchar_t
Vuchar	unsigned character
Vwchar	wide character, type wchar_t
Vshort	short integer, 16 bits
Vushort	unsigned short integer
Vint	integer, 32 bits
Vuint	unsigned integer
Vlong	long integer, 64 bits
Vulong	unsigned long integer
Vfloat	single precision floating point, the same size as Vint
Vdouble	double precision floating point, 64 bits
Vobject	void*
Vword	maximum sizeof Vint, Vfloat and Vobject
Vquad	quadruple precision floating point, 128 bits

All arguments (other than specific object pointers) passed to any user callable CEETRON SAM function are typed using the above defined types. The Vtchar type is single byte (char) by default or wide character (wchar_t) if the symbol VKI_WIDECHAR is defined.

Pointers to specific object types are typedef ‘ed using a four letter prefix, such as vis_ in the VisTools library, and the name of the module from which the object was instanced. For example, Contour objects are typed as vis_Contour. These module type definitions appear in the header file for each module. The base.h, vis.h, vismesh.h, vgl.h, vfe.h, vfs.h, vfx.h and vdm.h files include all the required module header files. It is recommended that one use the #include pre-processor directive as follows:

#include "base/base.h"
#include "vgl/vgl.h"
#include "vis/vis.h"
#include "vis/vismesh.h"
#include "vdm/vdm.h"
#include "vfe/vfe.h"
#include "vfs/vfs.h"
#include "vfx/vfx.h"

An include file, userdefs.h, is installed in the devtools/src/base directory specifically for user defined C preprocessor commands and is meant to be edited and customized by the user. This include file is guaranteed to be included by any CEETRON SAM include file. One particular use of userdefs.h is customization with respect to compiling features in VfxTools which are dependent upon underlying toolkits. The following #define ‘s should be added indicating toolkits which are not licensed.

#define VKI_NOVGLTOOLS
#define VKI_NOVISTOOLS
#define VKI_NOVISTOOLSMESH
#define VKI_NOVDMTOOLS

Versioning

CEETRON SAM releases are named using the Semantic Versioning scheme. The include file base.h contains two macros which can be used for retrieving the version information:

SYS_VERSION defines a hexadecimal value built up from major, minor and patch version numbers. This value is guaranteed to be monotonically increasing for each new release.
SYS_VERSIONSTR defines a string built up from major, minor and patch version numbers. It may also contain pre-release and other information if available.

C++ Language Bindings

CEETRON SAM supports a C++ language binding. The C++ language binding is a derivative of the C language binding. The object oriented technology of the C language binding maps naturally into C++ classes. The following rules determine the form of the C++ language binding from the C language binding.

All CEETRON SAM C language modules map into C++ classes. The “Begin” and “End” functions in a module become the constructor and destructor methods for the corresponding C++ classes. These functions correspond to the new and delete operators in C++. All other module functions map into a corresponding member function of the class. C++ class names are the same as the C language module names.
The class methods are derived from the module functions by removing the letters vis_ and the module name. For example, vis_ContourSetObject() now becomes contour->SetObject assuming that the Contour object had been created as follows:
```
vis_Contour *contour;
contour = new vis_Contour;
```
The argument lists are identical except for the elimination of the first argument (the object argument). For example:
(C) vis_ContourSetTopology(contour,VIS_SHAPEQUAD,0,0)
(C++) contour->SetTopology(VIS_SHAPEQUAD,0,0).
The C++ class definitions and functions are contained in the cplusplus subdirectory in the source directory for each library. For example, the C++ wrapper files for the VisTools library reside in src/vis/cplusplus. The C++ wrapper files need to be compiled only if C++ bindings are required. The header files to be used with the C++ classes are the standard C language header files.

FORTRAN Language Bindings

CEETRON SAM supports a FORTRAN language binding. The FORTRAN language binding is a derivative of the C language binding and maintains the same object oriented technology as the C language binding. Functionality is in all cases identical for all language bindings. The following rules determine the form of the FORTRAN language binding from the C language binding.

There is a one to one correspondence between C and FORTRAN entry points. The FORTRAN entry point may be derived from any C entry point by adding a lower case letter f to the 3 letter prefix. For example the entry point to set an attribute object in a Contour object vis_ContourSetObject() becomes visf_ContourSetObject. Note that FORTRAN is case insensitive. The FORTRAN language binding does not conform to the FORTRAN 77 standard in the sense that entry point names exceed 6 characters.
All functions in the C binding become subroutine calls in the FORTRAN binding. The argument lists are identical except for those functions in the C binding which have function return values. There are two cases. 1) The object creation functions (eg. vis_ContourBegin()) return an object. The corresponding FORTRAN subroutine returns the object in an argument list (eg. visf_ContourBegin(contour)). Use a double precision variable in FORTRAN to hold the object (eg. real*8 contour). 2) The object error flag return functions (eg. vis_ContourError()) return an integer error flag. The corresponding FORTRAN subroutine returns the error flag at the end of the argument list (eg. visf_ContourError(contour,errorflag)).
All defined constants in C become identically named integer parameters in FORTRAN. The FORTRAN entry points are contained in the fortran subdirectory in the source directory for each library. For example, the FORTRAN wrapper files for the VisTools library reside in src/vis/fortran. The FORTRAN wrapper files need to be compiled only if FORTRAN bindings are required. All standard C language header (.h) files have a corresponding include (.inc) file for FORTRAN.
Use the following data type translations.

Vchar

character

Vtchar

character

Vuchar

character

Vshort

integer*2

Vushort

integer*2

Vint

integer

Vuint

integer

Vfloat

real

Vdouble

real*8

Vobject

real*8

Vword

real*8

C# Language Bindings

CEETRON SAM supports a C# language binding. The C# language binding is a derivative of the C language binding and maintains the same object oriented technology as the C language binding. Functionality is in all cases identical for all language bindings. The following rules determine the form of the C# language binding from the C language binding.

There is a one to one correspondence between C and C# entry points. The C# entry point may be derived from any C entry point by replacing the first _ (underbar) in a function name by a . (dot). For example the entry point to set an attribute object in a Contour object vis_ContourSetObject() becomes vis.ContourSetObject.
All strings passed to functions which are defined in C as NULL-terminated arrays of type char become StringBuilder classes. The initial memory allocation of these StringBuilder variables must be large enough to contain the returned value. The vsy.SYS_MAXPATHCHAR macro can be used to initialize them when retrieving paths, while the vsy.SYS_MAXNAME macro can be used in all other cases.
All strings which are returned by address in C become type IntPtr. The C# String may be retrieved from the IntPtr using
```
String mystring = Marshal.PtrToStringAnsi (myintptr);
```
Multi-dimensional arrays in C become single-dimensional arrays in C#. For example, the C declaration int a[10][3]; becomes int [] a = new int[30]; in C#.
All objects become type IntPtr. This means that all Begin methods return IntPtr variables.
All function arguments that only return a single variable are passed in C# by reference. Note that all references must be first initialized. For example,
```
int id = 0;
vis.IdTranGetId (idtran,10,ref id);
```
Function arguments that may return one or more values must be declared as arrays, even if only one parameter is being returned.
All constant parameters for all modules in each toolkit are contained in their respective classes. For example, TRANSMAP_UP, defined in the TransMap module, is referred to as vis.TRANSMAP_UP in a C# program. Likewise, all parameters defined in the base directory can be accessed using the vsy class name. For example, one would use vsy.SYS_ON, vsy.SYS_RES_D, etc.
The C# class definitions and functions are contained in the csharp subdirectory in the source directory for each library. C# wrappers consist of a single class for each directory: vsy, for the base directory; vis, for the vis directory; vgl, for the vgl directory; vdm, for the vdm directory; vfe, for the vfe directory; vfs, for the vfs directory; and vfx, for the vfx directory.

The built-in CEETRON SAM make system may be used to build the C# library and examples. Assuming all toolkits are available, the C# library can be built with the following steps:

cd base
nmake /f Makefile.win32 buildcs
cd ../vdm
nmake /f Makefile.win32 buildcs
cd ../vis
nmake /f Makefile.win32 buildcs
cd ../vgl
nmake /f Makefile.win32 buildcs
cd ../vfe
nmake /f Makefile.win32 buildcs
cd ../vfs
nmake /f Makefile.win32 buildcs
cd ../vfx
nmake /f Makefile.win32 buildcs
cd ../..
nmake -f Makefile.win32 buildcs

The last step in the sequence above creates a devtools.dll and devtoolscs.dll. While the path to devtools.dll may be added to the Windows PATH environment variable, devtoolscs.dll must be registered in the GAC. Alternatively, it may be copied to the location where the application that uses it resides. The latter is the approach utilized in the examples provided.

To build and run the intro1 example in vfe/exam use

cd vfe/exam
nmake /f Makefile.win32 intro1cs
intro1cs.exe

Parallelization and Thread Safety

All CEETRON SAM toolkits may be used in a straight-forward way to take advantage of multiprocessing computing platforms using an industry standard multithreading API such as OpenMP, Pthreads or Windows threads. Most modules are thread safe in that there are no writable global variables (the only modules which must be executed serially are the graphics device interface modules in the VglTools library). This allows multiple instances of CEETRON SAM objects to be executed simultaneously in a multithreaded, multiprocessor environment.

Single instances of objects containing global data such as finite element model and results information may be reliably shared and accessed by multiple threads through a set of read only functions. These functions will have const declarations of the object in their prototypes. There are additional functions which can be used by multiple threads with a single object which are not declared const. These functions are documented with (thread safe) in the function summary. These functions can not formally be declared as const since the object internal error flag may be set if a user input error is detected.

Certain CEETRON SAM functions are internally parallelized. There are two types of internally parallelized functions.

Implicit parallelization using OpenMP. These functions use OpenMP internally and the number of threads to be used is set by the environment variable OMP_NUM_THREADS or alternatively the environment variable VKI_NUM_THREADS. The variable VKI_NUM_THREADS, if defined, takes precedent over the variable OMP_NUM_THREADS. These functions are documented with %(parallel) in the function summary and also listed in a Parallel Functions section for each object. This feature requires compilation with VKI_LIBAPI_OPENMP. If these environment variables are not defined or define a number of threads less than or equal to 1, then serial execution is indicated. The defined number of threads is capped by an internally defined CEETRON SAM maximum.
Explicit parallelization set using an object function call such as vfs_DofTabSetNumThreads. All functions which are internally parallelized in this way will be individually documented as such. The default number of threads is 1. A number of threads specified less than 1 will result in an error being generated. A number of threads equal to 1 will result in serial execution. The specified number of threads is capped by an internally defined CEETRON SAM maximum.

Using CEETRON SAM toolkits to implement parallelization may be performed with minimal impact on the host application. All required software architecture is local in scope. The object oriented technology of CEETRON SAM is critical from a practical standpoint to a successful implementation of parallelization in an application with a multithreading API.

Floating Point Precision

A number of CEETRON SAM modules support various levels of floating point precision. The precision levels are the following:

SYS_DOUBLE, 64 bit floating point type Vdouble
SYS_FLOAT, 32 bit floating point type Vfloat
SYS_HALF, 16 bit floating point type Vshort

The reduced precision type, SYS_HALF, is implemented using the 16 bit IEEE floating point standard. This standard represents approximately 3.3 decimal digits of precision. The minimum and maximum representable values are 6.10e-5 and 65504.

The modules which support varying precision levels have facilities for setting and accessing data in float and double precision. These access routines will ensure that the data which is set and returned is properly converted to the internal precision representation.