 |
Installing QMG |
|
|
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.
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.
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.
$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.
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.
custom explain this option.
custom according
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 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;
with
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
“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.
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.
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,
readme_src.
readme_matlab.
readme_tcl.
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.
alltestssource $qmg_library2/alltests.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
or
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
interactive=1
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