Home

DOLFIN User Manual

1. DOLFIN User Manual Hoffman Jansson Logg Wells If allowed by the underlying representation a Function u may also be eval uated directly at any given Point Point 70 5 0 5 0 5 cout lt lt Value at p lt lt p lt lt f f lt lt f p lt lt endl As in the case of evaluation at a Vertex the component index may be given as an additional argument for a vector valued Function 5 1 3 Assignment One Function may be assigned to another Function Function f Function g f 5 1 4 Components and sub functions If a Function is vector valued a new Function may be created to represent any given component of the original Function as illustrated by the following example Function f Function with three components Function f 0 first component Function f 1 second component Function f 2 third component If a Function represents a mixed function one defined in terms of a mixed FiniteElement see below then indexing has the effect of picking out sub functions With w a Function representing the discrete solution w U P 35 DOLFIN User Manual Hoffman Jansson Logg Wells of a Stokes or Navier Stokes system with U the vector valued velocity and P the scalar pressure the following example illustrates how to pick sub functions and components of w Function w mixed Function U P U w 0 first sub function velocity P w 1 second sub function
2. In this example the Function f represents a function in the trial space for the BilinearForm a 5 3 User defined functions In the simplest case a user defined Function is just an expression in terms of the coordinates and is typically used for defining source terms and initial conditions For example a source term could be given by f f x y z 2ysin z 7 5 2 There are two ways to create a user defined Function either by creating a sub class of Function or by creating a Function from a given function pointer 5 3 1 Creating a sub class A user defined Function may be defined by creating a sub class of Function and overloading the eval function The following example illustrates how to create a Function representing the function in 5 2 39 DOLFIN User Manual Hoffman Jansson Logg Wells class Source public Function real eval const Point amp p unsigned int i return x y sin z DOLFIN_PI Source f To create a vector valued Function the vector dimension must be supplied to the constructor of Function class Source public Function public Source Function 3 real eval const Point amp p unsigned int i if i 0 return 0 0 else if i 1 return x y sin z DOLFIN_PI else return x y Source f DOLFIN User Manual Hoffman Jansson Logg Wells 5 3 2 Specifying a function pointer A user defined Function may alternatively be defi
3. file lt lt U return 0 2 2 3 Compiling the program The easiest way to compile the program is to create a Makefile that tells the standard Unix command make how to build the program The following 21 DOLFIN User Manual Hoffman Jansson Logg Wells example shows how to write a Makefile for the above example CFLAGS dolfin config cflags LIBS dolfin config libs CXX dolfin config compiler LINK dolfin config linker DEST dolfin poisson OBJECTS main o all DEST install clean rm f o core core OBJECTS DEST DEST COBJECTS LINK o OBJECTS CFLAGS LIBS Cpp o CXX CFLAGS c lt With the Makefile in place we just need to type make to compile the pro gram generating the executable as the file dolfin poisson 2 2 4 Running the program To run the program simply type the name of the executable dolfin poisson Computing mesh connectivity Found 289 vertices Found 512 cells Lead Krylov solver gmres ilu converged in 21 iterations Saved function to file poisson pvd in VTK format DOLFIN User Manual Hoffman Jansson Logg Wells 2 2 5 Visualizing the solution DOLFIN relies on external programs for visualization In this example we chose to save the solution in VTK format which can be imported into for example ParaView or MayaVi Figure 2 1 The solution of Poisson s equation 2 1 visualized i
4. 55 8 3 Incremental Newton solver aa a 55 9 Input output 57 LI Fies and ob c oe nieki pateni ra ee eed eS oi 57 A soo eee a e EG ewe ee eee ELR oe 59 9 2 1 DOLFIN XML 59 Ro VIR ca ee ee OR ee oe we on we EH Ak SE 60 923 VOC as bee aa as Cee ow oe 61 O24 GNU Octave 224225448 Ee R444 REELED EX 61 Na MATLAB e amp Buh 4 HSER EES EES RM RS s 62 Oey TOI 2 4242 toa dh EG ee Eee OE Ee OES 62 ie GUD da a See ee rs SESS 63 9 3 Converting between file formats 00 63 9 4 A note on new file formats 204 63 10 The log system 65 10 1 Generating log Messages pe 65 102 Warnings 300 COTE lt a AA a A StS 66 10 3 Debug messages and assertions 67 10 4 Task notification 2 iscr e ew ee rss AA 68 DOLFIN User Manual Hoffman Jansson Logg Wells 10 5 Progress Dars s ce ee oe ae adao eR KES oO 69 10 6 Controlling the destination of output 70 11 The parameter system 73 11 1 Retrieving the value of a parameter 73 11 2 Modifying the value of a parameter 74 11 3 Adding a new parame ter lt kc eh a PA a OREO 75 11 4 Saving parameters to file 76 11 5 Loading parameters from fle 76 12 Solvers TT 12 1 Poisson s equation lt s ete sorone oea A G 78 IZLI UGE 20 paseoa pag e Ree ars wee OS HG 78 LLE Performante e soo cae eo ad ee A ee eo dw 79 Teoh
5. Here s an example of how it works Start from the latest release of DOLFIN which we here assume is release 0 1 0 You then have a directory structure under dolfin 0 1 0 where you have made modifications to some files which you think could be useful to other users 1 Clean up your modified directory structure to remove temporary and binary files which will be rebuilt anyway 105 DOLFIN User Manual Hoffman Jansson Logg Wells make clean 2 From the parent directory rename the DOLFIN directory to something else mv dolfin 0 1 0 dolfin 0 1 0 mod 3 Unpack the version of DOLFIN that you started from tar zxfv dolfin 0 1 0 tar gz 4 You should now have two DOLFIN directory structures in your current directory 1s dolfin 0 1 0 dolfin 0 1 0 mod 5 Now use the diff tool to create the patch diff u new file recursive dolfin 0 1 0 dolfin 0 1 0 mod gt dolfin lt identifier gt lt date gt patch written as one line where lt identifier gt is a keyword that can be used to identify the patch as coming from you your username last name first name a nickname etc and lt date gt is today s date in the format yyyy mm dd 6 The patch now exists as dolfin lt identifier gt lt date gt patch and can be distributed to other people who already have dolfin 0 1 0 to easily create your modified version If the patch is large compressing it with for example gzip is advisable gzip dolfin l
6. Compute F u void F Vector amp b const Vector amp x Insert F u into the vector b Compute J void J Matrix amp A const Vector amp x Insert the Jacobian into the matrix A dolfin uint size Return the dimension of the Jacobian matrix dolfin uint nzsize Return the maximum number of zeroes per row of J private Pointers to objects with which F u is defined E 94 DOLFIN User Manual Hoffman Jansson Logg Wells 8 2 Newton solver 8 2 1 Linear solver 8 2 2 Application of Dirichlet boundary conditions The application of inhomogenuous Dirichlet boundary conditions in the con text of a Newton solver requires particular attention 8 2 3 Newton solver parameters 8 2 4 Application of Dirichlet boundary conditions 8 3 Incremental Newton solver 59 Chapter 9 Input output DOLFIN relies on external programs for pre and post processing which means that computational meshes must be imported from file pre processing and computed solutions must be exported to file and then imported into an other program for visualization post processing To simplify this process DOLFIN provides support for easy interaction with files and includes output formats for a number of visualization programs 9 1 Files and objects A file in DOLFIN is represented by the class File and reading writing data is done using the standard C operators gt gt read a
7. faces and cells 90 DOLFIN User Manual Hoffman Jansson Logg Wells Figure A 3 Physical coordinates of the reference tetrahedron 91 DOLFIN User Manual Hoffman Jansson Logg Wells Figure A 4 Ordering of mesh entities vertices edges faces for the reference tetrahedron 92 DOLFIN User Manual Hoffman Jansson Logg Wells A 3 2 Ordering among mesh entities With each mesh entity there can be associated zero or more nodes and the nodes are ordered locally and globally based on the topological dimension of the mesh entity with which they are associated Thus any nodes associated with vertices are ordered first and nodes associated with cells last If more than one node is associated with a single mesh entity the internal ordering of the nodes associated with the mesh entity becomes important in particular for edges and faces where the nodes of two adjacent cells sharing a common edge or face must line up A 3 3 Internal ordering on edges For edges containing more than one node the nodes are ordered in the di rection from the first vertex v of the edge to the second vertex uv of the edge as in Figure A 5 0 Ve Figure A 5 Internal ordering of nodes on edges DOLFIN User Manual Hoffman Jansson Logg Wells A 3 4 Alignment of edges Depending on the orientation of any given cell an edge on the cell may be aligned or not aligned with the corresponding edge on the reference cell if the
8. terminal Other options include directing messages to a curses interface or turning of messages completely To specify the output destination use the function dolfin_output available in the dolfin namespace void dolfin_output const char destination DOLFIN User Manual Hoffman Jansson Logg Wells where destination is one of plain text standard output curses curses interface or silent no messages printed When messages are directed to the DOLFIN curses interface a text mode graphical and interactive user interface is started in the current terminal window To see a list of options press h for help The curses interface is updated periodically but the function dolfin_update can be used to force a refresh of the display It is possible to switch the DOLFIN log system on or off using the function dolfin_log available in the dolfin namespace This function accepts as argument a bool specifying whether or not messages should be directed to the current output destination This function can be useful to suppress excessive logging for example when calling a function that generates log messages multiple times GMRES gmres while dolfin_log false gmres solve A x b dolfin_log true 71 Chapter 11 The parameter system gt Developer s note Since this chapter was written the DOLFIN parame ter system has been completely redesigned and now supports l
9. v f dx DOLFIN User Manual Hoffman Jansson Logg Wells which generates a file Heat h when compiled with FFC To initializations the corresponding forms we write real k time step Vector x0 vector containing dofs for u0 Function U0 x0 mesh solution at previous time step Heat BilinearForm a k Heat LinearForm L UO f k 51 Chapter 8 Nonlinear solver gt Developer s note This chapter is currently being written DOLFIN provides tools for solving nonlinear equations of the form F x 0 8 1 where F R R The nonlinear solvers are based on Newton s method and utilise functions from PETSc 11 To use the nonlinear solver a nonlinear function must be defined The non linear solver is then initialised with this function and a solution computed 8 1 Nonlinear functions To solve a nonlinear problem the user must defined a class which The class should be derived from the DOLFINclass NonlinearFunction The class should contain the necessary functions to form the function F u and the Jacobian matrix J OF Ou The precise form of the user defined class will depend on the PDE being solved and the numerical method The structu of a user defined class MyNonlinearFunction is shown below 53 DOLFIN User Manual Hoffman Jansson Logg Wells class MyNonlinearFunction public NonlinearFunction public Constructor MyNonlinearFunction NonlinearFunction
10. FEM formulation so the solver can handle convection dominated problems The time integration is done using cG 1 Crank Nicolson 12 2 1 Usage The API for the convection diffusion solver Create convection diffusion solver ConvectionDiffusionSolver Meshg mesh Function amp w Function amp f BoundaryCondition amp bc Solve convection diffusion void solve 80 DOLFIN User Manual Hoffman Jansson Logg Wells Solve convection diffusion static version static void solve Mesh amp mesh Functionk w Function amp f BoundaryCondition amp bc A simple example of using the solver int main dolfin_output curses Mesh mesh dolfin xml gz Convection w Source f MyBC bc ConvectionDiffusionSolver solve mesh w f bc return 0 12 2 2 Performance There are no particular performance issues with the solver GMRES is used for solving the linear system 12 2 3 Limitations Currently many coefficients such as diffusivity are not user definable they need to be exposed by the interface 81 DOLFIN User Manual Hoffman Jansson Logg Wells 12 3 Incompressible Navier Stokes Write introduction here equations etc 12 3 1 Usage Present API of solver and give an example 12 3 2 Performance Write something about the performance of the solver 12 3 3 Limitations Write something about the limitations of the solver 12 4 Elasticity Navier s equations of elastici
11. can be scalar or vector valued e A Function can be evaluated at each Vertex of a Mesh e A Function can be restricted to each local Cell of a Mesh e The underlying representation of a Function may vary 33 DOLFIN User Manual Hoffman Jansson Logg Wells Depending on the actual underlying representation of a Function it may also be possible to evaluate a Function at any given Point 5 1 1 Representation Currently supported representations of Functions include discrete Functions and user defined Functions These are discussed in detail below 5 1 2 Evaluation All Functions can be evaluated at the Vertices of a Mesh The following example illustrates how to evaluate a scalar Function at each Vertex of a given Mesh Function f Mesh mesh for VertexIterator vertex mesh vertex end vertex cout lt lt Value at vertex lt lt xvertex lt lt f lt lt f vertex lt lt endl If the Function is vector valued an additional argument is needed to spec ify the component The following example illustrates how to evaluate all components of a vector valued Function at all each Vertex of a given Mesh Function f Mesh mesh for VertexIterator vertex mesh vertex end vertex for unsigned int i 0 i lt u vectordim i cc cout lt lt Value of component lt lt i lt lt at vertex lt lt vertex lt lt lt lt f rvertex i lt lt endl
12. components of the eigenvalues are returned in the vector er and the complex components of the eigenvalues are returned in the vector ec The procedure for computing the eigenvalues of a matrix is computationally intensive and should only be used for relatively small matrices 3 4 Preconditioning The Preconditioner class specifies the interface for user defined Krylov method preconditioners To implement our own preconditioner we only need to supply a function that approximately solves the linear system given a right hand side 27 DOLFIN User Manual Hoffman Jansson Logg Wells To change the default preconditioner in the DOLFIN GMRES solver edit the constructor of the GMRES class For example to choose the ILU preconditioner for GMRES we write PC pc KSPGetPC ksp amp pc PCSetType pc PCILU As a complement to the preconditioners available in PETSc DOLFIN also uses Hypre 3 which is a library for solving large sparse linear systems of equations on massively parallel computers To use a preconditioner from Hypre together with a PETSc solver in DOLFIN we write PCSetType pc PCHYPRE PCHYPRESetType pc boomeramg In particular the above preconditioner boomeramg is an algebraic multigrid preconditioner which is very useful 28 Chapter 4 The mesh gt Developer s note This chapter is currently being written The concept of a mesh is central in the implementation of adaptive Galerkin finit
13. hand side f of 2 1 This is done by defining a new subclass of Function and overloading the eval function to return the value f x y xsin y 18 DOLFIN User Manual Hoffman Jansson Logg Wells class public Function real eval const Point amp p unsigned int i return p x sin p y f The boundary condition is specified similarly by overloading the eval function for a subclass of BoundaryCondition class public BoundaryCondition void eval BoundaryValue amp value const Point amp p unsigned int i if std abs p x 1 0 lt DOLFIN_EPS value 0 0 be We only need to specify the boundary condition explicitly on the Dirich let boundary On the remaining part of the boundary DOLFIN assumes homogeneous Neumann boundary conditions by default Note that there is currently no easy way to impose non homogeneous Neu mann boundary conditions or other combinations of boundary conditions This will most certainly be added to a future release of DOLFIN Next we need to create a mesh DOLFIN relies on external programs for mesh generation and imports meshes in DOLFIN XML format However for simple domains like the unit square or unit cube DOLFIN provides a built in mesh generator To generate a uniform mesh of the unit square with mesh size 1 16 with a total of 2 16 512 triangles we can just type UnitSquare mesh 16 16 DOLFIN User Manual Hoffman Jan
14. lt lt mesh The same thing can of course be accomplished by gunzip c mesh xml gz gt mesh xml on the command line There is currently no visualization tool that can read DOLFIN XML files so the main purpose of this format is to save and transfer data 9 2 2 VTK Data saved in VTK format 13 can be visualized using various packages The powerful and freely available ParaView 10 is recommended Alternatively VTK data can be visualized in MayaVi 5 which is recommended for quality vector PostScript output Time dependent data is handled automatically in the VTK format The below code illustrates how to export a function in VTK format Function u File out data pvd out lt lt u DOLFIN User Manual Hoffman Jansson Logg Wells The sample code produces the file data pvd which can be read by Par aView The file data pvd contains a list of files which contain the results computed by DOLFIN For the above example these files would be named dataXXX vtu where XXX is a counter which is incremented each time the function is saved If the function u was to be saved three times the files data000000 vtu data000001 vtu data000002 vtu would be produced Individual snapshots can be visualized by opening the desired file with the extension vtu using ParaView ParaView can produce on screen animations High quality animations in various formats can be produced using a combination of ParaView a
15. matches the first edge on the corresponding face on the reference tetrahedron and also the second edge matches the second edge on the reference tetrahedron then the alignment is 0 If only the first 94 DOLFIN User Manual Hoffman Jansson Logg Wells Figure A 6 Internal ordering of nodes on faces 95 DOLFIN User Manual Hoffman Jansson Logg Wells edge matches then the alignment is 1 We similarly define alignments 2 3 by matching the first and second edges with the second and third edges on the corresponding face on the reference tetrahedron and alignments 4 5 by matching the first and second edges with the third and first edges on the corresponding face on the reference tetrahedron Example 1 The alignment of the first face of a tetrahedron is 0 if the first edge of the face is edge number 5 and the second edge is edge number 0 Example 2 The alignment of the first face of a tetrahedron is 1 if the first edge of the face is edge number 5 and the second edge is not edge number 0 It must then be edge number 4 Example 3 The alignment of the first face of a tetrahedron is 4 if the first edge of the face is edge number 4 and the second edge is edge number 5 Example 4 The alignment of the first face of a tetrahedron is 5 if the first edge of the face is edge number 4 and the second edge is not edge number 5 It must then be edge number 0 96 Appendix B Installation The source code of DOLFIN is portable and
16. should compile on any Unix system although it is developed mainly under GNU Linux in particular Debian GNU Linux DOLFIN can be compiled under Windows through Cygwin 1 Questions bug reports and patches concerning the installation should be directed to the DOLFIN mailing list at the address dolfin dev fenics org DOLFIN must currently be compiled directly from source but effort is under way to provide precompiled Debian packages of DOLFIN and other FENICS components B 1 Installing from source B 1 1 Dependencies and requirements DOLFIN depends on a number of libraries that need to be installed on your system These libraries include Libxml2 and PETSc In addition to these 97 DOLFIN User Manual Hoffman Jansson Logg Wells libraries you need to install FIAT and FFC if you want to define your own variational forms Installing Libxml2 Libxml2 is a library used by DOLFIN to parse XML data files Libxml2 can be obtained from http xmlsoft org Packages are available for most Linux distributions For Debian users the package to install is libxm12 dev Installing PETSc PETSc is a library for the solution of linear and nonlinear systems function ing as the backend for the DOLFIN linear algebra classes DOLFIN depends on PETSc version 2 3 1 or 2 3 0 which can be obtained from http www unix mcs anl gov petsc petsc 2 Follow the installation instructions on the PETSc web page Normally you should only have
17. software Also for each author s protection and ours we want to make certain that everyone understands that there is no warranty for this free software If the software is modified by someone else and passed on we want its recipients to know that what they have is not the original so that any problems introduced by others will not reflect on the original authors reputations Finally any free program is threatened constantly by software patents We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses in effect making the program proprietary To prevent this we have made it clear that any patent must be licensed for everyone s free use or not licensed at all The precise terms and conditions for copying distribution and modification follow GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING DISTRIBUTION AND MODIFICATION O This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License The Program below refers to any such program or work and a work based on the Program means either the Program or any derivative work under copyright law that is to say a work containing the Program or a portion of it either verbatim or with modifications and or translated into another 110 DOLFIN User Manual Hoffman Jansson Logg Wells language H
18. to perform the following simple steps in the PETSc source directory export PETSC_DIR pwd config configure py with clanguage cxx with shared 1 make all Add download hypre yes to configure py if you want to install Hypre which provides a collection of preconditioners including algebraic multigrid AMG 98 DOLFIN User Manual Hoffman Jansson Logg Wells DOLFIN assumes that PETSC_DIR is usr local lib petsc but this can be controlled using the flag with petsc dir lt path gt when configuring DOLFIN see below Installing FFC DOLFIN uses the FEniCS Form Compiler FFC to process variational forms FFC can be obtained from http www fenics org Follow the installation instructions given in the FFC manual FFC follows the standard for Python packages which means that normally you should only have to perform the following simple step in the FFC source directory python setup py install Note that FFC depends on FIAT which in turn depends on the Python pack ages Numeric Debian package python numeric and LinearAlgebra Debian package python numeric ext Refer to the FFC manual for further details B 1 2 Downloading the source code The latest release of DOLFIN can be obtained as a tar gz archive in the download section at http www fenics org Download the latest release of DOLFIN for example dolfin 0 1 0 tar gz and unpack using the command DOLFIN User Manual Hoffman Jansso
19. vertices of the cell are mapped to the reference cell We define the alignment of an edge with respect to a cell to be 0 if the edge is aligned with the orientation of the reference cell and 1 otherwise Example 1 The alignment of the first edge e on a triangle is 0 if the first vertex of the edge is the second vertex v of the triangle Example 2 The alignment of the second edge et on a tetrahedron is 0 if the first vertex of the edge is the third vertex v of the tetrahedron If two cells share a common edge and the edge is aligned with one of the cells and not the other we must reverse the order in which the local nodes are mapped to global nodes on one of the two cells As a convention the order is kept if the alignment is 0 and reversed if the alignment is 1 A 3 5 Internal ordering on faces For faces containing more than one node the ordering of nodes is nested going from the first to the third vertex and in each step going from the first to the second vertex as in Figure A 6 A 3 6 Alignment of faces There are six different ways for a face to be aligned on a tetrahedron there are three ways to pick the first edge of the face and once the first edge is picked there are two ways to pick the second edge To define an alignment of faces as an integer between 0 and 5 we compare the ordering of edges on a face with the ordering of edges on the corresponding face on the reference tetrahedron If the first edge of the face
20. 2 B2 Debian PALA nde we ee ER eee ee 103 B 3 Installing from source under Windows 103 C Contributing code 105 Gl Creating a pateh ciao 105 Ge Sending patches gt a sec ra sga tayia WOR daw we ee aS 107 C 3 Applying a patch maintainers 107 C 4 License agreement 2 2 62 ib eA a EAE BER BS 108 D License 109 About this manual This manual is currently being written As a consequence some sections may be incomplete or inaccurate Intended audience This manual is written both for the beginning and the advanced user There is also some useful information for developers More advanced topics are treated at the end of the manual or in the appendix Typographic conventions e Code is written in monospace typewriter like this e Commands that should be entered in a Unix shell are displayed as follows configure make Commands are written in the dialect of the bash shell For other shells such as tcsh appropriate translations may be needed 11 DOLFIN User Manual Hoffman Jansson Logg Wells Enumeration and list indices Throughout this manual elements x of sets x of size n are enumerated from 0 toi n 1 Derivatives in R are enumerated similarly 2 0 Jro Dr Binet Contact Comments corrections and contributions to this manual are most welcome and should be sent to dolfin dev fenics org 12 Chapter 1 Introduction
21. DOLFIN User Manual February 24 2006 Hoffman Jansson Logg Wells www fenics org Visit http www fenics org for the latest version of this manual Send comments and suggestions to dolfin dev fenics org Contents About this manual 1 Introduction 1 1 The PERIS project lt ss csse ee ae mi keui oi ae 1 2 The finite element method LS OVErViGW oee ene ada e aod a kg iaa a a 2 Quickstart 2 1 Downloading and installing DOLFIN 2 2 Solving Poisson s equation with DOLFIN ya al a a 2 2 3 2 2 4 2 2 9 Setting up the variational problem Writing the solver lt lt lt lt lt aces ra Compiling the POETA lt gt sor e s sore a co Running the program occiso Visualizing the solution lt 4 lt 4 ses eee 24 6 os 3 13 13 13 13 15 DOLFIN User Manual Hoffman Jansson Logg Wells 3 Linear algebra 25 31 Matrices and VOCs coc kc ae eee ed Pa eee Se we 25 32 Mate 168 matricos vos ras e ee ee ee a 26 A a AR af dal cee CNL ol a ce ESOR SA ai 27 4 The mesh 29 LIL WEST se s cod acea ir e A A ee 29 A2 Mesh refinement lt es scs 24 creta ARA 31 5 Functions 33 Dl Basie PONG a ew RA ORE a Ce BX 33 Dll Representation e cce s peace a Oo es 34 Mia Evalia hion e ees ecrane aa 34 Dio ASUS y cra 35 5 1 4 Components and sub functions 35 Ma E e sra oa e Kaa Re we ES 36 5 2 Discrete functions
22. Don eo Be D ee er a ee ek ee eS 79 12 2 Convection diffusion lt a o no ee OR ee Ee Oe SS 80 1221 BOO oca aw bg k ERK Se EE OR BG 80 122 2 POSO 2c ea oo we eRe a ee eA OS 81 ENERO 81 12 3 Incompressible Navier Stokes 0 wee dees 82 A og area oY ele eB a Pee ee Oe wee 82 12 3 2 POLOS o lt 5 c ss ge eao De be we ees 82 DOLFIN User Manual Hoffman Jansson Logg Wells Td LEMONS 2k ch ae oe aoe ee prada 82 TEA AOS nk See ek ee BE ES BEE Eh we CEES E 82 WAL U cg ks ot ee ee oe ee oe Be ee Ps we 83 124 2 Perormanee o a a E BH 83 AA A Re Se ee Se Ee 83 A Reference elements 87 A 1 The reference triangle 0 22 000004 87 A 2 The reference tetrahedron 2 22004 89 A 3 Ordering of degrees of freedom 0 00004 90 A 3 1 Mesh entities cronista 90 A 3 2 Ordering among mesh entities 93 A 3 3 Internal ordering on edges 93 A 3 4 Alignment of edges 2 00 94 A 3 5 Internal ordering on faces 00 94 A 3 6 Alignment of faces 94 B Installation 97 BL Installing irom source dai need roserne i 97 B 1 1 Dependencies and requirements 97 B 1 2 Downloading the source code 99 B 1 3 Compiling the source code 100 8 DOLFIN User Manual Hoffman Jansson Logg Wells B 1 4 Compiling the demo programs 102 B 1 5 Compiling a program against DOLFIN 10
23. Iterator v2 n1 v2 end v2 cout lt lt v2 lt lt endl 4 2 Mesh refinement Adaptive mesh refinement is implemented in DOLFIN for triangular meshes in 2D and tetrahedral meshes in 3D see Figure 4 2 based on the algo rithm given in 14 To refine a mesh the cells triangles or tetrahedrons are first marked according to some criterion for refinement before the mesh is refined A hierarchy of meshes that can be used for example in a multigrid computation is automatically created The following example illustrates how to iterate over the Cells of a Mesh to mark some Cells for refinement before refining the Mesh 31 DOLFIN User Manual Hoffman Jansson Logg Wells Mark cells for refinement for Celllterator cell mesh cell end ce11 if ee cell omark Refine mesh mesh refine It is also possible to directly mark all Cells for refinement to refine the Mesh uniformly Refine all cells mesh refineUniformly 32 Chapter 5 Functions gt Developer s note Since this chapter was written the Function class has seen a number of improvements which are not covered here Chapter needs to be updated The central concept of a function on a domain 2 C R is modeled by the class Function which is used in DOLFIN to represent coefficients or solutions of partial differential equations 5 1 Basic properties The following basic properties hold for all Functions A Function
24. N will then automatically try to determine the Mesh and the FiniteElement In some cases 1t is necessary to also supply a Mesh when initializing a discrete Function Vector x Mesh mesh Function f x mesh If possible DOLFIN will then automatically try to determine the FiniteElement 37 DOLFIN User Manual Hoffman Jansson Logg Wells In general however a discrete Function must be initialized from a given Vector a Mesh and a FiniteElement Vector x Mesh mesh FiniteElement element Function f x mesh element 5 2 2 Accessing discrete function data It is possible to access the data of a discrete Function including the associ ated Vector Mesh and FiniteElement Vector amp x u vector Mesh amp mesh u mesh FiniteElement amp element u element 5 2 3 Attaching discrete function data After a discrete Function has been initialized it is possible to associate or reassociate data with the Function Vector x Mesh mesh FiniteElement element Function f x f attach mesh f attach element DOLFIN User Manual Hoffman Jansson Logg Wells Usually the FiniteElement is given by the BilinearForm defining the prob lem Considering the Poisson example in Chapter 2 a Function u represent ing the solution can be initialized as follows Vector x Mesh mesh Function f x mesh Poisson BilinearForm a FiniteElement amp element a trial f attach element
25. Public License applies to most of the Free Software Foundation s software and to any other program whose authors commit to using it Some other Free Software Foundation software is covered by the GNU Library General Public License instead You can apply it to your programs too When we speak of free software we are referring to freedom not price Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software and charge for 109 DOLFIN User Manual Hoffman Jansson Logg Wells this service if you wish that you receive source code or can get it if you want it that you can change the software or use pieces of it in new free programs and that you know you can do these things To protect your rights we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights These restrictions translate to certain responsibilities for you if you distribute copies of the software or if you modify it For example if you distribute copies of such a program whether gratis or for a fee you must give the recipients all the rights that you have You must make sure that they too receive or can get the source code And you must show them these terms so they know their rights We protect your rights with two steps 1 copyright the software and 2 offer you this license which gives you legal permission to copy distribute and or modify the
26. Time dependent functions gt Developer s note Write about time dependent and pseudo time dependent functions 42 Chapter 6 Ordinary differential equations gt Developer s note This chapter is currently being written 43 Chapter 7 Partial differential equations gt Developer s note This chapter is currently being written gt Developer s note Use U for discrete solution and U for corresponding representation in the code DOLFIN provides a general interface for defining a partial differential equa tion PDE in variational form The variational form is compiled with FFC which generates code for the assembly of a matrix and a vector correspond ing to the discretization of the PDE with a user defined finite element method FEM where the basis functions of the FEM space are constructed using FIAT 7 1 Boundary value problems As a prototype of a boundary value problem in R we consider the scalar Poisson equation with homogeneous Dirichlet boundary conditions Au z f r rencrR 7 1 ulz 0 600 45 DOLFIN User Manual Hoffman Jansson Logg Wells 7 2 Variational formulation A variational formulation of 7 1 takes the form find u V such that a v u L v Wwe V 7 2 where a V x V gt Ris a bilinear form acting on V x V with V and V the test space and trial space respectively defined by Ov Ou T where we employ tensor notation so that the double index i
27. am is restricted in certain countries either by patents or by copyrighted interfaces the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries so that distribution is permitted only in or among countries not thus excluded In such case this License incorporates the limitation as if written in the body of this License 9 The Free Software Foundation may publish revised and or new versions of the General Public License from time to time Such new versions will be similar in spirit to the present version but may differ in detail to address new problems or concerns Each version is given a distinguishing version number If the Program specifies a version number of this License which applies to it and any later version you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation If the Program does not specify a version number of this License you may choose any version ever published by the Free Software Foundation 114 DOLFIN User Manual Hoffman Jansson Logg Wells 10 If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different write to the author to ask for permission For software which is copyrighted by the Free Software Foundation write to the Free Software Foundation we sometimes make
28. arForm are automatically generated by FFC and to assemble the corresponding matrix and vector for the Poisson problem 7 2 with source term f we write Poisson BilinearForm a Poisson LinearForm L f Mesh mesh Mat A Vec b FEM assemble a L A b mesh In the assemble function the element matrices and vectors are computed by calling the function eval in the classes Bilinearform and Linearform The eval functions at a certain element in the assembly algorithm take as argument an AffineMap object describing the mapping from the reference element to the actual element by computing the Jacobian J of the mapping also J7 and det J are computed 48 DOLFIN User Manual Hoffman Jansson Logg Wells 7 7 Specifying boundary conditions and data The boundary conditions are specified by defining a new subclass of the class BoundaryCondition which we here will name MyBC class MyBC public BoundaryCondition const BoundaryValue operator const Point amp p BoundaryValue value if std abs p x 0 0 DOLFIN_EPS std abs p x 0 lt DOLFIN_EPS if if std abs p 0 DOLFIN_EPS if std abs p 0 DOLFIN_EPS if std abs p 0 DOLFIN_EPS if std abs p 0 DOLFIN_EPS return value where we have assumed homogeneous Dirichlet boundary conditions for the unit cube We only need to specify the boundary conditions explicitly on the Dirichlet boundary On the remaining part of the
29. bound ary Po x y OQ x 1 homogeneous Neumann boundary condi tions on the remaining part of the boundary and right hand side given by f xsin y Au z y gsin y e0 0 1 x 0 1 2 1 us 0 welg iey eon 21 2 2 Onu z 0 xEdON To 2 3 To solve a partial differential equation such as Poisson with DOLFIN it must first be rewritten in variational form The discrete variational finite element formulation for Poisson s equation reads Find u V such that a v U L v Ww V 2 4 with Vh Vp a pair of suitable function spaces the test and trial spaces The bilinear form a Vp x Vp R is given by alv U ve VU dx 2 5 16 DOLFIN User Manual Hoffman Jansson Logg Wells and the linear form L V gt R is given by L v fosas 2 6 2 2 1 Setting up the variational problem The variational problem 2 4 must be given to DOLFIN as a pair of bilin ear and linear forms a L using the form compiler FFC This is done by entering the definition of the forms in a text file with extension form e g Poisson form as follows element FiniteElement Lagrange triangle 1 BasisFunction element BasisFunction element Function element dot grad v grad U dx v f dx The example is given here for piecewise linear finite elements in two dimen sions but other choices are available including arbitrary order Lagrange elements in two and t
30. boundary homoge neous Neumann boundary conditions are automatically imposed weakly by the variational form The boundary conditions are then imposed as an argument to the assemble function MyBC bc FEM assemble a L A b mesh bc There is currently no easy way to impose non homogeneous Neumann bound ary conditions or other combinations of boundary conditions This will be added to a future release of DOLFIN 49 DOLFIN User Manual Hoffman Jansson Logg Wells The right hand side f of 7 1 is similarly specified by defining a new subclass of Function which we here will name MyFunction and overloading the evaluation operator class MyFunction public Function real operator const Point amp p const return p x p z sin p y with the source f x y z xzsin y 7 8 Initial value problems A time dependent problem has to be discretized in time manually and the resulting variational form is then discretized in space using FFC similarly to a stationary problem with the solution at previous time steps provided as data to the form file For example the form file Heat form for the heat equation discretized in time with the implicit Euler method takes the form BasisFunction scalar test function BasisFunction scalar value at next time step Function scalar value at previous time step Function scalar source term Constant time step v xUL dx k v dx i U1 dx i dx v U0 xdx
31. ch can be used to test the patch without actually applying it 5 The modified version now exists as dolfin 0 1 0 C 4 License agreement By contributing a patch to DOLFIN you agree to license your contributed code under the GNU General Public License a condition also built into the GPL license of the code you have modified Before creating the patch please update the author and date information of the file s you have modified according to the following example Copyright C 2004 2005 Johan Hoffman and Anders Logg Licensed under the GNU GPL Version 2 Modified by Johan Jansson 2005 Modified by Garth N Wells 2005 First added 2004 06 22 Last changed 2005 09 01 As a rule of thumb the original author of a file holds the copyright 108 Appendix D License DOLFIN is licensed under the GNU General Public License GPL version 2 included verbatim below GNU GENERAL PUBLIC LICENSE Version 2 June 1991 Copyright C 1989 1991 Free Software Foundation Inc 59 Temple Place Suite 330 Boston MA 02111 1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document but changing it is not allowed Preamble The licenses for most software are designed to take away your freedom to share and change it By contrast the GNU General Public License is intended to guarantee your freedom to share and change free software to make sure the software is free for all its users This General
32. e element methods for partial differential equations Related important concepts include vertices cells edges faces boundaries and mesh hierar chies These concepts are all implemented as C classes in DOLFIN as shown in Figure 4 1 4 1 Mesh iterators Algorithms operating on a mesh including adaptive mesh refinement can often be expressed in terms of iterators i e objects used for the traversal of aggregate structures such as the list of vertices contained in a mesh Iter ators implemented in DOLFIN include a VertexIterator CellIterator Edgelterator Facelterator and a MeshIterator The following code il lustrates how to iterate over all vertex neighbors of all vertices of all cells within a given mesh 29 DOLFIN User Manual Hoffman Jansson Logg Wells MeshHierarchy Figure 4 1 Class diagram of the basic mesh classes in DOLFIN 30 DOLFIN User Manual Hoffman Jansson Logg Wells eo nt IN O x a N SSS83 a e RRNA rt a s A hs E oa a RRR l eea saasa k 3 rr LL 4 NS eres sess os q or oo on on rr a a AA a n KKA OS oe ee ASENN i oo AY Y oam aa anaman Cres i pan seeee ee lt a can en an cr rasaae Ni Nx Figure 4 2 Adaptive mesh refinement of triangular and tetrahedral meshes in DOLFIN for CellIterator c m c end c for VertexIterator vi c vi end Q v1 for Vertex
33. e following examples illustrate the use of add add tolerance 0 01 add number of samples 10 add solve dual problem true add file name solution xml DOLFIN User Manual Hoffman Jansson Logg Wells 11 4 Saving parameters to file The following code illustrates how to save the current database of parameters to a file in DOLFIN XML format File file parameters xml file lt lt ParameterSystem parameters When running a simulation in DOLFIN saving the parameter database to a file is an easy way to document the set of parameters used in the simulation 11 5 Loading parameters from file The following code illustrates how to load a set of parameters into the current database of parameters from a file in DOLFIN XML format File file parameters xml file gt gt ParameterSystem parameters The following example illustrates how to specify a list of parameters in the DOLFIN XML format lt xml version 1 0 encoding UTF 8 gt lt dolfin xmlns dolfin http www fenics org dolfin gt lt parameters gt lt parameter name tolerance type real value 0 01 gt lt parameter name number of samples type int value 10 gt lt parameter name solve dual problem type bool value false gt lt
34. e linear algebra backend to PETSc Do grep FIXME in src kernel io Tomat Vector Matrix Hesh Function Sample Fite inont inont nfo Fev ot ot _ Fite ropena owt ow _ File octave ou ou out ou ow Fite matlab out ou ou ot ot Fite tecpiot out ow Fega ot ow Table 9 2 Matrix of supported combinations of classes and file formats for input output in DOLFIN 9 2 File formats In this section we give some pointers to each of the file formats supported by DOLFIN For detailed information we refer to the respective user manual of each format program gt Developer s note This section needs to be improved and expanded Any contributions are welcome 9 2 1 DOLFIN XML DOLFIN XML is the native format of DOLFIN As the name says data is stored in XML ASCII format This has the advantage of being a robust and human readable format and if the files are compressed there is little overhead in terms of file size compared to a binary format DOLFIN automatically handles gzipped XML files as illustrated by the fol lowing example which reads a Mesh from a compressed DOLFIN XML file and saves the mesh to an uncompressed DOLFIN XML file 99 DOLFIN User Manual Hoffman Jansson Logg Wells Mesh mesh File in mesh xml gz in gt gt mesh File out mesh xml out
35. eee a Re eR oe ee Ee OS 36 5 2 1 Creating a discrete function 37 5 2 2 Accessing discrete function data 38 5 2 3 Attaching discrete function data 38 5 3 User defined functions a aooaa aaa a a 39 DOLFIN User Manual Hoffman Jansson Logg Wells 5 3 1 Creating asub class s s som eee rratua 5 3 2 Specifying afunction pointer 5 3 3 Cell dependent functions 5 4 Time dependent functions ooo e e e a 6 Ordinary differential equations 7 Partial differential equations TAL Boundary value problems s r deraye aray nan td es T2 Vanational formulation case ea pie poda a pe BS 7 3 Finite elements and FIAT 7 4 Compiling the variational form with FFC 7 5 Element matrices and vectors o 7 6 Assemble matrices and vectors ooo a 7 7 Specifying boundary conditions and data 7 0 Initial value problems lt e e be preg ra 8 Nonlinear solver 8 1 Nonlinear functions s s e sad e eor oe Se e ROE e 8 2 Newlon solver 224i Gk bee dc deit d oa daea A 8 2 1 Linear solver ec raoga rama e na dh e bows 8 2 2 Application of Dirichlet boundary conditions 5 43 45 45 46 46 47 47 48 49 50 53 DOLFIN User Manual Hoffman Jansson Logg Wells 8 2 3 Newton solver parameters 55 8 2 4 Application of Dirichlet boundary conditions
36. er this License and any other pertinent obligations then as a consequence you 113 DOLFIN User Manual Hoffman Jansson Logg Wells may not distribute the Program at all For example if a patent license would not permit royalty free redistribution of the Program by all those who receive copies directly or indirectly through you then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program If any portion of this section is held invalid or unenforceable under any particular circumstance the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system it is up to the author donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License 8 If the distribution and or use of the Progr
37. ereinafter translation is included without limitation in the term modification Each licensee is addressed as you Activities other than copying distribution and modification are not covered by this License they are outside its scope The act of running the Program is not restricted and the output from the Program is covered only if its contents constitute a work based on the Program independent of having been made by running the Program Whether that is true depends on what the Program does 1 You may copy and distribute verbatim copies of the Program s source code as you receive it in any medium provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty keep intact all the notices that refer to this License and to the absence of any warranty and give any other recipients of the Program a copy of this License along with the Program You may charge a fee for the physical act of transferring a copy and you may at your option offer warranty protection in exchange for a fee 2 You may modify your copy or copies of the Program or any portion of it thus forming a work based on the Program and copy and distribute such modifications or work under the terms of Section 1 above provided that you also meet all of these conditions a You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change b Y
38. essages Thus the above examples can also be implemented as follows cout lt lt Solving linear system lt lt endl cout lt lt Size of vector lt lt x size lt lt lt lt endl cout lt lt R lt lt R lt lt TOL lt lt TOL lt lt lt lt endl Note the use of dolfin cout and dolfin endl from the dolfin names pace corresponding to the standard standard std cout and std endl in namespace std If log messages are directed to standard output see below then dolfin cout and std cout may be mixed freely Most classes provided by DOLFIN can be used together with dolfin cout and dolfin end1 to display short informative messages about objects Matrix A 10 10 cout lt lt A lt lt endl To display detailed information for an object use the member function disp Matrix A 10 10 A disp Use with caution for large objects For a Matrix calling disp will displays all matrix entries 10 2 Warnings and errors Warnings and error messages can be generated using the macros 66 DOLFIN User Manual Hoffman Jansson Logg Wells dolfin_warning message dolfin_error message In addition to displaying the given string message the macro dolfin_error also displays information about the location of the code that generated the error file function name and line number Once an error is encountered t
39. exceptions for this Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally NO WARRANTY 11 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE THERE IS NO WARRANTY FOR THE PROGRAM TO THE EXTENT PERMITTED BY APPLICABLE LAW EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND OR OTHER PARTIES PROVIDE THE PROGRAM AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESSED OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU SHOULD THE PROGRAM PROVE DEFECTIVE YOU ASSUME THE COST OF ALL NECESSARY SERVICING REPAIR OR CORRECTION 12 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY MODIFY AND OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE BE LIABLE TO YOU FOR DAMAGES INCLUDING ANY GENERAL SPECIAL INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES END OF TERMS AND CONDITIONS 115 Index F
40. g Wells
41. g example int num_samples get number of samples for int i 0 i lt num_samples i 11 2 Modifying the value of a parameter To modify the value of a parameter use the function set available in the dolfin namespace void set std string key Parameter value This function accepts as arguments a string key together with the corre sponding value The value type should match the type of parameter that is 74 DOLFIN User Manual Hoffman Jansson Logg Wells being modified An error message is printed through the log system if there is no parameter with the given key in the database The following examples illustrate the use of set set tolerance 0 01 set number of samples 10 set solve dual problem true set file name solution xml Note that changing the values of parameters using set does not change the values of already retrieved parameters it only changes the values of parameters in the database Thus the value of a parameter must be changed before using a component that is controlled by the parameter in question 11 3 Adding a new parameter To add a parameter to the database use the function add available in the dolfin namespace void add std string key Parameter value This function accepts two arguments a unique key identifying the new pa rameter and the value of the new parameter Th
42. gt Developer s note This chapter is currently being written 1 1 The FEniCS project 1 2 The finite element method 1 3 Overview DOLFIN is implemented as a C library and can be used either as a stand alone solver or as a tool for the development and implementation of new methods To simplify usage and emphasize structure DOLFIN is organized into three levels of abstraction referred to as kernel level module level and user level as shown in Figure 1 1 Core features such as the automatic eval uation of variational forms and adaptive mesh refinement are implemented as basic tools at kernel level At module level new solvers modules can be assembled from these basic tools and integrated into the system At user level a model of the form is specified and solved either using one of the built in solvers modules or by direct usage of the basic tools 13 DOLFIN User Manual Hoffman Jansson Logg Wells main cpp user program IN User level N Module level Poisson N Kernel level solver module Navier Stokes solver module Elasticity solver module solver module Wave equation solver module Multi adaptive solver module Multi __ Automatic adaptivity assembly evaluation Function algebra geometry representation Basic Element data structures library Basic database math D o ES Linear Mesh and esa Ea __ Quadrature es Figure 1 1 Simp
43. he assertion and a segmentation fault is raised to enable easy attachment to a debugger The following examples illustrate the use of dolfin_assert dolfin_assert i gt 0 dolfin_assert i lt n dolfin_assert cell type Cell triangle dolfin_assert cell type Cell tetrahedron Note that assertions are only active when compiling DOLFIN and your program with DEBUG defined configure option enable debug or compiler flag DDEBUG Otherwise the macro dolfin_assert expands to nothing meaning that liberal use of assertions does not affect performance since as sertions are only present during development and debugging 10 4 Task notification The two functions dolfin_begin and dolfin_end available in the dolfin name space can be used to notify the DOLFIN log system about the begin ning and end of a task void dolfin_begin void dolfin_end Alternatively a string message or a formatting string with optional argu ments can be supplied DOLFIN User Manual Hoffman Jansson Logg Wells void dolfin_begin const char message void dolfin_end const char message These functions enable the DOLFIN log system to display messages warn ings and errors hierarchically by automatically indenting the output pro duced between calls to dolfin_begin and dolfin_end A program may contain an arbitrary number of nested tasks 10 5 Progress bars The DOLFIN log system provides the class Progres
44. he program is stopped Note that in order to pass formatting strings and additional arguments to warnings or errors the variations dolfin_error1 dolfin_error2 and so on must be used as illustrated by the following examples dolfin_error GMRES solver did not converge dolfin_error1 Unable to find face opposite to node 7 d n dolfin_error2 Unable to find edge between nodes d and d nO n1 10 3 Debug messages and assertions The macro dolfin_debug works similarly to dolfin_info dolfin_debug message but in addition to displaying the given message information is printed about the location of the code that generated the debug message file function name and line number Note that in order to pass formatting strings and additional arguments with debug messages the variations dolfin_debug1 dolfin_debug2 and so on depending on the number of arguments must be used Assertions can often be a helpful programming tool Use assertions whenever you assume something about about a variable in your code such as assum ing that given input to a function is valid DOLFIN provides the macro dolfin_assert for creating assertions 67 DOLFIN User Manual Hoffman Jansson Logg Wells dolfin_assert check This macro accepts a boolean expression and if the expression evaluates to false an error message is displayed including the file function name and line number of t
45. hedral grid refinement Computing 55 1995 pp 355 378 85 Appendix A Reference elements A 1 The reference triangle The reference triangle Figure A 1 is defined by the following three vertices v 0 0 v 1 0 A 1 v 0 1 Note that this corresponds to a counter clockwise orientation of the vertices in the plane The edges of the reference triangle are ordered following the convention that edge ef should be opposite to vertex v for i 0 1 2 with the vertices of each edge ordered to give a counter clockwise orientation of the triangle in the plane e loo e v v A 2 e v yl 87 DOLFIN User Manual Hoffman Jansson Logg Wells Lo yo ut Figure A 1 Physical coordinates of the reference triangle v e e y e v Figure A 2 Ordering of mesh entities vertices and edges for the reference triangle 88 DOLFIN User Manual Hoffman Jansson Logg Wells A 2 The reference tetrahedron The reference tetrahedron Figure A 3 is defined by the following four ver tices u 0 0 0 v 1 0 0 y kl y A3 v 0 1 0 AH vt 0 0 1 The faces of the reference tetrahedron are ordered following the convention that face f should be opposite to vertex v for i 0 1 2 3 with the vertices of each face ordered to give a counter clockwise orientation of each face as seen from the outside of the tetrahedron and the first vertex of face f given by vertex v
46. hen adding a new file format or improving upon an existing file format is a good place to start Take a look at one of the current formats in the subdirectory src kernel io of the DOLFIN source tree to get a feeling for how to de sign the file format or ask at dolfin dev fenics org for directions Also consider contributing to the dolfin convert script by adding a con version routine for your favorite format The script is written in Python and should be easy to extend with new formats 63 Chapter 10 The log system DOLFIN provides provides a simple interface for uniform handling of log messages including warnings and errors All messages are collected to a single stream which allows the destination and formatting of the output from an entire program including the DOLFIN library to be controlled by the user 10 1 Generating log messages Log messages can be generated using the function dolfin_info available in the dolfin namespace void dolfin_info const char message which works similarly to the standard C library function printf The fol lowing examples illustrate the usage of dolfin_info dolfin_info Solving linear system dolfin_info Size of vector d x size dolfin_info R 3e TOL 3e R TOL 65 DOLFIN User Manual Hoffman Jansson Logg Wells As an alternative to dolfin_info DOLFIN provides a C style in terface to generating log m
47. hole and thus to each and every part regardless of who wrote it Thus it is not the intent of this section to claim rights or contest your rights to work written entirely by you rather the intent is to exercise the right to control the distribution of derivative or collective works based on the Program In addition mere aggregation of another work not based on the Program with the Program or with a work based on the Program on a volume of a storage or distribution medium does not bring the other work under the scope of this License 3 You may copy and distribute the Program or a work based on it under Section 2 in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following a Accompany it with the complete corresponding machine readable source code which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange or b Accompany it with a written offer valid for at least three years to give any third party for a charge no more than your cost of physically performing source distribution a complete machine readable copy of the corresponding source code to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange or c Accompany it with the information you received as to the offer to distribute corresponding source code This alternative is allowed only fo
48. hree dimensions To compile the pair of forms a L now call the form compiler on the command line as follows ffc Poisson form This generates the file Poisson h which implements the forms in C for inclusion in your DOLFIN program 17 DOLFIN User Manual Hoffman Jansson Logg Wells 2 2 2 Writing the solver Having compiled the variational problem 2 4 with FFC it is now easy to implement a solver for Poisson s equation We first discuss the implementa tion line by line and then present the complete program The source code for this example is available in the directory src demo pde poisson of the DOLFIN source tree At the beginning of our C program which we write in a text file named main cpp we must first include the header file dolfin h which gives our program access to the DOLFIN class library In addition we include the header file Poisson h generated by the form compiler Since all classes in the DOLFIN class library are defined within the namespace dolfin we also specify that we want to work within this namespace include lt dolfin h gt include Poisson h using namespace dolfin Since we are writing a C program we need to create a main function You are free to organize your program any way you like but in this simple example we just write our program inside the main function int main Write your program here return 0 We now proceed to specify the right
49. ile 57 Progress 69 add 75 cout 65 dolfin_assert 67 dolfin_begin 68 dolfin_debug 67 dolfin_end 68 dolfin_error 66 dolfin_info 65 dolfin_log 70 dolfin_output 70 dolfin_warning 66 endl 65 get Q 73 set 74 assertions 67 automation 13 compiling 100 102 contact 12 contributing 105 convection diffusion 80 curses interface 70 Cygwin 103 Debian package 103 debugging 67 demo programs 102 dependencies 97 117 diff 105 downloading 15 99 eigenvalue solver 27 enumeration 12 errors 66 FEniCS 13 FFC 99 fte 17 FIAT 99 file formats 59 finite element method 13 Function 33 functions 33 GNU General Public License 109 GPL 109 I O 57 incompressible Navier Stokes 82 indices 12 input output 57 installation 15 97 Libxml2 98 license 108 109 log system 65 MayaVi 36 Navier Stokes 82 Newton s method 53 55 DOLFIN User Manual NewtonSolver 55 nonlinear solver 53 NonlinearFunction 53 object 57 output destination 70 parameters 73 ParaView 36 partial differential equations 45 patch 105 107 PETSc 98 Poisson s equation 16 78 post processing 57 pre processing 57 progress bar 69 quickstart 15 reference tetrahedron 89 reference triangle 87 source code 99 tasks 68 typographic conventions 11 user defined functions 39 warnings 66 XML 59 76 118 Hoffman Jansson Log
50. it mod 4 E ee Foura l Pee we a The edges of the reference tetrahedron are ordered following the convention that edges e e e should correspond to the edges of the reference triangle Edges e e e all ending up at vertex v are ordered based on their first vertex A 5 iN N SS Oo DB DB ODO OH 0 w The ordering of vertices on faces implicitly defines an ordering of edges on 89 DOLFIN User Manual Hoffman Jansson Logg Wells faces by identifying an edge on a face with the opposite vertex on the face A 6 Note that the ordering of edges on f is the same as the ordering of edges on the reference triangle Also note that the internal ordering of vertices on edges does not always follow the orientation of the face which is not possible A 3 Ordering of degrees of freedom The local and global orderings of degrees of freedom or nodes are obtained by associating each node with a mesh entity locally and globally A 3 1 Mesh entities We distinguish between mesh entities of different topological dimensions vertices topological dimension 0 edges topological dimension 1 faces topological dimension 2 cells topological dimension 2 or 3 A cell can be either a triangle or a tetrahedron depending on the type of mesh For a mesh consisting of triangles the mesh entities involved are vertices edges and cells and for a mesh consisting of tetrahedrons the mesh entities involved are vertices edges
51. lified component diagram of DOLFIN 14 Chapter 2 Quickstart This chapter demonstrates how to get started with DOLFIN including down loading and installing the latest version of DOLFIN and solving Poisson s equation These topics are discussed in more detail elsewhere in this manual In particular see Appendix B for detailed installation instructions and Chap ter 7 for a detailed discussion of how to solve partial differential equations with DOLFIN 2 1 Downloading and installing DOLFIN The latest version of DOLFIN can be found on the FENICS web page http www fenics org The following commands illustrate the installation process assuming that you have downloaded release 0 1 0 of DOLFIN tar zxfv dolfin 0 1 0 tar gz cd dolfin 0 1 0 15 DOLFIN User Manual Hoffman Jansson Logg Wells configure make make install Make sure that you download the latest release which is not 0 1 0 Note that you may need to be root on your system to perform the last step Since DOLFIN depends on a number of other packages including the linear algebra package PETSc and the form compiler FFC you may also need download and install these packages before you can compile DOLFIN See Appendix B for detailed instructions 2 2 Solving Poisson s equation with DOLFIN Let s say that we want to solve Poisson s equation on the unit square 2 0 1 x 0 1 with homogeneous Dirichlet boundary conditions on the
52. means summation from i 1 d and L V Ris a linear form acting on the test space V defined by a v u ve Vuide 7 3 L v for dx 7 4 For this problem we typically use V V Hd Q with H Q the standard Sobolev space of square integrable functions with also their first derivatives square integrable in the Lebesgue sense with the functions being zero on the boundary in the sense of traces The FEM method for 7 2 is now find U V such that a v U L v Ww Va 7 5 where V C V and VA C V are finite dimensional subspaces of dimension M The finite element spaces Vp Vi are characterized by their sets of basis functions y 4 4 The FEM method 7 5 is thus specified by the variational form and the basis functions of V and Vp 1 3 Finite elements and FIAT Finite element basis functions in DOLFIN are defined using FIAT which supports the generation of arbitrary order Lagrange finite elements on lines triangles and tetrahedra Upcoming versions of FIAT will also support Her mite and nonconforming elements as well as H div and H curl elements such as Raviart Thomas and Nedelec 46 DOLFIN User Manual Hoffman Jansson Logg Wells 7 4 Compiling the variational form with FFC In DOLFIN a PDE is defined in variational form using tensor notation in a form file which is compiled using FFC In the language of FFC with V V the space of piecewise linear Lagra
53. n Logg Wells tar zxfv dolfin 0 1 0 tar gz This creates a directory dolfin 0 1 0 containing the DOLFIN source code If you want the very latest version of DOLFIN there is also a version named dolfin cvs current tar gz which provides a snapshot of the current CVS version of DOLFIN updated automatically from the CVS repository each hour This version may contain features not yet present in the latest release but may also be less stable and even not work at all B 1 3 Compiling the source code DOLFIN is built using the standard GNU Autotools Automake Autoconf which means that the installation procedure is simple configure make followed by an optional make install to install DOLFIN on your system The configure script will check for a number of libraries and try to figure out how compile DOLFIN against these libraries The configure script accepts a collection of optional arguments that can be used to control the compilation process A few of these are listed below Use the command configure help 100 DOLFIN User Manual Hoffman Jansson Logg Wells for a complete list of arguments e Use the option prefix lt path gt to specify an alternative directory for installation of DOLFIN The default directory is usr local which means that header files will be installed under usr local include and libraries will be installed under usr local lib This option can be useful if you don t have roo
54. n ParaView 23 Chapter 3 Linear algebra gt Developer s note This chapter is currently being written DOLFIN does not have its own linear algebra routines but instead uses the external package PETSc 11 for linear algebra functionality PETSc is a suite of data structures and routines for the scalable parallel solution of scientific applications modeled by partial differential equations It employs the MPI standard for all message passing communication For convenience DOLFIN provides wrappers for some of the most common linear algebra functionality For more advanced usage DOLFIN provides direct access to the PETSc pointers to be used with the standard PETSc interface 3 1 Matrices and vectors The matrix class Matrix provides wrappers for initializing a sequential sparse matrix or a sequential sparse matrix in block compressed row format For parallel matrices the PETSc interface has to be used directly The code for initializing a sequential sparse M x N matrix takes the form 25 DOLFIN User Manual Hoffman Jansson Logg Wells uint M 100 uint N 100 Matrix A M N Similarly the vector class Vector allows for a simple initialization of a M vector Vector b M Further wrappers for some basic linear algebra functionality such as matrix vector multiplication norms etc are provided with an intentionally simple interface for example matrix vector multiplication is defined by Vector Ax A m
55. nd lt lt write Thus if file is a File and object is an object of some class that can be written to file then the object can be written to file as follows file lt lt object Similarly if object is an object of a class that can be read from file then data can be read from file overwriting any previous data held by the object 57 DOLFIN User Manual Hoffman Jansson Logg Wells as follows file gt gt object The format type of a file is determined by its filename suffix if not otherwise specified Thus the following code creates a File for reading writing data in DOLFIN XML format File file data xml A complete list of file formats and corresponding file name suffixes is given in Table 9 1 Alternatively the format of a file may be explicitly defined One may thus create a file named data xml for reading writing data in GNU Octave for at File file data xml File octave B DOLFIN XMI VTK OpenDX GNU Octane File matlab MATLAB Tecplo GD Table 9 1 File formats and corresponding file name suffixes Although many of the classes in DOLFIN support file input output it is not supported by all classes and the support varies with the choice of file format A summary of supported classes formats is given in Table 9 2 58 DOLFIN User Manual Hoffman Jansson Logg Wells gt Developer s note Some of the file formats are partly broken after changing th
56. nd MEn coder 6 Developer s note Add MEncoder example to create animation 9 2 3 OpenDX OpenDX 9 is a powerful free visualization tool based on IBM s Visualization Data Explorer To visualize data with OpenDX a user needs to build a visual program that instructs OpenDX how to extract and visualize relevant parts of your data DOLFIN provides a ready made visual program suitable for visualization of DOLFIN data in OpenDX The visual program can be found in the subdirectory src utils opendx of the DOLFIN source tree file dolfin net and accompanying configuration dolfin cfg 9 24 GNU Octave GNU Octave 7 is a free clone of MATLAB that can be used to visualize solutions computed in DOLFIN using the commands pdemesh pdesurf 61 DOLFIN User Manual Hoffman Jansson Logg Wells and pdeplot These commands are normally not part of GNU Octave but are provided by DOLFIN in the subdirectory src utils octave of the DOLFIN source tree These commands require the external program ivview included in the open source distribution of Open Inventor 8 Debian users install the package inventor clients To visualize a solution computed with DOLFIN and exported in GNU Octave format first load the solution into GNU Octave by just typing the name of the file without the m suffix If the solution has been saved to the file poisson m then just type octave 1 gt poisson The solution can now be visualized using the command
57. ned by specifying a func tion pointer The following example illustrates an alternative way of creating a Function representing the function in 5 2 real source const Point amp p unsigned int i return x y sin z DOLFIN_PI Function f source As before for vector valued Functions the vector dimension must be sup plied to the constructor of Function real source const Point amp p unsigned int i if i 0 return 0 0 else if i 1 return x y sin z DOLFIN_PI else return x y Function f source 3 5 3 3 Cell dependent functions In some cases it may be convenient to define a Function in terms of proper ties of the current Cell One such example is a Function that at any given point takes the value of the mesh size at that point Al DOLFIN User Manual Hoffman Jansson Logg Wells The following example illustrates how to create such as Function by over loading the eval function class MeshSize public Function real eval const Point amp p unsigned int i return cell diameter y MeshSize h Note that the current Cell is only available during assembly and has no meaning otherwise It is thus not possible to write the Function h to file since the current Cell is not available when evaluating a Function at any given Vertex Furthermore note that the current Cell is not available when creating a Function from a function pointer 5 4
58. nge finite elements on a tetrahedral mesh 7 5 is defined as element FiniteElement Lagrange tetrahedron 1 BasisFunction element BasisFunction element Function element v dx i u dx i dx v f dx where dx signifies integration over the domain Q and the finite element space is constructed using FIAT DOLFIN is not communicating directly with FIAT but only through FFC in the definition of the variational form in the form file Compiling the form file with ffc Poisson form generates a file Poisson h containing classes for the bilinear form a and the linear form L and classes for the finite element spaces V and Vj 7 5 Element matrices and vectors The element matrices and vectors for a given cell may be factored into two tensors with one tensor depending on the geometry of the cell and the 47 DOLFIN User Manual Hoffman Jansson Logg Wells other tensor only involving integration of products of basis functions and their derivatives over the reference element For efficiency in the computation of the element matrices and vectors FFC precomputes the tensors that are independent of the geometry of a certain cell 7 6 Assemble matrices and vectors The class FEM automates the assembly algorithm constructing a linear system of equations from a PDE given in the form of a variational problem 7 2 with a bilinear form a and a linear form L The classes BilinearForm and Line
59. ocalization of parameters to objects or hierarchies of objects Chapter needs to be updated DOLFIN keeps a global database of parameters that control the behavior of the various components of DOLFIN Parameters are controlled using a uni form type independent interface that allows retrieving the values of existing parameters modifying existing parameters and adding new parameters to the database 11 1 Retrieving the value of a parameter To retrieve the value of a parameter use the function get available in the dolfin namespace Parameter get std string key This function accepts as argument a string key and returns the value of the parameter matching the given key An error message is printed through the 73 DOLFIN User Manual Hoffman Jansson Logg Wells log system if there is no parameter with the given key in the database The value of the parameter is automatically cast to the correct type when assigning the value of get to a variable as illustrated by the following examples real TOL get tolerance int num_samples get number of samples bool solve_dual get solve dual problem std string filename get file name Note that there is a small cost associated with accessing the value of a pa rameter so if the value of a parameter is to be used multiple times then it should be retrieved once and stored in a local variable as illustrated by the followin
60. octave 2 gt pdesurf points cells u or to visualize just the mesh type octave 3 gt pdesurf points edges cells 9 2 5 MATLAB Since MATLAB 4 is not free users are encouraged to use GNU Octave whenever possible That said data is visualized in much the same way in MATLAB as in GNU Octave using the MATLAB commands pdemesh pdesurf and pdeplot 9 2 6 Tecplot Tecplot 12 is a proprietary visualization tool The Tecplot format is not actively maintained and may be removed in future versions of DOLFIN if 62 DOLFIN User Manual Hoffman Jansson Logg Wells there is not sufficient interest to maintain the format 9 2 7 GiD GiD 2 is a proprietary visualization tool The GiD format is not actively maintained and may be removed in future versions of DOLFIN if there is not sufficient interest to maintain the format 9 3 Converting between file formats DOLFIN supplies a script for easy conversion between different file formats The script is named dolfin convert and can be found in the directory src utils convert of the DOLFIN source tree The only supported file formats are currently the Medit mesh format which can be generated by TetGen the gmsh format generated by Gmsh and the DOLFIN XML mesh format dolfin convert mesh mesh mesh xml 94 A note on new file formats With some effort DOLFIN can be expanded with new file formats Any con tributions are welcome If you wish to contribute to DOLFIN t
61. ou must cause any work that you distribute or publish that in whole or in part contains or is derived from the Program or any part thereof to be licensed as a whole at no charge to all third parties under the terms of this License c If the modified program normally reads commands interactively when run you must cause it when started running for such interactive use in the most ordinary way to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty or else saying that you provide a warranty and that users may redistribute the program under these conditions and telling the user how to view a copy of this License Exception if the Program itself is interactive but does not normally print such an announcement your work based on the Program is not required to print an announcement 111 DOLFIN User Manual Hoffman Jansson Logg Wells These requirements apply to the modified work as a whole If identifiable sections of that work are not derived from the Program and can be reasonably considered independent and separate works in themselves then this License and its terms do not apply to those sections when you distribute them as separate works But when you distribute the same sections as part of a whole which is a work based on the Program the distribution of the whole must be on the terms of this License whose permissions for other licensees extend to the entire w
62. oundaryCondition amp bc Solve Poisson s equation void solve Solve Poisson s equation static version static void solve Meshg mesh Functiong f BoundaryCondition amp bc 78 DOLFIN User Manual Hoffman Jansson Logg Wells A simple example of using the solver int main Mesh mesh mesh xml gz MyFunction f MyBC bc PoissonSolver solve mesh f bc return 0 Where f is a Function specifying the right hand side of the equation and be is a BoundaryCondition 12 1 2 Performance The solver is an illustrative example and performance has not been a goal It uses a GMRES linear solver where a multi grid linear solver would give optimal performance 12 1 3 Limitations The solver is meant to be the simplest example solver and therefore some simplifications have been made Typically the general form of Poisson s equa tion includes a diffusion coefficient which has been omitted here 79 DOLFIN User Manual Hoffman Jansson Logg Wells 12 2 Convection diffusion The convection diffusion equation with Dirichlet and homogeneous Neumann boundary conditions is given by u b Vu V aVu f nQx 0 7 u gp nT x 0 T u 0 on Py x 0 T 12 3 e ul ug inQ where the convection is given by the vector b b x t and the diffusion is given by a a z t The variational formulation is FIXME Stabilized convection diffusion This is a stabilized
63. parameter name file name type string value solution xml gt lt parameters gt lt dolfin gt 76 Chapter 12 Solvers gt Developer s note This chapter is currently being written DOLFIN provides a number of pre defined PDE solvers called modules in the source structure by default The solver interface is intentionally very simple to facilitate users writing their own solvers These are the pre defined solvers 1 Poisson 2 Convection Diffusion 3 Navier Stokes 4 Elasticity A solver for a PDE should provide the following interface 1 a constructor which takes a mesh equation coefficients and possibly additional data 2 a solve method which solves the equation given the specified data 3 a static solve function which constructs and solves the equation TT DOLFIN User Manual Hoffman Jansson Logg Wells FIXME List solvers then present in detail include lots of nice images with solver output 12 1 Poisson s equation Poisson s equation with Dirichlet and homogeneous Neumann boundary con ditions Au f mo u gp only 12 1 0 u 0 onl The variational formulation is given by f Vu Vudx fi fodre W 12 2 The boundary conditions are enforced strongly and thus don t appear in the variational formulation 12 1 1 Usage The API for the Poisson solver Create Poisson solver PoissonSolver Mesh amp mesh Function amp f B
64. pressure uo ULO first component of the velocity U1 UL 1 second component of the velocity U2 U 21 third component of the velocity Note that picking a component or sub function creates a new Function that shares data with the original Function 5 1 5 Output A Function can be written to a file in various file formats To write a Function u to file in VTK format suitable for viewing in ParaView or MayaVi create a file with extension pvd File file solution pvd file lt lt U For further details on available file formats see Chapter 9 5 2 Discrete functions A discrete Function is defined in terms of a Vector of nodal values degrees of freedom a Mesh and a FiniteElement specifying the distribution of the nodal values on the Mesh In particular a discrete Function is given by a 36 DOLFIN User Manual Hoffman Jansson Logg Wells linear combinations of basis functions N v X vidi 5 1 i 1 where is the global basis of the finite element space defined by the Mesh and the FiniteElement and the nodal values v are given by the values of a Vector Note that a discrete Function may not be evaluated at arbitrary points only at each Vertex of a Mesh 5 2 1 Creating a discrete function A discrete Function can be initialized in several ways In the simplest case only a Vector x of nodal values needs to be specified Vector x Function f x If possible DOLFI
65. program you want to compile and type make You may also compile all demo programs at once using the command make demo B 1 5 Compiling a program against DOLFIN Whether you are writing your own Makefiles or using an automated build system such as GNU Autotools or BuildSystem it is straightforward to com pile a program against DOLFIN The necessary include and library paths can be obtained through the script dolfin config which is automatically generated during the compilation of DOLFIN and installed in the bin sub directory of the lt path gt specified with prefix Assuming this directory is in your executable path environment variable PATH the include path for building DOLFIN can be obtained from the command dolfin config cflags and the path to DOLFIN libraries can be obtained from the command dolfin config libs If dolfin config is not in your executable path you need to provide the full path to dolfin config Examples of how to write a proper Makefile are provided with each of the example programs in the subdirectory src demo in the DOLFIN source tree 102 DOLFIN User Manual Hoffman Jansson Logg Wells B 2 Debian package In preparation B 3 Installing from source under Windows DOLFIN can be used under Windows using Cygwin which provides a Linux like environment The installation process is largely the same as under GNU Linux This section addresses some Cygwin specific issues To use DOLFIN
66. r noncommercial distribution and only if you received the program in object code or executable form with such an offer in accord with Subsection b above The source code for a work means the preferred form of the work for making modifications to it For an executable work complete source code means all the source code for all modules it contains plus any associated interface definition files plus the scripts used to 112 DOLFIN User Manual Hoffman Jansson Logg Wells control compilation and installation of the executable However as a special exception the source code distributed need not include anything that is normally distributed in either source or binary form with the major components compiler kernel and so on of the operating system on which the executable runs unless that component itself accompanies the executable If distribution of executable or object code is made by offering access to copy from a designated place then offering equivalent access to copy the source code from the same place counts as distribution of the source code even though third parties are not compelled to copy the source along with the object code 4 You may not copy modify sublicense or distribute the Program except as expressly provided under this License Any attempt otherwise to copy modify sublicense or distribute the Program is void and will automatically terminate your rights under this License However parties who have
67. received copies or rights from you under this License will not have their licenses terminated so long as such parties remain in full compliance 5 You are not required to accept this License since you have not signed it However nothing else grants you permission to modify or distribute the Program or its derivative works These actions are prohibited by law if you do not accept this License Therefore by modifying or distributing the Program or any work based on the Program you indicate your acceptance of this License to do so and all its terms and conditions for copying distributing or modifying the Program or works based on it 6 Each time you redistribute the Program or any work based on the Program the recipient automatically receives a license from the original licensor to copy distribute or modify the Program subject to these terms and conditions You may not impose any further restrictions on the recipients exercise of the rights granted herein You are not responsible for enforcing compliance by third parties to this License 7 If as a consequence of a court judgment or allegation of patent infringement or for any other reason not limited to patent issues conditions are imposed on you whether by court order agreement or otherwise that contradict the conditions of this License they do not excuse you from the conditions of this License If you cannot distribute so as to satisfy simultaneously your obligations und
68. s for simple creation of progress sessions A progress session automatically displays the progress of a computation using a progress bar If the number of steps of a computation is known a progress session should be defined in terms of the number of steps and updated in each step of the computation as illustrated by the following example Progress p Assembling mesh noCells for CellIterator c mesh c end c It is also possible to specify the step number explicitly by assigning an integer to the progress session Progress p Iterating over vector x size for uint i 0 i lt x size i 69 DOLFIN User Manual Hoffman Jansson Logg Wells p 1 Alternatively if the number of steps is unknown the progress session needs to be updated with the current percentage of the progress Progress p Time stepping while t lt T p t T The progress bar created by the progress session will only be updated if the progress has changed significantly since the last update by default at least 10 The amount of change needed for an update can be controlled using the parameter progress step dolfin_set progress step 0 01 Note that several progress sessions may be created simultaneously or nested within tasks 10 6 Controlling the destination of output By default the DOLFIN log system directs messages to standard output the
69. sson Logg Wells Next we initialize the pair of bilinear and linear forms that we have previ ously compiled with FFC Poisson BilinearForm a Poisson LinearForm L f We may now define a PDE from the pair of forms the mesh and the boundary conditions PDE pde a L mesh bc To solve the PDE we now just need to call the solve function as follows Function U pde solve Finally we export the solution u to a file for visualization Here we choose to save the solution in VTK format for visualization in ParaView or MayaVi which we do by specifying a file name with extension pvd File file poisson pvd file lt lt U The complete program for Poisson s equation now looks as follows include lt dolfin h gt include Poisson h using namespace dolfin int main Right hand side 20 DOLFIN User Manual Hoffman Jansson Logg Wells class public Function real eval const Point amp p unsigned int i return p x sin p y f Boundary condition class public BoundaryCondition void eval BoundaryValue amp value const Point amp p unsigned int i if std abs p x 1 0 lt DOLFIN_EPS value 0 0 bc Set up problem UnitSquare mesh 16 16 Poisson BilinearForm a Poisson LinearForm L f PDE pde a L mesh bc Compute solution Function U pde solve Save solution to file File file poisson pvd
70. t access but want to install DOLFIN locally on a user account as follows mkdir local configure prefix local make make install a se the option enable debug to compile DOLFIN with debugging symbols and assertions e Use the option enable optimization to compile an optimized ver sion of DOLFIN without debugging symbols and assertions e Use the option disable curses to compile DOLFIN without the curses interface a text mode graphical user interface e Use the option disable mpi to compile DOLFIN without support for MPI Message Passing Interface assuming PETSc has been com piled without support for MPI e Use the option with petsc dir lt path gt to specify the location of the PETSc directory By default DOLFIN assumes that PETSc has been installed in usr local lib petsc Alternatively use the script configure local to install DOLFIN in a sub directory local of the DOLFIN source tree This can be convenient if you are not root don t want to install DOLFIN on your system or are working on several different source trees configure local make make install 101 DOLFIN User Manual Hoffman Jansson Logg Wells B 1 4 Compiling the demo programs After compiling the DOLFIN library according to the instructions above you may want to try one of the demo programs in the subdirectory src demo of the DOLFIN source tree Just enter the directory containing the demo
71. t identifier gt lt date gt patch 106 DOLFIN User Manual Hoffman Jansson Logg Wells C 2 Sending patches Patch files should be sent to the DOLFIN mailing list at the address dolfin dev fenics org Include a short description of what your patch accomplishes Small patches have a better chance of being accepted so if you are making a major con tribution please consider breaking your changes up into several small self contained patches if possible C 3 Applying a patch maintainers Let s say that a patch has been built relative to DOLFIN release 0 1 0 The following description then shows how to apply the patch to a clean version of release 0 1 0 1 Unpack the version of DOLFIN which the patch is built relative to tar zxfv dolfin 0 1 0 tar gz 2 Check that you have the patch dolfin lt identifier gt lt date gt patch and the DOLFIN directory structure in the current directory 1s dolfin 0 1 0 dolfin lt identifier gt lt date gt patch Unpack the patch file using gunzip if necessary 3 Enter the DOLFIN directory structure cd dolfin 0 1 0 107 DOLFIN User Manual Hoffman Jansson Logg Wells 4 Apply the patch patch p1 lt dolfin lt identifier gt lt date gt patch The option p1 strips the leading directory from the filename references in the patch to match the fact that we are applying the patch from inside the directory Another useful option to patch is dry run whi
72. ty with Dirichlet and homogeneous Neumann boundary conditions 82 DOLFIN User Manual Hoffman Jansson Logg Wells u x X vu 0 inQ b V o f m0 o Ee u E Vu Vu Ee Atr e I 2pe v 0 v u 0 u ino u gp onl x 0 T pu 0 onT x 0 T The variational form fo twdz fo olu je v fwdz Vw 12 4 The time integration is done using dG 0 backward Euler The mass matrix appearing from Jo vwdz is lumped equivalent to computing it using nodal quadrature 12 4 1 Usage Present API of solver and give an example 12 4 2 Performance Write something about the performance of the solver 12 4 3 Limitations Write something about the limitations of the solver 83 Bibliography 10 11 12 13 14 Cygwin 2005 http cygwin com GiD 2005 http gid cimne upc es Hypre 2005 http acts nersc gov hypre MATLAB 2005 http www mathworks com MayaVi 2005 http mayavi sourceforge net MEncoder 2005 http www mplayerhq hu Octave 2005 http www octave org Open Inventor 2005 http http oss sgi com projects inventor OpenDX 2005 http www opendx org Para View 2005 http www paraview org Portable extensible toolkit for scientific computation petsc 2005 http www unix mcs anl gov petsc petsc 2 Tecplot 2005 http www tecplot com The Visualization Toolkit VTK 2005 http www vtk org J BEY Tetra
73. ult b Ax For more advanced operations a pointer to the PETSc matrix and vector is accessed by mat and vec respectively 3 2 Matrix free matrices The DOLFIN class VirtualMatrix represents a matrix free matrix of di mension M x M The matrix free matrix is a simple wrapper for a PETSc shell matrix The interface is intentionally simple and for advanced usage the PETSc Mat pointer is accessed by the function mat The class VirtualMatrix enables the use of Krylov subspace methods for linear systems Ax b without having to explicitly store the matrix A All that is needed is that the user defined VirtualMatrix implements multi plication with vectors Note that the multiplication operator needs to be defined in terms of PETSc data structures Vec since it will be called from PETSc DOLFIN User Manual Hoffman Jansson Logg Wells 3 3 Linear solvers A general interface to all linear solvers for systems of the form Ax b is provided through the class LinearSolver In particular wrappers for a direct LU solver and an iterative Krylov GMRES solver are implemented in the classes LU and GMRES To solve the linear system Ax b using GMRES in DOLFIN simply write Vec x GMRES solver solver solve A x b DOLFIN also provides a wrapper for an eigenvalue solver in PETSc The following code computes the eigenvalues of the matrix A Vector er ec EigenvalueSolver esolver esolver eigen A er ec The real
74. under Cygwin the Cygwin development tools must be in stalled Instructions for installing PETSc under Cygwin can be found on the PETSc web page Installation of FFC and FIAT is the same as under GNU Linux The Python package Numeric is not available as a Cygwin package and must be installed manually To compile DOLFIN the Cygwin package 1ibxm12 devel must be installed DOLFIN does not link correctly with the curses libraries of Cygwin so under Cygwin DOLFIN can be built configure disable curses make ion If MPI has not been installed configure disable mpi disable curses make Due to problems with the latest GCC compilers provided by Cygwin GCC 3 4 4 compiling DOLFIN will lead to fatal errors These problems can be avoided by using GCC version 3 3 3 provided by Cygwin 103 Appendix C Contributing code If you have created a new module fixed a bug somewhere or have made a small change which you want to contribute to DOLFIN then the best way to do so is to send us your contribution in the form of a patch A patch is a file which describes how to transform a file or directory structure into another The patch is built by comparing a version which both parties have against the modified version which only you have C 1 Creating a patch The tool used to create a patch is called diff and the tool used to apply the patch is called patch These tools are free software and are standard on most Unix systems

DOLFIN User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents