docs: improve kernel docs

Author: alexfikl

doc/conf.py

@@ -2,8 +2,7 @@
 from urllib.request import urlopen
 
 
-_conf_url = \
-        "https://raw.githubusercontent.com/inducer/sphinxconfig/main/sphinxconfig.py"
+_conf_url = "https://raw.githubusercontent.com/inducer/sphinxconfig/main/sphinxconfig.py"
 with urlopen(_conf_url) as _inf:
     exec(compile(_inf.read(), _conf_url, "exec"), globals())
 
@@ -30,9 +29,13 @@
 ]
 
 sphinxconfig_missing_reference_aliases = {
+    # sympy
+    "sp.Matrix": "class:sympy.matrices.dense.DenseMatrix",
     # pymbolic
-    "Expression": "obj:pymbolic.typing.Expression",
     "ArithmeticExpression": "obj:pymbolic.ArithmeticExpression",
+    "Expression": "obj:pymbolic.typing.Expression",
+    # sumpy
+    "ArithmeticExpr": "obj:sumpy.kernel.ArithmeticExpr",
 }
 
 

sumpy/kernel.py

@@ -69,25 +69,46 @@
 Kernel interface
 ----------------
 
-.. autoclass:: Kernel
+.. autoclass:: ArithmeticExpr
+
 .. autoclass:: KernelArgument
+.. autoclass:: Kernel
+    :show-inheritance:
 
 Symbolic kernels
 ----------------
 
 .. autoclass:: ExpressionKernel
+    :show-inheritance:
+    :members: mapper_method
 
 PDE kernels
 -----------
 
 .. autoclass:: LaplaceKernel
+    :show-inheritance:
+    :members: mapper_method
 .. autoclass:: BiharmonicKernel
+    :show-inheritance:
+    :members: mapper_method
 .. autoclass:: HelmholtzKernel
+    :show-inheritance:
+    :members: mapper_method
 .. autoclass:: YukawaKernel
+    :show-inheritance:
+    :members: mapper_method
 .. autoclass:: StokesletKernel
+    :show-inheritance:
+    :members: mapper_method
 .. autoclass:: StressletKernel
+    :show-inheritance:
+    :members: mapper_method
 .. autoclass:: ElasticityKernel
+    :show-inheritance:
+    :members: mapper_method
 .. autoclass:: LineOfCompressionKernel
+    :show-inheritance:
+    :members: mapper_method
 
 Derivatives
 -----------
@@ -97,22 +118,50 @@
 
 .. autoclass:: DerivativeBase
 .. autoclass:: AxisTargetDerivative
+    :show-inheritance:
+    :undoc-members:
+    :members: mapper_method,target_array_name
 .. autoclass:: AxisSourceDerivative
+    :show-inheritance:
+    :members: mapper_method
+.. autoclass:: DirectionalDerivative
+    :show-inheritance:
+    :members: directional_kind
 .. autoclass:: DirectionalSourceDerivative
+    :show-inheritance:
+    :members: mapper_method,directional_kind
 .. autoclass:: DirectionalTargetDerivative
+    :show-inheritance:
+    :undoc-members:
+    :members: mapper_method,directional_kind,target_array_name
 
 Transforming kernels
 --------------------
 
+.. autoclass:: TargetPointMultiplier
+    :undoc-members:
+    :members: mapper_method,target_array_name
+
+.. autoclass:: ResultT
+
 .. autoclass:: KernelMapper
+    :show-inheritance:
 .. autoclass:: KernelCombineMapper
+    :show-inheritance:
 .. autoclass:: KernelIdentityMapper
+    :show-inheritance:
 .. autoclass:: AxisSourceDerivativeRemover
+    :show-inheritance:
 .. autoclass:: AxisTargetDerivativeRemover
+    :show-inheritance:
 .. autoclass:: SourceDerivativeRemover
+    :show-inheritance:
 .. autoclass:: TargetDerivativeRemover
-.. autoclass:: TargetPointMultiplier
+    :show-inheritance:
+.. autoclass:: TargetTransformationRemover
+    :show-inheritance:
 .. autoclass:: DerivativeCounter
+    :show-inheritance:
 """
 
 ArithmeticExpr: TypeAlias = int | float | complex | sym.Basic
@@ -145,7 +194,7 @@ class Kernel(ABC):
     .. autoattribute:: is_translation_invariant
 
     .. autoattribute:: dim
-    .. autoattribute:: is_complex_valued
+    .. autoproperty:: is_complex_valued
 
     .. automethod:: get_base_kernel
     .. automethod:: replace_base_kernel
@@ -516,6 +565,11 @@ def get_pde_as_diff_op(self) -> LinearPDESystemOperator:
 
 @dataclass(frozen=True)
 class HelmholtzKernel(ExpressionKernel):
+    """
+    .. autoattribute:: helmholtz_k_name
+    .. autoattribute:: allow_evanescent
+    """
+
     mapper_method: ClassVar[str] = "map_helmholtz_kernel"
 
     helmholtz_k_name: str
@@ -592,6 +646,10 @@ def get_pde_as_diff_op(self) -> LinearPDESystemOperator:
 
 @dataclass(frozen=True)
 class YukawaKernel(ExpressionKernel):
+    """
+    .. autoattribute:: yukawa_lambda_name
+    """
+
     mapper_method: ClassVar[str] = "map_yukawa_kernel"
 
     yukawa_lambda_name: str
@@ -675,6 +733,12 @@ def get_pde_as_diff_op(self) -> LinearPDESystemOperator:
 
 @dataclass(frozen=True)
 class ElasticityKernel(ExpressionKernel):
+    """
+    .. autoattribute:: icomp
+    .. autoattribute:: jcomp
+    .. autoattribute:: viscosity_mu
+    .. autoattribute:: poisson_ratio
+    """
     mapper_method: ClassVar[str] = "map_elasticity_kernel"
 
     icomp: int
@@ -791,6 +855,12 @@ def get_pde_as_diff_op(self) -> LinearPDESystemOperator:
 
 
 class StokesletKernel(ElasticityKernel):
+    """
+    .. autoattribute:: icomp
+    .. autoattribute:: jcomp
+    .. autoattribute:: viscosity_mu
+    """
+
     def __new__(cls, dim, icomp, jcomp, viscosity_mu="mu", poisson_ratio=0.5):
         return object.__new__(cls)
 
@@ -806,6 +876,12 @@ def __str__(self) -> str:
 
 @dataclass(frozen=True)
 class StressletKernel(ExpressionKernel):
+    """
+    .. autoattribute:: icomp
+    .. autoattribute:: jcomp
+    .. autoattribute:: kcomp
+    .. autoattribute:: viscosity_mu
+    """
     mapper_method: ClassVar[str] = "map_stresslet_kernel"
 
     icomp: int
@@ -893,6 +969,10 @@ class LineOfCompressionKernel(ExpressionKernel):
          *Force at a Point in the Interior of a Semi-Infinite Solid*.
          Physics. 7 (5): 195-202.
          `doi:10.1063/1.1745385 <https://doi.org/10.1063/1.1745385>`__.
+
+    .. autoattribute:: axis
+    .. autoattribute:: viscosity_mu
+    .. autoattribute:: poisson_ratio
     """
 
     mapper_method: ClassVar[str] = "map_line_of_compression_kernel"
@@ -976,6 +1056,7 @@ def get_pde_as_diff_op(self) -> LinearPDESystemOperator:
 @dataclass(frozen=True)
 class KernelWrapper(Kernel, ABC):
     inner_kernel: Kernel
+    """The kernel that is being wrapped (to take a derivative of, etc.)."""
 
     def __init__(self, inner_kernel: Kernel) -> None:
         Kernel.__init__(self, inner_kernel.dim)
@@ -1056,6 +1137,12 @@ def get_derivative_taker(
 # {{{ derivatives
 
 class DerivativeBase(KernelWrapper, ABC):
+    """Bases: :class:`Kernel`
+
+    .. autoattribute:: inner_kernel
+    .. automethod:: replace_inner_kernel
+    """
+
     @override
     def get_pde_as_diff_op(self) -> LinearPDESystemOperator:
         return self.inner_kernel.get_pde_as_diff_op()
@@ -1071,9 +1158,14 @@ def replace_inner_kernel(self, new_inner_kernel: Kernel) -> Kernel:
 
 @dataclass(frozen=True)
 class AxisSourceDerivative(DerivativeBase):
+    """
+    .. autoattribute:: axis
+    """
+
     mapper_method: ClassVar[str] = "map_axis_source_derivative"
 
     axis: int
+    """Direction axis for the source derivative."""
 
     def __init__(self, axis: int, inner_kernel: Kernel) -> None:
         super().__init__(inner_kernel)
@@ -1108,6 +1200,10 @@ def replace_inner_kernel(self, new_inner_kernel: Kernel) -> Kernel:
 
 @dataclass(frozen=True)
 class AxisTargetDerivative(DerivativeBase):
+    """
+    .. autoattribute:: axis
+    """
+
     mapper_method: ClassVar[str] = "map_axis_target_derivative"
     target_array_name: ClassVar[str] = "targets"
 
@@ -1195,8 +1291,14 @@ def map_common_subexpression_uncached(self,
 
 @dataclass(frozen=True)
 class DirectionalDerivative(DerivativeBase):
+    """
+    .. autoattribute:: dir_vec_name
+    """
     directional_kind: ClassVar[Literal["src", "tgt"]]
+    """The kind of this directional derivative (can only be a source or target)."""
+
     dir_vec_name: str
+    """Name of the vector used for the direction."""
 
     def __init__(self, inner_kernel: Kernel, dir_vec_name: str | None = None) -> None:
         if dir_vec_name is None:
@@ -1223,7 +1325,6 @@ def replace_inner_kernel(self, new_inner_kernel: Kernel) -> Kernel:
 
 class DirectionalTargetDerivative(DirectionalDerivative):
     mapper_method: ClassVar[str] = "map_directional_target_derivative"
-
     directional_kind: ClassVar[Literal["src", "tgt"]] = "tgt"
     target_array_name: ClassVar[str] = "targets"
 
@@ -1356,14 +1457,19 @@ def prepare_loopy_kernel(self, loopy_knl: lp.TranslationUnit) -> lp.TranslationU
 
 
 class TargetPointMultiplier(KernelWrapper):
-    """Wraps a kernel :math:`G(x, y)` and outputs :math:`x_j G(x, y)`
+    """Bases: :class:`Kernel`
+
+    Wraps a kernel :math:`G(x, y)` and outputs :math:`x_j G(x, y)`
     where :math:`x, y` are targets and sources respectively.
+
+    .. autoattribute:: axis
     """
 
     mapper_method: ClassVar[str] = "map_target_point_multiplier"
     target_array_name: ClassVar[str] = "targets"
 
     axis: int
+    """Coordinate axis with which to multiply the kernel."""
 
     def __init__(self, axis: int, inner_kernel: Kernel) -> None:
         KernelWrapper.__init__(self, inner_kernel)
@@ -1438,6 +1544,9 @@ def replace_inner_kernel(self, new_inner_kernel: Kernel) -> Kernel:
 
 
 class KernelMapper(Generic[ResultT]):
+    """
+    .. automethod:: __call__
+    """
     def rec(self, kernel: Kernel) -> ResultT:
         try:
             method = cast(
@@ -1453,6 +1562,10 @@ def __call__(self, kernel: Kernel) -> ResultT:
 
 
 class KernelCombineMapper(KernelMapper[ResultT], ABC):
+    """
+    .. automethod:: combine
+    """
+
     @abstractmethod
     def combine(self, values: Iterable[ResultT]) -> ResultT:
         raise NotImplementedError
@@ -1511,32 +1624,42 @@ def map_directional_source_derivative(
 
 
 class AxisSourceDerivativeRemover(KernelIdentityMapper):
+    """Removes all axis source derivatives from the kernel."""
+
     @override
     def map_axis_source_derivative(self, kernel: AxisSourceDerivative) -> Kernel:
         return self.rec(kernel.inner_kernel)
 
 
 class AxisTargetDerivativeRemover(KernelIdentityMapper):
+    """Removes all axis target derivatives from the kernel."""
+
     @override
     def map_axis_target_derivative(self, kernel: AxisTargetDerivative) -> Kernel:
         return self.rec(kernel.inner_kernel)
 
 
 class TargetDerivativeRemover(AxisTargetDerivativeRemover):
+    """Removes all target derivatives from the kernel."""
+
     @override
     def map_directional_target_derivative(
             self, kernel: DirectionalTargetDerivative) -> Kernel:
         return self.rec(kernel.inner_kernel)
 
 
 class SourceDerivativeRemover(AxisSourceDerivativeRemover):
+    """Removes all source derivatives from the kernel."""
+
     @override
     def map_directional_source_derivative(
             self, kernel: DirectionalSourceDerivative) -> Kernel:
         return self.rec(kernel.inner_kernel)
 
 
 class TargetTransformationRemover(TargetDerivativeRemover):
+    """Removes all target transformations from the kernel."""
+
     @override
     def map_target_point_multiplier(self, kernel: TargetPointMultiplier) -> Kernel:
         return self.rec(kernel.inner_kernel)
@@ -1546,6 +1669,8 @@ def map_target_point_multiplier(self, kernel: TargetPointMultiplier) -> Kernel:
 
 
 class DerivativeCounter(KernelCombineMapper[int]):
+    """Counts the number of derivatives in the kernel."""
+
     @override
     def combine(self, values: Iterable[int]) -> int:
         return sum(values)