First, I should warn you that installing this software is not so easy. The reason is that three different software environments are involved: a C++ compiler, Matlab, and TCL. If you install the Geomview option, you also have Geomview and TCL-DP involved. The packages coexist uneasily and were not written with the others in mind. I have successfully installed the QMG software on the following five Unix platforms:
The g++ compiler has been used to install the stand-alone software (see below) on a DEC Alpha running OSF Unix by a colleague.
If you have a non-Unix platform, you are on your own!
The QMG package has an optional Geomview interface for quality rendering of 3D breps. I have installed the Geomview client software on all the above platforms. However, I have installed the Geomview server on a Sun Sparc only, so far. Installing the Geomview server and client are additional installation tasks described below.
The QMG package uses Matlab as a front end for all the geometric modeling routines and the mesh generator itself. In addition, it uses Matlab exclusively (no C++) in the finite element solver (gmfem and related routines).
The C++ routines that are part of QMG get compiled into ``mex'' files, which are dynamically loadable by Matlab. C++ mex files are not officially supported by Mathworks, which is why the installation of QMG requires a lot of patience if you are starting from scratch with a new platform.
You should already be familiar with Matlab if you intend to use QMG. This documentation assumes prior knowledge of Matlab. Matlab comes with online demos and tutorials to get started.
If you do not have Matlab or you do not wish to use it in conjunction with QMG, you can install a special stand-alone version of the QMG mesh generator, verifier, and refiner that are callable as a Unix commands. (The geometric modeling routines and the finite element package are not available as stand-alone packages.) You have come up with your own method for producing a brep. You also have to write your own finite element solver.
Many sites already have TCL installed somewhere; check with your system administrator before you go to the trouble of installing it. The QMG package uses TCL for parsing, hash tables, and for connectivity to other software packages
You do not have to know the TCL language to use the QMG software package. However, you may need to learn TCL if you plan to hook up an external graphics package of your own, or if you plan to use the mesh-generator in stand-alone mode (without Matlab). The TCL language is documented in J. Ousterhout, ``Tcl and the Tk Toolkit,'' Addison Wesley, 1994.
libtcl.sl: ${OBJS}
rm -f libtcl.sl
ld -b -o libtcl.sl ${OBJS}
gunzip
program and may be built into your
ftp program). After 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 untarred qmg1.0.tar as $QMG.
(These directories are set up so that you can build the
QMG software for several different platforms sharing a common
networked file system.)
$QMG/Copyright
: the copyright statement for QMG.
$QMG/commonXXX
:
compiled .o files for the sources in $QMG/commonsrc
, where
XXX is the name of the platform. These
directories are initially empty. You can delete directories for
platforms you don't plan to use.
$QMG/commonsrc
: source files common to the different
Makefiles.
$QMG/custom
:
files that are included by Makefiles that are custom to your
installation. This directory is initially empty, and you have
put three custom files in it. See below.
$QMG/custom-examples
:
Examples of what to put in the custom directory.
$QMG/doc
: these html files.
$QMG/examples
:
These are mfiles and diaries of the mfiles
that are examples of using QMG.
$QMG/execXXX
:
compiled .mexXXX files for various platforms, where XXX is the
name of the platform. These directories are initially empty.
You can delete directories for platforms you don't plan to use.
$QMG/makeinclude
:
files that are included by the Makefiles.
$QMG/meshgen
:
C++ source code for the mesh generator.
$QMG/mfiles
:
matlab m-files.
$QMG/model
:
C++ source code for the geometric modeling toolkit and
related routines.
$QMG/tcl
:
TCL scripts used for linking Geomview to QMG. You don't
need this directory if you don't plan to install the Geomview
hookup.
$QMG/model
directory
and one in the $QMG/meshgen
directory. Both of them
use the include
command to read files that are in
the $QMG/custom
directory. The package has been set
up so that the files that need customization are all in the
$QMG/custom
directory, and you shouldn't need to
edit the Makefiles directly.
In particular, you have to create three custom files in this directory: plat, paths, and compiler.
The plat file is the easiest: it has a single
assignment statement statement
PLAT = your-platform-name
This is the name of your platform as defined by the extension to mex
files used by the cmex command for Matlab. (Type ``man cmex'' for
a list of the extensions.)
For instance, if you have a Sun workstation running SunOS,
then you would set PLAT=4. If you are using an RS6000 running AIX,
you would set PLAT=rs6.
The file ``paths'' defines two variables, INCLUDEFLAGS0 and LD_PATH. INCLUDEFLAGS0 gets a sequence of include options of the form -Idir1 -Idir2 etc. You have to set this to include directories with mex.h (for Matlab) and tcl.h (for TCL). If you install the Geomview option, you also need dp.h and tk.h. Depending on your C++ compiler, you might also need -I options for the standard C++ header files like iostream.h.
The LD_PATH variable is the -L options to various compiled libraries. In addition to the standard libraries (libC.a, libX11.a, etc), you also need libtcl.a, libtk.a, libdpnetwork.a (the latter two are needed only for the geomview client), and libmex.a (only for the SunOS 4.x platform). You should set LD_PATH to -Ldir1 -Ldir2 etc. On HP-UX, the lib files have the extension .sl instead of .a.
The file ``compiler'' contains the commands and options associated with the compiler. The following variables must be defined in this file:
$QMG/custom-examples
. Among the examples
are:
$QMG/custom-examples/sun-sunos-cfront
.
$QMG/custom-examples/sun-solaris-sparcworks
.
$QMG/custom-examples/hp-ux-cfront
.
$QMG/custom-examples/ibm-aix-xlc
.
The first thing to do is to create directories named commonXXX and execXXX, where XXX is the code for your platform used by Matlab. The code names are displayed in the man-page for cmex.
Next, customize the files. Files ``paths'' and ``plat'' are easy to customize, but file ``compiler'' is tricky. Here are some notes about the obstacles to C++ compilation for matlab and tips on how to work around them.
First, some notes about C++ templates. The QMG source code uses a feature of the C++ language called ``templates.'' [Only two of the programs in QMG use templates: gm_bool.mexXXX and gm_meshgen.mexXXX. However, these are both important if you want QMG to be useful.] 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. Here are some examples of how templates work in C++ compilers I am familiar with.
As you can see from the above list, the technique to force template instantiation varies from platform to platform. Nothing needs to be done for Sparcworks C++ or xlC, but for C-Front, you have to force a compilation all the way to a.out. This means that you need to link a file with ``main'' in it. Compiling down to a.out is complicated by the fact that the routines call functions like mxGetN which are not defined in any lib file (except on the SunOS 4.x platform, in which they are in libmex.a). Therefore, compilation down to a.out often produces errors about undefined function names. I have figured out a way around this for HP-UX.
Once you have figured out how to get the templates instantiated, you have to figure out how to get them linked by the ``cmex'' command. Under xlC this is no problem because they are already in the .o files. For the other compilers, this problem is solved by putting an 'ls' Unix command in backquotes in the cmex instruction.
If you need to experiment with template instantiation, you can play around with the C++ program called `test.C' in the directory $QMG/examples/template-test. This is a program that prints out the line 0 1 4 9 16 in a complicated way.
The second headache with using Matlab's cmex to link C++ object files concerns libraries. A typical C++ compiler will link in one or more different libraries whose names you must figure out, because the cmex command doesn't know about these libraries. Most C++ compilers link a file called libC.a, so it is almost certain that you will need -lC as an option to the cmex 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 cmex command.
There may be additional complications with linking C++ into mex files that vary from platform to platform. For instance, to link C++ object files on the HP-UX platform, the ld command needs to initially undefine a symbol __head and mark it exportable. Details like this can be figured out only with great patience.
After this, all of the mex files should be installed in directory execXXX, where XXX is the code for your platform.
If you want to make the stand-alone mesh generator, type ``make stdalone'' in the directory meshgen. This will create three files in that same directory called ``meshg,'' ``checktri'' and ``refine'' which are executable. There are accompanying TCL files meshg_init.tcl, size_control.tcl, and refine_init.tcl. The programs are set up so that these TCL files are expected to be in the current directory when the commands are executed. If you want to install these TCL files in some central repository, then you should edit the source files meshg_stdalone.C, meshg_init.tcl, and refine_stdalone.C to read the tcl files from the directory you have in mind..
Geomview provides a very nice environment to view three-dimensional breps created with the geometric modeler. (The Matlab 3D renderer doesn't work properly and produces confusing images; see the section on graphics for more information.)
Geomview is not so easy to connect to QMG. The Geomview package cannot be accessed by an external package as a callable C subroutine; instead it accepts instructions from external packages via Unix pipes.
Since it's not possible to set up QMG to send commands directly to Geomview through a pipe, the QMG-Geomview interface sets up Geomview as a separate process and then uses an RPC mechanism to send commands to Geomview. This is a fairly elaborate solution, but it has some advantages. For instance, it is possible to have Geomview running on a separate platform from the rest of QMG. This RPC mechanism may be extended in the future to enable QMG to interact with other Unix software packages.
Thus, there are two separate procedures: one to install the Geomview server program and one to install the Geomview client program. They do not have to be installed on the same platforms. (I have installed the server program a Sun running SunOS only, but I have installed the client program on several platforms.)
The server program is Geomview with an ``external module'' written in TCL for accepting RPC connections, and has no relationship to Matlab or the rest of QMG.
The client program is the QMG function gmgeomview, a matlab m-file, and its associated mex file gm_tclexecute.
The server installation process is as follows. The first step is to install Geomview. The instructions for installing geomview are shipped with the files from the Geometry center. See the hyperlink above.
Next, you should install TCL-DP, the package used for remote procedure calls. TCL-DP is written by B. Smith and L. Rowe. It is available from the same ftp archive as TCL mentioned above. You need to compile it to obtain the executable file ``dpwish'' and the the library libdpnetwork.a. To install Tk you must have already installed TCL. To install TCL-DP, you must have already installed TCL and Tk. Special note to HP-UX users: the libraries have to be libdpnetwork.sl and libtk.sl, not libdpnetwork.a and libtk.a. See the comments above concerning libtcl.sl and HP-UX.
Next, you should edit the file called $QMG/tcl/.geomview in the directory so that the emodule-define statement has the correct path to the $QMG/tcl directory.
Next, you should edit the file called geomview_frontend in the
$QMG/tcl directory so that the first line correctly points to the
dpwish program (wherever you installed it during the TCL-DP installation).
This line should have the form
#!..../dpwish -f
The Geomview server is now ready to be
called by clients. The procedure for setting up the
client software is as follows.
Go to directory $QMG/model
and type
``make all.'' If you have already installed all the other programs
with ``make subset,'' then
this will install one addition mex file, gm_tclexecute.mexXXX.
This additional mex file needs libdpnetwork.a and libtk.a.
Next, you should edit the m-file gmgeomview in the directory
$QMG/mfiles
:
at the beginning of this file is a path name. You must edit this
pathname so that it correctly points to the $QMG/tcl directory in the
distribution.
This completes the client installation. Now you can proceed to install yourself as a user (see below).
The directory with the mex files will has the name $QMG/execXXX, where $QMG is the path to the directory in which QMG is installed, and XXX is the name of your platform (e.g. exec4 for Sun running SunOS, exechp7 for the HP700 series, etc.) The directory with the mfiles is $QMG/mfiles. There is also another directory, $QMG/examples, which contains the test set of eight examples of using QMG.
The mex files must come FIRST in the path before the mfiles, otherwise QMG won't work!
Then run matlab, and everything should work as documented.
If you want to run through all the tests, type alltests
when you enter Matlab. This runs the tests in order and produces
seven diary files. You can compare these diary files to the diaries shipped
with QMG in $QMG/examples. If you build the standalone mesh-generator but
you have Matlab, you can the stand-alone mesh generator with test_stdalone
.
If you want to use Geomview for rendering 3D breps, you need to take
some additional steps. First, copy the file .geomview
from directory $QMG/tcl into either your home directory,
or into the directory in which plan to start geomview running.
Next create a file called config.
This file has a single line in it of the following form:
geomview <host-name> <port-number>
The host-name is the name of the host that will be running geomview. The port number is an IP port number that the geomview server will listen to. I would recommend some number between 2000 and 8000.
The config file should be in the current directory wherever you are running matlab and also in the current directory wherever you start geomview. (If you plan to start geomview in a directory different from the one from which you are running matlab, then you need two copies of config.) This file is read by both the geomview server and the geomview client.
Next, you need a password file. This should be a file one line long with a lengthy string (30-40 characters) of letters and digits that you make up. The name of this file is ``password.'' Again, this file has to be in the current directory for matlab and for geomview; if these directories are not the same, then make two copies of the file.
The password string must avoid the special characters '', {, and }. Stick to digits and letters to be safe.
The password file is used to authenticate the connection to the server port from the client. In other words, when geomview starts, it reads in the password file. Then, whenever other any process tries to establish a connection to that port (presumably the ``gmgeomview'' command in your matlab program), the geomview server waits for a password from the client. The passwords must match, else it closes the connection to the client.
You should make sure that the file protection is set on the password file so that it is not world readable!
I believe this password mechanism is secure (provided your password stays private), but I make no guarantees! See the warranty statement in the file `Copyright,' which disclaims all warranties on QMG.
Now you are ready to go. Start geomview by typing ``geomview'' or ``geomview &.'' The usual complement of geomview windows should appear. In addition, a small window with the single line ``Geomview server is on-line'' should appear. If this latter window does not appear, then the server is not on line. To shutdown the server without exiting Geomview, use your X-windows manager to destroy the small window (for instance, in Openwindows, you destroy a window by clicking right on its title bar and then dragging down to ``quit''.) Then you can restart the server again by clicking on ``RPC server'' in the external modules panel of Geomview.
The server should now respond to the gmgeomview
instruction that you type in Matlab. You can enter and exit Matlab
and Geomview independently from one another without affecting the
operation of the other.
This documentation is written by Stephen A. Vavasis and is copyright (c) 1995 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.
installation.html,v 1.2 1995/05/06 00:42:01 vavasis Exp
Stephen A. Vavasis, Computer Science Department, Cornell University, Ithaca, NY 14853, vavasis@cs.cornell.edu