From 3e957a97a0691e222e6ce32b6751ac8e339eafbb Mon Sep 17 00:00:00 2001 From: Markus Neumann Date: Thu, 17 Aug 2017 14:34:53 +0200 Subject: [PATCH] finished docstrings in model_1d some more docu --- .idea/dictionaries/nem.xml | 1 + HierMat/__init__.py | 1 + HierMat/examples/model_1d.py | 111 ++++++++++++++++++++++++++++------- setup.py | 2 +- source/HierMat.rst | 9 +-- source/conf.py | 4 +- source/index.rst | 9 +-- 7 files changed, 102 insertions(+), 35 deletions(-) diff --git a/.idea/dictionaries/nem.xml b/.idea/dictionaries/nem.xml index ba52d2a..bd07f7e 100644 --- a/.idea/dictionaries/nem.xml +++ b/.idea/dictionaries/nem.xml @@ -1,6 +1,7 @@ + chebyshev clustertree decomp discretized diff --git a/HierMat/__init__.py b/HierMat/__init__.py index f84eda5..d671e5b 100644 --- a/HierMat/__init__.py +++ b/HierMat/__init__.py @@ -7,3 +7,4 @@ from rmat import RMat from splitable import RegularCuboid, MinimalCuboid, Balanced, Splitable from utils import plot, export, load, divisor_generator +from examples.model_1d import model_1d diff --git a/HierMat/examples/model_1d.py b/HierMat/examples/model_1d.py index 8b9708e..477c81d 100644 --- a/HierMat/examples/model_1d.py +++ b/HierMat/examples/model_1d.py @@ -1,18 +1,50 @@ -"""This is an implementation of the one-dimensional model example from :cite:`borm2003hierarchical`. -It shows a basic use-case of hierarchical matrices: +"""This is an implementation of the one-dimensional model example described in :cite:`thesis`. +It shows a typical use-case of hierarchical matrices: -.. admonition:: integral equation - - we start with the one-dimensional integral equation of the form +.. admonition:: Integral Equation .. math:: - u(x) + \int_0^1 \log |x-y| u(y) dy = g(x) + \int_0^1 \log |x-y| u(y) dy = g for :math:`x \in [0,1]`. - - + After Galerkin discretization, we end up with a linear system + + .. math:: + + \mathbf{A}^{\\text{Gal}} \cdot \\alpha = \mathbf{g} + + where + + .. math:: + + \mathbf{A}^{\\text{Gal}}_{t,\\tau}:= \int_{t}\int_{\\tau} \log |x-y| dy dx + + To determine admissible blocks we start by building the geometric objects: + + .. code-block:: python + + midpoints = [((i + 0.5)/n,) for i in xrange(n)] + intervals = {p: (p[0] - 0.5/n, p[0] + 0.5/n) for p in midpoints} + grid = HierMat.Grid(points=midpoints, supports=intervals) + cluster = HierMat.Cluster(grid=grid) + unit_cuboid = HierMat.Cuboid([0], [1]) + strategy = HierMat.RegularCuboid(cluster=cluster, cuboid=unit_cuboid) + cluster_tree = HierMat.build_cluster_tree(splitable=strategy, max_leaf_size=n_min) + block_cluster_tree = HierMat.build_block_cluster_tree(left_cluster_tree=cluster_tree, + right_cluster_tree=cluster_tree, + admissible_function=HierMat.admissible + ) + + With the structure established, we can produce the hierarchical matrix: + + .. code-block:: python + + hmat = HierMat.build_hmatrix(block_cluster_tree=block_cluster_tree, + generate_rmat_function=lambda bct: galerkin_1d_rank_k(bct, max_rank), + generate_full_matrix_function=galerkin_1d_full + ) """ import numpy import scipy.integrate as integrate @@ -24,7 +56,16 @@ def model_1d(n=2 ** 3, max_rank=1, n_min=1): - """""" + """This is an implementation of the one-dimensional model example described in :cite:`thesis`. + + :param n: number of discretization points + :type n: int + :param max_rank: max rank of the low-rank approximation + :type max_rank: int + :param n_min: minimal leaf size for cluster trees + :type n_min: int + :return: 0 (just for testing) + """ midpoints = [((i + 0.5)/n,) for i in xrange(n)] intervals = {p: (p[0] - 0.5/n, p[0] + 0.5/n) for p in midpoints} grid = HierMat.Grid(points=midpoints, supports=intervals) @@ -53,7 +94,7 @@ def model_1d(n=2 ** 3, max_rank=1, n_min=1): def kerlog(x): - """kerlog function as in master thesis + """kerlog function as in :cite:`thesis`. .. math:: @@ -72,17 +113,33 @@ def kerlog(x): def ker(x, y): - """ + """Kernel to integrate + + .. math:: - :param x: - :param y: - :return: + ker(x, y):= \log\left(\Vert x - y \Vert\\right) + + :param x: real number + :type x: float + :param y: real number + :type y: float + :return: :math:`\log\left(\Vert x - y \Vert\\right)` + :rtype: float """ return numpy.log(abs(x - y)) def galerkin_1d_rank_k(block_cluster_tree, max_rank): - """ + """Low-rank approximation of the kernel + + .. math:: + + R: &= A \cdot B^T + + A_{\\tau, k}: &= \int_\\tau \log \Vert x-y_k\Vert dx + + B_{\\tau, k}: &= \int_\\tau \mathcal{L}_k(y) dy + :param block_cluster_tree: admissible block cluster tree :type block_cluster_tree: HierMat.BlockClusterTree @@ -126,7 +183,7 @@ def galerkin_1d_full(block_cluster_tree): A_{i,j}=A_{\\tau,t}^{Gal}=\int_t\int_\\tau\log\Vert x-y\Vert \;dydx - :param block_cluster_tree: + :param block_cluster_tree: inadmissible block cluster tree :type block_cluster_tree: HierMat.BlockClusterTree :return: matrix with same shape as block_cluster_tree.shape() :rtype: numpy.matrix @@ -142,14 +199,24 @@ def galerkin_1d_full(block_cluster_tree): def get_chebyshev_interpol_points(points, lower=0, upper=1): - """ + """Get Chebyshev interpolation points on interval :math:`(a, b)`. + + .. math:: + + \\frac{1}{2} (a + b) + \\frac{1}{2} (b - a) \cos\left(\\frac{2k+1}{2n}\pi\\right) + + for :math:`k=0, ..., \\text{points} - 1` - :param points: - :param lower: - :param upper: - :return: + :param points: number of points + :type points: int + :param lower: :math:`a`, (default 0) + :type lower: float + :param upper: :math:`b`, (default 0) + :type upper: float + :return: :math:`\\frac{1}{2} (a + b) + \\frac{1}{2} (b - a) \cos\left(\\frac{2k+1}{2n}\pi\\right)` + :rtype: list(floats) """ - return [(lower + upper + (upper - lower) * numpy.cos((2 * k - 1) * numpy.pi / 2 * points)) / 2 + return [(lower + upper + (upper - lower) * numpy.cos((2 * k + 1) * numpy.pi / 2 * points)) / 2 for k in xrange(points)] diff --git a/setup.py b/setup.py index d5fa122..9ee84af 100644 --- a/setup.py +++ b/setup.py @@ -35,7 +35,7 @@ setup( name='HierMat', - version='0.7.4', + version='0.7.5', packages=['HierMat', 'HierMat/examples'], url='http://hierarchicalmatrices.readthedocs.io/en/latest/index.html', download_url='https://github.com/maekke97/HierarchicalMatrices', diff --git a/source/HierMat.rst b/source/HierMat.rst index 38fb134..3615608 100644 --- a/source/HierMat.rst +++ b/source/HierMat.rst @@ -84,10 +84,7 @@ utils module :undoc-members: :show-inheritance: -Submodules +Examples ---------- - -* **example module** - - .. automodule:: HierMat.examples - :members: +.. automodule:: HierMat.examples + :members: diff --git a/source/conf.py b/source/conf.py index 8234446..302322b 100644 --- a/source/conf.py +++ b/source/conf.py @@ -63,9 +63,9 @@ # built documents. # # The short X.Y version. -version = u'0.7.4' +version = u'0.7.5' # The full version, including alpha/beta/rc tags. -release = u'0.7.4' +release = u'0.7.5' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/source/index.rst b/source/index.rst index ff89814..f9ca069 100644 --- a/source/index.rst +++ b/source/index.rst @@ -75,13 +75,12 @@ The package is available on different platforms, so there are different ways to Basic Usage ----------- -.. todo:: - - implement examples and show their usage here +Best look at the examples section .. code-block:: python - import HierMat + from HierMat import * + model_1d(32, 2, 1) Links and references -------------------- @@ -104,4 +103,6 @@ Links and references .. rubric:: References +.. todo:: Add thesis to bib + .. bibliography:: thesis.bib