diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0f0f630b023b09f998fb9fe2902939cb9a32ba9f..25e262d074551a616c5d65ad5874871afb936137 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -52,6 +52,21 @@ jobs: build_py_project_in_conda_env run_examples + docs: + name: Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: "Main Script" + run: | + sudo apt-get update + sudo apt-get install openmpi-bin libopenmpi-dev + CONDA_ENVIRONMENT=.test-conda-env-py3.yml + curl -L -O -k https://gitlab.tiker.net/inducer/ci-support/raw/master/ci-support.sh + . ci-support.sh + build_py_project_in_conda_env + build_docs + # vim: sw=4 diff --git a/.gitignore b/.gitignore index 94648fab1309424c88e2836ab4034eab05049871..14be95d194bd112b5596328cf5bafcfc092e0cce 100644 --- a/.gitignore +++ b/.gitignore @@ -33,3 +33,5 @@ run-debug-* .cache .pytest_cache + +*.json diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 66fc4e491c73a020bba5baee77f85048805696be..ebe4262476c11ae643380f4111a45f0d083f304c 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -128,8 +128,6 @@ Documentation: - ". ./build-docs.sh" tags: - python3 - only: - - master Flake8: script: diff --git a/doc/conf.py b/doc/conf.py index d75d2aa2ac850052f2c0ad196affaea5b0ec9e98..dc8f0e244b6a4212b817e4751f54e348bbe9661b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -170,7 +170,7 @@ html_sidebars = { # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +#html_static_path = ['_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -327,4 +327,4 @@ intersphinx_mapping = { 'https://documen.tician.de/meshmode/': None, 'http://documen.tician.de/loopy/': None, } -autoclass_content = "both" +autoclass_content = "class" diff --git a/doc/discretization.rst b/doc/discretization.rst new file mode 100644 index 0000000000000000000000000000000000000000..414111348b5de7a8261b088bdf5b5a2c28680a24 --- /dev/null +++ b/doc/discretization.rst @@ -0,0 +1,12 @@ +Discretization +============== + +.. module:: grudge + +.. automodule:: grudge.discretization + +Discretization with Eager Evaluation +==================================== + +.. automodule:: grudge.eager + diff --git a/doc/eager.rst b/doc/eager.rst deleted file mode 100644 index 5d2bdd5b071a15623134a1f549589ce6d0178f13..0000000000000000000000000000000000000000 --- a/doc/eager.rst +++ /dev/null @@ -1,5 +0,0 @@ -Eagerly-evaluated Operation -=========================== - -.. automodule:: grudge.eager - diff --git a/doc/index.rst b/doc/index.rst index 6d7782bc950b12431961f3bd0b8ee30deba4d050..7b6ce79d0a108cdcc8df3d05c00af34ee7213190 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,9 +6,9 @@ Contents: .. toctree:: :maxdepth: 2 - misc + discretization symbolic - eager + misc Indices and Tables diff --git a/grudge/discretization.py b/grudge/discretization.py index 7c0573c2e5ec3515843b6f8c377ad10301256aaa..a5452a24b9e690ec14cd0b5bf455f711f3b7f2e7 100644 --- a/grudge/discretization.py +++ b/grudge/discretization.py @@ -30,12 +30,12 @@ import numpy as np # noqa: F401 from meshmode.array_context import ArrayContext -# FIXME Naming not ideal -class DiscretizationBase(object): - pass +__doc__ = """ +.. autoclass:: DGDiscretizationWithBoundaries +""" -class DGDiscretizationWithBoundaries(DiscretizationBase): +class DGDiscretizationWithBoundaries(object): """ .. automethod :: discr_from_dd .. automethod :: connection_from_dds @@ -53,10 +53,11 @@ class DGDiscretizationWithBoundaries(DiscretizationBase): """ :param quad_tag_to_group_factory: A mapping from quadrature tags (typically strings--but may be any hashable/comparable object) to a - :class:`meshmode.discretization.ElementGroupFactory` indicating with - which quadrature discretization the operations are to be carried out, - or *None* to indicate that operations with this quadrature tag should - be carried out with the standard volume discretization. + :class:`~meshmode.discretization.poly_element.ElementGroupFactory` + indicating with which quadrature discretization the operations are + to be carried out, or *None* to indicate that operations with this + quadrature tag should be carried out with the standard volume + discretization. """ self._setup_actx = array_context @@ -390,7 +391,7 @@ class DGDiscretizationWithBoundaries(DiscretizationBase): def order(self): from warnings import warn warn("DGDiscretizationWithBoundaries.order is deprecated, " - "consider the orders of element groups instead. " + "consider using the orders of element groups instead. " "'order' will go away in 2021.", DeprecationWarning, stacklevel=2) diff --git a/grudge/eager.py b/grudge/eager.py index 87368161e5045b2a7c1b508b89cf60ebb336053a..4cff62c5efe9dda454cff20b06789f0db0412f44 100644 --- a/grudge/eager.py +++ b/grudge/eager.py @@ -45,15 +45,28 @@ __doc__ = """ class EagerDGDiscretization(DGDiscretizationWithBoundaries): """ + Inherits from :class:`~grudge.discretization.DGDiscretizationWithBoundaries`. + + .. automethod:: __init__ .. automethod:: project .. automethod:: nodes + .. automethod:: grad + .. automethod:: d_dx .. automethod:: div + .. automethod:: weak_grad + .. automethod:: weak_d_dx .. automethod:: weak_div + .. automethod:: normal .. automethod:: inverse_mass .. automethod:: face_mass + + .. automethod:: norm + .. automethod:: nodal_sum + .. automethod:: nodal_min + .. automethod:: nodal_max """ def interp(self, src, tgt, vec): @@ -64,6 +77,14 @@ class EagerDGDiscretization(DGDiscretizationWithBoundaries): return self.project(src, tgt, vec) def project(self, src, tgt, vec): + """Project from one discretization to another, e.g. from the + volume to the boundary, or from the base to the an overintegrated + quadrature discretization. + + :arg src: a :class:`~grudge.sym.DOFDesc`, or a value convertible to one + :arg tgt: a :class:`~grudge.sym.DOFDesc`, or a value convertible to one + :arg vec: a :class:`~meshmode.dof_array.DOFArray` + """ if (isinstance(vec, np.ndarray) and vec.dtype.char == "O" and not isinstance(vec, DOFArray)): @@ -72,19 +93,80 @@ class EagerDGDiscretization(DGDiscretizationWithBoundaries): return self.connection_from_dds(src, tgt)(vec) - def nodes(self): - return self._volume_discr.nodes() + def nodes(self, dd=None): + r"""Return the nodes of a discretization. + + :arg dd: a :class:`~grudge.sym.DOFDesc`, or a value convertible to one. + Defaults to the base volume discretization. + :returns: an object array of :class:`~meshmode.dof_array.DOFArray`\ s + """ + if dd is None: + return self._volume_discr.nodes() + else: + return self.discr_from_dd(dd).nodes() + + # {{{ derivatives @memoize_method def _bound_grad(self): return bind(self, sym.nabla(self.dim) * sym.Variable("u"), local_only=True) def grad(self, vec): + r"""Return the gradient of the volume function represented by *vec*. + + :arg vec: a :class:`~meshmode.dof_array.DOFArray` + :returns: an object array of :class:`~meshmode.dof_array.DOFArray`\ s + """ return self._bound_grad()(u=vec) + @memoize_method + def _bound_d_dx(self, xyz_axis): + return bind(self, sym.nabla(self.dim)[xyz_axis] * sym.Variable("u"), + local_only=True) + + def d_dx(self, xyz_axis, vec): + r"""Return the derivative along axis *xyz_axis* of the volume function + represented by *vec*. + + :arg xyz_axis: an integer indicating the axis along which the derivative + is taken + :arg vec: a :class:`~meshmode.dof_array.DOFArray` + :returns: a :class:`~meshmode.dof_array.DOFArray`\ s + """ + return self._bound_d_dx(xyz_axis)(u=vec) + + def _div_helper(self, diff_func, vecs): + if not isinstance(vecs, np.ndarray): + raise TypeError("argument must be an object array") + assert vecs.dtype == np.object + + if vecs.shape[-1] != self.ambient_dim: + raise ValueError("last dimension of *vecs* argument must match " + "ambient dimension") + + if len(vecs.shape) == 1: + return sum(diff_func(i, vec_i) for i, vec_i in enumerate(vecs)) + else: + result = np.zeros(vecs.shape[:-1], dtype=object) + for idx in np.ndindex(vecs.shape[:-1]): + result[idx] = sum( + diff_func(i, vec_i) for i, vec_i in enumerate(vecs[idx])) + return result + def div(self, vecs): - return sum( - self.grad(vec_i)[i] for i, vec_i in enumerate(vecs)) + r"""Return the divergence of the vector volume function + represented by *vecs*. + + :arg vec: an object array of + a :class:`~meshmode.dof_array.DOFArray`\ s, + where the last axis of the array must have length + matching the volume dimension. + :returns: a :class:`~meshmode.dof_array.DOFArray` + """ + + return self._div_helper( + lambda i, subvec: self.d_dx(i, subvec), + vecs) @memoize_method def _bound_weak_grad(self, dd): @@ -93,6 +175,16 @@ class EagerDGDiscretization(DGDiscretizationWithBoundaries): local_only=True) def weak_grad(self, *args): + r"""Return the "weak gradient" of the volume function represented by + *vec*. + + May be called with ``(vecs)`` or ``(dd, vecs)``. + + :arg dd: a :class:`~grudge.sym.DOFDesc`, or a value convertible to one. + Defaults to the base volume discretization if not provided. + :arg vec: a :class:`~meshmode.dof_array.DOFArray` + :returns: an object array of :class:`~meshmode.dof_array.DOFArray`\ s + """ if len(args) == 1: vec, = args dd = sym.DOFDesc("vol", sym.QTAG_NONE) @@ -103,7 +195,48 @@ class EagerDGDiscretization(DGDiscretizationWithBoundaries): return self._bound_weak_grad(dd)(u=vec) + @memoize_method + def _bound_weak_d_dx(self, dd, xyz_axis): + return bind(self, + sym.stiffness_t(self.dim, dd_in=dd)[xyz_axis] + * sym.Variable("u", dd), + local_only=True) + + def weak_d_dx(self, *args): + r"""Return the derivative along axis *xyz_axis* of the volume function + represented by *vec*. + + May be called with ``(xyz_axis, vecs)`` or ``(dd, xyz_axis, vecs)``. + + :arg xyz_axis: an integer indicating the axis along which the derivative + is taken + :arg vec: a :class:`~meshmode.dof_array.DOFArray` + :returns: a :class:`~meshmode.dof_array.DOFArray`\ s + """ + if len(args) == 2: + xyz_axis, vec = args + dd = sym.DOFDesc("vol", sym.QTAG_NONE) + elif len(args) == 3: + dd, xyz_axis, vec = args + else: + raise TypeError("invalid number of arguments") + + return self._bound_weak_d_dx(dd, xyz_axis)(u=vec) + def weak_div(self, *args): + r"""Return the "weak divergence" of the vector volume function + represented by *vecs*. + + May be called with ``(vecs)`` or ``(dd, vecs)``. + + :arg dd: a :class:`~grudge.sym.DOFDesc`, or a value convertible to one. + Defaults to the base volume discretization if not provided. + :arg vec: a object array of + a :class:`~meshmode.dof_array.DOFArray`\ s, + where the last axis of the array must have length + matching the volume dimension. + :returns: a :class:`~meshmode.dof_array.DOFArray` + """ if len(args) == 1: vecs, = args dd = sym.DOFDesc("vol", sym.QTAG_NONE) @@ -112,8 +245,11 @@ class EagerDGDiscretization(DGDiscretizationWithBoundaries): else: raise TypeError("invalid number of arguments") - return sum( - self.weak_grad(dd, vec_i)[i] for i, vec_i in enumerate(vecs)) + return self._div_helper( + lambda i, subvec: self.weak_d_dx(dd, i, subvec), + vecs) + + # }}} @memoize_method def normal(self, dd): @@ -221,6 +357,8 @@ def interior_trace_pair(discrwb, vec): return TracePair("int_faces", i, e) +# {{{ distributed-memory functionality + class _RankBoundaryCommunication: base_tag = 1273 @@ -295,5 +433,7 @@ def cross_rank_trace_pairs(discrwb, vec, tag=None): else: return _cross_rank_trace_pairs_scalar_field(discrwb, vec, tag=tag) +# }}} + # vim: foldmethod=marker diff --git a/grudge/symbolic/operators.py b/grudge/symbolic/operators.py index 4ecd920c8d82ee429855183b319fd191ed524a9f..df886d4571379570305e46087836d16c88ba28c3 100644 --- a/grudge/symbolic/operators.py +++ b/grudge/symbolic/operators.py @@ -94,12 +94,12 @@ class Operator(pymbolic.primitives.Expression): """ .. attribute:: dd_in - an instance of :class:`~grudge.symbolic.primitives.DOFDesc` describing the + an instance of :class:`~grudge.sym.DOFDesc` describing the input discretization. .. attribute:: dd_out - an instance of :class:`~grudge.symbolic.primitives.DOFDesc` describing the + an instance of :class:`~grudge.sym.DOFDesc` describing the output discretization. """ @@ -477,7 +477,10 @@ class VandermondeOperator(ElementwiseLinearOperator): class MassOperatorBase(Operator): """ - :attr:`dd_in` and :attr:`dd_out` may be surface or volume discretizations. + Inherits from :class:`Operator`. + + :attr:`~Operator.dd_in` and :attr:`~Operator.dd_out` may be surface or volume + discretizations. """ def __init__(self, dd_in=None, dd_out=None): diff --git a/grudge/symbolic/primitives.py b/grudge/symbolic/primitives.py index 78261d658e2871379f042ee0d714e2d8cd9e3547..0a49034568f6ec45c25b45018e9451fb866fe361 100644 --- a/grudge/symbolic/primitives.py +++ b/grudge/symbolic/primitives.py @@ -55,6 +55,8 @@ class ExpressionBase(prim.Expression): __doc__ = """ +.. currentmodule:: grudge.sym + DOF description ^^^^^^^^^^^^^^^