sdcquad.py

"""PyPFASST SDC quadrature matrix generation routines.

Compute the integration matrix for 9 Gauss-Lobatto nodes::

  >>> nodes, mask = sdcquad.nodes('GL', 9)
  >>> smat = sdcquad.smat(nodes, mask)

Compute the integration matrix for the 5 nodes corresponding to a
refinement of 9 Gauss-Lobatto nodes::

  >>> nodes, mask = sdcquad.nodes('GL', 9, refine=2)
  >>> smat = sdcquad.smat(nodes, mask)

"""

# Copyright (c) 2011, Matthew Emmett.  All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
#
#   1. Redistributions of source code must retain the above copyright
#      notice, this list of conditions and the following disclaimer.
#
#   2. Redistributions in binary form must reproduce the above
#      copyright notice, this list of conditions and the following
#      disclaimer in the documentation and/or other materials provided
#      with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
# COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.


import numpy as np
import sympy
import sympy.mpmath as mpmath


################################################################################
# polynomial generator, roots etc


def legendre_poly(n):
  """Return Legendre polynomial :math:`P_n(x)`.

  :param n: polynomial degree
  """

  x = sympy.var('x')
  p = (1.0*x**2 - 1.0)**n

  top = p.diff(x, n)
  bot = 2**n * 1.0*sympy.factorial(n)

  return (top / bot).as_poly()


def find_roots(p):
  """Return a list of the roots of the polynomial *p*."""

  return sorted(p.nroots(n=100))


def map_to_zero_one(roots):
  """Map roots in [-1,1] to [0,1]."""

  return sorted(set([mpmath.mpf('0.5') + r/mpmath.mpf('2.0') for r in roots]))


################################################################################
# quadrature points

def gauss_legendre_nodes(n):
  """Return Gauss-Legendre nodes.

  Before mapping to [0,1], the nodes are: roots of :math:`P_n(x)`.
  """

  p = legendre_poly(n)
  r = find_roots(p)

  return map_to_zero_one(r)


def gauss_lobatto_nodes(n):
  """Return Gauss-Lobatto nodes.

  Before mapping to [0,1], the nodes are: roots of :math:`P'_{n-1}(x)`
  and -1, 1.
  """

  x = sympy.var('x')
  p = legendre_poly(n-1).diff(x)
  r = find_roots(p)
  r = [mpmath.mpf('-1.0'), mpmath.mpf('1.0')] + r

  return map_to_zero_one(r)


def gauss_radau_nodes(n):
  """Return Gauss-Radau nodes.

  Before mapping to [0,1], the nodes are: -1 times the roots of
  :math:`P_n(x) + P_{n-1}(x)`.
  """

  if n == 1:
    r = [ 1.0 ]
  else:
    p = legendre_poly(n) + legendre_poly(n-1)
    r = find_roots(p)
    r = [ -1.0*x for x in r ]

  return map_to_zero_one(r)


def clenshaw_curtis_nodes(n):
  """Return Clenshaw-Curtis nodes."""

  r = set()
  for i in range(n):
    r.add(mpmath.cos(i*mpmath.pi/mpmath.mpf(n-1)))

  return map_to_zero_one(r)


def uniform_nodes(n):
  """Return uniform nodes."""

  r = set()
  for i in range(n):
    r.add(mpmath.mpf('-1.0') + i * mpmath.mpf('2.0')/(n-1))

  return map_to_zero_one(r)


################################################################################
# integration matrices

def smat(nodes, mask):
  r"""Return the node-to-node integration matrix :math:`S` for the
  given set of nodes.

  :param nodes: list of nodes
  :param mask:  boolean mask array to determine which nodes are proper nodes

  The integration matrix :math:`S` is generated by integrating
  polynomial interpolants between nodes.

  The action of the integration matrix :math:`S` is as follows: given
  :math:`F = \bigl( f(t_0) \ldots f(t_{M-1}) \bigr)^T` then

  .. math::

    \bigl( S F \bigr)_i \approx \int_{t_{i-1}}^{t_{i}} f(\tau) \,d\tau.

  """

  x = sympy.var('x')

  inodes = [ i for i in range(len(nodes)) if mask[i] ]
  nnodes = len(inodes)

  nsnodes = len(nodes)
  matrix  = np.zeros((nsnodes-1,nsnodes), dtype=np.object)

  if nnodes == 1:

    matrix[0,1] = 1.0

  else:

    for i in inodes:
      # construct polynomial p(x)
      p = 1
      ks = list(inodes)
      ks.remove(i)
      for k in ks:
        p = p * (x - nodes[k])
      p = p.as_poly()
      P = p.integrate(x)

      # define integral(a, b) = \int_a^b p(x) dx
      integral = lambda a, b: P.subs(x, b).evalf(100) - P.subs(x, a).evalf(100)
      norm     = p.eval(x, nodes[i]).evalf(100)

      # compute matrix elements
      for j in range(1, nsnodes):
        matrix[j-1, i] = integral(nodes[j-1], nodes[j]) / norm

  return matrix


def qmat(nodes, mask):
  r"""Return the 0-to-node integration matrix :math:`Q` for the given
  set of nodes.

  :param nodes: list of nodes
  :param mask:  boolean mask array to determine which nodes are proper nodes

  The integration matrix :math:`Q` is generated by integrating
  polynomial interpolants from 0 to each node.

  The action of the integration matrix :math:`Q` is as follows: given
  :math:`F = \bigl( f(t_0) \ldots f(t_{M-1}) \bigr)^T` then

  .. math::

    \bigl( Q F \bigr)_i \approx \int_{t_{0}}^{t_{i}} f(\tau) \,d\tau.

  """

  x = sympy.var('x')

  inodes = [ i for i in range(len(nodes)) if mask[i] ]
  nnodes = len(inodes)

  nsnodes = len(nodes)
  matrix  = np.zeros((nsnodes-1,nsnodes), dtype=np.object)

  if nnodes == 1:

    matrix[0,1] = 1.0

  else:

    for i in inodes:
      # construct polynomial p(x)
      p = 1
      ks = list(inodes)
      ks.remove(i)
      for k in ks:
        p = p * (x - nodes[k])
      p = p.as_poly()
      P = p.integrate(x)

      # define integral(a, b) = \int_0^b p(x) dx
      integral = lambda a, b: P.subs(x, b).evalf(100) - P.subs(x, 0).evalf(100)
      norm     = p.eval(x, nodes[i]).evalf(100)

      # compute matrix elements
      for j in range(1, nsnodes):
        matrix[j-1, i] = integral(nodes[j-1], nodes[j]) / norm

  return matrix


def nodes(qtype, nnodes, refine=1):
  """Return SDC nodes (mpmath).

  :param qtype:  type of quadrature
  :param nnodes: number of nodes (including the left endpoint
                 regardless of *qtype*)
  :param refine: refinement factor

  Valid quadrature types are:

  * 'G'  - Gauss-Legendre
  * 'U'  - Uniform
  * 'GL' - Gauss-Lobatto
  * 'CC' - Clenshaw-Curtis
  * 'GR' - Gauss-Radau

  :returns: tuple (*nodes*, *left*)

  The returned list of nodes *nodes* always includes the left endpoint
  0.0.  The returned flag *left* indicates whether the left endpoint
  is considered a proper SDC node or not.

  """

  if qtype == 'G':
    nodes = gauss_legendre_nodes(nnodes-2)
  elif qtype == 'U':
    nodes = uniform_nodes(nnodes)
  elif qtype == 'GL':
    nodes = gauss_lobatto_nodes(nnodes)
  elif qtype == 'GR':
    nodes = gauss_radau_nodes(nnodes-1)
  elif qtype == 'CC':
    nodes = clenshaw_curtis_nodes(nnodes)
  else:
    raise ValueError, ('Quadrature type "%s" not understood.' +
                       '  Valid types are "G", "U", "GL", "CC", or "GR".')

  mask = len(nodes) * [ True ]

  if nodes[0] > 0.0:
    nodes.insert(0, 0.0)
    mask.insert(0, False)

  if nodes[-1] < 1.0:
    nodes.append(1.0)
    mask.append(False)

  nodes = np.array(nodes, dtype=np.object)

  return nodes[::refine], mask[::refine]