  ***************************************************************************
  * All the software  contained in this library  is protected by copyright. *
  * Permission  to use, copy, modify, and  distribute this software for any *
  * purpose without fee is hereby granted, provided that this entire notice *
  * is included  in all copies  of any software which is or includes a copy *
  * or modification  of this software  and in all copies  of the supporting *
  * documentation for such software.                                        *
  ***************************************************************************
  * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED *
  * WARRANTY. IN NO EVENT, NEITHER  THE AUTHORS, NOR THE PUBLISHER, NOR ANY *
  * MEMBER  OF THE EDITORIAL BOARD OF  THE JOURNAL  "NUMERICAL ALGORITHMS", *
  * NOR ITS EDITOR-IN-CHIEF, BE  LIABLE FOR ANY ERROR  IN THE SOFTWARE, ANY *
  * MISUSE  OF IT  OR ANY DAMAGE ARISING OUT OF ITS USE. THE ENTIRE RISK OF *
  * USING THE SOFTWARE LIES WITH THE PARTY DOING SO.                        *
  ***************************************************************************
  * ANY USE  OF THE SOFTWARE  CONSTITUTES  ACCEPTANCE  OF THE TERMS  OF THE *
  * ABOVE STATEMENT.                                                        *
  ***************************************************************************

   AUTHORS:

       Markus Aurada, Michael Ebner, Michael Feischl
       Thomas Fuehrer, Petra Goldenits,
       Markus Mayr, Dirk Praetorius
       Vienna University of Technology, Vienna, Austria
       E-mail: hilbert@asc.tuwien.ac.at

       Samuel Ferraz-Leite
       Max Planck Institute for Mathematics in the Sciences, Leipzig, Germany

       Michael Karkulik
       Pontificia Universidad Católica de Chile, Santiago, Chile

   REFERENCE:

    -  HILBERT - A MATLAB Implementation of Adaptive 2D-BEM
       NUMERICAL ALGORITHMS, 67 (2014), pp. 1-32

   SOFTWARE REVISION DATE:

       V1.0, May 2013

   SOFTWARE LANGUAGE:

       MATLAB 7.4 ( + ANSI-C)

=====================================================================
DESCRIPTION
=====================================================================

HILBERT is a Matlab toolbox for h-adaptive Galerkin BEM. 
Lowest-order elements for the 2D Laplacian are implemented, i.e., piecewise
constants P0 for fluxes and piecewise affine and globally continuous S1 for
traces of concentrations.
The HILBERT program package is shipped as a zipped archive, named
hilberttools.zip. After unzipping, it has the following structure:

hilberttools/
    demos/
        laplace/
        poisson/
    paper/
    source/
        make/

The MATLAB files are contained in the main directory hilberttools/,
whereas the C-files for computing the integral operators are contained 
in source/.
The folder demos/ contains various examples and demo files which
demonstrate the use of HILBERT.

The file documentation.pdf in the main directory contains a detailed
description of the HILBERT program package and its usage. The documentation
reports on the aspects of the implementation and provides mathematical
background and references. It therefore may serve as both, users and
developers handbook.

=====================================================================
PACKAGE
=====================================================================

Files without ending are executable Matlab files.

The root directory hilberttools/ contains the following files

README.txt                : This file.
documentation.pdf         : Detailed description of the program package.
buildHypsingStabilization : Stabilization matrix for the hypersingular IE.
buildK                    : Galerkin matrix corresponding to the double-layer
                            potential.
buildM                    : Assembles a mass-type matrix M.
buildN                    : Assembles Galerkin matrix corresponding to the
                            Newton potential.
buildV                    : Galerkin matrix corresponding to simple-layer
                            potential.
buildW                    : Galerkin matrix corresponding to hypersingular
                            integral operator.
evaluateK                 : Pointwise evaluation of the double-layer potential.
evaluateKadj              : Pointwise evaluation of adjoint double-layer
                            potential.
evaluateN                 : Pointwise evaluation of the Newton potential.
evaluateN1                : Pointwise evaluation of the Newton potential N1.
evaluateV                 : Pointwise evaluation of the simple-layer potential.
evaluateW                 : Pointwise evaluation of the hypersingular integral
                            operator.
computeEstHypEta          : (h-h/2)-based estimator eta for hypsing IE.
computeEstHypEtaTilde     : (h-h/2)-based estimator eta-tilde for hypsing IE. 
computeEstHypMu           : (h-h/2)-based estimator mu for hypsing IE.
computeEstHypMuTilde      : (h-h/2)-based estimator mu-tilde for hypsing IE.
computeEstHypResidual     : Weighted-residual estimator for hypsing IE.
computeEstHypTau          : (h-h/2)-based two-level estimator tau for hypsing
                            IE.
computeEstMixResidual     : Weighted-residual estimator for mixed problem.
computeEstMixTau          : (h-h/2)-based two-level estimator for mixed problem.
computeEstSlpEta          : (h-h/2)-based estimator eta for Symm's IE. 
computeEstSlpEtaTilde     : (h-h/2)-based estimator eta-tilde for Symm's IE.
computeEstSlpMu           : (h-h/2)-based estimator mu for Symm's IE.
computeEstSlpMuTilde      : (h-h/2)-based estimator mu-tilde for Symm's IE.
computeEstSlpResidual     : Weighted-residual estimator for Symm's IE.
computeEstSlpTau          : (h-h/2)-based two-level estimator tau for Symm's IE.
computeErrDirichlet       : Error between a function and S1-approximation.
computeErrNeumann         : Error between a function and P0-approximation.
computeOscDirichlet       : Computes oscillations and discrete Dirichlet data. 
computeOscDirichletL2     : Computes oscillations and discrete Dirichlet data.
computeOscMixed           : Computes oscillations and discrete data.
computeOscNeumann         : Computes oscillations and discrete Neumann data.
computeOscVolume          : Computes oscillations and discrete volume data.
buildSortedMesh           : Provides a numbering of the nodes.
generateFather2Son        : Generates Father2Son relation.
markElements              : Marks elements for refinement.
refineBoundaryMesh        : Refines a given boundary mesh.
refineMesh                : Refines a given volume mesh.
buildHypsingRHS           : Right-hand side for the hypersingular IE.
buildHypsingVolRHS        : Right hand-side for hypsing IE with volume force.
buildMixedRHS             : Right hand-side for a mixed problem.
buildMixedVolRHS          : Right-hand side for mixed problem with volume
                            force.
buildSymmRHS              : Right-hand side for Symm's integral equation.
buildSymmVolRHS           : Right-hand side for Symm's IE with volume force.
plotArclengthP0           : Plots P0-function.
plotArclengthS1           : Plots S1-function.
make                      : Builds HILBERT's operators.
Contents.m                : Contents file for Matlab.

The directory hilberttools/demos/laplace/ contains the following files:

coordinates.dat              : Coordinates of nodes for L-shaped domain.
elements.dat                 : Elements of boundary mesh for L-shaped domain.
adaptiveHypHierarchical      : Demo for hypersingular IE with tau estimator.
adaptiveHypMu                : Demo for hypsing IE with mu estimator on Lshape.
adaptiveHypMuTilde           : Demo for hypsing IE with mu-tilde estimator on
                               Lshape.
adaptiveHypResidual          : Demo for hypsing IE on Lshape with rho estimator.
adaptiveHypResidualIndirect  : Demo for hypsing IE on slit with rho estimator.
adaptiveMixedHierarchical    : Demo for the mixed problem with tau estimator.
adaptiveMixedMu              : Demo for the mixed problem with the mu error
                               estimator.
adaptiveMixedMuTilde         : Demo for the mixed problem with mu-tilde
                               estimator.
adaptiveMixedResidual        : Demo for the mixed problem with rho estimator.
adaptiveSymmHierarchical     : Demo for Symm's IE with tau estimator on Lshape.
adaptiveSymmMu               : Demo for Symm's IE with mu estimator on Lshape.
adaptiveSymmMuTilde          : Demo for Symm's IE with mu-tilde estimator on
                               Lshape.
adaptiveSymmResidual         : Demo for Symm's IE on Lshape with rho estimator.
adaptiveSymmResidualIndirect : Demo for Symm's IE on slit with rho estimator.
g                            : Provides the Dirichlet data for some homogeneous
                               Laplace problem.
parameter                    : Provides parameter for the exact solution of the
                               demos.
phi                          : Provides the Neumann data for some homogeneous
                               Laplace problem.
Contents.m                   : Contents file for Matlab.

The directory hilberttools/demos/poisson/ contains the following files:

coordinates.dat             : Coordinates of nodes for L-shaped domain.
elements.dat                : Elements of boundary mesh for L-shaped domain.
triangles.dat               : Elements of volume mesh for L-shaped domain.
adaptiveHypVolMuTilde       : Demo for hypsing IE with mu-tilde estimator. 
adaptiveHypVolResidual      : Demo for hypsing IE with rho estimator.
adaptiveMixedVolMuTilde     : Demo for the mixed problem with the mu-tilde est.
adaptiveMixedVolResidual    : Demo for the mixed problem with rho estimator.
adaptiveSymmVolHierarchical : Demo for Symms IE with volume force and tau.
adaptiveSymmVolMu           : Demo for Symms IE with volume force and mu
                              estimator.
adaptiveSymmVolMuTilde      : Demo for Symms IE with volume force and mu-tilde.
adaptiveSymmVolResidual     : Demo for Symms IE with volume force and rho est.
f                           : Volume data for some Poisson problem.
g                           : Dirichlet data for some Poisson problem.
parameters                  : Provides parameters for some poisson problem.
phi                         : Neumann data for some Poisson problem.
Contents.m                  : Contents file for Matlab.

The directory hilberttools/paper/ contains the following files:

figure2_threading  : Produces Figure 2 from paper.
figure3_symm       : Produces Figure 3 from paper.
figure4_pointerror : Produces Figure 4 from paper.
figure5_hypsing    : Produces Figure 5 from paper.
figure6_mixedVol   : Produces Figure 6 from paper.
myLegend           : Creates legend for figures.
Contents.m         : Contents file for Matlab.

All the other files shipped with the HILBERT program package are not
intended to be used directly.

=====================================================================
INSTALLATION
=====================================================================

First of all, unzip the archive. To install the package, start MATLAB and
change into the root folder of the HILBERT package. Then type 'make' at the
MATLAB command line. This will lead you to a graphical-based configuration
dialog. Under WINDOWS you are given the choice to install precompiled binaries
(with or without multithreading), which are shipped with the HILBERT program
package. In the configure menu, you can set up different options, i.e.,
activate or deactivate multithreading, number of cores (threads), Gaussian
quadrature order, compiler flags. After configuring, the compilation process
will start automatically (If it does not, type 'make' again in the command
line).

Note that the LCC compiler provided by MATLAB under WINDOWS does not
support multithreading. Therefore, HILBERT provides precompiled binaries 
for the multithreaded mex functions which should be preferred if 
multithreading is enabled. The precompiled binaries depend on Microsoft's
Visual C Redistributable package 2008 AND 2010.

HILBERT is known to compile on Mac OS X and Linux using the GNU Compiler
Collection (gcc) and on WINDOWS using Microsoft's Visual C Compiler.
Furthermore, it is known to compile on WINDOWS using MATLAB's LCC compiler,
if multithreading is disabled. You might be able to compile HILBERT using
other ANSI-C compliant compilers though.

If make fails to compile the library on your WINDOWS system, please type 
'make realclean' and 'make' and choose the (standard) configuration without 
multithreading.

After the installation process add the root directory hilberttools/ via the
MATLAB command 'addpath' to your search directory to use the functions provided
by the HILBERT package, e.g., 'addpath installationDirectory/hilberttools/'.

The 'make' command tries to start a graphical-based installer (on all
supported systems). If you have started MATLAB under Linux in a session where
no windows can be displayed (e.g., with the -nodisplay option) then 'make'
will change to a text-based modus.
Note that you can start the text-based configure system directly, if you type
'make configure-text' at the MATLAB prompt.

You can modify the source code in the source/ directory. After that, just type
'make' in the root directory hilberttools/. The make-system detects changes in
the source files automatically and will compile only the necessary parts.

The 'make' command comes along with many other options. Further information is
obtained by typing 'make help' or 'help make' at the MATLAB command line.

=====================================================================
PRECOMPILED LIBRARIES
=====================================================================

Under WINDOWS you have the possibility to install precompiled libraries with
or without enabled threading. This is the preferred option if MATLAB fails to
compile the source code on your WINDOWS machine.
See also the INSTALLATION resp. KNOWN ISSUES section for further details.

=====================================================================
TEST
=====================================================================

You may test the installation by running some examples from the demos/ folder.
These example m-files are described in the paper and in the file
documentation.pdf, which is available in the main package directory.

=====================================================================
KNOWN ISSUES
=====================================================================

(1) Make fails to compile the library under WINDOWS:

The 64-bit version of MATLAB does not ship with a compiler. If you want
to compile HILBERT yourself, you need a third-party compiler like Microsoft's
Visual C Compiler. The 32-bit version of MATLAB ships with the LCC compiler,
which, however, does not support the library HILBERT uses for parallelization.
Therefore, you need Microsoft's Visual C Compiler to compile HILBERT with
multithreading enabled.

In order to provide multithreading-enabled operators to WINDOWS users, who do
not have access to Microsoft's Visual C Compiler, HILBERT comes with
precompiled versions of all MEX functions. During the installation, you are
asked whether you would like to install these precompiled binaries.

If MATLAB displays the following error message when calling MEX functions
you are missing the Microsoft Visual C Redistributable package:
  Invalid MEX-file ...: The specific module could not be found
Please install the versions 2008 AND 2010 of Microsoft's Visual C
Redistributable package. These packages can be found at
www.microsoft.com/download or by using your favourite search engine.

If make fails to compile the library on your WINDOWS system, please type 
'make realclean' and 'make' and choose the (standard) installation without 
multithreading. If this does not work, please send an email to 
hilbert@asc.tuwien.ac.at which includes information on your WINDOWS system 
and MATLAB release as well as full error or warning statements.

=====================================================================
COMPATIBLE SYSTEM CONFIGURATIONS
=====================================================================

It is known that the HILBERT program package will work with the following
configurations:

Linux:
  Kernel 3.2.0 (64-bit) with gcc 4.6.3:
    MATLAB 7.11 (R2010b)
    MATLAB 7.14 (R2012a)
  Kernel 3.9.4 (64-bit) with gcc 4.8.0:
    MATLAB 7.11 (R2010b)

Mac OS X (10.8):
  Xcode 4.6.1:
    MATLAB 8 (R2012b)

Windows XP 32-bit:
  MATLAB 7.11 (R2010b)
    precompiled libraries (with Visual C Redistributable package 2008 and 2010)
    LCC compiler (shipped with MATLAB)
    Microsoft's Visual C Compiler (Visual Studio 2010)

Windows 7 64-bit:
  MATLAB 7.11 (R2010b)
    precompiled libraries (with Visual C Redistributable package 2008 and 2010)
    Microsoft's Visual C Compiler (Visual Studio 2010)

Note that the provided software package was tested under the above
configurations, but should also work on different configurations.
HILBERT should compile without problems using MATLAB versions >=7.4 (or even
lower) and compatible ANSI-C compilers.

=====================================================================
THIRD PARTY LIBRARIES
=====================================================================

The directory hilberttools/source/make/ext contains third party software covered
by the GNU Lesser General Public License (LGPL). The license is located in
hilberttools/source/make/ext/LICENSE.

The software used by HILBERT is pthreads-win32
(http://sourceware.org/pthreads-win32/). It is an implementation of POSIX
threads for WINDOWS. HILBERT only ships with a binary distribution of this
software and some header files that are required for compiling. If you request
the source code, you can either download it from the project's site or send a
request to the HILBERT team. A copy will be sent to you by e-mail.

The following files are covered by the LGPL:
  hilberttools/source/make/ext/lib/mexw32/pthreadVC2.dll
  hilberttools/source/make/ext/lib/mexw64/pthreadVC2.dll
  hilberttools/source/make/ext/include/pthread.h
  hilberttools/source/make/ext/include/sched.h
  hilberttools/source/make/ext/include/semaphor.h

=====================================================================
CONTACT, TROUBLE-SHOOTING, AND BUG REPORTS
=====================================================================

If you have any questions, problems, or if you unfortunately found a bug,
please contact the HILBERT-Team under hilbert@asc.tuwien.ac.at.
Additional information can also be found on the homepage
http://www.asc.tuwien.ac.at/abem/hilbert

