Documentation generated by
00001 /** \page GeomDoc Geometry in Sundance 00002 00003 <BODY> 00004 00005 There are two categories of geometric objects in Sundance: 00006 those relating to discrete geometry (see \ref MeshDoc) and 00007 those relating to symbolic geometry (see \ref CellSetDoc). 00008 00009 You will need to work with the discrete geometry objects when you 00010 read meshes (see \ref MeshInputDoc), 00011 and when you tag certain cells on which boundary conditions 00012 might be applied (see \ref LabelDoc). 00013 00014 Weak equations and boundary conditions will be associated with 00015 symbolic geometry objects called CellSets. A CellSet might refer 00016 to all cells given a certain label, for instance. 00017 00018 \section MeshDoc Discrete geometry 00019 00020 The user-level discrete geometry objects are Point, Cell, and Mesh. 00021 <ul> 00022 00023 <li> A Point represents the position vector of 00024 a point in space, parametrized by its cartesian coordinates. Operator 00025 overloading is used to define vector arithmetic operations on points; for 00026 example, a+b adds the position vectors of a and b. 00027 00028 <li> A Cell is a topological cell in the mesh. Zero-cells are points, 00029 one-cells are lines, two-cells are polygons, three-cells are polyhedra. 00030 Any given Cell can be tagged with a String label, so that it can be identified 00031 as part of a domain on which an equation is to be applied (see \ref CellSetDoc 00032 and \ref LabelDoc below). 00033 00034 Cells store topological information (connectivity with their neighbors) and 00035 geometric information (positions of nodes) independently. You can reposition 00036 a node point, and all cells that contain it will automatically refer 00037 to the new nodal position. 00038 00039 A Cell has accessors that let you look up its facet and cofacet Cells, and 00040 look up its vertex and node points. You will often use these in writing 00041 conditional functions to identify cells on a particular subdomain 00042 (see \ref LabelDoc). 00043 00044 The data underlying a Cell object is stored by reference, so a change to 00045 a Cell also changes all copies of that Cell. 00046 00047 <li> A Mesh is a data structure that contains all Points 00048 and all Cells of dimension 0 through DMax. 00049 Unless you are building meshes from scratch (see \ref MeshBuildingDoc) 00050 you will usually only need two methods of Mesh: 00051 00052 <ul> 00053 <li> labelCells() for tagging groups of cells with a label (see \ref LabelDoc). 00054 <li> scatterMesh() for scattering a mesh to several processors 00055 (see \ref PartitionDoc) 00056 </ul> 00057 00058 A Mesh is a reference-counted handle to a lower-level mesh data structure. 00059 You can freely copy meshes without blowing out memory, but be aware 00060 that changes to a mesh will instantly propagate to all copies you have made. 00061 00062 </ul> 00063 00064 \warning There is a feature of Mesh and Cell memory management that 00065 can result in memory corruption, fortunately only in circumstances 00066 that are rare and easily avoidable. To avoid problems 00067 please follow the simple rule that 00068 <b> a Cell must never be used after its Mesh has been destroyed. </b> 00069 Here's a simple example: 00070 \code 00071 // never, ever do this 00072 Cell myCell; 00073 00074 { 00075 Mesh myMesh = someMeshReader.getMesh(); 00076 myCell = myMesh.cell(0, 0); 00077 } 00078 // at end of scope, myMesh was destroyed and myCell is left 00079 // with a reference to a nonexistent mesh. The next statement 00080 // will segfault. 00081 00082 Point x = myCell.point(0); 00083 \endcode 00084 Follow the rule above, make sure your Meshes survive as long as 00085 their Cells do, and you will have no problem with memory management 00086 in Sundance geometry. 00087 00088 \section MeshInputDoc Reading meshes from files 00089 00090 In most problems you will read a mesh from an input file. 00091 There are many mesh file formats out there, so Sundance has an extensible 00092 inteface for reading meshes: the MeshReader system. 00093 00094 To create a MeshReader, allocate one of the mesh reader subclasses 00095 and capture into a MeshReader handle. For example, if your mesh 00096 was created with Jonathan Shewchuk's 00097 <A HREF="http://www.cs.cmu.edu/~quake/triangle.html"> triangle </A> 00098 mesher and stored in Shewchuk's file format in files "myMesh.node" and 00099 "myMesh.ele", you would create 00100 a ShewchukMeshReader object. 00101 \code 00102 MeshReader reader = new ShewchukMeshReader("myMesh"); 00103 \endcode 00104 To create a mesh, you would then invoke the getMesh() method of 00105 MeshReader: 00106 \code 00107 Mesh myMesh = reader.getMesh(); 00108 \endcode 00109 00110 \section CellSetDoc Grouping Cells into subdomains (CellSets) 00111 00112 Sundance lets you define subdomains, called CellSets, 00113 on which you can apply 00114 an equation; for example, you can define a boundary region on which 00115 a boundary condition is going to hold. 00116 00117 There are several ways to create CellSets 00118 <ul> 00119 <li> defining a CellSet to include all cells having a given label (to see 00120 how to set labels on a group of cells, see \ref LabelDoc below.) 00121 <li> doing a union operation on two or more existing CellSets 00122 <li> using the predefined BoundaryCellSet object, which includes all boundary cells 00123 of dimension \f$D_{max}-1\f$. 00124 <li> using the predefined MaximalCellSet object, which includes all cells 00125 od dimension \f$D_{max}\f$. 00126 </ul> 00127 00128 A CellSet is a symbolic geometry object, independent of any particular 00129 mesh. 00130 00131 \section LabelDoc Labeling cells 00132 00133 Setting a label on a given Cell is simple enough: just call the setLabel() 00134 method on that Cell with the String label as an argument. However, 00135 usually your task won't be labeling Cells, it will be identifying the group 00136 of Cells that you want to label. For example, you might want to find 00137 all Cells that are positioned on the top of a wing, and give each of them the 00138 label "top". 00139 00140 Mesh has a method called labelCells() 00141 for identifying and labeling Cells that satisfy 00142 a user-defined condition. The condition is specified through a 00143 user-defined C++ function of type CellConditional. CellConditional takes 00144 a Cell as its sole argument, and returns a bool. For example, 00145 suppose you want to give the label "A" to all 1-cells that are on the 00146 line segment y=0.1 x + 0.5 with the additional stipulation that x be 00147 in the interval [0, 3]. You can write a CellConditional function 00148 that returns true if both of the cell's vertices are on that line, 00149 otherwise false: 00150 00151 \code 00152 bool onLineA(const Cell& cell) 00153 { 00154 00155 // identify cells for which all vertices are on y = 0.1*x + 0.5 00156 00157 for (int i=0; i<cell.numFacets(); i++) 00158 { 00159 const Point& pt = cell.facet(0,i).point(0); 00160 bool ptIsOnLine = fabs(0.1*pt[0] + 0.5 - pt[1]) < 1.0e-10; 00161 if (!ptIsOnLine) return false; 00162 } 00163 00164 return true; 00165 } 00166 00167 \endcode 00168 00169 Having written such a conditional function, you can then label 00170 all cells for which the condition is true by making a call to 00171 labelCells(). 00172 00173 \code 00174 /* read mesh from a file in Shewchuk format */ 00175 MeshReader reader = new ShewchukMeshReader("myMesh"); 00176 Mesh mesh = reader.getMesh(); 00177 00178 /* give label "A" to all cells on line y=0.1*x + 0.5 */ 00179 mesh.labelCells(1, "A", onLineA); 00180 \endcode 00181 00182 00183 00184 \section PartitionDoc Partitioning meshes for parallel solves 00185 00186 The present version of 00187 Sundance does mesh partitioning in serial, and then scatters the processor 00188 submeshes to files for use in a later parallel run. Currently, all 00189 partitioning is done with Chaco. 00190 00191 To partition a mesh, do the following: 00192 <ul> 00193 <li> create or read 00194 a mesh in serial (presumably on a machine with lots of memory). 00195 <li> create a MeshWriter for writing the submeshes to files. 00196 <li> decide the number of pieces into which the mesh will be partitioned. 00197 <li> call the scatterMesh() method of Mesh, which does the partitioning 00198 and writes the submeshes to files. 00199 </ul> 00200 00201 Support for parallel mesh partitioning is a long-term goal. 00202 00203 00204 00205 \section MeshBuildingDoc Assembling a mesh from scratch 00206 00207 Normally, you will read a mesh from a file. However, in some cases 00208 you may want to assemble a mesh by hand (perhaps in order to write a 00209 new MeshReader subclass to handle your favorite mesh file format). 00210 00211 <ul> 00212 <li> First, create an empty Mesh, specifying the dimension of the mesh. 00213 <li> Next, use the addPoint() method of Mesh to put your nodal points into the mesh. 00214 <li> Finally, use the createMaximalCell() method of Mesh to put your maximal 00215 cells into the mesh. All lower-dimensional cells are automatically and 00216 transparently created 00217 in the process of inserting the maximal cells. 00218 <ul> 00219 <li> When creating the maximal cells, you don't work with the Cell constructors 00220 directly. Rather, You create a CellFactory object of the appropriate type; 00221 then when createMaximalCell() needs to construct a Cell, it makes 00222 a call to methods of CellFactory. 00223 The CellFactory constructor takes as its arguments information on the nodes 00224 of the cell you are about to create. 00225 Currently there are CellFactory subtypes for points, affine lines, triangles, 00226 and tetrahedra: 00227 <ul> 00228 <li> PointCellFactory 00229 <li> AffineLineCellFactory 00230 <li> AffineTriangleCellFactory 00231 <li> AffineTetCellFactory 00232 </ul> 00233 To extend Sundance to use other types of cells, e.g. brick cells, one would 00234 have to write a new CellFactory describing those cells. Since the creation 00235 of cells in a Mesh is done entirely with the CellFactory interface, 00236 the methods of Mesh 00237 that build cells would need no modification to handle the new cell type. 00238 </ul> 00239 </ul> 00240 00241 00242 00243 00244 <H2> 00245 Next section: \ref FEDoc 00246 </h2> 00247 00248 00249 </BODY> 00250 */ 00251 00252 00253 00254 00255 00256