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.
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.
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.
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.
$QMG_ROOT/copyright: the copyright statement
and licensing terms for QMG.
$QMG_ROOT/build:
This directory has a number of subdirectory; each subdirectory
has a Makefile. 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.
In that directory you will find
a Makefile that will build your code. That makefile may need
some customization; see below.
$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, plus some samples
to test your compiler.
$QMG_ROOT/ex: 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.
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.
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".
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.
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.
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.
alltestssource $qmg_library2/alltests.tclAfter 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
interactive=1
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.
Stephen A. Vavasis, Computer Science Department, Cornell University, Ithaca, NY 14853, vavasis@cs.cornell.edu