
   ***************************************************************************
   * 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:

       Alexey Chernov, University of Bonn, Germany (corresponding author)
       Current affiliation: University of Oldenburg, Germany
       Email: alexey.chernov@uni-oldenburg.de

       Christoph Schwab, ETH Zurich, Switzerland
       Email: schwab@sam.math.ethz.ch

       Tobias von Petersdorff, University of Maryland, College Park, USA
       Email: tvp@math.umd.edu

   REFERENCE:

       Quadrature algorithms for high dimensional singular integrands on simplices,
       NUMERICAL ALGORITHMS, 70 (2015), pp. 847-874

   SOFTWARE REVISION DATE:

       V1.2, February 2 2015

   SOFTWARE LANGUAGE:

       MATLAB 7.9 (R2009b)

=================================================================================
SOFTWARE
=================================================================================

This package contains a set of MATLAB functions to compute approximately the
value of a singular integrand of the the form

I = \int_S1 \int_S2 f(x,y) dx dy

where S1 and S2 are two simplices from a regular Finite Element mesh in d dimensions
and f(x,y) has an integrable singularity when x = y. The quadrature algorithm is
based on a general desingularizing coordinate transformation simplifying
simultaneously the structure of the singularity and the integration domain. After
transformation, the integrand becomes singular in the first coordinate direction
and regular in the other whereas the integration domain becomes a unit cube.
The transformation consists of building a suitable quadrature in the reference
cube and transforming it back to the physical domain S1xS2. For that, the steps of
the coordinate transformation are performed in a bottom-up way (step 8, step 7,...,
step 1).

This package contains full implementation for three types of quadrature rules which
are distinguished by different combination of singular (in the first coordinate
direction) and regular (in the other coordinate directions) one-dimensional
quadrature rules:

1) composite Gauss-Legendre / Gauss-Legendre (CGL-GL)
2)           Gauss-Jacobi   / Gauss-Legendre ( GJ-GL)
3)           Gauss-Jacobi   / Gauss-Jacobi   ( GJ-GJ)

See the help page of each function for the calling syntax.

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

Description of the files:

README.txt    :   this file

eval_ssquad.m : manages computation and evaluation of the total quadrature

subquad.m     :   realizes Steps 8,7,6 of the algorithm for the case where
                  monomial weights in regular directions are not incorporated in quadrature
                  weights (as e.g. for Gauss-Legendre quadrature in regular directions)

subquadw.m    :   realizes Steps 8,7,6 of the algorithm for the case
                  where monomial weights in regular directions are incorporated in quadrature
                  weights (i.e. for Gauss-Jacobi quadrature in regular directions)

ssquadtrf.m   :   realizes Steps 5,4,3 of the algorithm for the case where
                  monomial weights in regular directions are not incorporated in quadrature
                  weights (as e.g. for Gauss-Legendre quadrature in regular directions)

ssquadtrfw.m  :   realizes Steps 5,4,3 of the algorithm for the case
                  where monomial weights in regular directions are incorporated in quadrature
                  weights (i.e. for Gauss-Jacobi quadrature in regular directions)

quad2rfs.m    :   realizes Step 2 of the algorithm (transformation to the reference simplex)

quad2phs.m    :   realizes Step 1 of the algorithm (transformation to the physical simplex)

quadrc.m      :   initializes various types of quadrature rules on the reference cube

c2s.m         :   transforms a quadrature rule from the unit cube to the unit simplex

cglquad.m     :   implementation of the composite Gauss-Legendre quadrature rule

glquad.m      :   implementation of the Gauss-Legendre quadrature rule

gjquad.m      :   implementation of the Gauss-Jacobi quadrature rule

gjquadrs.m    :   realizes a tensorized Gauss-Jacobi quadrature on the reference simplex

tensquad.m    :   realizes the product of two quadrature rules

nextperm.m    :   this routine generates the next permutation in the lexicographic order

cpscube.m     :   realizes Step 8 of the algorithm

test/                 :   a directory containing the scripts for numerical experiments

test/demoXXXXXX.m     :   Demonstration scripts containing predefined test examples. These scripts may
                          be run from the MATLAB command line without input parameters. Refer to
                          particular files for the precise description.

test/ssquad_mgr.m     :   This routine manages evaluation of the numerical quadrature of the
                          isotropic singularity ||z||^alpha, alpha = -2*d+k+1/pi where d is the space
                          dimension and k is the dimension of the intersection. The user may change the
                          integrand function by implementing new func_id in this routine. This routine
                          sets up the computation parameters, calls eval_ssquad for evaluation of
                          the quadrature and generates the output.

test/initvert.m       :   this file contains predefined coordinates of the simplices

test/outputXXXX.m     :   contains output (new output overwrites the existing)

test/outputXXXX_ori.m :   contains output of corresponding demonstration scripts test/demoXXXXXX.m

test/log.txt          :   contains logs (new logs will be appended)

test/log_ori.txt      :   contains logs of the demonstration scripts test/demoXXXXXX.m
                          executed in the following order:
                          demod3k0.m
                          demod3k1.m
                          demod3k2.m
                          demod3k3.m
                          demod3kminus1.m
                          demod4k0.m
                          demod4k1.m
                          demod4k2.m
                          demod4k3.m
                          demod4k4.m
                          demod4kminus1.m


=================================================================================
HOW TO INSTALL
=================================================================================

When the archive file containing the package is uncompressed, it creates a directory
named ssquad. The user must change the current directory to ssquad/test to run the
predefined examples.

=================================================================================
NUMERICAL TESTS
=================================================================================

The directory ssquad/test contains some scripts which perform the numerical
experiments described in the paper. Eleven predefined examples are named as

demoXXXXXX.m

and realized numerical tests from the article "Quadrature algorithms for high
dimensional singular integrands on simplices", Section 5.

Output is written in text files named

outputXXXXXXXX

The log on performed computations is written (appended) to the file log.txt

=================================================================================
HOW TO BUILD NEW TEST EXAMPLES
=================================================================================

The user can modify existing numerical examples in the following ways:

i) Change the integrand function
ii) Change the integration domain (two simplices)
iii) Change the quadrature rule

The details are summarized below. In this description and in the code
the following parameters are used:

d is the space dimension
k is the dimension of the intersection of two simplices, so that
k=-1 means distant simplices
k=0  means two simplices sharing a vertex
k=1  means two simplices sharing an edge
...
k=d  means two identical simplices

i) Change the integrand function

The integrand function can be modified by the user by implementing new
func_id in the routine ssquad_mgr.m.

ii) Change the integration domain (two simplices)

The integration domain can be modified by the user by implementing new
domain_id in the routine test/initvert.m. Two simplices S1 and S2 are defined by
specifying their vertices in the rows of the matrix vertexlist. Notice that
if the simplices share the same vertex, it should not be repeated in the
vertexlist again. Every vertexlist should contain
 - (d+1) vertices of the first simplex S1 in the first (d+1) rows of vertexlist
   NOTICE: shared vertices come at the beginning of the list,
 - (d-k) vertices of the second simplex S2 in the final (d-k) rows of vertexlist
   NOTICE: only new vertices of the second simplex should be listed here.

The parameters d and k are uniquely determined ones a correct vertexlist
is specified via

    d =         min(size(vertexlist));
    k = 2*d+1 - max(size(vertexlist));

iii) Change the quadrature rule

A new quadrature rule can be specified by the user by implementing new
quadtype_id in the routine quadrc. Currently, various combinations of
the tensor-product Gauss-Legendre, Gauss-Jacobi, and composite Gauss-Legendre
quadrature are implemented within quadtype_id = 1,2,3 and 31,32,33,34.
CAUTION: this modification should be done by an experienced user! Do not
modify this file if the functionality is not completely clear.
