Beta release!
Please note that the library has not been "officially" released.
While we continue to work on the documentation, these web pages
are likely to contain broken links and documents in draft form.
Please send an email to
oomph-lib AT maths DOT man DOT ac DOT uk
if you wish to be informed of the library's "official" release.
|
Frequently Asked Questions
Here are some frequently asked questions (with assorted frequently given answers...). Please check these before contacting us with any problems.
- Compiler flags/options for the compilation of the library
By default, oomph-lib's installation is performed with the gcc compiler suite, using full optimisation and warning (-O6 -Wall ).
If you install the library with the autogen.sh script you are given the option to overwrite the default compilation flags, either by specifying alternative flags on the command line, or by recycling any of the previously used combinations of flags, stored in the directory config/configure_options. The files in this directory also contain more details on available flags and options.
If you prefer the standard linux configure/make/make install installation procedure, you should already know how to specify flags at the configure stage...
- Compiler flags/options for the compilation of individual (driver) codes
Within the autotools framework, additional flags for the compilation of individual (driver) codes may be specified by setting the appropriate automake variables in the Makefile.am. For instance, to use the compiler flag -DUSE_TAYLOR_HOOD during the compilation of the executable test_code, add test_code_CXXFLAGS = -DUSE_TAYLOR_HOOD
Makefile.am. The C++ section of the automake manual provides more detail on other automake variables.
If you link against oomph-lib from outside the autotools framework, you can, of course, use whatever technique you prefer to customise the compilation of your driver code.
oomph-lib is developed in a GNU Linux enviroment, using the gcc compiler suite. We believe (!) the source code complies with the C++ standard and it compiles cleanly under the gcc compilers that we have access to (version 3.2.3 and later). Some warning messages tend to be issued during the compilation of the third-party libraries distributed with oomph-lib, but these are not our responsibility!
We occasionally compile (or get other people to compile) the library under other compilers and we generally try to rectify any problems that are flagged up in the process. If you encounter any problems (errors or warning messages) while compiling the library with your own (non-gcc) compiler we would like to hear from you, especially if you suggest concrete bug fixes.
There are problems with version 7 of the intel compiler suite but the library compiles cleanly under version 9. We suggest you upgrade to that if you wish to use the intel compilers.
Here are a few things to check:
- Make sure the gcc compiler suite is sufficiently up-to-date (we recommend version 3.2.3 or later).
- The build process will fail if you have (foolishly!) chosen a windows username that contains spaces. The build script (executed under linux) makes frequent references to the (absolute!) path to the
oomph-lib installation directory. Linux does not allow spaces in directory names!
Here are some general guidelines for installing under OSX, contributed by Rich Hewitt:
- Make sure you have installed the development tools from the OSX install DVDs. If your install media is fairly old, you may wish to look for an updated online version at:
http://developer.apple.com/tools/xcode/
You do not need to use the Xcode IDE, but we do need the associated development kit tools (in particular GCC!)
- Install a FORTRAN compiler. Apple does not ship a FORTRAN version, so the easiest way to do this is to install the relevant pre-packaged GNU FORTRAN from here:
http://hpc.sourceforge.net/
(I would recommend sticking with the version of GCC4 provided by Apple.)
- Make sure the FORTRAN compiler ('gfortran' in the packages pointed to above) is in the installing user's path.
- Follow the oomph-lib install procedure as normal.
- For associated Unix-goodness (doxygen, gnuplot, subversion etc), I would recommend using a ports mechanism to install any additional unix tools painlessly:
http://trac.macosforge.org/projects/macports/wiki
For example: "sudo port install gnuplot" etc.
As discussed in the installation instructions, Darwin (the BSD-derived UNIX core of Apple's OSX operating system) requires a slight change to the default procedure for linking against oomph-lib from outside its autotools framework. As a result, the linking self-test tends to fail on machines with this operating system. Instructions on how to fix this problem are provided in installation instructions.
Tolerance of comparison between floating point numbers
The full oomph-lib distribution contains a large number of demo codes in the sub-directory demo_drivers. Primarily, these codes serve as demo codes for the oomph-lib documentation (contained in the sub-directory doc) but they are also used during the library's self-test procedure which checks that oomph-lib was installed correctly. The self-tests can either be initiated at the end of the autogen.sh - based installation or by typing
in oomph-lib's top-level directory. The self-test builds and runs all demo codes and compares their results against the reference data stored in the validata sub-directories. The comparison is performed with the python script bin/fpdiff.py which tolerates small (machine- and compiler-dependent) roundoff errors and suppresses the comparison of numbers whose absolute value falls below some threshold (to avoid the comparison of numerical zeroes).
If any of the self-test fail, you should first check the output in the file validation.log to assess if the differences between the computed data and the reference data are significant. If the discrepancy appears to be due to larger-than-anticipated round-off errors (you'll have to judge this yourself!), modify the validate.sh script to specify a larger relative tolerance and/or a larger value for the threshold below which fpdiff.py regards numbers as numerical zeroes and excluses them from the comparison. [Type
in oomph-lib's top-level directory for instructions on how to use the script].
The self-test fails even though the output files produced by the code are correct
This is an odd error that is usually caused by the use of wildcards in the validations scripts, or the comparison of data that is stored in certain STL containers. Typically, the self-test is performed by the validate.sh shell script, which runs the executable and concatenates selected output files to a single file whose contents are compared against the reference file in the validata directory.
While it is tempting to write
cat RESLT* /soln0.dat > results_file.dat
|-- RESLT
| |-- soln0.dat
| `-- trace.dat
|-- RESLT_elastic
| |-- soln0.dat
| `-- trace.dat
cat RESLT/soln0.dat RESLT_elastic/soln0.dat > results_file.dat
cat RESLT_elastic/soln0.dat RESLT/soln0.dat > results_file.dat
validate.sh scripts should therefore not contain any wildcards.
Similar problems can arise if the validation data includes data that is stored in certain STL containers such as sets. The order in which items are stored in such containers may vary from machine to machine and from compiler to compiler. If such data is to be included in a self-test the data should be sorted first, based on a user-controllable sorting criterion.
To facilitate the installation, the oomph-lib distribution includes the relevant parts of certain third-party libraries, such as SuperLU and BLAS. These "external libraries" are built and installed along with oomph-lib's own sub-libraries. To distinguish them from any already existing local versions of these libraries, their names are pre-fixed with the string oomph_.
All demo codes are automatically linked against these libraries. This is achieved by defining the variable EXTERNAL_LIBS in the configure script:
# Define "external" libraries
#----------------------------
# These are the third-party libraries distributed with oomph-lib.
# Note: If you want to link against another, already existing local
# installation of one of these libraries, edit the EXTERNAL_LIBS
# assignment below. As an example, if you want to use your own BLAS
# library, and you'd usually link against this with
#
# g++ -o my_code my_code.cc -lblas
#
# then replace "-loomph_blas" by "-lblas" below:
#
EXTERNAL_LIBS='-loomph_hsl -loomph_superlu_3.0 -loomph_metis_4.0 -loomph_arpack -loomph_lapack -loomph_flapack -loomph_blas'
If you wish to link against some other version of the library, edit the EXTERNAL_LIBS variable accordingly.
WARNING: If you work within the autotools framework, remember that the configure script is generated by autoconf, using the file configure.ac, which is itself (re-)generated whenever you run autogen.sh with the --rebuild flag. If you use the autotools, you should edit the EXTERNAL_LIBS variable in the file configure/configure.ac_scripts/start which forms one of the building blocks from which autogen.sh assembles the configure.ac file. Once you have changed the EXTERNAL_LIBS variable in configure/configure.ac_scripts/start you should (re-)run autogen.sh --rebuild in oomph-lib's top-level directory.
NEW (version 0.85) You can now use the --with-blas and --with-lapack configure flags to specify the location of your own blas and lapack libraries; see the installation tutorial for details. Equivalent flags will soon be added for the other libraries. |
Recent versions of the gcc compilers enforce the C++ standard much more rigorously than earlier versions. Unfortunately, the standard includes some rules that are so counter-intuitive that it is hard get into the habit of using them, especially if code is developed on a compiler that does not enforce the standard as rigorously.
The most frequent problem arises in classes that are derived from a templated base class. The C++ standard insists that all references to member functions (or member data) that is defined in the templated base class must be preceded by "this->" when the reference is made in the derived class. Allegedly, this is necessary to avoid ambiguities, though it is not entirely clear what this ambiguity is supposed to be... Here is a driver code that illustrates the problem.
#include<iostream>
template<unsigned TEMPLATE_PARAMETER>
class TemplatedBaseClass
{
public:
TemplatedBaseClass(){};
~TemplatedBaseClass(){};
void say_hello_world()
{
std::cout << "Hello world from base class " << std::endl;
}
};
template<unsigned TEMPLATE_PARAMETER>
class SomeDerivedClass : public virtual TemplatedBaseClass<TEMPLATE_PARAMETER>
{
public:
SomeDerivedClass(){};
virtual ~SomeDerivedClass(){};
void output_template_parameter()
{
std::cout << "My template parameter is: "
<< TEMPLATE_PARAMETER << std::endl;
#ifdef USE_BROKEN_VERSION
say_hello_world();
#else
this->say_hello_world();
#endif
}
};
int main()
{
SomeDerivedClass<2> object;
object.output_template_parameter();
}
If you compile this with sufficiently recent versions of the gcc compilers, using the flag -DUSE_BROKEN_VERSION, the compilation will fail with the following error:
broken_this_demo.cc: In member function 'void SomeDerivedClass<TEMPLATE_PARAMETER>::output_template_parameter()':
broken_this_demo.cc:55: error: there are no arguments to 'say_hello_world' that depend on a template parameter, so a declaration of 'say_hello_world' must be available
broken_this_demo.cc:55: error: (if you use '-fpermissive', G++ will accept your code, but allowing the use of an undeclared name is deprecated)
You may not only stumble across this problem in one of your own codes but it is also possible that some code in the library itself still violates this rule. This is because templated classes are only built when needed and it is conceivable that oomph-lib's suite of self-tests do not instantiate all templated classes that exist in the library. If you encounter any such problems, check if putting a "this->" in front of the function call fixes the problem. If it does, let us know!
When linking, some versions of the gcc compiler produce warnings about references to "discarded sections" being referenced. Here's an example:
/usr/bin/ld: `.gnu.linkonce.t._ZNK5oomph8QElementILj3ELj3EE14vertex_node_ptERKj' referenced in section `.rodata' of /home/mheil/version185/oomph/build/lib/libgeneric.a(Qelements.o): defined in discarded section `.gnu.linkonce.t._ZNK5oomph8QElementILj3ELj3EE14vertex_node_ptERKj' of /home/mheil/version185/oomph/build/lib/libgeneric.a(Qelements.o)
We admit to being slightly baffled by this. Other libraries seem to suffer from the same problem (google for .rodata discarded, say), but as far as we can tell no solution has ever been suggested, nor does one seem to be required. The executable works fine. Upgrade to a newer version of gcc?
Suggestions:
- Run
Problem::self_test() before solving the problem. This function performs a large number of sanity checks and reports any inconsistencies in the data structure.
- Recompile the relevant libraries with the PARANOID and RANGE_CHECKING flags set. Segmentation faults are often caused by out-of-bounds access to STL containers. Since > 95% (?) of the containers used in
oomph-lib are Vectors (oomph-lib's wrapper to the STL vector class, with optional range checking) they can easily be detected. Make sure to re-compile again with RANGE_CHECKING switched off before you start any production runs -- the run-time overheads incurred by range-checking are significant!
- Recompile the relevant libraries and your driver code with the debugging flag ("-g" for the gnu compiler suite) switched on and all optimisation disabled. Re-run the code in a debugger (
gdb or its GUI-based equivalent ddd) to (try to!) find out where the segmentation fault occured. [Careful: If the segmentation fault is caused by a pointer problem, this naive inspection can be quite misleading -- tell-tale signs are that the traceback displays a non-sensical call stack, e.g. a function being called "out of nowhere"; variables that have just been given values not existing; etc.]
Suggestions:
- Have you applied the boundary conditions correctly? Check this by looping over all nodes in your mesh and documenting the pinned-status of their nodal values, using the function
Node::is_pinned(...).
- Have you passed the required (function) pointers to the elements? Most element constructors assign default values for any physical parameters, e.g. the Reynolds number in the Navier-Stokes elements. Similarly, most source functions etc. default to zero. For instance
oomph-lib's Poisson elements solve the Laplace equation unless a function pointer to the source function is specified.
- In time-dependent problems, have you assigned suitable initial conditions? Note that, if you use elements that are based on the ALE formulation (and all time-dependent elements should be!) you must initialise the history values for the nodal positions, even if the mesh is stationary! See the discussion of
oomph-lib's timestepping procedures in the context of the unsteady heat equation for details.
- Have you implemented the relevant "action" functions, such as
Problem::actions_before_implicit_timestep() to update any time-dependent boundary conditions?
Suggestions:
oomph-lib's default solver Problem::newton_solve(...) will converge quadratically, provided
- a "good" initial guess for the solution has been assigned,
or
If the Newton solver fails to converge for a nonlinear problem, try to identify a related linear problem and use continuation to generate a sequence of good initial guesses. For instance, to solve the Navier-Stokes equations at a Reynolds number of 500, say, start by solving the problem for zero Reynolds number (in which case the problem becomes linear so that the Newton method converges in one iteration); increase the Reynolds number by 50, say, and re-solve. Repeat this procedure until the desired value of the Reynolds number is reached.
Note: oomph-lib also provides automatic continuation methods, based on Keller's arclength continuation, but at the moment, no tutorials exist for these.
- If you have tried the above and the Newton method fails to converge even for a linear version of your problem, the most likely reasons are that
- You have developed a new element and made a mistake in the implementation of the element's Jacobian matrix. To check if this is the case, comment out the function that computes the element's Jacobian matrix, i.e. the element member functions
get_jacobian(...) or fill_in_contribution_to_jacobian(...). oomph-lib will then use the default implementation of these functions in the GeneralisedElement base class to compute the Jacobian matrices by finite-differencing. The executable is likely to run more slowly since the finite-difference-based computation is unlikely to be as efficient as the customised implementation for your specific element, but if the Newton method then converges, you know where to look for your bug! You may also want to check for any un-initialised variables. They are the most likely culprits if your code behaves differently at different levels of optimisation as more agressive optimisation may suppress any default initialisations of data -- in fact, you should never rely on that anyway!
- Your problem contains "enslaved" variables, such as the nodal positions in a free-boundary problem. If the node update in response to changes in the shape of the domain boundary is performed by an algebraic node update procedure (using
AlgebraicNodes, SpineNodes or nodes whose position is updated by a MacroElement/Domain - based procedure), the position of the nodes in the "bulk" mesh must be updated whenever the Newton method updates the unknowns. This is most easily done by calling Mesh::node_update() in Problem::actions_before_newton_convergence_check().
oomph-lib's high-level post-processing routines output the results of the computations in a form that is suitable for display with tecplot, a powerful commercial plotting package. Purists may find it odd that an open-source library should choose an output format that is customised for a commercial software package. We tend to agree... Our only excuse is that tecplot is very very good, and without it we would have found it extremely difficult to create many of the plots shown in the tutorials. [If you know of any open-source plotting package whose capabilities are comparable to those of tecplot, let us know!]
Angelo Simone has written a python script that converts oomph-lib's output to the vtu format that can be read by paraview, an open-source 3D plotting package. The conversion script can currently deal with output from meshes that are composed of 2D quad elements -- the extension to 3D is work in progress. Use of the conversion script is documented in another tutorial.
It is possible to display oomph-lib's default output (in more elementary form, obviously) with gnuplot. The trick is to specify the using option in gnuplot's plot commands -- in this mode gnuplot ignores tecplot's "ZONE" commands. For instance, trying to plot the x-y data created by the demo code for the solution of the 1D Poisson equation with
will fail because gnuplot gets confused by the ZONE specifications required by tecplot. However, plot "RESLT/soln0.dat" using 1:2
If the data is too complex to be displayed by gnuplot, you may wish to customise the output for your preferred plotting package. This is easily done as oomph-lib creates its output element-by-element. The elements' various output(...) functions are virtual functions that can easily be overloaded in a user-defined wrapper class.
Here is an example driver code that illustrates how to change the output from oomph-lib's QPoissonElement family of 1D-line/2D-quad/3D-brick Poisson elements so that they output the string "Hello world".
We include oomph-lib's generic and poisson library headers:
#include "generic.h"
#include "poisson.h"
and then create a customised version of the Poisson elements in which we overload the tecplot-based QPoissonElement<DIM,NNODE_1D>::output(...) function, defined in the poisson library:
namespace oomph
{
template<unsigned DIM, unsigned NNODE_1D>
class CustomisedQPoissonElement : public virtual QPoissonElement<DIM,NNODE_1D>
{
public:
CustomisedQPoissonElement(){};
~CustomisedQPoissonElement(){};
void output(std::ostream& output_file)
{
output_file << "Hello world" << std::endl;
}
};
}
If we now call the output function, the version defined in the customised element is used. The remaining implementation of the Poisson element remains unchanged.
int main()
{
using namespace oomph;
CustomisedQPoissonElement<2,2> element;
element.output(std::cout);
}
Many of oomph-lib's equations classes (or elements) are implemented in great generality. For instance, our discretisation of the Navier-Stokes equations includes a source term in the continuity equation, and body force terms in the momentum equations; it allows switching between the stress-divergence and simplified forms of the viscous terms; it includes the mesh velocity into the ALE formulation of the time-derivatives; etc. This makes the elements very versatile and robust. However, the generality/robustness comes at a price: Even though we provide default values for most functions (e.g. the body force terms default to zero), their evaluation requires a finite amount of CPU time. If you wish to use the elements in a simple application in which the Navier-Stokes equations are solved in a fixed domain, without any body forces or other source terms, say, you may wish to disable the additional functionality.
This is easily done: After all, oomph-lib is open-source software and you can therefore change anything you want! In principle, you could edit the source code in the src/navier_stokes directory and delete (or at least comment out) all the functionality that you do not require. However, this is probably a risky step as it will break all demo codes (used during oomph-lib's self-test procedure) that use some of the features that you are not interested in. We therefore recommend copying the content of the directory src/navier_stokes into a new directory, e.g. user_src/my_navier_stokes and to edit the copied sources. Follow the instructions on the oomph-lib installation page to turn these sources into a separate library against which you can link.
Yes, oomph-lib does contain a lot of code and a lot of documentation. How to get started obviously depends on your background: Are you familiar with the finite element method? How good is your knowledge of C++? Etc.
Here are some possible "routemaps" around the library:
- You are familiar with the finite element method and have a fairly good knowledge of C++
- Have a look through the list of example codes to get a feeling for
oomph-lib's capabilities. Pick a problem that interests you and study the associated tutorial. Copy the driver code into your own directory and play with it.
- Once you have played with a few example codes, you may wish to to learn more about
oomph-lib's overall data structure, or find out how to optimise the library for your particicular application.
- You have never used finite element methods but have a fairly good knowledge of C++
- Study the "Top Down" introduction. This document includes a "low tech" overview of the mathematical/theoretical background and contrasts procedural implementations of the finite element method with the object-oriented approach adopted in
oomph-lib.
- Consult the (Not-So-)Quick-Guide to learn how to construct basic
oomph-lib objects for your problem: Problems, Meshes, FiniteElements, etc.
- Continue with the steps suggested above.
- You have never used finite element methods and are a newcomer to C++
- Buy Daoqi Yang brilliant book C++ and Object-Oriented Numeric Computing for Scientists and Engineers. Read it! Pretty much everything in this book is relevant for some parts of
oomph-lib. You should at least understand:
- The procedural aspects of C++ (basic types, functions and control structures).
- Namespaces.
- Classes (private, protected and public members; inheritance and multiple inheritance; virtual and pure virtual functions; base classes and derived classes; static and dynamic casts).
- Templates and template instantiations.
- The standard template library (STL).
- Continue with the steps suggested above.
Assume you have studied one of the example codes and wish to find out more about the implementation of a particular class or function that is used there. How do you find its source code and/or its full documentation?
Generally, a class/function that is used in a demo code can only be defined in one of two places:
- In the demo driver code itself.
- In an included file and/or an associated library.
oomph-lib's tutorials tend to provide a fairly complete annotated listing of the relevant driver codes; if the function you are interested in is not mentioned explicitly in the tutorial, it is most likely to be defined in an include file. You can inspect the driver code in its entirety by following the link at the end of the tutorials. If you cannot find the class/function there, it must be defined in one of the include files listed at the beginning of the source code.
The included files themselves can either be located in the same directory as the demo driver (the directory also tends to be mentioned at the end of the tutorial) or in one of oomph-lib's sub-libraries. The source code for these is located in the sub-directories of the src directory. Often the class/function is defined in a source file with an "obvious" name; if not, use grep to find it. This can, of course, be done recursively. For instance, the command
find . \( -name '*.h' -o -name '*.cc' \) -exec grep -H FiniteElement {} \;
issued in oomph-lib's top-level directory will search through the entire distribution to locate files that contain the string "FiniteElement".
You can also use the html-based representation of oomph-lib's data structure, created by doxygen, in the "bottom-up" discussion of the data structure. (Note that the search menu may not work on your browser.)
If all else fails and you think you have found a bug in the library, make sure you follow these steps:
- Isolate the problem: Try to identify the shortest driver code that still produces the problem.
- Double-check the relevant documentation, the installation instructions and the other FAQs listed here.
- Does the problem persist when you compile the library and your test code without optimisation, and when the
RANGE_CHECKING and PARANOID flags are set?
- Does the problem occur with a sufficiently recent version of the gcc compiler suite (version 3.2.3 and later)?
- If the above steps identify the problem, let us know, ideally with a bug fix!
- If you can't fix the problem yourself, get in touch either directly, or via our bugzilla-based bug-and-feature-tracking system, accessible online at
http://oomph-lib.maths.man.ac.uk/bugzilla
and provide as much information as possible (clear description of the problem; the source code; the Makefile; details of the compiler and compilation flags used; any warning/error messages that are displayed during the compilation of the library or the driver code itself; etc.)
A pdf version of this document is available.
Generated on Mon Aug 10 11:18:34 2009 by
1.4.7
