Documentation generated by
00001 /** \page ExprDoc Mathematical expressions in Sundance 00002 00003 <BODY> 00004 <H1> Mathematical expressions in Sundance </H1> 00005 00006 Class Expr represents a mathematical expression. An Expr 00007 can be an atomic entity 00008 such as a constant, a function, or a differential operator; or an expr 00009 can be a compound object such as a sum, project, or list of exprs. 00010 00011 \section Contents 00012 00013 <UL> 00014 <LI> \ref CreatingExprs 00015 <LI> \ref ViewingExprs 00016 <LI> \ref AssigningExprs 00017 <LI> \ref ListingExprs 00018 <LI> \ref ExprMath 00019 </UL> 00020 00021 00022 \section CreatingExprs Creating expressions 00023 00024 The simplest type of Expr to create is a constant real-valued Expr, 00025 for example: 00026 00027 \code Expr solarMass = 2.0e33; // mass of the Sun in grams \endcode 00028 00029 00030 More generally, you can create an Expr by giving its constructor 00031 a pointer to an ExprBase 00032 subclass object. For example, to construct an Expr that represents the 00033 coordinate on the zeroth (x) axis, create a new CoordExpr object and pass 00034 it to an Expr ctor as follows: 00035 00036 \code Expr x = new CoordExpr(0, "x"); \endcode 00037 00038 The expression types that can be created at the user level are 00039 <ul> 00040 <li> CoordExpr - represents a coordinate function 00041 <li> Derivative - represents a differentiation operator 00042 <li> DiscreteFunction - represents a function that has been discretized 00043 on a finite-element space 00044 <li> ParameterExpr - represents a design parameter 00045 <li> UnknownFunction - represents an unknown in a finite-element problem 00046 <li> UserFuncExpr - can be used to access a function defined by the user 00047 <li> TestFunction - represents a test function in a finite-element 00048 problem 00049 </ul> 00050 00051 \section ViewingExprs Viewing Exprs 00052 00053 You might want to do several types of output with Exprs: 00054 <ul> 00055 <li> human-readable,, math-like symbolic output for information and debugging. 00056 This can be done with the stream insertion operator or the toString() method. 00057 For example, 00058 \code 00059 Expr f = 1.0 + 2.0*x; 00060 cout << f << endl; // writes 1 + 2*x; 00061 // or 00062 cout << f.toString() << endl; 00063 \endcode 00064 00065 <li> machine-readable symbolic output for use in a later Sundance session. 00066 Sundance uses XML for machine-readable representation of expressions. The 00067 toXML() method of Expr creates an XML tree representing the structure 00068 of the expression. 00069 <li> full output of the numerical values of a discrete function for 00070 visualization. This is done with FieldWriter methods, described in a later 00071 section. 00072 </ul> 00073 00074 00075 \section AssigningExprs Assignment and copying of expressions 00076 00077 It is important to understand the meaning of the assignment (=) operator 00078 for Sundance Exprs. Assignment and copy are by reference, so that 00079 if you create an expression 00080 \code 00081 f = a + b + c; 00082 \endcode 00083 and then assign something to \c c \c, 00084 \code 00085 c = sin(x); 00086 \endcode 00087 that change will instantly propagate to the copy of c in the sum f. 00088 \code 00089 cout << f << endl; // will print a + b + sin(x) 00090 \endcode 00091 00092 This feature lets you automatically update expressions in timestepping 00093 or nonlinear solve loops, making the code for such problems more efficient 00094 and much easier to understand. 00095 00096 The case when the lhs of an assignment operator appears on the rhs is 00097 handled as follows: the sequence of operations 00098 \code 00099 x = 5; 00100 x = y + x; 00101 \endcode 00102 leaves x set to y + 5. 00103 00104 00105 00106 00107 \section ListingExprs Listing expressions 00108 00109 Exprs can be listed heterogeneously. Listing can be used to create 00110 vector-valued or tensor-valued exprs. 00111 00112 You can create a listed expr using 00113 the List global method. For example, List(a, List(b, c)) produces 00114 a list that is structured like {a, {b, c}}. Lists can be manipulated with 00115 append(), join(), and flatten() methods, and elements (either scalar entries 00116 or sublists) can be accessed 00117 with the bracket ([]) operator. 00118 00119 The List() methods can take at most four entries. If you want to build 00120 a list with greater than four elements, create a list and then append 00121 to it. 00122 00123 00124 \subsection ExprAlgebra Algebraic operations 00125 00126 Operator overloading is used to represent operations on Exprs: 00127 <UL> 00128 <LI> addition: a+b, where a and b have identical list structures 00129 <LI> subtraction: a-b, where a and b have identical list structures 00130 <LI> multiplication: a*b, where a and b have list structures as follows: 00131 <UL> 00132 <LI> at least one of the two factors a and b is scalar-valued. 00133 <LI> a and b have a list structure such that a*b can be interpreted as 00134 a dot product. 00135 </UL> 00136 <LI> division: a/b, where b is a scalar 00137 </UL> 00138 00139 Sundance will simplify algebraic operations by grouping like terms and 00140 cancelling where appropriate. 00141 00142 \code 00143 Expr f = x + y + x; 00144 cout << f << endl; // prints 2*x + y 00145 \endcode 00146 00147 \code 00148 Expr f = x + y - x; 00149 cout << f << endl; // prints y 00150 \endcode 00151 00152 <B> Warning </B> <I> 00153 It is quite possible to create a meaningless expr, for example 00154 dividing by a vector-valued expr, x/{y,z}. It is not possible to detect 00155 such nonsensical exprs at compile-time, so all operations are 00156 checked at runtime and if nonsense is detected an exception is thrown. </I> 00157 00158 \subsection ExprDiff Differentiation 00159 00160 Differentiation operators are represented by the Derivative class. 00161 Application of a Derivative is done with the overloaded multiplication 00162 operator: 00163 00164 \code 00165 // create a differentiation operator 00166 Expr dx = new Derivative(0,1); 00167 00168 // create some function f 00169 Expr f = x*x; 00170 00171 // differentiate f 00172 Expr df = dx*f; 00173 00174 cout << df << endl; // prints 2*x 00175 00176 \endcode 00177 00178 Sundance symbolic objects are programmed to obey the sum, product, quotient, 00179 and chain rules. 00180 00181 00182 00183 \subsection ExprElemFunc Elementary functions 00184 00185 Elementary functions have been overloaded to act on Sundance Exprs. 00186 The argument to an elementary function must be a scalar-valued Expr. 00187 Example: 00188 00189 \code 00190 Expr f = sin(x); 00191 Expr df = dx*f; 00192 cout << df << endl; // prints cos(x) 00193 \endcode 00194 00195 Currently, Sundance defines: sin, cos, exp, log, cosh, sinh, sqrt, and pow. 00196 00197 00198 00199 00200 <H2> 00201 Next section: \ref GeomDoc 00202 </h2> 00203 00204 </BODY> 00205 */ 00206 00207 00208 00209 00210 00211