Documentation generated by
00001 /** \page AboutDoc Read me first 00002 00003 <BODY> 00004 00005 Sundance is a moderately large and rather complex package. The good news 00006 for you is that only a small fraction of the classes and an 00007 even smaller fraction of the methods are needed for user-level code. 00008 In fact, for many "user-level" classes the only method you 00009 ever call will be 00010 the contructor. 00011 00012 One of the main goals of this document is to distinguish those 00013 user-level classes and methods from developer-level classes and methods. 00014 The class reference manual has separate pages for 00015 <A HREF="group_UserLevelClasses.html"> user-level classes </A> 00016 and for 00017 <A HREF="group_LowLevelClasses.html"> low-level classes. </A> 00018 Furthermore, in the method listing for each user-level class, 00019 there are subgroups for user-level and developer-only methods. 00020 00021 Please read the following sections on 00022 <ul> 00023 <li> \ref TypographicalConventions 00024 <li> \ref HandlePattern 00025 <li> \ref MemoryManagement 00026 <li> \ref Parallelism 00027 <li> \ref UsingSundanceEffectively 00028 </ul> 00029 00030 00031 00032 \section TypographicalConventions Typographical conventions in the source code and examples. 00033 00034 <ul> 00035 <li> Class names begin with capital letters, 00036 and each word within the name also begins capitalized. 00037 For example: MeshReader, DiscreteFunction. 00038 <li> method names and variables 00039 begin with lower-case letters, but subsequent words 00040 within the name are capitalized. For example: getCells() or numCells. 00041 <li> data member names end with an underscore. For example: myName_. 00042 </ul> 00043 00044 \section HandlePattern Handles and polymorphism in Sundance 00045 00046 Understanding <b> handle classes </b> and how they are used in Sundance 00047 is important for reading and writing Sundance code and browsing the source 00048 and class documentation. Handle classes are used in Sundance 00049 to simplify user-level polymorphism 00050 and provide transparent memory management. 00051 00052 Polymorphism is a buzzword meaning the representation 00053 of different but related object types (derived classes, or subclasses) 00054 through a common interface (the base class). In C++, you can't use a base-class 00055 object to represent a derived class; you have to use a <i> pointer </i> 00056 to the base class object to represent a <i> pointer </i> to the derived 00057 class. That leads to a rather awkward syntax and also requires attention 00058 to memory management. To simplify the interface and make memory 00059 management automatic, all user-level polymorphism is done with handle 00060 classes. A handle class is simply a class that contains a pointer 00061 to a base class, along with an interface providing user-callable methods, 00062 and a (presumably) intelligent scheme for memory 00063 management. 00064 00065 So if you want to work with a family of Sundance objects, for instance 00066 the different flavors of symbolic objects, you need only use: 00067 <ul> 00068 <li> the methods of the handle class for that family of classes 00069 <li> the <i> constructors </i> for the derived classes. 00070 </ul> 00071 You do not need to, and shouldn't, use any methods of the derived classes; 00072 all work with the family should be done with methods of the handle class. 00073 00074 For example, Sundance symbolic objects are represented with a handle class 00075 called Expr. The different symbolic types derive from ExprBase, but they are 00076 never used directly after construction; they are used only through the 00077 Expr handle class. The code fragment below shows some Exprs being constructed 00078 through subclass constructors and then being used in Expr operations. 00079 \code 00080 Expr x = new CoordExpr(0, "x"); 00081 Expr f = x + 3.0*sin(x); 00082 Expr dx = new Derivative(0); 00083 Expr df = dx*f; 00084 \endcode 00085 00086 Notice that a pointer 00087 to a subclass object is created using the <b> new </b> operator, 00088 and then given to the handle. The handle object assumes responsibility 00089 for that pointer: it does all memory management, any copying that might occur, 00090 and will eventually delete it. <b> You, the user, should <em> never </em> 00091 delete a pointer that has been passed to a handle. Memory management is 00092 the responsibility of the handle. </b> 00093 (Code like this will seem familiar to Java programmers, who call new 00094 but never delete). 00095 00096 Some important user-level handle classes in Sundance are 00097 <ul> 00098 <li> Expr, which is a handle for the subclasses of ExprBase. 00099 <li> CellSet, which is a handle for the subclasses of CellSetBase. 00100 <li> BasisFamily, which is a handle for the subclasses of BasisFamilyBase. 00101 <li> MeshReader, which is a handle for the subclasses of MeshReaderBase. 00102 <li> MeshWriter, which is a handle for the subclasses of MeshWriterBase. 00103 </ul> 00104 00105 In all of those cases 00106 <b> you should learn and use the methods of the handle classes. 00107 You should use only the <em> constructors </em> 00108 of the base class and its subclasses. </b> 00109 00110 00111 \section MemoryManagement Memory management 00112 00113 Sundance has been designed so that memory management is transparent to 00114 the user; that is, the user should never have to worry about deleting memory 00115 that has been allocated. With the exception of <b> new </b> pointers that are 00116 immediately passed to handles, user-level code is entirely free of pointers. 00117 00118 When writing Sundance code, you can assume that 00119 <ul> 00120 <li> User-level classes have well-defined behavior for copying and 00121 assignment. 00122 <li> User-level classes have well-defined destructors, and take 00123 care of their own memory management. 00124 </ul> 00125 00126 Data structures in a finite-elements problem can become rather large; for 00127 this reason, objects such as meshes, matrices, and degree-of-freedom 00128 maps are shallow-copied so 00129 that both the original and the copy refer to the same chunk of memory. A 00130 reference counted "smart pointer" 00131 is used to ensure that data is deleted only when necessary. 00132 It is important to understand that such a copying scheme leads to side 00133 effects: when a copy is modified, the original is modified as well. 00134 00135 Memory management of symbolic expressions is designed so that the contents 00136 of an expression can be modified after the fact. This lets you use the same 00137 expression with different data 00138 at all steps in an iterative procedure, for instance. 00139 Please see the section 00140 on \ref AssigningExprs for more information. 00141 00142 00143 \section Parallelism Parallelism 00144 00145 Sundance can both <i> assemble </i> and <i> solve </i> linear systems 00146 in parallel. 00147 00148 Parallel Sundance uses the SPMD paradigm, in which the same code 00149 is run on all processors. Communication is done using the CSMR MPIComm 00150 class, which is essentially an object wrapper for selected MPI features. 00151 To use Sundance's parallel capabilities, the CPPUtilities 00152 package supporting Sundance has to be built with 00153 MPI enabled, and you must use a parallel solver such as Trilinos. See the 00154 installation documentation for help in installing parallel Sundance. 00155 00156 One of the design goals was to make parallel solves look 00157 to the user as much as possible like serial solves. 00158 In particular, 00159 the symbolic description of an equation set and boundary conditions 00160 is completely unchanged from serial to parallel runs. 00161 To run a problem in parallel, you simply need to 00162 <ul> 00163 <li> use a parallel solver (such as trilinos) 00164 <li> use a partitioned mesh (see \ref PartitionDoc) 00165 </ul> 00166 Operations such as norms and definite integrals on discrete functions 00167 are done such that the result is collected from all processors. 00168 00169 \section UsingSundanceEffectively Using Sundance effectively 00170 00171 Sundance is 00172 a <I> high-level </I> system, in which a finite-element problem is described 00173 with expressions, function spaces, and domains instead of low-level 00174 concepts such as matrix entries, 00175 elements, and nodes. If you find yourself asking things such as 00176 "how can I modify the entries 00177 in row k" instead of "how can I modify my symbolic equation set," 00178 you're probably thinking about the problem the wrong way. 00179 Of course, you <I> can </i> write Sundance code using it's low-level features 00180 directly, but such code will be harder to read and almost always 00181 less efficient. 00182 So please stick to the higher-level objects and operations. 00183 Matlab programmers 00184 who have learned to write their problems as high-level vector and 00185 matrix operations instead of low-level loops will find this way of thinking 00186 natural. 00187 00188 <H2> 00189 Next section: \ref ExprDoc 00190 </h2> 00191 00192 00193 </BODY> 00194 */ 00195 00196 00197 00198 00199 00200 00201 00202 00203