From 52c7318c777efebf2c559986f0f7b6a429898e89 Mon Sep 17 00:00:00 2001
From: Thomas Gibson <gibsonthomas1120@hotmail.com>
Date: Wed, 26 May 2021 07:21:42 -0500
Subject: [PATCH] Add various documentation updates
---
grudge/discretization.py | 28 +++++++++++++++-------------
grudge/geometry/metrics.py | 8 +++++++-
grudge/op.py | 2 +-
grudge/trace_pair.py | 8 ++++----
4 files changed, 27 insertions(+), 19 deletions(-)
diff --git a/grudge/discretization.py b/grudge/discretization.py
index 8fdefc53..632cff30 100644
--- a/grudge/discretization.py
+++ b/grudge/discretization.py
@@ -45,13 +45,14 @@ from meshmode.discretization.connection import (
FACE_RESTR_ALL,
make_face_restriction
)
-from meshmode.mesh import BTAG_PARTITION
+from meshmode.mesh import Mesh, BTAG_PARTITION
from warnings import warn
class DiscretizationCollection:
- """A collection of discretizations on various mesh entities
+ """A collection of discretizations, defined on the same underlying
+ :class:`~meshmode.mesh.Mesh`, corresponding to various mesh entities
(volume, interior facets, boundaries) and associated element
groups.
@@ -70,14 +71,12 @@ class DiscretizationCollection:
.. automethod:: zeros
"""
- def __init__(self, array_context, mesh, order=None,
- discr_tag_to_group_factory=None, mpi_communicator=None,
- # FIXME: `quad_tag_to_group_factory` is deprecated
- quad_tag_to_group_factory=None):
- """Constructor for the :class:`DiscretizationCollection` object.
-
- :arg actx: an :class:`~arraycontext.context.ArrayContext`.
- :arg mesh: a :class:`~meshmode.mesh.Mesh` object.
+ def __init__(self, array_context: ArrayContext, mesh: Mesh,
+ order=None,
+ discr_tag_to_group_factory=None, mpi_communicator=None,
+ # FIXME: `quad_tag_to_group_factory` is deprecated
+ quad_tag_to_group_factory=None):
+ """
:arg discr_tag_to_group_factory: A mapping from discretization tags
(typically one of: :class:`grudge.dof_desc.DISCR_TAG_BASE`,
:class:`grudge.dof_desc.DISCR_TAG_MODAL`, or
@@ -145,6 +144,7 @@ class DiscretizationCollection:
self.group_factory_for_discretization_tag(DISCR_TAG_BASE)
)
+ # NOTE: Can be removed when symbolics are completely removed
# {{{ management of discretization-scoped common subexpressions
from pytools import UniqueNameGenerator
@@ -553,13 +553,14 @@ class DiscretizationCollection:
@property
def mesh(self):
- """Return a :class:`meshmode.mesh.Mesh` over which the discretization
+ """Return the :class:`meshmode.mesh.Mesh` over which the discretization
collection is built.
"""
return self._volume_discr.mesh
def empty(self, array_context: ArrayContext, dtype=None):
- """Return an empty :class:`~meshmode.dof_array.DOFArray`.
+ """Return an empty :class:`~meshmode.dof_array.DOFArray` defined at
+ the volume nodes: :class:`grudge.dof_desc.DD_VOLUME`.
:arg array_context: an :class:`~arraycontext.context.ArrayContext`.
:arg dtype: type special value 'c' will result in a
@@ -569,7 +570,8 @@ class DiscretizationCollection:
return self._volume_discr.empty(array_context, dtype)
def zeros(self, array_context: ArrayContext, dtype=None):
- """Return a zero-initialized :class:`~meshmode.dof_array.DOFArray`.
+ """Return a zero-initialized :class:`~meshmode.dof_array.DOFArray`
+ defined at the volume nodes, :class:`grudge.dof_desc.DD_VOLUME`.
:arg array_context: an :class:`~arraycontext.context.ArrayContext`.
:arg dtype: type special value 'c' will result in a
diff --git a/grudge/geometry/metrics.py b/grudge/geometry/metrics.py
index 2ac1f701..5fc01869 100644
--- a/grudge/geometry/metrics.py
+++ b/grudge/geometry/metrics.py
@@ -542,6 +542,12 @@ def surface_normal(
def _compute_mv_normal(
actx: ArrayContext, dcoll: DiscretizationCollection, dd
) -> MultiVector:
+ """Exterior unit normal as a :class:`~pymbolic.geometric_algebra.MultiVector`.
+
+ :arg dd: a :class:`~grudge.dof_desc.DOFDesc` as the surface discretization.
+ :returns: a :class:`~pymbolic.geometric_algebra.MultiVector`
+ containing the unit normals.
+ """
import grudge.dof_desc as dof_desc
dd = dof_desc.as_dofdesc(dd)
@@ -681,7 +687,7 @@ def summed_curvature(actx: ArrayContext, dcoll: DiscretizationCollection,
.. math::
- \kappa = \mathrm{Trace}(C(x))
+ \kappa = \operatorname{Trace}(C(x))
where :math:`x(u, v)` defines a parameterized surface, :math:`u,v` are
coordinates on the parameterized surface, and :math:`C(x)` is the shape
diff --git a/grudge/op.py b/grudge/op.py
index d57e98f0..0df1ef20 100644
--- a/grudge/op.py
+++ b/grudge/op.py
@@ -187,7 +187,7 @@ def nodes(dcoll: DiscretizationCollection, dd=None) -> np.ndarray:
@memoize_on_first_arg
-def normal(dcoll: DiscretizationCollection, dd):
+def normal(dcoll: DiscretizationCollection, dd) -> np.ndarray:
r"""Get the unit normal to the specified surface discretization, *dd*.
:arg dd: a :class:`~grudge.dof_desc.DOFDesc` as the surface discretization.
diff --git a/grudge/trace_pair.py b/grudge/trace_pair.py
index d8cc62d1..64ea2109 100644
--- a/grudge/trace_pair.py
+++ b/grudge/trace_pair.py
@@ -108,16 +108,16 @@ class TracePair:
object.__setattr__(self, "exterior", exterior)
def __getattr__(self, name):
- """Return a :class:`TracePair` associated with the attributes
- of the array containers defining :attr:`int` and :attr:`ext`.
+ """Return a new :class:`TracePair` resulting from executing attribute
+ lookup with *name* on :attr:`int` and :attr:`ext`.
"""
return TracePair(self.dd,
interior=getattr(self.interior, name),
exterior=getattr(self.exterior, name))
def __getitem__(self, index):
- """Return a :class:`TracePair` associated with the subarrays
- of :attr:`int` and :attr:`ext`, denoted by `index`.
+ """Return a new :class:`TracePair` resulting from executing
+ subscripting with *index* on :attr:`int` and :attr:`ext`.
"""
return TracePair(self.dd,
interior=self.interior[index],
--
GitLab