QMG installation

These instructions have two parts: installing the software on your system and then installing yourself as a user. You can either install the software in your directory for private use, or else install it in some public place so that colleagues can also use it. If you choose the latter and you have already installed the software, then your colleagues who want to use it should skip directly to the instructions on installing themselves as users.

Installing the QMG software on your system

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:

If you have one of the above Unix platforms, you are in luck because I have already figured out how to customize the Makefiles to install the software (see below). If you have a different Unix platform, then you will probably have to put some time into getting the package running. There are some tips below.

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.

Preliminary installation: Matlab

First, you have to install Matlab. Matlab is commercial product; for information contact
The Mathworks, Inc. There are also free software packages that imitate Matlab, but I don't know whether any of them is compatible with QMG.

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.

Preliminary installation: TCL

After you have installed Matlab, you next have to install TCL. TCL is a scripting language written by J. Ousterhout. TCL is available by anonymous FTP from the TCL archive. TCL is handy for scripting Unix applications that involve different software packages. Its partner Tk is very handy for quickly building X-Windows user interfaces. (You do not need Tk for QMG unless you install Geomview; see below).

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.

Special note on installing TCL under HP-UX

In order to link the TCL library into Matlab under HP-UX, you need to create a shared library libtcl.sl. The TCL installation procedure, if you run it ``out of the box,'' will create libtcl.a instead, which is not compatible with Matlab in HP-UX. To create libtcl.sl, carry out the following steps:

Obtaining the QMG software

The QMG software is obtainable by anonymous ftp. Click here to access the source file. The file is name qmg1.0.tar.gz. You should uncompress and untar this file. (The uncompressing should be done with the 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.)

Customizing the Makefiles

There are two Makefiles, one in the $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:

The ``cmex'' command is a Unix command associated with Matlab to produce dynamically-loadable mex files from C programs. The ``cmex'' program is intended for C rather than C++. (Mathworks does not currently support C++ mex files). The QMG software uses cmex as a linker only, and not as a compiler. But even so, there are still big pitfalls because C++ .o object files are sometimes different than C object files in subtle ways, so the cmex command needs customization.

Prewritten custom files

Tested examples of the custom files are in directory $QMG/custom-examples. Among the examples are: There are also some examples using g++. If you have one of these platforms, you can delete the empty directory $QMG/custom and replace it with a symbolic link (using the ln -s command in unix) directly to $QMG/custom-example/xxxx directory. You will probably have to still fix the file named ``paths'' for your own installation.

Customization procedures for an unsupported Unix platform

If you are installing this software on some Unix platform other than the ones listed above, you will probably have to spend some effort to get the three files paths, plat and compiler right.

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.

When you customize the ``compiler'' file 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.

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.

Running make and completing the installation

Now go to the directory named model and type ``make subset'' (if you don't want the Geomview client program) or ``make all'' (if you want it). Then go to the directory named meshgen and type ``make mex.''

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..

Customizing the source code

I have not found it necessary to customize the source code itself for various platforms because the C++ used is fairly standard. The QMG code does not use multiple inheritance or the exception-handling mechanism. Here are a couple of nonstandard features of the code:

Installing Geomview and the QMG-Geomview interface

Geomview is a software package available from the University of Minnesota Geometry Center. This package is available by anonymous ftp.

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).

Data files shipped with geomview

Along with the geomview software, there are numerous data files with 3D geometric objects. This format (called OFF format) is incompatible with the brep format used in QMG. There are several sources of incompatibility, but the most severe is the numerical precision. For each facet of a three-dimensional QMG brep, the vertices of the facet must be coplanar up to double precision. On the other hand, the OFF files shipped with geomview store vertex coordinates in single precision. Thus, OFF files shipped with geomview cannot be imported into QMG.

Installing yourself as a user

Assuming the package has been installed on your system, you can now install yourself as a user of the package. Just add the directory with the mex files and the directory with mfiles to your matlab path. There are many ways to set your matlab path; for instance, the Unix environment variable MATLABPATH will do the trick. See the Matlab documentation.

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.

Back to the QMG home page.

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