 # Contents of /trunk/doc/user/escript.tex

Revision 1957 - (show annotations)
Mon Nov 3 06:14:18 2008 UTC (12 years, 7 months ago) by jfenwick
File MIME type: application/x-tex
File size: 48991 byte(s)
Some fixes to user guide


 1 2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 3 % 4 % Copyright (c) 2003-2008 by University of Queensland 5 % Earth Systems Science Computational Center (ESSCC) 6 7 % 8 % Primary Business: Queensland, Australia 9 % Licensed under the Open Software License version 3.0 10 11 % 12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 13 14 15 \chapter{The Module \escript} 16 \label{ESCRIPT CHAP} 17 18 19 \begin{figure} 20 \includegraphics[width=\textwidth]{figures/EscriptDiagram1} 21 \caption{\label{ESCRIPT DEP}Dependency of Function Spaces. An arrow indicates that a function in the 22 function space at the starting point can be interpreted as a function in the function space of the arrow target.} 23 \end{figure} 24 25 \escript is a Python module that allows you to represent the values of 26 a function at points in a \Domain in such a way that the function will 27 be useful for the Finite Element Method (FEM) simulation. It also 28 provides what we call a function space that describes how the data is 29 used in the simulation. Stored along with the data is information 30 about the elements and nodes which will be used by \finley. 31 32 In order to understand what we mean by the term 'function space', 33 consider that the solution of a partial differential equation 34 \index{partial differential equation} (PDE) is a function on a domain 35 $\Omega$. When solving a PDE using FEM, the solution is 36 piecewise-differentiable but, in general, its gradient is 37 discontinuous. To reflect these different degrees of smoothness, 38 different function spaces are used. For instance, in FEM, the 39 displacement field is represented by its values at the nodes of the 40 mesh, and so is continuous. The strain, which is the symmetric 41 part of the gradient of the displacement field, is stored on the 42 element centers, and so is considered to be discontinuous. 43 44 A function space is described by a \FunctionSpace object. The 45 following statement generates the object \var{solution_space} which is 46 a \FunctionSpace object and provides access to the function space of 47 PDE solutions on the \Domain \var{mydomain}: 48 49 \begin{python} 50 solution_space=Solution(mydomain) 51 \end{python} 52 The following generators for function spaces on a \Domain \var{mydomain} are available: 53 \begin{itemize} 54 \item \var{Solution(mydomain)}: solutions of a PDE. 55 \item \var{ReducedSolution(mydomain)}: solutions of a PDE with a reduced smoothness requirement. 56 \item \var{ContinuousFunction(mydomain)}: continuous functions, eg. a temperature distribution. 57 \item \var{Function(mydomain)}: general functions which are not necessarily continuous, eg. a stress field. 58 \item \var{FunctionOnBoundary(mydomain)}: functions on the boundary of the domain, eg. a surface pressure. 59 \item \var{FunctionOnContact0(mydomain)}: functions on side $0$ of the discontinuity. 60 \item \var{FunctionOnContact1(mydomain)}: functions on side $1$ of the discontinuity. 61 \end{itemize} 62 63 The reduced smoothness for PDE solution is often used to fulfill the Ladyzhenskaya–-Babuska–-Brezzi condition \cite{LBB} when 64 solving saddle point problems \index{saddle point problems}, eg. the Stokes equation. 65 A discontinuity \index{discontinuity} is a region within the domain across which functions may be discontinuous. 66 The location of discontinuity is defined in the \Domain object. 67 \fig{ESCRIPT DEP} shows the dependency between the types of function spaces. 68 69 The solution of a PDE is a continuous function. Any continuous function can be seen as a general function 70 on the domain and can be restricted to the boundary as well as to one side of 71 discontinuity (the result will be different depending on 72 which side is chosen). Functions on any side of the 73 discontinuity can be seen as a function on the corresponding other side. 74 75 A function on the boundary or on one side of 76 the discontinuity cannot be seen as a general function on the domain as there are no values 77 defined for the interior. For most PDE solver libraries 78 the space of the solution and continuous functions is identical, however in some cases, eg. 79 when periodic boundary conditions are used in \finley, a solution 80 fulfills periodic boundary conditions while a continuous function does not have to be periodic. 81 82 The concept of function spaces describes the properties of 83 functions and allows abstraction from the actual representation 84 of the function in the context of a particular application. For instance, 85 in the FEM context a 86 function of the \Function type 87 is usually represented by its values at the element center, 88 but in a finite difference scheme the edge midpoint of cells is preferred. 89 By changing its function space you can use the same function in a Finite Difference 90 scheme instead of Finite Element scheme. 91 Changing the function space of a particular function 92 will typically lead to a change of its representation. 93 So, when seen as a general function, 94 a continuous function which is typically represented by its values 95 on the node of the FEM mesh or finite difference grid 96 must be interpolated to the element centers or the cell edges, 97 respectively. Interpolation happens automatically in \escript 98 whenever it is required. 99 100 In \escript the class that stores these functions is called \Data. 101 The function is represented through its values on \DataSamplePoints where 102 the \DataSamplePoints are chosen according to the function space 103 of the function. 104 \Data class objects are used to define the coefficients 105 of the PDEs to be solved by a PDE solver library 106 and also to store the solutions of the PDE. 107 108 The values of the function have a rank which gives the 109 number of indices, and a \Shape defining the range of each index. 110 The rank in \escript is limited to the range $0$ through $4$ and 111 it is assumed that the rank and \Shape is the same for all \DataSamplePoints. 112 The \Shape of a \Data object is a tuple (list) \var{s} of integers. The length 113 of \var{s} is the rank of the \Data object and the \var{i}-th index ranges between $0$ and $\var{s[i]}-1$. 114 For instance, a stress field has rank $2$ and 115 \Shape $(d,d)$ where $d$ is the spatial dimension. 116 The following statement creates the \Data object 117 \var{mydat} representing a 118 continuous function with values 119 of \Shape $(2,3)$ and rank $2$: 120 \begin{python} 121 mydat=Data(value=1,what=ContinuousFunction(myDomain),shape=(2,3)) 122 \end{python} 123 The initial value is the constant $1$ for all \DataSamplePoints and 124 all components. 125 126 \Data objects can also be created from any \numarray 127 array or any object, such as a list of floating point numbers, 128 that can be converted into a \numarrayNA \cite{NUMARRAY}. 129 The following two statements 130 create objects which are equivalent to \var{mydat}: 131 \begin{python} 132 mydat1=Data(value=numarray.ones((2,3)),what=ContinuousFunction(myDomain)) 133 mydat2=Data(value=[[1,1],[1,1],[1,1]],what=ContinuousFunction(myDomain)) 134 \end{python} 135 In the first case the initial value is \var{numarray.ones((2,3))} 136 which generates a $2 \times 3$ matrix as a \numarrayNA 137 filled with ones. The \Shape of the created \Data object 138 it taken from the \Shape of the array. In the second 139 case, the creator converts the initial value, which is a list of lists, 140 and converts it into a \numarrayNA before creating the actual 141 \Data object. 142 143 For convenience \escript provides creators for the most common types 144 of \Data objects in the following forms (\var{d} defines the 145 spatial dimension): 146 \begin{itemize} 147 \item \var{Scalar(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(,))} (each value is a scalar), 148 e.g a temperature field. 149 \item \var{Vector(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d))} (each value is a vector), e.g 150 a velocity field. 151 \item \var{Tensor(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d))}, 152 eg. a stress field. 153 \item \var{Tensor4(0,Function(mydomain))} is the same as \var{Data(0,Function(myDomain),(d,d,d,d))} 154 eg. a Hook tensor field. 155 \end{itemize} 156 Here the initial value is $0$ but any object that can be converted into a \numarrayNA and whose \Shape 157 is consistent with \Shape of the \Data object to be created can be used as the initial value. 158 159 \Data objects can be manipulated by applying unary operations (eg. cos, sin, log) point 160 and can be combined point-wise by applying arithmetic operations (eg. +, - ,* , /). 161 It is to be emphasized that \escript itself does not handle any spatial dependencies as 162 it does not know how values are interpreted by the processing PDE solver library. 163 However \escript invokes interpolation if this is needed during data manipulations. 164 Typically, this occurs in binary operation when both arguments belong to different 165 function spaces or when data are handed over to a PDE solver library 166 which requires functions to be represented in a particular way. 167 168 The following example shows the usage of {\tt Data} objects: Assume we have a 169 displacement field $u$ and we want to calculate the corresponding stress field 170 $\sigma$ using the linear--elastic isotropic material model 171 \begin{eqnarray}\label{eq: linear elastic stress} 172 \sigma\hackscore {ij}=\lambda u\hackscore {k,k} \delta\hackscore {ij} + \mu ( u\hackscore {i,j} + u\hackscore {j,i}) 173 \end{eqnarray} 174 where $\delta\hackscore {ij}$ is the Kronecker symbol and 175 $\lambda$ and $\mu$ are the Lame coefficients. The following function 176 takes the displacement {\tt u} and the Lame coefficients 177 \var{lam} and \var{mu} as arguments and returns the corresponding stress: 178 \begin{python} 179 from esys.escript import * 180 def getStress(u,lam,mu): 181 d=u.getDomain().getDim() 182 g=grad(u) 183 stress=lam*trace(g)*kronecker(d)+mu*(g+transpose(g)) 184 return stress 185 \end{python} 186 The variable 187 \var{d} gives the spatial dimension of the 188 domain on which the displacements are defined. 189 \var{kronecker} returns the Kronecker symbol with indexes 190 $i$ and $j$ running from $0$ to \var{d}-1. The call \var{grad(u)} requires 191 the displacement field \var{u} to be in the \var{Solution} or \ContinuousFunction 192 function space. The result \var{g} as well as the returned stress will be in the \Function function space. 193 If, for example, \var{u} is the solution of a PDE then \var{getStress} might be called 194 in the following way: 195 \begin{python} 196 s=getStress(u,1.,2.) 197 \end{python} 198 However \var{getStress} can also be called with \Data objects as values for 199 \var{lam} and \var{mu} which, 200 for instance in the case of a temperature dependency, are calculated by an expression. 201 The following call is equivalent to the previous example: 202 \begin{python} 203 lam=Scalar(1.,ContinuousFunction(mydomain)) 204 mu=Scalar(2.,Function(mydomain)) 205 s=getStress(u,lam,mu) 206 \end{python} 207 208 The function \var{lam} belongs to the \ContinuousFunction function space 209 but with \var{g} the function \var{trace(g)} is in the \Function function space. 210 In the evaluation of the product \var{lam*trace(g)} we have different function 211 spaces (on the nodes versus in the centers) and at first glance we have incompatible data. 212 \escript converts the arguments in an appropriate function space according to 213 Table~\ref{ESCRIPT DEP}. In this example that means 214 \escript sees \var{lam} as a function of the \Function function space. 215 In the context of FEM this means the nodal values of 216 \var{lam} are interpolated to the element centers. 217 The interpolation is automatic and requires no special handling. 218 219 \begin{figure} 220 \includegraphics[width=\textwidth]{figures/EscriptDiagram2} 221 \caption{\label{Figure: tag}Element Tagging. A rectangular mesh over a region with two rock types {\it white} and {\it gray}. 222 The number in each cell refers to the major rock type present in the cell ($1$ for {\it white} and $2$ for {\it gray}). 223 } 224 \end{figure} 225 226 Material parameters such as the Lame coefficients are typically dependent on rock types present in the 227 area of interest. A common technique to handle these kinds of material parameters is "tagging", which 228 uses storage efficiently. \fig{Figure: tag} 229 shows an example. In this case two rock types {\it white} and {\it gray} can be found in the domain. The domain 230 is subdivided into triangular shaped cells. Each 231 cell has a tag indicating the rock type predominately found in this cell. Here $1$ is used to indicate 232 rock type {\it white} and $2$ for rock type {\it gray}. The tags are assigned at the time when the cells are generated 233 and stored in the \Domain class object. To allow easier usage of tags, names can be used instead of numbers. These names are typically defined 234 at the time when the geometry is generated. 235 236 The following statements show how, for the 237 example of \fig{Figure: tag}, the stress calculation discussed above and tagged values are used for 238 \var{lam}: 239 \begin{python} 240 lam=Scalar(value=2.,what=Function(mydomain)) 241 insertTaggedValue(lam,white=30.,gray=5000.) 242 s=getStress(u,lam,2.) 243 \end{python} 244 In this example \var{lam} is set to $30$ for those cells with tag {\it white} (=$1$) and to $5000.$ for those cells 245 with tag {\it gray} (=$2$_. The initial value $2$ of \var{lam} is used as a default value for the case when a tag 246 is encountered which has not been linked with a value. The \var{getStress} method 247 does not need to be changed now that we are using tags. 248 \escript resolves the tags when \var{lam*trace(g)} is calculated. 249 250 This brings us to a very important point about \escript. 251 You can develop a simulation with constant Lame coefficients, and then later switch to tagged 252 Lame coefficients without otherwise changing your python script. 253 In short, you can use the same script to model with different domains and different types of input data. 254 255 There are three main ways in which \Data objects are represented internally: constant, tagged, and expanded. 256 In the constant case, the same value is used at each sample point and only a single value is stored to save memory. 257 In the expanded case, each sample point has an individual value (such as for the solution of a PDE). 258 This is where your largest data sets will be created because the values are stored as a complete array. 259 The tagged case has already been discussed above. 260 261 Expanded data is created when you create a \Data object with expanded=True. 262 Tagged data sets are created when you use the insertTaggedValue() method as shown above. 263 264 Values are accessed through a sample reference number. Operations on expanded \Data 265 objects have to be performed for each sample point individually. When tagged values are used, the values are 266 held in a dictionary. Operations on tagged data require processing the set of tagged values only, rather than 267 processing the value for each individual sample point. 268 \escript allows any mixture of constant, tagged and expanded data in a single expression. 269 270 \Data objects can be written to disk files and read with \var{dump} and \var{load}, both of which use \netCDF. 271 Use these to save data for visualization, checkpoint/restart or simply to save and reuse data that was expensive to compute. 272 273 For instance to save the coordinates of the data points of the \FunctionSpace 274 \ContinuousFunction to the file {\tt x.nc} use 275 \begin{python} 276 x=ContinuousFunction(mydomain).getX() 277 x.dump("x.nc") 278 \end{python} 279 To recover the object \var{x} use 280 \begin{python} 281 x=load("x.nc", mydomain) 282 \end{python} 283 The dump file {\tt x.nc} does not contain a representation of the \Domain, even though it is required to recreate \var{x}. 284 It is common to simply recreate the \Domain before reading a \Data, or you may read and write your \Domain in a separate file with 285 \var{domain=ReadMesh(fileName)} and \var{domain.write(fileName)}. 286 287 The function space of the \Data is stored in {\tt x.nc}, though. 288 That means that \Data objects that are constant or tagged can be recovered with a different \Domain (provided that the domains use the same \FunctionSpace types). 289 If the \Data object 290 is expanded, the number of data points in the file and of the \Domain for the particular \FunctionSpace must match. 291 Moreover, the ordering of the values is checked using the reference identifiers provided by 292 \FunctionSpace on the \Domain. In some cases, data points will be re-ordered. Take care to be sure you get what you want! 293 294 295 \section{\escript Classes} 296 \declaremodule{extension}{esys.escript} 297 \modulesynopsis{Data manipulation} 298 299 \subsection{\Domain class} 300 \begin{classdesc}{Domain}{} 301 A \Domain object is used to describe a geometric region together with 302 a way of representing functions over this region. 303 The \Domain class provides an abstract representation of the domain of \FunctionSpace and \Data objects. 304 \Domain itself has no initialization but implementations of \Domain are 305 instantiated by numerical libraries making use of \Data objects. 306 \end{classdesc} 307 The following methods are available: 308 \begin{methoddesc}[Domain]{getDim}{} 309 returns the spatial dimension of the \Domain. 310 \end{methoddesc} 311 312 \begin{methoddesc}[Domain]{getX}{} 313 returns the locations in the \Domain. The \FunctionSpace of the returned 314 \Data object is chosen by the \Domain implementation. Typically it will be 315 in the \Function. 316 \end{methoddesc} 317 318 \begin{methoddesc}[Domain]{setX}{newX} 319 assigns a new location to the \Domain. \var{newX} has to have \Shape $(d,)$ 320 where $d$ is the spatial dimension of the domain. Typically \var{newX} must be 321 in the \ContinuousFunction but the space actually to be used depends on the \Domain implementation. 322 \end{methoddesc} 323 324 \begin{methoddesc}[Domain]{getNormal}{} 325 returns the surface normals on the boundary of the \Domain as \Data object. 326 \end{methoddesc} 327 328 \begin{methoddesc}[Domain]{getSize}{} 329 returns the local sample size, e.g. the element diameter, as \Data object. 330 \end{methoddesc} 331 332 \begin{methoddesc}[Domain]{setTagMap}{tag_name, tag} 333 defines a mapping of the tag name \var{tag_name} to the \var{tag}. 334 \end{methoddesc} 335 \begin{methoddesc}[Domain]{getTag}{tag_name} 336 returns the tag associated with the tag name \var{tag_name}. 337 \end{methoddesc} 338 \begin{methoddesc}[Domain]{isValidTagName}{tag_name} 339 return \True if \var{tag_name} is a valid tag name. 340 \end{methoddesc} 341 342 \begin{methoddesc}[Domain]{__eq__}{arg} 343 returns \True of the \Domain \var{arg} describes the same domain. Otherwise 344 \False is returned. 345 \end{methoddesc} 346 347 \begin{methoddesc}[Domain]{__ne__}{arg} 348 returns \True of the \Domain \var{arg} does not describe the same domain. 349 Otherwise \False is returned. 350 \end{methoddesc} 351 352 \begin{methoddesc}[Domain]{__str__}{g} 353 returns string representation of the \Domain. 354 \end{methoddesc} 355 356 \subsection{\FunctionSpace class} 357 \begin{classdesc}{FunctionSpace}{} 358 \FunctionSpace objects are used to define properties of \Data objects, such as continuity. \FunctionSpace objects 359 are instantiated by generator functions. \Data objects in particular \FunctionSpace are 360 represented by their values at \DataSamplePoints which are defined by the type and the \Domain of the 361 \FunctionSpace. 362 \end{classdesc} 363 The following methods are available: 364 \begin{methoddesc}[FunctionSpace]{getDim}{} 365 returns the spatial dimension of the \Domain of the \FunctionSpace. 366 \end{methoddesc} 367 368 369 370 \begin{methoddesc}[FunctionSpace]{getX}{} 371 returns the location of the \DataSamplePoints. 372 \end{methoddesc} 373 374 \begin{methoddesc}[FunctionSpace]{getNormal}{} 375 If the domain of functions in the \FunctionSpace 376 is a hypermanifold (e.g. the boundary of a domain) 377 the method returns the outer normal at each of the 378 \DataSamplePoints. Otherwise an exception is raised. 379 \end{methoddesc} 380 381 \begin{methoddesc}[FunctionSpace]{getSize}{} 382 returns a \Data objects measuring the spacing of the \DataSamplePoints. 383 The size may be zero. 384 \end{methoddesc} 385 386 \begin{methoddesc}[FunctionSpace]{getDomain}{} 387 returns the \Domain of the \FunctionSpace. 388 \end{methoddesc} 389 390 \begin{methoddesc}[FunctionSpace]{setTags}{new_tag, mask} 391 assigns a new tag \var{new_tag} to all data sample 392 where \var{mask} is positive for a least one data point. 393 \var{mask} must be defined on the this \FunctionSpace. 394 Use the \var{setTagMap} to assign a tag name to \var{new_tag}. 395 \end{methoddesc} 396 397 \begin{methoddesc}[FunctionSpace]{__eq__}{arg} 398 returns \True of the \Domain \var{arg} describes the same domain. Otherwise 399 \False is returned. 400 \end{methoddesc} 401 402 \begin{methoddesc}[FunctionSpace]{__ne__}{arg} 403 returns \True of the \Domain \var{arg} describes the note same domain. 404 Otherwise \False is returned. 405 \end{methoddesc} 406 407 \begin{methoddesc}[Domain]{__str__}{g} 408 returns string representation of the \Domain. 409 \end{methoddesc} 410 411 The following function provide generators for \FunctionSpace objects: 412 \begin{funcdesc}{Function}{domain} 413 returns the \Function on the \Domain \var{domain}. \Data objects in this type of \Function 414 are defined over the whole geometric region defined by \var{domain}. 415 \end{funcdesc} 416 417 \begin{funcdesc}{ContinuousFunction}{domain} 418 returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function 419 are defined over the whole geometric region defined by \var{domain} and assumed to represent 420 a continuous function. 421 \end{funcdesc} 422 423 \begin{funcdesc}{FunctionOnBoundary}{domain} 424 returns the \ContinuousFunction on the \Domain domain. \Data objects in this type of \Function 425 are defined on the boundary of the geometric region defined by \var{domain}. 426 \end{funcdesc} 427 428 \begin{funcdesc}{FunctionOnContactZero}{domain} 429 returns the \FunctionOnContactZero the \Domain domain. \Data objects in this type of \Function 430 are defined on side 0 of a discontinuity within the geometric region defined by \var{domain}. 431 The discontinuity is defined when \var{domain} is instantiated. 432 \end{funcdesc} 433 434 \begin{funcdesc}{FunctionOnContactOne}{domain} 435 returns the \FunctionOnContactOne on the \Domain domain. 436 \Data objects in this type of \Function 437 are defined on side 1 of a discontinuity within the geometric region defined by \var{domain}. 438 The discontinuity is defined when \var{domain} is instantiated. 439 \end{funcdesc} 440 441 \begin{funcdesc}{Solution}{domain} 442 returns the \SolutionFS on the \Domain domain. \Data objects in this type of \Function 443 are defined on geometric region defined by \var{domain} and are solutions of 444 partial differential equations \index{partial differential equation}. 445 \end{funcdesc} 446 447 \begin{funcdesc}{ReducedSolution}{domain} 448 returns the \ReducedSolutionFS on the \Domain domain. \Data objects in this type of \Function 449 are defined on geometric region defined by \var{domain} and are solutions of 450 partial differential equations \index{partial differential equation} with a reduced smoothness 451 for the solution approximation. 452 \end{funcdesc} 453 454 \subsection{\Data Class} 455 \label{SEC ESCRIPT DATA} 456 457 The following table shows arithmetic operations that can be performed point-wise on 458 \Data objects. 459 \begin{tableii}{l|l}{textrm}{expression}{Description} 460 \lineii{+\var{arg0}} {identical to \var{arg} \index{+}} 461 \lineii{-\var{arg0}} {negation\index{-}} 462 \lineii{\var{arg0}+\var{arg1}} {adds \var{arg0} and \var{arg1} \index{+}} 463 \lineii{\var{arg0}*\var{arg1}} {multiplies \var{arg0} and \var{arg1} \index{*}} 464 \lineii{\var{arg0}-\var{arg1}} {difference \var{arg1} from\var{arg1} \index{-}} 465 \lineii{\var{arg0}/\var{arg1}} {divide \var{arg0} by \var{arg1} \index{/}} 466 \lineii{\var{arg0}**\var{arg1}} {raises \var{arg0} to the power of \var{arg1} \index{**}} 467 \end{tableii} 468 At least one of the arguments \var{arg0} or \var{arg1} must be a 469 \Data object. 470 Either of the arguments may be a \Data object, a python number or a numarray object. 471 472 If \var{arg0} or \var{arg1} are 473 defined on different \FunctionSpace an attempt is made to convert \var{arg0} 474 to the \FunctionSpace of \var{arg1} or to convert \var{arg1} to 475 the \FunctionSpace of \var{arg0}. Both arguments must have the same 476 \Shape or one of the arguments may be of rank 0 (a constant). 477 478 The returned \Data object has the same \Shape and is defined on 479 the \DataSamplePoints as \var{arg0} or \var{arg1}. 480 481 The following table shows the update operations that can be applied to 482 \Data objects: 483 \begin{tableii}{l|l}{textrm}{expression}{Description} 484 \lineii{\var{arg0}+=\var{arg2}} {adds \var{arg0} to \var{arg2} \index{+}} 485 \lineii{\var{arg0}*=\var{arg2}} {multiplies \var{arg0} with \var{arg2} \index{*}} 486 \lineii{\var{arg0}-=\var{arg2}} {subtracts \var{arg2} from\var{arg2} \index{-}} 487 \lineii{\var{arg0}/=\var{arg2}} {divides \var{arg0} by \var{arg2} \index{/}} 488 \lineii{\var{arg0}**=\var{arg2}} {raises \var{arg0} by \var{arg2} \index{**}} 489 \end{tableii} 490 \var{arg0} must be a \Data object. \var{arg1} must be a 491 \Data object or an object that can be converted into a 492 \Data object. \var{arg1} must have the same \Shape like 493 \var{arg1} or has rank 0. In the latter case it is 494 assumed that the values of \var{arg1} are constant for all 495 components. \var{arg1} must be defined in the same \FunctionSpace as 496 \var{arg0} or it must be possible to interpolate \var{arg1} onto the 497 \FunctionSpace of \var{arg1}. 498 499 The \Data class supports taking slices from a \Data object as well as assigning new values to a slice of an existing 500 \Data object. \index{slicing} 501 The following expressions for taking and setting slices are valid: 502 \begin{tableiii}{l|ll}{textrm}{rank of \var{arg}}{slicing expression}{\Shape of returned and assigned object} 503 \lineiii{0}{ no slicing } {-} 504 \lineiii{1}{\var{arg[l0:u0]}} {(\var{u0}-\var{l0},)} 505 \lineiii{2}{\var{arg[l0:u0,l1:u1]}} {(\var{u0}-\var{l0},\var{u1}-\var{l1})} 506 \lineiii{3}{\var{arg[l0:u0,l1:u1,l2:u2]} } {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2})} 507 \lineiii{4}{\var{arg[l0:u0,l1:u1,l2:u2,l3:u3]}} {(\var{u0}-\var{l0},\var{u1}-\var{l1},\var{u2}-\var{l2},\var{u3}-\var{l3})} 508 \end{tableiii} 509 where 510 $0 \le \var{l0} \le \var{u0} \le \var{s}$, 511 $0 \le \var{l1} \le \var{u1} \le \var{s}$, 512 $0 \le \var{l2} \le \var{u2} \le \var{s}$, 513 $0 \le \var{l3} \le \var{u3} \le \var{s}$ and \var{s} the \Shape if \var{arg}. 514 Any of the lower indexes \var{l0}, \var{l1}, \var{l2} and \var{l3} may not be present in which case 515 $0$ is assumed. 516 Any of the upper indexes \var{u0}, \var{u1}, \var{u2} and \var{u3} may not be present in which case 517 \var{s} is assumed. The lower and upper index may be identical, in which case the column and the lower or upper 518 index may be dropped. In the returned or in the object assigned to a slice the corresponding component is dropped, 519 i.e. the rank is reduced by one in comparison to \var{arg}. 520 The following examples show slicing in action: 521 \begin{python} 522 t=Data(1.,(4,4,6,6),Function(mydomain)) 523 t[1,1,1,0]=9. 524 s=t[:2,:,2:6,5] # s has rank 3 525 s[:,:,1]=1. 526 t[:2,:2,5,5]=s[2:4,1,:2] 527 \end{python} 528 529 \subsection{Generation of \Data class objects} 530 \begin{classdesc}{Data}{value=0,shape=(,),what=FunctionSpace(),expand=\False} 531 creates a \Data object with \Shape \var{shape} in the \FunctionSpace \var{what}. 532 The values at all \DataSamplePoints are set to the double value \var{value}. If \var{expanded} is \True 533 the \Data object is represented in expanded from. 534 \end{classdesc} 535 536 \begin{classdesc}{Data}{value,what=FunctionSpace(),expand=\False} 537 creates a \Data object in the \FunctionSpace \var{what}. 538 The value for each \DataSamplePoints is set to \numarray, \Data object \var{value} or a dictionary of 539 \numarray or floating point numbers. In the latter case the keys must be integers and are used 540 as tags. 541 The \Shape of the returned object is equal to the \Shape of \var{value}. If \var{expanded} is \True 542 the \Data object is represented in expanded form. 543 \end{classdesc} 544 545 \begin{classdesc}{Data}{} 546 creates an \EmptyData object. The \EmptyData object is used to indicate that an argument is not present 547 where a \Data object is required. 548 \end{classdesc} 549 550 \begin{funcdesc}{Scalar}{value=0.,what=escript::FunctionSpace(),expand=\False} 551 returns a \Data object of rank 0 (a constant) in the \FunctionSpace \var{what}. 552 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True 553 the \Data object is represented in expanded from. 554 \end{funcdesc} 555 556 \begin{funcdesc}{Vector}{value=0.,what=escript::FunctionSpace(),expand=\False} 557 returns a \Data object of \Shape \var{(d,)} in the \FunctionSpace \var{what} 558 where \var{d} is the spatial dimension of the \Domain of \var{what}. 559 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True 560 the \Data object is represented in expanded from. 561 \end{funcdesc} 562 563 \begin{funcdesc}{Tensor}{value=0.,what=escript::FunctionSpace(),expand=\False} 564 returns a \Data object of \Shape \var{(d,d)} in the \FunctionSpace \var{what} 565 where \var{d} is the spatial dimension of the \Domain of \var{what}. 566 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True 567 the \Data object is represented in expanded from. 568 \end{funcdesc} 569 570 \begin{funcdesc}{Tensor3}{value=0.,what=escript::FunctionSpace(),expand=\False} 571 returns a \Data object of \Shape \var{(d,d,d)} in the \FunctionSpace \var{what} 572 where \var{d} is the spatial dimension of the \Domain of \var{what}. 573 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True 574 the \Data object is re\var{arg}presented in expanded from. 575 \end{funcdesc} 576 577 \begin{funcdesc}{Tensor4}{value=0.,what=escript::FunctionSpace(),expand=\False} 578 returns a \Data object of \Shape \var{(d,d,d,d)} in the \FunctionSpace \var{what} 579 where \var{d} is the spatial dimension of the \Domain of \var{what}. 580 Values are initialed with \var{value}, a double precision quantity. If \var{expanded} is \True 581 the \Data object is represented in expanded from. 582 \end{funcdesc} 583 584 \begin{funcdesc}{load}{filename,domain} 585 recovers a \Data object on \Domain \var{domain} from the file \var{filename}, which was created by \var{dump}. 586 \end{funcdesc} 587 588 \subsection{\Data class methods} 589 These are the most frequently-used methods of the 590 \Data class. A complete list of methods can be found on \ReferenceGuide. 591 \begin{methoddesc}[Data]{getFunctionSpace}{} 592 returns the \FunctionSpace of the object. 593 \end{methoddesc} 594 595 \begin{methoddesc}[Data]{getDomain}{} 596 returns the \Domain of the object. 597 \end{methoddesc} 598 599 \begin{methoddesc}[Data]{getShape}{} 600 returns the \Shape of the object as a \class{tuple} of 601 integers. 602 \end{methoddesc} 603 604 \begin{methoddesc}[Data]{getRank}{} 605 returns the rank of the data on each data point. \index{rank} 606 \end{methoddesc} 607 608 \begin{methoddesc}[Data]{isEmpty}{} 609 returns \True id the \Data object is the \EmptyData object. 610 Otherwise \False is returned. 611 \end{methoddesc} 612 613 \begin{methoddesc}[Data]{setTaggedValue}{tag_name,value} 614 assigns the \var{value} to all \DataSamplePoints which have the tag 615 assigned to \var{tag_name}. \var{value} must be an object of class 616 \class{numarray.NumArray} or must be convertible into a 617 \class{numarray.NumArray} object. \var{value} (or the corresponding 618 \class{numarray.NumArray} object) must be of rank $0$ or must have the 619 same rank like the object. 620 If a value has already be defined for tag \var{tag_name} within the object 621 it is overwritten by the new \var{value}. If the object is expanded, 622 the value assigned to \DataSamplePoints with tag \var{tag_name} is replaced by 623 \var{value}. If no tag is assigned tag name \var{tag_name}, no value is set. 624 \end{methoddesc} 625 626 \begin{methoddesc}[Data]{dump}{filename} 627 dumps the \Data object to the file \var{filename}. The file stores the 628 function space but not the \Domain. It is in the responsibility of the user to 629 save the \Domain. 630 \end{methoddesc} 631 632 \begin{methoddesc}[Data]{__str__}{} 633 returns a string representation of the object. 634 \end{methoddesc} 635 636 \subsection{Functions of \Data class objects} 637 This section lists the most important functions for \Data class objects \var{a}. 638 A complete list and a more detailed description of the functionality can be fond on \ReferenceGuide. 639 \begin{funcdesc}{saveVTK}{filename,**kwdata} 640 writes \Data defined by keywords in the file with \var{filename} using the 641 vtk file format \VTK file format. The key word is used as an identifier. The statement 642 \begin{python} 643 saveVTK("out.xml",temperature=T,velocity=v) 644 \end{python} 645 will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the 646 file \file{out.xml}. Restrictions on the allowed combinations of \FunctionSpace apply. 647 \end{funcdesc} 648 \begin{funcdesc}{saveDX}{filename,**kwdata} 649 writes \Data defined by keywords in the file with \var{filename} using the 650 vtk file format \OpenDX file format. The key word is used as an identifier. The statement 651 \begin{python} 652 saveDX("out.dx",temperature=T,velocity=v) 653 \end{python} 654 will write the scalar \var{T} as \var{temperature} and the vector \var{v} as \var{velocity} into the 655 file \file{out.dx}. Restrictions on the allowed combinations of \FunctionSpace apply. 656 \end{funcdesc} 657 \begin{funcdesc}{kronecker}{d} 658 returns a \RankTwo \Data object in \FunctionSpace \var{d} such that 659 \begin{equation} 660 \code{kronecker(d)}\left[ i,j\right] = \left\{ 661 \begin{array}{cc} 662 1 & \mbox{ if } i=j \\ 663 0 & \mbox{ otherwise } 664 \end{array} 665 \right. 666 \end{equation} 667 If \var{d} is an integer a $(d,d)$ \numarray array is returned. 668 \end{funcdesc} 669 \begin{funcdesc}{identityTensor}{d} 670 returns a \RankTwo \Data object in \FunctionSpace \var{d} such that 671 \begin{equation} 672 \code{identityTensor(d)}\left[ i,j\right] = \left\{ 673 \begin{array}{cc} 674 1 & \mbox{ if } i=j \\ 675 0 & \mbox{ otherwise } 676 \end{array} 677 \right. 678 \end{equation} 679 If \var{d} is an integer a $(d,d)$ \numarray array is returned. 680 \end{funcdesc} 681 \begin{funcdesc}{identityTensor4}{d} 682 returns a \RankFour \Data object in \FunctionSpace \var{d} such that 683 \begin{equation} 684 \code{identityTensor(d)}\left[ i,j,k,l\right] = \left\{ 685 \begin{array}{cc} 686 1 & \mbox{ if } i=k \mbox{ and } j=l\\ 687 0 & \mbox{ otherwise } 688 \end{array} 689 \right. 690 \end{equation} 691 If \var{d} is an integer a $(d,d,d,d)$ \numarray array is returned. 692 \end{funcdesc} 693 \begin{funcdesc}{unitVector}{i,d} 694 returns a \RankOne \Data object in \FunctionSpace \var{d} such that 695 \begin{equation} 696 \code{identityTensor(d)}\left[ j \right] = \left\{ 697 \begin{array}{cc} 698 1 & \mbox{ if } j=i\\ 699 0 & \mbox{ otherwise } 700 \end{array} 701 \right. 702 \end{equation} 703 If \var{d} is an integer a $(d,)$ \numarray array is returned. 704 705 \end{funcdesc} 706 707 \begin{funcdesc}{Lsup}{a} 708 returns the $L^{sup}$ norm of \var{arg}. This is the maximum of the absolute values 709 over all components and all \DataSamplePoints of \var{a}. 710 \end{funcdesc} 711 712 \begin{funcdesc}{sup}{a} 713 returns the maximum value over all components and all \DataSamplePoints of \var{a}. 714 \end{funcdesc} 715 716 \begin{funcdesc}{inf}{a} 717 returns the minimum value over all components and all \DataSamplePoints of \var{a} 718 \end{funcdesc} 719 720 \begin{funcdesc}{sin}{a} 721 applies sine function to \var{a}. 722 \end{funcdesc} 723 724 \begin{funcdesc}{cos}{a} 725 applies cosine function to \var{a}. 726 \end{funcdesc} 727 728 \begin{funcdesc}{tan}{a} 729 applies tangent function to \var{a}. 730 \end{funcdesc} 731 732 \begin{funcdesc}{asin}{a} 733 applies arc (inverse) sine function to \var{a}. 734 \end{funcdesc} 735 736 \begin{funcdesc}{acos}{a} 737 applies arc (inverse) cosine function to \var{a}. 738 \end{funcdesc} 739 740 \begin{funcdesc}{atan}{a} 741 applies arc (inverse) tangent function to \var{a}. 742 \end{funcdesc} 743 744 \begin{funcdesc}{sinh}{a} 745 applies hyperbolic sine function to \var{a}. 746 \end{funcdesc} 747 748 \begin{funcdesc}{cosh}{a} 749 applies hyperbolic cosine function to \var{a}. 750 \end{funcdesc} 751 752 \begin{funcdesc}{tanh}{a} 753 applies hyperbolic tangent function to \var{a}. 754 \end{funcdesc} 755 756 \begin{funcdesc}{asinh}{a} 757 applies arc (inverse) hyperbolic sine function to \var{a}. 758 \end{funcdesc} 759 760 \begin{funcdesc}{acosh}{a} 761 applies arc (inverse) hyperbolic cosine function to \var{a}. 762 \end{funcdesc} 763 764 \begin{funcdesc}{atanh}{a} 765 applies arc (inverse) hyperbolic tangent function to \var{a}. 766 \end{funcdesc} 767 768 \begin{funcdesc}{exp}{a} 769 applies exponential function to \var{a}. 770 \end{funcdesc} 771 772 \begin{funcdesc}{sqrt}{a} 773 applies square root function to \var{a}. 774 \end{funcdesc} 775 776 \begin{funcdesc}{log}{a} 777 applies the natural logarithm to \var{a}. 778 \end{funcdesc} 779 780 \begin{funcdesc}{log10}{a} 781 applies the base-$10$ logarithm to \var{a}. 782 \end{funcdesc} 783 784 \begin{funcdesc}{sign}{a} 785 applies the sign function to \var{a}, that is $1$ where \var{a} is positive, 786 $-1$ where \var{a} is negative and $0$ otherwise. 787 \end{funcdesc} 788 789 \begin{funcdesc}{wherePositive}{a} 790 returns a function which is $1$ where \var{a} is positive and $0$ otherwise. 791 \end{funcdesc} 792 793 \begin{funcdesc}{whereNegative}{a} 794 returns a function which is $1$ where \var{a} is negative and $0$ otherwise. 795 \end{funcdesc} 796 797 \begin{funcdesc}{whereNonNegative}{a} 798 returns a function which is $1$ where \var{a} is non--negative and $0$ otherwise. 799 \end{funcdesc} 800 801 \begin{funcdesc}{whereNonPositive}{a} 802 returns a function which is $1$ where \var{a} is non--positive and $0$ otherwise. 803 \end{funcdesc} 804 805 \begin{funcdesc}{whereZero}{a\optional{, tol=0.}} 806 returns a function which is $1$ where \var{a} equals zero with tolerance \var{tol} and $0$ otherwise. 807 \end{funcdesc} 808 809 \begin{funcdesc}{whereNonZero}{a\optional{, tol=0.}} 810 returns a function which is $1$ where \var{a} different from zero with tolerance \var{tol} and $0$ otherwise. 811 \end{funcdesc} 812 813 \begin{funcdesc}{minval}{a} 814 returns at each \DataSamplePoints the minimum value over all components. 815 \end{funcdesc} 816 817 \begin{funcdesc}{maxval}{a} 818 returns at each \DataSamplePoints the maximum value over all components. 819 \end{funcdesc} 820 821 \begin{funcdesc}{length}{a} 822 returns at Euclidean norm at each \DataSamplePoints. For a \RankFour function \var{a} this is 823 \begin{equation} 824 \code{length(a)}=\sqrt{\sum\hackscore{ijkl} \var{a} \left[i,j,k,l\right]^2} 825 \end{equation} 826 \end{funcdesc} 827 \begin{funcdesc}{trace}{a\optional{,axis_offset=0}} 828 returns the trace of \var{a}. This is the sum over components \var{axis_offset} and \var{axis_offset+1} with the same index. For instance in the 829 case of a \RankTwo function and this is 830 \begin{equation} 831 \code{trace(a)}=\sum\hackscore{i} \var{a} \left[i,i\right] 832 \end{equation} 833 and for a \RankFour function and \code{axis_offset=1} this is 834 \begin{equation} 835 \code{trace(a,1)}\left[i,j\right]=\sum\hackscore{k} \var{a} \left[i,k,k,j\right] 836 \end{equation} 837 \end{funcdesc} 838 839 \begin{funcdesc}{transpose}{a\optional{, axis_offset=None}} 840 returns the transpose of \var{a}. This swaps the first \var{axis_offset} components of \var{a} with the rest. If \var{axis_offset} is not 841 present \code{int(r/2)} is used where \var{r} is the rank of \var{a}. 842 the sum over components \var{axis_offset} and \var{axis_offset+1} with the same index. For instance in the 843 case of a \RankTwo function and this is 844 \begin{equation} 845 \code{transpose(a)}\left[i,j\right]=\var{a} \left[j,i\right] 846 \end{equation} 847 and for a \RankFour function and \code{axis_offset=1} this is 848 \begin{equation} 849 \code{transpose(a,1)}\left[i,j,k,l\right]=\var{a} \left[j,k,l,i\right] 850 \end{equation} 851 \end{funcdesc} 852 853 \begin{funcdesc}{swap_axes}{a\optional{, axis0=0 \optional{, axis1=1 }}} 854 returns \var{a} but with swapped components \var{axis0} and \var{axis1}. The argument \var{a} must be 855 at least of \RankTwo. For instance in the 856 for a \RankFour argument, \code{axis0=1} and \code{axis1=2} this is 857 \begin{equation} 858 \code{swap_axes(a,1,2)}\left[i,j,k,l\right]=\var{a} \left[i,k,j,l\right] 859 \end{equation} 860 \end{funcdesc} 861 862 \begin{funcdesc}{symmetric}{a} 863 returns the symmetric part of \var{a}. This is \code{(a+transpose(a))/2}. 864 \end{funcdesc} 865 \begin{funcdesc}{nonsymmetric}{a} 866 returns the non--symmetric part of \var{a}. This is \code{(a-transpose(a))/2}. 867 \end{funcdesc} 868 \begin{funcdesc}{inverse}{a} 869 return the inverse of \var{a}. This is 870 \begin{equation} 871 \code{matrix_mult(inverse(a),a)=kronecker(d)} 872 \end{equation} 873 if \var{a} has shape \code{(d,d)}. The current implementation is restricted to arguments of shape 874 \code{(2,2)} and \code{(3,3)}. 875 \end{funcdesc} 876 \begin{funcdesc}{eigenvalues}{a} 877 return the eigenvalues of \var{a}. This is 878 \begin{equation} 879 \code{matrix_mult(a,V)=e[i]*V} 880 \end{equation} 881 where \code{e=eigenvalues(a)} and \var{V} is suitable non--zero vector \var{V}. 882 The eigenvalues are ordered in increasing size. 883 The argument \var{a} has to be the symmetric, ie. \code{a=symmetric(a)}. 884 The current implementation is restricted to arguments of shape 885 \code{(2,2)} and \code{(3,3)}. 886 \end{funcdesc} 887 \begin{funcdesc}{eigenvalues_and_eigenvectors}{a} 888 return the eigenvalues and eigenvectors of \var{a}. This is 889 \begin{equation} 890 \code{matrix_mult(a,V[:,i])=e[i]*V[:,i]} 891 \end{equation} 892 where \code{e,V=eigenvalues_and_eigenvectors(a)}. The eigenvectors \var{V} are orthogonal and normalized, ie. 893 \begin{equation} 894 \code{matrix_mult(transpose(V),V)=kronecker(d)} 895 \end{equation} 896 if \var{a} has shape \code{(d,d)}. The eigenvalues are ordered in increasing size. 897 The argument \var{a} has to be the symmetric, ie. \code{a=symmetric(a)}. 898 The current implementation is restricted to arguments of shape 899 \code{(2,2)} and \code{(3,3)}. 900 \end{funcdesc} 901 \begin{funcdesc}{maximum}{*a} 902 returns the maximum value over all arguments at all \DataSamplePoints and for each component. 903 For instance 904 \begin{equation} 905 \code{maximum(a0,a1)}\left[i,j\right]=max(\var{a0} \left[i,j\right],\var{a1} \left[i,j\right]) 906 \end{equation} 907 at all \DataSamplePoints. 908 \end{funcdesc} 909 \begin{funcdesc}{minimum}{*a} 910 returns the minimum value over all arguments at all \DataSamplePoints and for each component. 911 For instance 912 \begin{equation} 913 \code{minimum(a0,a1)}\left[i,j\right]=min(\var{a0} \left[i,j\right],\var{a1} \left[i,j\right]) 914 \end{equation} 915 at all \DataSamplePoints. 916 \end{funcdesc} 917 918 \begin{funcdesc}{clip}{a\optional{, minval=0.}\optional{, maxval=1.}} 919 cuts back \var{a} into the range between \var{minval} and \var{maxval}. A value in the returned object equals 920 \var{minval} if the corresponding value of \var{a} is less than \var{minval}, equals \var{maxval} if the 921 corresponding value of \var{a} is greater than \var{maxval} 922 or corresponding value of \var{a} otherwise. 923 \end{funcdesc} 924 \begin{funcdesc}{inner}{a0,a1} 925 returns the inner product of \var{a0} and \var{a1}. For instance in the 926 case of \RankTwo arguments and this is 927 \begin{equation} 928 \code{inner(a)}=\sum\hackscore{ij}\var{a0} \left[j,i\right] \cdot \var{a1} \left[j,i\right] 929 \end{equation} 930 and for a \RankFour arguments this is 931 \begin{equation} 932 \code{inner(a)}=\sum\hackscore{ijkl}\var{a0} \left[i,j,k,l\right] \cdot \var{a1} \left[j,i,k,l\right] 933 \end{equation} 934 \end{funcdesc} 935 936 \begin{funcdesc}{matrix_mult}{a0,a1} 937 returns the matrix product of \var{a0} and \var{a1}. If \var{a1} is \RankOne this is 938 \begin{equation} 939 \code{matrix_mult(a)}\left[i\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k\right] 940 \end{equation} 941 and if \var{a1} is \RankTwo this is 942 \begin{equation} 943 \code{matrix_mult(a)}\left[i,j\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[k,j\right] 944 \end{equation} 945 \end{funcdesc} 946 947 \begin{funcdesc}{transposed_matrix_mult}{a0,a1} 948 returns the matrix product of the transposed of \var{a0} and \var{a1}. The function is equivalent to 949 \code{matrix_mult(transpose(a0),a1)}. 950 If \var{a1} is \RankOne this is 951 \begin{equation} 952 \code{transposed_matrix_mult(a)}\left[i\right]=\sum\hackscore{k}\var{a0} \cdot \left[k,i\right]\var{a1} \left[k\right] 953 \end{equation} 954 and if \var{a1} is \RankTwo this is 955 \begin{equation} 956 \code{transposed_matrix_mult(a)}\left[i,j\right]=\sum\hackscore{k}\var{a0} \cdot \left[k,i\right]\var{a1} \left[k,j\right] 957 \end{equation} 958 \end{funcdesc} 959 960 \begin{funcdesc}{matrix_transposed_mult}{a0,a1} 961 returns the matrix product of \var{a0} and the transposed of \var{a1}. 962 The function is equivalent to 963 \code{matrix_mult(a0,transpose(a1))}. 964 If \var{a1} is \RankTwo this is 965 \begin{equation} 966 \code{matrix_transposed_mult(a)}\left[i,j\right]=\sum\hackscore{k}\var{a0} \cdot \left[i,k\right]\var{a1} \left[j,k\right] 967 \end{equation} 968 \end{funcdesc} 969 970 \begin{funcdesc}{outer}{a0,a1} 971 returns the outer product of \var{a0} and \var{a1}. For instance if \var{a0} and \var{a1} both are \RankOne then 972 \begin{equation} 973 \code{outer(a)}\left[i,j\right]=\var{a0} \left[i\right] \cdot \var{a1}\left[j\right] 974 \end{equation} 975 and if \var{a0} is \RankOne and \var{a1} is \RankThree 976 \begin{equation} 977 \code{outer(a)}\left[i,j,k\right]=\var{a0} \left[i\right] \cdot \var{a1}\left[j,k\right] 978 \end{equation} 979 \end{funcdesc} 980 981 \begin{funcdesc}{tensor_mult}{a0,a1} 982 returns the tensor product of \var{a0} and \var{a1}. If \var{a1} is \RankTwo this is 983 \begin{equation} 984 \code{tensor_mult(a)}\left[i,j\right]=\sum\hackscore{kl}\var{a0}\left[i,j,k,l\right] \cdot \var{a1} \left[k,l\right] 985 \end{equation} 986 and if \var{a1} is \RankFour this is 987 \begin{equation} 988 \code{tensor_mult(a)}\left[i,j,k,l\right]=\sum\hackscore{mn}\var{a0} \left[i,j,m,n\right] \cdot \var{a1} \left[m,n,k,l\right] 989 \end{equation} 990 \end{funcdesc} 991 992 \begin{funcdesc}{transposed_tensor_mult}{a0,a1} 993 returns the tensor product of the transposed of \var{a0} and \var{a1}. The function is equivalent to 994 \code{tensor_mult(transpose(a0),a1)}. 995 If \var{a1} is \RankTwo this is 996 \begin{equation} 997 \code{transposed_tensor_mult(a)}\left[i,j\right]=\sum\hackscore{kl}\var{a0}\left[k,l,i,j\right] \cdot \var{a1} \left[k,l\right] 998 \end{equation} 999 and if \var{a1} is \RankFour this is 1000 \begin{equation} 1001 \code{transposed_tensor_mult(a)}\left[i,j,k,l\right]=\sum\hackscore{mn}\var{a0} \left[m,n,i,j\right] \cdot \var{a1} \left[m,n,k,l\right] 1002 \end{equation} 1003 \end{funcdesc} 1004 1005 \begin{funcdesc}{tensor_transposed_mult}{a0,a1} 1006 returns the tensor product of \var{a0} and the transposed of \var{a1}. 1007 The function is equivalent to 1008 \code{tensor_mult(a0,transpose(a1))}. 1009 If \var{a1} is \RankTwo this is 1010 \begin{equation} 1011 \code{tensor_transposed_mult(a)}\left[i,j\right]=\sum\hackscore{kl}\var{a0}\left[i,j,k,l\right] \cdot \var{a1} \left[l,k\right] 1012 \end{equation} 1013 and if \var{a1} is \RankFour this is 1014 \begin{equation} 1015 \code{tensor_transposed_mult(a)}\left[i,j,k,l\right]=\sum\hackscore{mn}\var{a0} \left[i,j,m,n\right] \cdot \var{a1} \left[k,l,m,n\right] 1016 \end{equation} 1017 \end{funcdesc} 1018 1019 \begin{funcdesc}{grad}{a\optional{, where=None}} 1020 returns the gradient of \var{a}. If \var{where} is present the gradient will be calculated in \FunctionSpace \var{where} otherwise a 1021 default \FunctionSpace is used. In case that \var{a} has \RankTwo one has 1022 \begin{equation} 1023 \code{grad(a)}\left[i,j,k\right]=\frac{\partial \var{a} \left[i,j\right]}{\partial x\hackscore{k}} 1024 \end{equation} 1025 \end{funcdesc} 1026 \begin{funcdesc}{integrate}{a\optional{ ,where=None}} 1027 returns the integral of \var{a} where the domain of integration is defined by the \FunctionSpace of \var{a}. If \var{where} is 1028 present the argument is interpolated into \FunctionSpace \var{where} before integration. For instance in the case of 1029 a \RankTwo argument in \ContinuousFunction it is 1030 \begin{equation} 1031 \code{integrate(a)}\left[i,j\right]=\int\hackscore{\Omega}\var{a} \left[i,j\right] \; d\Omega 1032 \end{equation} 1033 where $\Omega$ is the spatial domain and $d\Omega$ volume integration. To integrate over the boundary of the domain one uses 1034 \begin{equation} 1035 \code{integrate(a,where=FunctionOnBoundary(a.getDomain))}\left[i,j\right]=\int\hackscore{\partial \Omega} a\left[i,j\right] \; ds 1036 \end{equation} 1037 where $\partial \Omega$ is the surface of the spatial domain and $ds$ area or line integration. 1038 \end{funcdesc} 1039 \begin{funcdesc}{interpolate}{a,where} 1040 interpolates argument \var{a} into the \FunctionSpace \var{where}. 1041 \end{funcdesc} 1042 \begin{funcdesc}{div}{a\optional{ ,where=None}} 1043 returns the divergence of \var{a}. This 1044 \begin{equation} 1045 \code{div(a)}=trace(grad(a),where) 1046 \end{equation} 1047 \end{funcdesc} 1048 \begin{funcdesc}{jump}{a\optional{ ,domain=None}} 1049 returns the jump of \var{a} over the discontinuity in its domain or if \Domain \var{domain} is present 1050 in \var{domain}. 1051 \begin{equation} 1052 \begin{array}{rcl} 1053 \code{jump(a)}& = &\code{interpolate(a,FunctionOnContactOne(domain))} \\ 1054 & & \hfill - \code{interpolate(a,FunctionOnContactZero(domain))} 1055 \end{array} 1056 \end{equation} 1057 \end{funcdesc} 1058 \begin{funcdesc}{L2}{a} 1059 returns the $L^2$-norm of \var{a} in its function space. This is 1060 \begin{equation} 1061 \code{L2(a)=integrate(length(a)}^2\code{)} \; . 1062 \end{equation} 1063 \end{funcdesc} 1064 1065 \subsection{\Operator Class} 1066 The \Operator class provides an abstract access to operators build 1067 within the \LinearPDE class. \Operator objects are created 1068 when a PDE is handed over to a PDE solver library and handled 1069 by the \LinearPDE class defining the PDE. The user can gain access 1070 to the \Operator of a \LinearPDE object through the \var{getOperator} 1071 method. 1072 1073 \begin{classdesc}{Operator}{} 1074 creates an empty \Operator object. 1075 \end{classdesc} 1076 1077 \begin{methoddesc}[Operator]{isEmpty}{fileName} 1078 returns \True is the object is empty. Otherwise \True is returned. 1079 \end{methoddesc} 1080 1081 \begin{methoddesc}[Operator]{setValue}{value} 1082 resets all entries in the object representation to \var{value} 1083 \end{methoddesc} 1084 1085 \begin{methoddesc}[Operator]{solves}{rhs} 1086 solves the operator equation with right hand side \var{rhs} 1087 \end{methoddesc} 1088 1089 \begin{methoddesc}[Operator]{of}{u} 1090 applies the operator to the \Data object \var{u} 1091 \end{methoddesc} 1092 1093 \begin{methoddesc}[Operator]{saveMM}{fileName} 1094 saves the object to a matrix market format file of name 1095 \var{fileName}, see 1096 \ulink{maths.nist.gov/MatrixMarket}{\url{http://maths.nist.gov/MatrixMarket}}. 1097 \index{Matrix Market} 1098 \end{methoddesc} 1099

## Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

 ViewVC Help Powered by ViewVC 1.1.26