QMG 1.1 Installation Instructions

There are a number of options for installing QMG. Unix users should download the source files and then compile them with a C++ compiler, for example, gcc. Windows users can also download the source files and compile them. Windows users lacking the proper compiler can also download executables. There are two kinds of executables: the Tcl/Tk executables or the Matlab executables. These instructions will go over all the options.

QMG1.1 runs on a variety of Unix platforms, and also under Windows NT running on an Intel-compatible PC. Besides Windows NT, QMG is shipped with makefiles for Sun Sparcstations (both SunOS and Solaris), IBM RS6000's, HP700 series, and SGI IRIX workstations.

Downloading the software

Installing Tcl/Tk

Users who would like the Tcl/Tk front-end must first install Tcl/Tk. (Note: Matlab QMG also uses a subset of Tcl7.6/Tk4.2 for parsing. However, this subset is shipped with QMG so Matlab users do not have to install Tcl/Tk themselves.)

QMG is written assuming that you will use Tcl7.5/Tk4.1 or Tcl7.6/Tk4.2. (Some of the makefiles assume Tcl7.5; others assume Tcl7.6. However, these two versions are fairly interchangeable.) If you download the Windows Tcl/Tk QMG executable, you must have Tcl7.6/Tk4.2. Tcl/Tk is a free software package written by J. Ousterhout of Sun Microsystems. It includes a scripting environment, a GUI-building toolkit, remote procedure calls, and other useful features. It runs on a variety of Unix platforms as well as Macs and Windows. Unix users should download the Tcl/Tk source code and compile it. Windows users can download either the source code (you need to have either Borland C++ or Microsoft C++ to compile the source) or a self-extracting executable that installs the binaries. Many sites already have Tcl/Tk installed somewhere; check with your system administrator before you go to the trouble of installing it. The download page was given above.

In the Tcl/Tk environment, the QMG routines are extensions to the Tcl/Tk core and are statically loaded routines. In a future release we may support dynamic loading of QMG routines under Tcl/Tk.

Installing Matlab

Matlab is commercial product that includes many routines for numerical computation, graphics and a scripting environment. For information contact The Mathworks, Inc. There are free software packages that imitate Matlab, but I don't know whether any of them is compatible with QMG.

You do not need to install Matlab if you plan to script QMG with the Tcl/Tk language. The Tcl/Tk scripting environment does not include the finite element solver that comes QMG---this portion of QMG is available only in Matlab.

Role of the scripting language

The QMG package uses the scripting language as a front end for all the geometric modeling routines and the mesh generator itself. Several routines are written entirely in the scripting language. In particular, the finite element solver (gmfem and related routines) is written in Matlab.

You need to be familiar with the scripting environment (either Matlab or Tcl/Tk) in order to use QMG. Matlab comes with online demos and tutorials to get started, and there are a number of textbooks on Matlab---see the home page of The Mathworks, Inc. for more information.

For Unix users only, the mesh generator and triangle-checking routines are available as stand-alone Unix commands. These standalone commands actually run the Tcl/Tk version of QMG by feeding it short scripts. Before using the Unix commands you must set the environment variables described below.

There are also several books on Tcl/Tk, for instance J. Ousterhout, ``Tcl and the Tk Toolkit,'' Addison Wesley, 1994. I have written a very brief synopsis of Tcl/Tk that will get you started.

Installing the QMG source code (Unix and Windows/Intel)

The QMG source code is obtainable by anonymous ftp at the download section above. After unzipping/untarring, there will be files and directories with the following names and purposes. In the following instructions, I will refer to the ``root'' where you have unzipped/untarred QMG as $QMG_ROOT. (These directories are set up so that you can build the QMG software for several different platforms sharing a common networked file system.)

Executing the makefiles

The QMG package source code comes with a number of Makefiles for building QMG on different platforms. As mentioned above, the subdirectories have names of the form arch_opsys_compiler_scripting where arch is the architecture, opsys is the name of the operating system, compiler is the name of the compiler, and scripting is the name of the scripting language. For example, if you have a Sun Sparc machine running Sun OS 4.1.4 and your C++ compiler is gcc 2.7.2, and you are scripting with Tcl7.6/Tk4.2, you would go to the subdirectory sparc_sunos414_gcc272_tcl76, and execute the make command (usually "make" in Unix) in that directory. Each makefile has some paths declared in it near the beginning; possibly you will have to change those paths for your system. For instance, the path to the Tcl/Tk library and to your compiler will have to be updated. Under unix, to run make you go to the relevant directory and type "make".

There are two example Unix makefiles, heavily document with comments; they are $QMG_ROOT/build/examples/makefile_tcl and $QMG_ROOT/build/examples/makefile_mex; the former is for Tcl/Tk scripting and the latter is for matlab.

The makefiles for building QMG under Matlab will put the executable files in directory $QMG_ROOT/mex. The makefiles for building QMG under Tcl/Tk will leave the executable (a single file called "qmg", or "qmg.exe" for windows) in the subdirectory of build where make was executed. You can then move the executable wherever you want.

Executing the makefiles for windows users

There are two subdirectories in the build directory for windows users: i386_wnt40_vc40_tcl76 and i386_wnt40_wc106_ma42. The first one is for building Tcl/Tk version of QMG and requires the Visual C++ 4.0 (or higher) compiler from Microsoft. Probably the software will also compile with a recent version of Borland's C++ compiler, but I do not have the Borland compiler. Watcom is not supported because I was not able to compile Tcl/Tk with Watcom. To invoke the VC++ makefile, after customizing the paths, type "nmake".

The makefile in i386_wnt40_wc106_ma42 is for building the Matlab version under Watcom 10.6. You cannot use any compiler other than Watcom for Matlab 4.2, because Matlab mex files use a format called "pharlap relocatable executable" which is not supported by Microsoft or Borland. (This is because Matlab 4.2 is not 32-bit compatible.) The command to type is "wmake /u".

Makefile customization

Customizing a makefile for one of the above listed supported platforms should be quite easy---only the paths in the Makefile will have to be adjusted. See the commented makefiles in $QMG_ROOT/build/examples for comments on what the paths mean.

Customization procedures for an unsupported Unix platform

If you are installing this software on some Unix platform other than the ones for which makefiles have been written, then you may have to spend some effort in getting a working makefile. In general, it will be easier to compile the software for Tcl/Tk than for for Matlab. There are two stumbling blocks in compiling QMG for Matlab.

The QMG source code uses a feature of the C++ language called ``templates.'' A template is a parameterized type and is associated with several parameterized functions. These parameterized functions must get instantiated by the C++ compiler into actual linkable functions. The instantiated template functions then must get stored in a .o file somewhere that the C++ compiler knows about. Different C++ compilers handle this in different ways.

When you customize the Makefile for your setup, you face two obstacles with regard to templates: figuring out how to get C++ to instantiate the templates, and then figuring out how to get the Matlab linker to link them into your program. Please look at some of the provided makefiles to see how this is done for other compilers.

If you need to experiment with template instantiation, you can play around with the C++ program called in the directory $QMG_ROOT/src/template-test. In this directory you will find a skeleton Makefile for compiling a very small C++ program that uses templates into a Matlab mex file.

The second headache in linking C++ object files to Matlab concerns libraries. A typical C++ compiler will link in one or more different libraries whose names you may have to figure out. Most Unix C++ compilers (except gcc) link a file called libC.a, so it is likely that you will need -lC as an option to the link command.

Many C++ compilers have a -v option to display the steps of compilation. This will help you figure out which libraries are involved in linking C++ code. The cmex command also has a -v option; this option will should you what the default libraries used by cmex are. By experimenting with these, you can probably figure out what additional -l and -L options to give the link command.

Customizing the source code

I have not found it necessary to customize the source code itself for various platforms because the C++ used is fairly standard. (If you have a CFRONT-based compiler, then you might have some trouble. Try include -DCFRONT as one of the flags during compilation.) The QMG code uses templates, full template specialization (in one place: assoc.h, and the specialization code can be omitted with the -DNO_SPECIALIZE compiler option), streams, and multiple inheritance with virtual base classes.

QMG does not use namespaces, exceptions, the standard template library, or RTTI.

The main nonstandard feature of the code is some pointer-casting that takes place in strarr.h and chunkio.cpp. This pointer-casting works on all platforms I've tried, but it would probably fail on a platform that has segmented memory addressing.

Setting up your environment

For viewing 3D breps and surface meshes, you need a VRML viewer installed in your web browser. For information about VRML including browsers, see the repository. You need a viewer that can handle VRML 1.0. Note: VRML 2.0 is not upward compatible with VRML 1.0.

You also need to set some environment variables. These are described in the readme_XXX file that is unpacked in the $QMG_ROOT directory. For example, the environment variable QMG_ROOT should be set to the directory where the software is installed.


There are 11 tests shipped with Matlab QMG and 10 tests shipped with Tcl/Tk QMG. To run through all the tests at once, execute the statement
in Matlab or
source $qmg_library2/alltests.tcl
in Tcl/Tk. This will leave a series of files test1.di,...,test10.di (and test11.di for Matlab) that you can compare to the di files shipped with QMG in directories $QMG_ROOT/tcl2 and $QMG_ROOT/mfiles2.

After alltests is done on either scripting language, there are two global variables set, meshsizesum and aspprod which is the sum of the number of vertices in each mesh generated by each test, and the product of the worst-case aspect ratios of each mesh. In most cases these numbers come out to 11962 and 3.2383...e16. In some cases the numbers come out similar to these, but different. This is because the mesh generators are not totally deterministic. But as long as all the tests run to completion and the two numbers are in this ballpark, QMG is successfully installed.

The tests can also be run individually. In Matlab, this is accomplished by typing test1, then test2, and so on. In Matlab you can first issue an "echo on" or diary command if you wish. To run the tests under Tcl/Tk, you can either type source $qmg_library2/test1.tcl, or eval_log $qmg_library2/test1.tcl, and so on up to test10. The source command does not echo commands as they are executed, whereas the eval_log command does.

If you are running the tests interactively, you can set the global variable interactive to 1. (In Matlab this is done as:

global interactive
In Tcl/Tk this is done as: set interactive 1 from the QMG shell.) Setting this variable causes the tests to generate plots and pause as they execute.

This documentation is written by Stephen A. Vavasis and is copyright (c) 1996 by Cornell University. Permission to reproduce this documentation is granted provided this notice remains attached. There is no warranty of any kind on this software or its documentation. See the accompanying file 'Copyright' for a full statement of the copyright.

Back to the QMG1.1 home page.

Stephen A. Vavasis, Computer Science Department, Cornell University, Ithaca, NY 14853, vavasis@cs.cornell.edu