Invoking QMG from the shell

Although most of this documentation covers the use of QMG from within the Matlab or Tcl/Tk scripting environments, it is also possible to invoke QMG functions directly from the Unix or Windows shell. Only a subset of QMG functionality is available from the shell, namely:

mesh generation,
checking a triangulation,
doubling internal boundaries,
translating between Ascii and XDR.

Note that you could extend this list to make more functions available from the shell by rewriting the file $QMG_ROOT/tcl/qmg_batch_init.tcl to incorporate more functionality.

To install QMG, follow the instructions for Tcl/Tk installation.

Once installation is complete, you should move or copy the binary to a location on your path. You also need to set the environment variables as documented in the readme file shipped with QMG.

You can test shell-command invocation of QMG using the command testshellqmg, which is a script file. (In Windows, the file is named testshellqmg.bat.) This command is in both the unixtcl and windowstcl subdirectories of QMGROOT/build. The printout from this command looks something like this.


  ... generating a mesh for the hexobj 3D geo
  qmg -meshgen -show 0 -fileformat ascii -logfile /dev/null -orientation 2 -curvecontrol "(const 1)" -tol 1e-12 ../../data/hexobj.geo hexobj.msh
  ... mesh has been generated; doubling internal boundaries
  qmg -double2 -fileformat ascii ../../data/hexobj.geo hexobj.msh hexobj_d.geo hexobj_d.msh \*
  ... internal boundary has been doubled; checking the mesh
qmg -checktri -fileformat ascii -orientation 2 -tol 1e-12 hexobj_d.geo hexobj_d.msh
Maximum aspect ratio =        72.4505 achieved in
simplex #1125 of topological entity hexnutcrack (3:0) which has vertices 314 3 442 445 
Maximum global side length =  0.780871
Minimum global altitude =     0.00196405
Number of nodes = 758 number of elements = 3182
  ... checktri has finished; removing files created by this script

Invoking QMG with no arguments like this

qmg

starts the interactive Tcl console. Specific qmg functions are obtained directly in the shell by additional arguments on the command line according to the following list. In this list, italicized curly braces indicate optional arguments, and vertical lines indicate either-or choices.

SPECIAL NOTE FOR WINDOWS USERS: Many of QMG's shell commands take file names as arguments. Use forward slashes to separate directories, not backward slashes.

Mesh generation

To generate a mesh, use

qmg -meshgen {-fileformat ascii|xdr} {-sizecontrol sizecontrolfunction} {-curvecontrol curvecontrolfunction} {-show 0|1} {-orientation 1|2} {-tol tolerance} infile outfile

Here infile is the name of a file holding a brep and outfile is the name of a file that will hold the mesh. If this file already exists, an error message is issued.

Command options are:

-fileformat format Controls the file format for both input and output: format is either ascii or xdr. The default is xdr.

-sizecontrol functionname Sets size control function. For instance, -sizecontrol "(const 1)" sets a global upper bound on element size of 1.0. The default value is "(const 1e307)", i.e., no upper bound on the element size. Note that the quotes are needed by the Windows and most Unix shells so that the entire string is regarded as a single argument.

-curvecontrol curvecontrolfunction Tells the mesh generator how closely to follow the curvature of the boundary. The default is "(const .5)", which allows normals to diverge by as much as about 20-30 degrees over an element. A looser setting, say "(const 1)", yields meshes with fewer elements but possibly with worse aspect ratio. It's theoretically possible that the aspect ratio could be far worse when the curvature control setting is raised. Note that the quotes are needed by the Windows and most Unix shells so that the entire string is regarded as a single argument.
-show 0|1 Controls whether a panel showing mesh generation progress should be displayed on your screen. If the setting is 0 (the default), no panel is displayed; if the setting is 1, then the panel is displayed and updated about once per second (although there is sometimes a lengthy delay right at the beginning of mesh generation). You must set environment variable DISPLAY if you choose to show the panel. When -show 1 is selected, this command does not exit until you click the "dismiss" button in the panel. Therefore, if you are running in batch mode or from a script then you should pick -show 0.
-orientation 1|2 Controls the orientation of the simplices generated by the mesh-generator. Orientation 1 (default) means right-handed; orientation 2 means left-handed.
-tol tolerance Controls the tolerance used by geometric operations in the mesh generator. The default is 1e-14.
-logfile filename Specifies the filename to write the mesh generation log. The default is mglogXXX, where XXX is the number of the process. Use /dev/null under Unix or nul under Windows to discard the log.

The qmg -meshgen command leaves a log file in the current working directory called mglogXXX, where XXX is the process ID. So you must have write-access to the CWD when this command is executed.

Checking a mesh

To check mesh quality, use

qmg -checktri {-fileformat ascii|xdr} {-checkorientation 0|1|2} {-tol tolerance} brepfile meshfile

This command checks correctness of a mesh, and also computes the aspect ratio of the worst element. It prints the results to stdout. The brepfile argument is the name of a file holding a brep, and the meshfile argument holds a mesh for that brep. Command options are:

-fileformat format Controls the file format for input, either ascii or xdr. The default is xdr.

-checkorientation 0|1|2 If this is set to 1 (default), then the routine checks that all elements have right-handed orientation (the default orientation produced by QMG). If this is set to 2, then every element is checked for left-handed orientation. Finally, if this is 0, then orientation is not checked.

-tol tolerance Relative tolerance for how close mesh nodes must lie on faces. Default is 1e-14.

Doubling the internal boundaries of a brep

There are two calling formats for doubling. To double the internal boundaries of a brep, use

qmg -double1 {-fileformat ascii|xdr} {-tol tolerance} brepinfile brepoutfile "facename1 facename2 ... facenamek"

This command replaces internal boundaries with two copies of that internal boundary. The brepinfile argument is the name of the file holding the input brep. After doubling, the brep is rewritten to a file named brepoutfile, which must be a file that doesn't already exist. The last argument is the list of names of topological surfaces that are to be doubled. Each surface in this list must be an internal boundary, i.e., it must occur twice in the "child" list of a region.

This routine also reorients boundaries so that all patches have the correct orientation.

The list of facenames may be empty "", in which case the routine simply reorients patches. It may also be *, meaning double every internal boundary. Note: in many shells, you must proceed the * with a backslash to prevent the shell from interpreting it.

The second calling format is:

qmg -double2 {-fileformat ascii|xdr} {-tol tolerance} brepinfile meshinfile brepoutfile meshoutfile "facename1 facename2 ... facenamek"

This command replaces an internal boundary with two copies of that internal boundary and replaces mesh nodes along that boundary with two copies, one for either side. The brepinfile argument is the file holding the input brep, and meshinfile is a file holding a mesh for that brep. After doubling, the brep and mesh are rewritten to files brepoutfile and meshoutfile, which must be files that don't already exist. The last argument is the list of names of topological surfaces that are to be doubled and was described above.

This routine also reorients boundaries so that all patches have the correct orientation. For more information, see the section on doubling in the finite element page.

The options are as follows:

-fileformat format Controls the file format for both input and output: format is either ascii or xdr. The default is xdr.

-tol tolerance Relative tolerance for how close mesh nodes must lie on faces. Default is 1e-14.

Translating file formats

To translate from xdr to ascii or back, use the command

qmg -translate toascii|toxdr infile outfile

The first argument after -translate controls the direction of translation, either toascii (i.e., from xdr to Ascii) or toxdr (i.e., from Ascii to xdr). The infile argument is the name of a file with the object to be translated, and the result is written to a file named outfile. This file must not already exist.

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

-fileformat format	Controls the file format for both input and output: format is either ascii or xdr. The default is xdr.
-sizecontrol functionname	Sets size control function. For instance, -sizecontrol "(const 1)" sets a global upper bound on element size of 1.0. The default value is "(const 1e307)", i.e., no upper bound on the element size. Note that the quotes are needed by the Windows and most Unix shells so that the entire string is regarded as a single argument.
-curvecontrol curvecontrolfunction	Tells the mesh generator how closely to follow the curvature of the boundary. The default is "(const .5)", which allows normals to diverge by as much as about 20-30 degrees over an element. A looser setting, say "(const 1)", yields meshes with fewer elements but possibly with worse aspect ratio. It's theoretically possible that the aspect ratio could be far worse when the curvature control setting is raised. Note that the quotes are needed by the Windows and most Unix shells so that the entire string is regarded as a single argument.
-show 0\|1	Controls whether a panel showing mesh generation progress should be displayed on your screen. If the setting is 0 (the default), no panel is displayed; if the setting is 1, then the panel is displayed and updated about once per second (although there is sometimes a lengthy delay right at the beginning of mesh generation). You must set environment variable DISPLAY if you choose to show the panel. When -show 1 is selected, this command does not exit until you click the "dismiss" button in the panel. Therefore, if you are running in batch mode or from a script then you should pick -show 0.
-orientation 1\|2	Controls the orientation of the simplices generated by the mesh-generator. Orientation 1 (default) means right-handed; orientation 2 means left-handed.
-tol tolerance	Controls the tolerance used by geometric operations in the mesh generator. The default is 1e-14.
-logfile filename	Specifies the filename to write the mesh generation log. The default is mglogXXX, where XXX is the number of the process. Use `/dev/null` under Unix or `nul` under Windows to discard the log.

-fileformat format	Controls the file format for input, either ascii or xdr. The default is xdr.
-checkorientation 0\|1\|2	If this is set to 1 (default), then the routine checks that all elements have right-handed orientation (the default orientation produced by QMG). If this is set to 2, then every element is checked for left-handed orientation. Finally, if this is 0, then orientation is not checked.
-tol tolerance	Relative tolerance for how close mesh nodes must lie on faces. Default is 1e-14.