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.
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.
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.
gmfemand 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.
$QMG_ROOT/build: This directory has a four subdirectories each of which has a makefile. The four are: unixmatlab, unixtcl, windowsmatlab, and windowstcl. These correspond to the four supported platforms (Unix/Matlab, etc.).
$QMG_ROOT/copyright: the copyright statement and licensing terms for QMG.
$QMG_ROOT/data: This directory contains some interesting data, for instance, the five Platonic solids.
$QMG_ROOT/doc: This directory contains these html files that you are reading.
$QMG_ROOT/ex: You can start Matlab in this directory if you are making a Matlab installation.
$QMG_ROOT/mex: This directory holds the compiled mex files for matlab. It is initially empty.
$QMG_ROOT/mfiles: This directory contains the matlab m-files that go with QMG. These are used only if you script QMG with Matlab.
$QMG_ROOT/mfiles2: This directory contains the m-files that contain tests QMG, as well as some utilities to assist in testing.
$QMG_ROOT/src: This directory has a number of subdirectories: common, model, meshgen, matlab, tcl, unix, win. These subdirectories contain the C++ source code. Each subdirectory also contains some portions of makefiles. See the guide to the source code.
$QMG_ROOT/tcl: This directory contains the Tcl files that go with QMG. These are used only if you script QMG with Tcl/Tk.
$QMG_ROOT/tcl2: This directory contains Tcl files that test QMG, as well as some utilities to assist in testing.
windowstcl. Proceed to the subdirectory corresponding to the platform you use. In this directory you will find a makefile (named
Makefilein Unix and
makefilein 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
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.
customexplain this option.
customaccording to the instructions in that file.
In addition, there is one more patch that is not reported
on the Dinkumware website. The following
code using standard class
requires O(n2) time in VC++5.0:
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
for (int i = 0; i < n; ++i)
os << i;
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.
The QMG source code uses a feature of the C++ language called
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.
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
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
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,
startup.mfile that sets all the paths correctly. To run the Tcl/Tk version of QMG, change to the
windowstclsubdirectory $QMG_ROOT/build. In that directory there is an executable called
qmg. Running this executable (no arguments) starts QMG.
in Matlab or
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.
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
and so on. In Matlab you can first issue an echo on or
To run the tests under
Tcl/Tk, you can type either
and so on up to
sourcecommand does not echo commands as they are executed, whereas the
If you are running the tests interactively, you can set the global
interactive to 1. In Matlab this is done by:
In Tcl/Tk this is done by:
set interactive 1from 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
testvizin matlab or
source $qmg_library2/testviz.tclin 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, firstname.lastname@example.org