Installation Usage Use with Gmsh
Fad is a programme for manipulating 3-D finite-element models.
.sap plain-text model-definition files as input.
Fad is implemented in Fortran. It was originally developed under VMS, and is currently being developed under Compaq (Digital) Unix for Alpha; GNU/Linux for Alpha and Intel; and (alas) Microsoft Windows. The binary is available for Unix and GNU/Linux by request; the binary for Windows is offered here. It can be used for any purpose as long as I am informed of its use. So far there is no documentation beyond the very incomplete beginning that you're looking at.
In this documentation, square brackets
are used to indicate
optional command arguments and should not be included in the commands
themselves. The visible-space character
is sometimes used to emphasize
where space characters should be used in commands.
In prompts within Fad, square brackets are sometimes used to indicate default values, that is, values that will be used if you just type Enter.
Either download the Fad executable for 32-bit Windows (about 4.0 Mbytes) or (if your computer is part of the McGill BME network) create a shortcut to the executable on probeShare. Follow the general instructions for installation of Dip software.
Issue with ClearType: If ClearType is turned on, faint ghosts will be left behind on the screen after Fad displays and then erases text. ClearType is off by default under Windows XP but on by default under Vista.
Missing points: It has been observed under Vista that
sometimes after a Fad
P␣0 command some nodes are not
displayed at first but then appear after the window is minimized and then
restored. The cause is unknown.
If your computer is part of the McGill BME network, create a
symbolic link (
ln -s) to the executable on
probeShare. Otherwise download the Fad executable from here and do
chmod u+x fad to make it executable.
Make sure that the xdg-utils package has been installed. (It is used to open Fad's documentation with the default Web browser.) Fad requires at least about 1500 to 2000 MB of memory to run. Follow the general instructions for installation of Dip software.
You can run Fad by opening a terminal window,
cd’ing into the directory where you saved it
and giving the command
or by giving the command
./Downloads/fad (assuming that you saved Fad in
Downloads subdirectory of your home directory.
Do not include
& at the end of the
|R␣fname[/SEC=fname]||Read model from .sap file(s)|
|W fname||Write model to .sap file|
|I fname.type||Import model from file|
|E||Export model to file|
|G||Generate new model|
|C||Change positions of nodes|
|B||Bisect edges of shell elements|
|A||Align primary model to secondary|
|2||convert to 2nd order|
|F||Fix current coordinates|
|J||Join secondary model to primary|
|N||couNt unconnected structures|
|V||Vacuum unused things|
|L [/MEASURE]||Locate using cursor|
|?||Help (display this Web page)|
When Fad is run, it should display a
Plotting to? question. Normally you should just type
Enter (or Return) here.
You should then see a
Do (? for help) ? prompt.
After every action you should be returned to this prompt. If not, it means
that Fad has crashed and you should look for an error message.
Typing ? and Enter will invoke your default Web browser to display this page of documentation. Typing ? as a second character for any command, and in some other places in Fad, will cause the same documentation page to be displayed, sometimes positioned at the relevant topic. Displaying this on-line help requires that you have an Internet connection open.
The first command that you give
would normally be
R to read in a .sap file, or perhaps
I to import a file that is in some other format, or
G to generate a new model.
When you give the
R command you will be presented with
a list of recently opened files. Select one of them by clicking,
or click on
to browse and find another file. See also
further information about using Dip
Sometimes it’s desirable to read in two models
at the same time.
To read in both a primary model and a
use the command
R␣/sec. When presented with the
file-selection menu, open the secondary file first and then the
primary file. The Align and Join commands are based on the use of
the Plot command includes
various ways of controlling how they're displayed together with
the primary model; and the Modify
and Import commands make use of them.
A typical plot command would be
P␣3, where the
3 is a plotting level.
Many options are available
For example, the command
Once you have used the
P command to display (plot) a
model (and the secondary model if there is one),
an interactive rotation, translation and clipping tool
will appear in the
bottom left corner. The x, y and z axes are
displayed in red, green and blue, respectively. Below the axes is
a concise indication of the current status of the tool. In the examples
shown on the right, for example:
Rindicates that the tools are in rotation mode, which is the initial mode. The other two modes are translation and clipping. To the left of the model(s) are displayed the current orientation(s), the current translation(s) if non-zero, and the current clipping value if active.
Yindicate the currently active axis, which can be either
Windicates that the tools are in the world-coördinates mode, as opposed to the object-coördinates mode.
5indicate the current incremental values for changing the rotation, translation or clipping plane. The initial setting is 10°.
(i)indicates that the tools are in the Immediate mode.
Bindicates that interactive changes will be applied to both the primary and secondary models, rather than just one or the other. The x, y and z axes for the secondary model are displayed in lighter shades of red, blue and green.
Typing just Enter causes the currently specified action to be taken, either rotating or translating the model or changing the position of the clipping plane. Typing a number followed by Enter will change the rotation, translation or clipping step size. Typing a letter followed by Enter changes other settings of the tool. The following commands are available:
A) will reset the model to its initial position.
/clipoption was used with the plot command.
There is no zoom function as part of the plot command. By default the model is automatically zoomed to almost fill the display area. This automatic scaling is based on which elements are selected in the primary model; if all elements are selected then the scaling is based on all of the nodes in the model, which may yield a different result from scaling based on all of the elements if there are some nodes that are not used in any element. If a secondary model is also displayed, then the scaling will also take into account all of its nodes (since element selection is not yet implemented for the secondary model). Something equivalent to zooming can be obtained using the Modify window command.
The first parameter of a plot command is a plotting level from 0 to 9.
A plotting-level parameter of 0 (zero) for the plot command causes only the nodes to be plotted, without elements.
If the plotting-level parameter is greater than 0, it specifies the minimum desired plotting level for which element edges will be plotted, with higher numbers corresponding to more important edges:
An important use of plotting levels is to confirm that a 3-D surface
is simple and closed and has all of its triangles oriented in the
correct direction, in which case a
should display nothing at all. This condition must be satisfied before
using Fad with Gmsh to create a tetrahedral mesh.
A quadrilateral element face is plotted as two triangles, which are formed by using an arbitrarily selected diagonal. That diagonal effectively has a plotting level less than 1 and is never plotted.
|P 0 [ istart [ istop [ istep ]]][switches]|
|/BCLAMPED to display clamped boundary cond''ns|
|/BFREE to display free bdy conditions|
|/SLAVE to tie slaves to masters (implies /BCLAMPED)|
|/-BROT to not display rotational bdy. cond''ns|
|/NODE_LABEL to label nodes|
|/COORD to display node coördinates|
|/USAGE to display which elements the nodes are used in|
|/NEAR to flag nodes with very near neighbours|
|/SIZE=size to specify symbol size for displaying nodes|
|P p [[S] e [ istart [ istop [ istep ]]]][switches]|
|p = plotting level for elements (1-9)|
|e = element type (5,6,7,8,13)|
|S refers to secondary model|
|/GREY to also plot edges with plotting levels <p and ≥p−2|
|/FILL to plot filled triangles|
|/-HIDE to suppress hidden-surface removal|
|/-ZBUFFER to use slow sorting instead of z buffer|
|/ELLOAD to indicate element loads (for shells & tetrahedra)|
|/THICK to indicate element thicknesses (for shells)|
|/ASPECTRATIO to indicate element aspect ratios|
|/VOLUME to display min & max tetrahedron volumes|
|/MATERIAL to indicate material types|
|/STIPPLE to use stippling for back faces|
|/-BACK to suppress different back-face colours|
|/NODES to display nodes as well as elements|
|/LABEL to label elements|
|/SURFACE to display clipped surfaces of tetrahedra|
|/HATCH for hatching (useful for anistropy)|
|/-CULL to suppress back-face culling|
|/WAIT to wait after displaying each triangle|
|For both nodes and elements|
|istart = starting node or triangle number|
|istop = stopping node or triangle number|
|istep = step size (e.g., 2 = every 2nd triangle)|
|/-ERASE to suppress screen erasure|
|/-ROT2 to not rotate secondary model|
|/-CONC to suppress concentrated loads|
|/CLIP to apply z clipping|
|/AXIS to display coordinate axes|
|/VRML to output things to a VRML file|
|/ANIMATE to record animation|
|/OUT to output plot to a file|
The table on the right summarizes the available options for the plot command. The sections below give further information about some of the options.
This option displays the x, y and z coördinates for the last node plotted. (Although this information is actually displayed for every node, it is subsequently overwritten for all but the last node.)
This option analyzes which elements each node is used in. Each node is displayed with a green symbol whose size is proportional (up to a maximum) to how many elements the node is used in. If a node is not used in any elements then it is displayed with a red symbol. For the last node displayed, the actual coördinates are displayed as text and a list is displayed of which elements the node is used in. (Although this information is actually displayed for every node, it is subsequently overwritten for all but the last node.) A message is also displayed that specifies which node has the greatest usage, and what that usage is.
This option provides an analysis of how close together nodes are, including both primary and secondary models. It is good for identifying duplicate nodes, and nodes that are so close together that they probably should be considered as duplicates.
For each node the distance to its nearest neighbour is calculated. If there are any duplicate (i.e., exactly superimposed nodes, with identical coordinates) a message will be displayed saying how many there are. Then a message will be displayed giving the ratio of the smallest to the largest nearest-neighbour distances. If this ratio is greater than, say, 100, it means that some nodes are much more closely spaced than others.
Duplicate nodes are displayed as red diamonds (or orange for the secondary model). Nodes that have almost the maximum nearest-neighbour distance are displayed as large black triangles (or blue for the secondary model). The remaining nodes are displayed as squares, with the symbol sizes larger for smaller nearest-neighbour distances, and with colours ranging from black to red (or from blue to orange for the secondary model).
By default each node is plotted as a single dot. If this size parameter is used then each node is plotted as a square. (The size of the square for a given size parameter depends on the screen resolution.) If this option is used when displaying elements then the nodes will also be plotted. (This currently doesn't work when z buffering is used.)
By default the model is plotted as a wireframe.
/fill causes each triangle to be filled with a colour
specified in the model-definition file, either explicitly or
implicitly (e.g., based on material type). Triangles whose nodes are
numbered counterclockwise as seen by the user are considered to be
facing the user, and triangles that face away from the user are displayed
Fad sorts the triangles and displays them from back to front, so if a surface is closed and all of its triangles are correctly oriented then no orange triangles should appear. Normally a small green circle should appear above the Plot interaction tool. A red cross appears if the sorting algorithm fails, usually because of intersecting triangles. In this case some triangles will be dropped and therefore orange triangles may appear.
By default, rotations and translations are applied to both the primary model
and the secondary model if there is one.
/-rot2 qualifier on the plot command to cause the
rotations and translations not to be applied to the secondary model.
Fad can import (with restrictions in some cases) the following formats:
Fad can export (primitively in some cases) the following formats:
The formats for which Fad exports actual tetrahedra are .msh version 2 (Gmsh), Nastran, Abaqus (CalculiX/FEBio), .feb (FEBio) and .mail (Code_Aster). For other formats it either ignores tetrahedra altogether or outputs them as sets of triangles.
Align command rotates and translates the primary
model to match the secondary model. Before giving the
Align command, use the
Plot command to
display the primary and secondary models; the rotation and translation
should be set to zero. You will be asked to select three nodes on the
primary model and then three corresponding nodes on the secondary
model. Fad will then rotate and translate the primary model to best
align the three primary nodes to the three secondary ones. Re-use the
Plot command to see the results.
This command causes 1st-order elements to be converted to 2nd order by having mid-edge nodes added. This applies only to brick8, shell and tetrahedral elements (types 5, 6 and 13), and applies only to selected elements in the primary model.
The effect of this command is lost if the model is saved in Sap format, since brick8, shell and tetrahedral elements are necessarily first order for Sap. This command is usually followed by an export.
This command causes the secondary model to be joined to the primary model by moving nodes of the secondary model to merge with nodes of the primary model. The user controls the process by specifying which element and material types are eligible, and by specifying a threshold distance. An eligible node on the secondary model will be merged with the closest eligible node on the primary model if the distance between them is less than the threshold.
A special case of this process is that of joining two models which have a shared surface, that is, a surface which appears in both models with identical node coordinates and element definitions. For this purpose, a very small threshold value is specified.
Visual feedback is given. All nodes on the primary model are first displayed with right-pointing black triangles, and nodes on the secondary model are displayed with left-pointing blue triangles. When two nodes are merged, the one on the secondary model is indicated with a large red circle, the one on the primary model is indicated with a smaller green circle, and a line is drawn between them.
The number of nodes merged is displayed along with the maximum distance between merged nodes. One can try different threshold values until the desired effect is obtained. Pressing Enter without specifying a new threshold causes the Join to be finalized. Typing CtrlZ causes it to be cancelled.
This function counts the number of unconnected structures in the model. It is intended to be used in conjunction with thefunction in Fie. Import the VRML file produced there and then invoke this function. It can take a long time if some structures contain large numbers of triangles.
Currently this function just counts and reports the numbers of unused nodes and material types. The intention is that it will actually remove them from the model.
|S ALL||to select all elements|
|S NONE||to deselect all elements|
|S CURSOR||to deselect elements with cursor|
|S PRESSURE||to select all elements with applied pressure|
|S s t [M] n1[,n2]||to select/deselect type-t elements|
|S s ax op coord||to select/deselect elements based on unrotated coordinates|
The various forms of the Select command are shown in the table on the right, where
When you click with the mouse on the model, a green dot will be displayed where you clicked and its x and y coördinates will be displayed in green. A red dot will be displayed at the node closest to where you clicked, and its x, y and z coördinates will be displayed in red. Then a list will be displayed of both front-facing and back-facing elements corresponding to the position of the green dot.
/measure option can be used to make 2-D and 3-D
|ALIGNMENT w.r.t. x axis||model|
|MATTYPE (material type)|
|TIME-VARYING load functions|
|KEQB: no. eqn's/block|
The table on the right lists the modifiable parameters. The following sections provide further details about some of them.
Scaling, translations and rotations are reflected immediately when the model is plotted, but are not applied to the actual model coördinates until and unless the fix command is given.
For scaling, the user is asked for an x scale factor, and then for yand z scale factors that by default are equal to the x scale factor.
For translation there are 3 methods for specifying the final offset,
which the user specifies by responding to the following question:
Use Secondary model, Abs. xyz or Rel. xyz (S,A,R) [R] ?
For rotation, the user is asked for x, y and z rotation angles, specified in degrees.
The alignment command asks the user to specify the node numbers of 2 nodes, and then determines a rotation such that the line between those 2 nodes will be parallel to the x axis. (The node numbers can be obtained using the locate command.)
Reverse the orientation (node numbering) of all selected shell elements.
For a specified element type, change material type mold (or all material types) to material type mnew.
This command allows you to modify the x and y ranges of the display window, which normally is automatically scaled. The command prompt displays the current xmin, xmax, ymin and ymax, and offers several alternative commands, each of which can be invoked by typing a single character:
A: Return the scaling to automatic.
I: Zoom in by a factor of 2.
O: Zoom out by a factor of 2.
U: Move the model up in the window.
D: Move the model down in the window.
L: Move the model to the left in the window.
R: Move the model to the right in the window.
W: You are prompted to click with the cursor in two places, which are then interpreted as diagonally opposite corners of a rectangle that defines the new display window.
C: You are prompted to click with the cursor at a location which will become the centre of the new display window, with the original scaling.
You can immediately specify one of these commands when giving the
Modify command itself (e.g.,
m w w).
After specifying any command but
A, you are asked
whether you want the window to be ‘floated’. Normally
you will want to accept the default
N (no) response.
The model is not immediately redisplayed with the new settings. You need to give whatever plot command you want.
On each pass of this iterative algorithm, the position of each node is moved to the average of the positions of the nodes to which it is connected. The iteration stops when no node is moved by greater than some specified tolerance; in this implementation, the tolerance is the longest dimension of the model's bounding box divided by 10 000.
A node is not moved if it is clamped or if it belongs to an element which is not currently selected. The user can also choose to have nodes not be moved if they are on a boundary between different materials or on an external boundary.
The algorithm of Taubin (1995) smooths a surface while attempting to avoid the shrinkage that usually occurs. In each iteration, a smoothing step is followed by an inflation step.
A node is not moved if it is on a boundary. Node clamping and element selection are not taken into account.
Reference – Taubin G (1995): Curve and surface smoothing without shrinkage. Pp. 852-857 in Proceedings of the Fifth International Conference on Computer Vision, IEEE Computer Society.
This function works only on triangular shell elements that have been selected.
A histogram of edge lengths is displayed, with triangles indicating the 50th, 95th and 99th percentiles. A percent cutoff is requested. Edges with lengths less than that cutoff will not be bisected.
We use Gmsh to create tetrahedral volume meshes from triangulated surface meshes. Gmsh is available as binaries for Linux, MS Windows and Mac OS X, and also as source code. It is also available through the Debian package manager.
The sequence of operations for use with Fad is:
Create a triangulated surface mesh using Tr3, or perhaps some other software that can produce files that Fad can read. The mesh should form a simple closed surface enclosing a volume, with the triangles oriented consistently and with neither holes nor overlapping triangles.
rcommand to read the
.sapfile created by Tr3, or use the
icommand to import the
.wrlfile created by Tr3. (If you're going to be doing finite-element modelling, you'll need material properties so you'll need to read the
.sapfile, not import the
Fad will initially display a wire-frame plot of
your model using
plotting level 3.
If you don't see parts of the model, it may be because you haven't
set material types and thicknesses for some lines in Fie.
At the bottom of the screen Fad will display a set of numbers. If the number of ‘reversed’ edges is non-zero, it means that not all of the triangles are numbered consistently. If the number of ‘surface’ or ‘boundary’ edges is non-zero, it means that there is a hole or some other defect in the surface.
p␣9/grey) to see where the problem is. Note that there must be a space between the
9. The parameter
9specifies that shared triangle edges should be displayed if they are both oriented in the same direction. The edge shared between two neighbouring triangles should be oriented in opposite directions if the two triangles are both oriented in the same direction, so if any edges are displayed by the
p 9command it means that some triangles are oriented incorrectly. The
/greyoption causes all edges with lower plotting levels to be plotted in grey, so you can see where the plotting-level-9 edges are located. You can rotate the model using the interactive control.
p␣7/greycommand. If your surface is simple and closed, then nothing will be displayed. If any edges are displayed, it means that something is wrong with your surface; for example, a cap may be missing. Again, the
/greyoption causes edges with plotting levels less than 7 to be displayed in grey, so you can see where in the model any black edges are. Any reversed edges will also be displayed when the plotting level is 7.
p␣5/greycommand. The parameter
5specifies material boundaries, so if your surface is simple, closed and consists of a single material, then nothing will be displayed. If your surface is supposed to be simple and closed, and it’s supposed to consist of a single material, and some edges are displayed by
p␣5, then it means that one of those suppositions is wrong.
If part of your structure’s surface is shared with some other structure, perhaps its material type is the one for that other structure? The material type can be overridden in the subset definition (see Fie tutorial).
/grey option causes edges with plotting
levels less than 5 to be displayed in grey, so you can see where in
the model any black edges are. Any reversed
or surface edges will also be
displayed when the plotting level is 5.
p␣3/fi), then use the interactive control to rotate the plot and view it from many directions, to confirm that no orange triangles are seen.
fill option makes the display very slow if there
are a lot of elements. An alternative is to export the model
obj format and view it with
With the default settings, faces that are backward will be dark
regardless of the orientation of the model. This can be checked
by turning on and observing whether the faces become
less dark; or by turning on and observing whether
the faces disappear. The function
is also useful.
Modify windowcommand may be useful as a crude zoom capability to identify small features.
You can also use the
Locate command to determine
the x, y
and z coördinates of the problem. The z
coördinate will correpond to a slice in Fie, and the
x and y coördinates can be related to
the positions of points in Fie.
In Fie you can use the
command to jump to the slice and coordinates corresponding to the most
Once you have diagnosed the problem, make the required corrections in Fie, rerun Tr3 to generate a new model, then reload it in Fad and check things again.
p␣3/elloadto see which triangular elements have pressure loads applied to them.
p␣0/bc/-eraseto see what boundary conditions are applied to your model. The
/-eraseoption allows you to see the boundary conditions and loads at the same time.
ain the interactive control. If the model does not have its original orientation when exported, Fad won't later be able to combine the boundary conditions and loads from the surface model with the volume model generated by Gmsh.
ecommand) as a Gmsh
.geofile. If the input file name contains
_dbg, as put there by Tr3, it might as well be removed from the output file name here, since it's irrelevant to the
.geofile and makes the file name unnecessarily long.
.geo file contains
specifications of the meshing algorithm to be used (Netgen)
and the number of optimization passes to be performed (3),
and contains computed characteristic lengths.
Triplicate line error message occurs
it means that three (or more) triangles are sharing an edge
rather than just two, so the model doesn't form a simple
closed surface. The error message includes the element numbers
of the first two triangles involved. You can localize
the problem by using the Plot command to display just those
For example, if the error message mentions elements 123 and 456,
the following sequence of plot commands will display the two
elements in relation to the rest of the model:
p 5/grey(to display the whole model)
p 1 6 123/-erase(to display a single type-6 shell element without erasing the previous plot)
p 1 6 456/-erase(to display the second element)
Do?prompt before giving each of the
The Locate command can also then be used to determine the z coördinates and the approximate x and y coördinates of the nodes involved in the triangles, to help in locating the problem in Fie.
If you want to see the messages that are produced during processing, do(or Ctrl-L). The contents of the message console can be saved by right-clicking within it and selecting .
.mshin the name), and click on . In the dialogue that pops up, select as the format. It is recommended that you append as the format, browse to the directory where your model files are and specify a filename (you may need to explicitly include the
Tto the file name to make it clear that the file contains a tetrahedral volume mesh rather than a surface mesh.
If your mesh resolution is very high, Gmsh may take a long time
and if there's something wrong with your model
then Gmsh may not completely finish the job at all.
It is therefore
possible to save the
before it’s finished; you can then import it into Fad, but Fad
may not find any of the tetrahedral elements that it is looking
for, or they may not be optimized. So make your mesh
resolution reasonable and then patiently wait for Gmsh to say
that it has
Done optimizing 3D mesh
before you try saving the results.
If it says
Done meshing 3D but never says
Done optimizing 3D mesh, there is probably something
wrong with your model that is preventing Gmsh from generating
a good mesh. Look at the message console as described above
to see if there are warning or error messages.
gmsh filename.geo -3 -o filenameT.msh
icommand) the resulting
.mshfile into Fad. In the process, Fad will offer to retrieve boundary conditions, etc. from the
.sapsurface-model file that led to the
.geofile that led in turn to the
.mshfile. The ability to retrieve boundary conditions and material properties from the original
.sapsurface file depends on the fact that Gmsh does not modify the original surface nodes or create new surface nodes, so Fad can establish a one-to-one correspondence between the original surface shell elements and the surface facets of the tetrahedral mesh produce by Gmsh.
p␣3). A line should be displayed saying
Nel13 =and a reasonable number of tetrahedral elements.
If you need to create a model that contains multiple connected
substructures, perform the above steps for each substructure,
and use the
Then use the Join command to join them
together. First join two of the substructures, then join a
third substructure to the combination, and so on.
to save the tetrahedral models as