QMG logo

Installing QMG

QMG2.0 runs on a variety of Unix platforms, and also under Windows NT running on an Intel-compatible PC.

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, egcs 1.1.2 or gcc-2.95. Windows users can also download the source files and compile them using, for example, Microsoft Visual C++ 5.0. 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.

Downloading the software

Installing Tcl/Tk

Users who would like the Tcl/Tk front-end must first install Tcl/Tk.

QMG 2.0 is written assuming that you will use Tcl/Tk 8.1.1. QMG should be compatible with Tcl/Tk 8.0 and with versions numbered higher than 8.1, but is not compatible with Tcl 7.x. Tcl/Tk is a free software package originally written by J. Ousterhout and now maintained by the staff of Scriptics. 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 the Tcl/Tk source code and compile it with Microsoft or Borland C compilers, or else they can download 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.

Tcl/Tk also uses tkcon.tcl, a Tcl script file for a console interface written by Jeffrey Hobbs. Tkcon is shipped with QMG, so you do not have to download it separately. In the Tcl/Tk environment, some QMG 2.0 routines are C++ extensions to the Tcl/Tk core and are statically loaded routines. Others are coded in Tcl. Tcl dynamic loading is used to load Tk. Tcl namespace and packages are not used.

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 none of them has been tested 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 to Matlab users.

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. For example, 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. There are several books on Tcl/Tk, for instance J. Ousterhout, Tcl and the Tk Toolkit, Addison Wesley, 1994. This documentation includes a very brief synopsis of Tcl/Tk that will get you started.

The mesh generator and a few other routines are available as stand-alone shell commands. These standalone commands run the Tcl/Tk version of QMG by feeding it short scripts. Therefore, to install QMG in standalone mode, follow the instructions for a Tcl installation.

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

The following information is about building QMG from the source code. If you have downloaded the Windows executable files rather than the source code, please skip ahead to the information below about setting up your environment. The QMG source code is available 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, $QMG_ROOT stands for the directory in which you unzipped/untarred QMG. (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 are called unixmatlab, unixtcl, windowsmatlab and windowstcl. Proceed to the subdirectory corresponding to the platform you use. In this directory you will find a makefile (named Makefile in Unix and makefile in Windows) and a second file called custom. This latter file needs to be customized. Use an editor to modify it according to the comments in the file.

QMG 2.0 has been successfully compiled with the following Unix compilers: egcs (version 1.1.2 or higher), KCC (version 3.2f or higher), Mips-Pro (version 7.3 or higher). It cannot be compiled with older compilers that do not support namespaces, STL or templates. It also cannot be compiled by Sun C++ 5.0.

When customization is done, build the binaries using the command make in Unix or nmake in Windows.

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 in Unix or qmg.exe in Windows) in the subdirectory of build where make was executed.

XDR in Tcl/QMG

QMG uses XDR (Sun RPC) in Tcl only. The necessary XDR routines are shipped with QMG. But you may prefer to use your own built-in XDR routines, which may be more efficient. Instructions in the file named custom explain this option.

Lapack and BLAS in QMG

QMG uses Lapack/BLAS in both Tcl and Matlab versions. The necessary Lapack (actually, Clapack, the C version of Lapack) and BLAS routines are shipped with QMG. But you may use your system's built-in Lapack/BLAS or just BLAS alone, which may be more efficient. In this case, you should customize the file named custom according to the instructions in that file.

Special note for Visual C++ users

It is recommended that you update the standard header files for Visual C++ 5.0 according to the Dinkumware website before compiling QMG. This fixes many bugs in the versions of the standard headers shipped with VC++ 5.0. It is not clear whether these bugs are fixed in VC++ 6.0.

In addition, there is one more patch that is not reported on the Dinkumware website. The following code using standard class ostringstream requires O(n2) time in VC++5.0:

using std::ostringstream;
ostringstream os;
for (int i = 0; i < n; ++i)
os << i;
This severely impacts the performance of conversion-to-string of breps and meshes in Tcl/QMG. It affects several other operations as well. To reduce the running time to O(n), make the following change to include-file SSTREAM. Replace the line
size_t _Ns = _Os + _Alsize;
size_t _Ns = (_Alsize > _Os)? _Os + _Alsize : 2 * _Os + 1;

Note: changing standard headers will affect all your C++ development (not just QMG). Any changes you make to standard headers are ENTIRELY AT YOUR OWN RISK. It is possible that the changes proposed above will cause other software to malfunction. The author of QMG, Cornell University and other organizations involved with QMG offer NO WARRANTY concerning patches to Visual C++ mentioned here (or anything else mentioned in this documentation) and disclaim all liability. See the license terms accompanying QMG for information about disclaimers.

General hints on customization

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. For example, for the Mips-Pro 7.3 C++ compiler, the flag -ptused is needed when compiling QMG for Matlab.

The second stumbling block 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. Many Unix C++ compilers (not egcs though) 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 option (possibly named -v) to display the steps of compilation. This will help you figure out which libraries are involved in linking C++ code. The mex command also has a -v option; this option will should you what the default libraries used by mex 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

It should not necessary to customize the source code itself for various platforms because the C++ used is fully standard-conforming. There are some bugs in some of the compilers which required special #ifdef/#endif pairs in the source code. The source code uses templates, the standard template library, streams, inheritance, namespaces, and exceptions. It also uses a very simple form of member templates. Exceptions can be turned off (under Matlab) by not defining ENABLE_EXCEPTIONS in the Makefile. In this case, when an error occurs and control is returned back to Matlab, QMG will not release memory allocated to it, and some files may not be closed. (Memory is released and files will be closed when you exit Matlab.)

QMG 2.0 does not use RTTI, multiple inheritance, template specialization, default template arguments, function templates. On some platforms, you must enable RTTI even though QMG does not use it because exception-handling may require RTTI.

QMG assume that unsigned ints have at least 32 bits. If your system uses fewer bits for unsigned ints, try modifying the typedef statement for UInt32 in $QMG_ROOT/src/common/qnamesp.h. Note: this has not been tested. Similarly, QMG assumes IEEE-conforming double-precision arithmetic. If your system uses some other kind of arithmetic, please modify the constants BIG_REAL and MACHINE_EPS in that file. Please also change the global variable gm_default_tol accordingly.

Setting up your environment

For viewing 3D breps and surface meshes in Tcl QMG, 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, but many VRML 2.0 viewers also support VRML 1.0.

You also need to set some environment variables. These are described in a readme file that is unpacked in the $QMG_ROOT directory. In particular,

For example, the environment variable QMG_ROOT should be set to the directory where the software is installed.

Running QMG

Once the environment variables are set, you can run QMG. To run the Matlab version of QMG, start matlab from the directory $QMG_ROOT/ex. This directory has a startup.m file that sets all the paths correctly. To run the Tcl/Tk version of QMG, change to the unixtcl or windowstcl subdirectory $QMG_ROOT/build. In that directory there is an executable called qmg. Running this executable (no arguments) starts QMG.


There are 11 tests shipped with 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,...,test11.di that you can compare to the di files shipped with QMG in directories $QMG_ROOT/tcl2 and $QMG_ROOT/mfiles2. Running this command will take at least 5 minutes, and possibly more than an hour, depending on the speed of your computer. The Matlab version takes slightly longer because test7 solves a finite element problem in Matlab but not in Tcl.

After alltests is done on either scripting language, there are two global variables set, meshsizesum, which is the sum of the number of vertices in each mesh generated by each test, and aspprod, which is the product of the worst-case aspect ratios of each mesh. These numbers should come out to 8473 and approximately 8.822e18. If so, then you have successfully installed QMG.

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. To run the tests under Tcl/Tk, you can type either

source $qmg_library2/test1.tcl
gmevallog $qmg_library2/test1.tcl
and so on up to test11. The source command does not echo commands as they are executed, whereas the gmevallog command does.

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

global interactive
In Tcl/Tk this is done by: set interactive 1 from the QMG shell. Setting this variable causes the tests to generate plots and pause as they execute. Finally, there is an interactive script called testviz to test the graphics capabilities of QMG. Type testviz in matlab or source $qmg_library2/testviz.tcl in Tcl/Tk.

This documentation is written by Stephen A. Vavasis and is copyright ©1999 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.

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