Introduction
============

BEM++ is a novel open-source HPC boundary-element library. Its development
started in October 2011.

History
=======

1.1 (11 December 2012)
----------------------

New features:

- Significantly simplified the implementation of custom boundary operators:

  * Thanks to the new GeneralElementarySingularIntegralOperator class there is
    no need to declare a new subclass of ElementaryIntegralOperator for each new
    kernel.

  * The mechanism of discrete weak-form caching has been modified and is no
    longer based on a global cache indexed with identifiers of abstract boundary
    operators. As a result, implementation of the AbstractBoundaryOperator::id()
    method in new operator classes can be safely skipped, as this method is no
    longer used.

- Improved the conversion of discrete operators into the H-matrix format:

  * This functionality has been implemented for discrete operators stored as
    sparse matrices and for blocked discrete operator. This means in particular
    that a discrete operator composed of several blocks stored as separate H-
    and/or sparse matrices can now be converted into a *single* H-matrix.

  * The default values of the arguments to
    DiscreteBoundaryOperator::asDiscreteAcaBoundaryOperator() have been changed
    to reduce the chances of unintended loss of accuracy during addition of
    H-matrices.

- Added the adjoint() function returning the adjoint of a boundary operator.

- Added the transpose(), conjugate() and conjugateTranspose() functions
  returning the respective transformations of discrete boundary operators.

- Added the UnitSpace class, representing the space consisting of the single
  function equal to 1 everywhere. This class is useful in the solution of
  Neumann problems.

- Added the estimateL2Error() function, which can be used to calculate
  accurately the L^2 norm of the difference between a numerical and analytical
  solution of a problem.

- GridFunction objects are now able to calculate their projections on any dual
  space, specified by a new parameter of the GridFunction::projections() method.
  For compatibility, it remains possible to fix the dual space during
  construction of a GridFunction and to call projections() without arguments.

- The quadrature order for single regular integrals specified with
  AccuracyOptions is now used during the discretisation of functions into
  GridFunction objects (previously it was only used during potential
  evaluation).

This version maintains source-level (but not binary-level) backward
compatibility with versions 1.0.x.

1.0.2 (12 November 2012)
------------------------

A maintenance release fixing a few minor bugs in BEM++. It contains a workaround
for a suspected compiler bug in llvm-gcc on MacOS X 10.7 in 64-bit mode and
adds support for GCC 4.7.

1.0.1 (3 November 2012)
-----------------------

A maintenance release correcting two bugs in the AHMED interface
and improving the update procedure.

1.0 (29 October 2012)
---------------------

The first official version of the library, including the following features:

- Galerkin discretization of all standard boundary integral operators
  (single-layer potential, double-layer potential, adjoint double-layer
  potential, hypersingular operator) for Laplace, Helmholtz and modified
  Helmholtz problems in three dimensions.

- Numerical evaluation of boundary-element integrals (singular integrals dealt
  with using Sauter-Schwab quadrature rules).

- Triangular surface mesh handling. Import of meshes in Gmsh format.

- Piecewise constant and continuous piecewise linear basis functions.

- Dense-matrix representation of boundary integral operators supported natively.

- Assembly of H-matrix representations of boundary integral operators via
  adaptive cross approximation (ACA) supported thanks to an interface to
  M. Bebendorf’s AHMED library.

- H-matrix-based preconditioners (via AHMED).

- Easy creation of operators composed of several logical blocks.

- Interfaces to iterative linear solvers from Trilinos.

- Evaluation of potentials in space (away from the discretized surface).

- Export of solutions in VTK format.

- Parallel operation on shared-memory CPU architectures.

- C++ and Python interfaces.

Obtaining the code
==================

The code is available from https://github.com/bempp/bempp.

To download the code, you need to have the Git version control system
(http://git-scm.com) installed. To get the (stable) version 1.0 of the library,
execute ``git clone -b release_1.0 git://github.com/bempp/bempp.git`` from the
command line in an empty directory. To download the current development version,
execute ``git clone git://github.com/bempp/bempp.git`` instead.

Installation
============

To build and install the library, you need

- a recent version of Python 2 (2.6 or newer; we recommend using the Enthought
  Python Distribution, http://www.enthought.com/products/epd.php)

- a modern C++ compiler

- a Fortran compiler (required by Dune, one of the BEM++ dependencies)

- a BLAS and LAPACK implementation (IMPORTANT: read the information in the
  "Location of BLAS and LAPACK" paragraph below)

- (optional) sources of the AHMED library for H-matrix calculations; you can
  download them from ``http://bebendorf.ins.uni-bonn.de/AHMED.html``

- (optional) the Python Mayavi module, if you want to use the visualization
  features from the Python interface to BEM++.

The library has been tested under Scientific Linux 6.1, Ubuntu 12.04,
OpenSUSE 12.1 and Mac OS 10.7.

The build system used to compile BEM++ (CMake) and the remaining dependencies of
the library (currently Armadillo, Boost, Dune, Intel TBB, Swig and Trilinos)
are automatically downloaded and compiled by the installer. You need at least
2.5 GB of free space to build the library and all its dependencies; however,
most of this space can be recovered after a successful installation.

To build the library, do the following:

1. Copy the file ``bempp_setup.cfg.template`` into another file
   (e.g. ``bempp_setup.cfg``) and adapt the configuration variables.

   You may wish to change at least the following options:

   - Location of BLAS and LAPACK.  You can either use MKL or manually specify
     BLAS and LAPACK libraries.  If you intend to use the Python wrappers of
     BEM++, you should link BEM++ with the same BLAS and LAPACK as the NumPy
     package.  If your NumPy is linked with MKL, as is the case with the full
     version of Enthought Python Distribution (i.e. other than EPD Free), you
     can tell the BEM++ installer to detect the location of the MKL libraries
     automatically.

     **Warning:** Many Linux distributions come with versions of BLAS and LAPACK
     built with the gfortran compiler.  Unfortunately, with its default
     compilation settings, gfortran produces non-threadsafe versions of some
     LAPACK routines (more information can be found at
     http://icl.cs.utk.edu/lapack-forum/viewtopic.php?f=2&t=1930). Linked
     against such versions of LAPACK and used in multithreaded mode, BEM++ will
     produce incorrect (random) results. Therefore you are strongly advised to
     either use LAPACK from Intel MKL, which is free from this bug, or to
     compile LAPACK yourself, including ``-fmax-stack-var-size=66560`` in the
     list of gfortran compilation options.

     **Note:** BEM++ by default uses multiple threads to assemble matrix
     representations of integral operators. To avoid performance loss due to
     nested parallelization, BLAS and LAPACK routines should therefore run in
     serial mode. For some popular BLAS and LAPACK implementations, this can be
     ensured as follows:

     - MKL: no need to do anything, BEM++ manages the number of threads
       automatically.
     - GotoBLAS and OpenBLAS: set the environmental variable OMP_NUM_THREADS to
       1 before running programs using BEM++.
     - ATLAS: number of threads is determined at compilation time. Use a serial
       version of ATLAS.

     **Take-home message:** If you do not feel comfortable with compiling LAPACK
     and NumPy on your own, and if you have access to a full version of the
     Enthought Python Distribution (i.e. other than EPD Free), we strongly
     recommend you to use it to install BEM++. In this case, you should
     uncomment the lines ``enable_mkl=yes`` and ``source=like_numpy`` in the
     ``MKL`` section of the configuration file. Note that academic users can
     obtain a full version of the Enthought Python Distribution free of charge.

   - Enable AHMED for H-matrix support. You need to uncomment
     ``enable_ahmed=yes`` and set the option ``file_name`` in the AHMED section
     to the location of the archive with AHMED source code.

2. Run the command ::

   python bempp_setup.py -b bempp_setup.cfg

   This bootstrap phase downloads the BEM++ build system (CMake) and
   all BEM++ dependencies (currently Armadillo, Boost, Dune, Swig, TBB
   and Trilinos), creates the necessary directories and compiles and
   installs CMake into the BEM++ installation directory. Note that you
   need to have write access to the installation directory.

3. Run the command ::

   python bempp_setup.py -c bempp_setup.cfg

   This extracts all BEM++ dependencies, patches their sources where
   necessary and generates a config file with automatically detected options.

4. Run the command ::

   python bempp_setup.py -i all bempp_setup.cfg

   This builds all the dependencies and installs them, and subsequently
   proceeds to building and installing BEM++ itself.

   The library will be installed into ``<prefix>/bempp/lib`` and the python
   module at ``<prefix>/bempp/python``, where ``<prefix>`` is the directory
   specified in the configuration file.  Note that the generation of the Python
   module takes rather a long time. Therefore, the installer may seem to hang
   for a few minutes without doing anything.

5. If you have Doxygen installed, you can generate documentation of the C++ API
   of BEM++ by going into ``<build_dir>`` and typing ``make doc``. The
   documentation is generated in the ``<build_dir>/doc/html`` directory. You are
   advised to use a recent version of Doxygen (e.g. 1.8.2), since older versions
   do not always parse C++ templates properly.

6. If you have Sphinx installed, you can generate documentation of the Python
   API of BEM++ by going into ``<build_dir>`` and typing ``make
   python_doc``. The documentation is generated in the
   ``<build_dir>/python/doc/html`` directory.

Updates
=======

Bugfixes to the stable version of BEM++ will be committed to the release_1.0
git branch. You can obtain the latest bugfixes by executing ::

   python bempp_setup.py -u all bempp_setup.cfg

in BEM++ source directory. This will check whether any updates are available,
and if yes, download them, recompile and install the library.

Usage
=====

As mentioned above, the ``examples`` and ``python/examples`` directories contain
a few examples demonstrating the usage of the C++ and Python interfaces to the
library. In particular, the ``tutorial_dirichlet.cpp`` and
``tutorial_dirichlet.py`` are described in detail on the BEM++ website
(``http://www.bempp.org/tutorial_dirichlet.html``). After a successful BEM++
installation, the compiled version of C++ examples are available in
``<build_dir>/examples``.

To build your own programs using BEM++, you need to add the
``<prefix>/bempp/include`` and ``<prefix>/bempp/include/bempp`` paths to the
include path of your compiler, and link to the ``bempp`` and ``teuchos``
libraries installed in ``<prefix>/bempp/lib`` (the latter is a component of
Trilinos). On Linux, it is also advisable to include ``<prefix>/bempp/lib`` in
the runtime path of your executable. On a Mac, you should add
``<prefix>/bempp/lib`` to the ``DYLD_LIBRARY_PATH`` environment variable before
running your program.

A schematic GCC invocation for compiling and linking a program ``my_program``
with BEM++ on Linux looks as follows::

g++ -I <prefix>/bempp/include -I <prefix>/bempp/include/bempp my_program.cpp
-o my_program -L <prefix>/bempp/lib -lbempp -lteuchos
-Wl,-rpath,<prefix>/bempp/lib

On a Mac, you would omit ``-Wl,-rpath,<prefix>/bempp/lib``, but type ``export
DYLD_LIBRARY_PATH=${DYLD_LIBRARY_PATH}:<prefix>/bempp/lib`` before running
``my_program``.

The file ``doc/misc/CMakeLists.txt.example`` contains an example ``CMakeLists``
file that can be used to build a program employing BEM++ with CMake.

To use the Python interface to BEM++, simply put ::

import sys
sys.path.append("<prefix>/bempp/python")
import bempp.lib as blib

at the beginning of your Python script (replacing ``<prefix>`` with the path to
the BEM++ installation directory).

Contact
=======

If you run into problems with installation or usage of BEM++, please let us know
by opening an issue at https://github.com/bempp/bempp/issues.

The BEM++ Team