Kernels

Kernel interface

class sumpy.kernel.KernelArgument(loopy_arg: KernelArgument)

loopy_arg: KernelArgument

A loopy.KernelArgument instance describing the type, name, and other features of this kernel argument when passed to a generated piece of code.

class sumpy.kernel.Kernel(dim: int)

Bases: ABC

Basic kernel interface.

mapper_method: ClassVar[str]

The name of the mapper method called for the kernel.

is_translation_invariant: ClassVar[bool] = True

A boolean flag indicating whether the kernel is translation invariant.

dim: int

Dimension of the space the kernel is defined in.

abstract property is_complex_valued: bool

A boolean flag indicating whether this kernel is complex valued.

get_base_kernel() → Kernel

Returns:

the kernel being wrapped by this one, or else self.

replace_base_kernel(new_base_kernel: Kernel) → Kernel

Returns:

the base kernel being wrapped by this one, or else new_base_kernel.

prepare_loopy_kernel(loopy_knl: TranslationUnit) → TranslationUnit

Apply some changes (such as registering function manglers) to the kernel.

Returns:

a new loopy kernel with the applied changes.

get_code_transformer() → Callable[[Expression], Expression]

Returns:

a function to postprocess the pymbolic expression generated from the result of get_expression() on the way to code generation.

abstractmethod get_expression(dist_vec: MutableDenseMatrix) → Expr

Returns:

a sympy expression for the kernel.

postprocess_at_source(expr: Expr, avec: MutableDenseMatrix) → Expr

postprocess_at_source(expr: ExprDerivativeTaker, avec: MutableDenseMatrix) → DifferentiatedExprDerivativeTaker

Transform a kernel evaluation or expansion expression in a place where the vector \(a\) (something - source) is known. (“something” may be an expansion center or a target)

The typical use of this function is to apply source-variable derivatives to the kernel.

postprocess_at_target(expr: Expr, bvec: MutableDenseMatrix) → Expr

postprocess_at_target(expr: ExprDerivativeTaker | DifferentiatedExprDerivativeTaker, bvec: MutableDenseMatrix) → DifferentiatedExprDerivativeTaker

Transform a kernel evaluation or expansion expression in a place where the vector \(b\) (target - something) is known. (“something” may be an expansion center or a target.)

The typical use of this function is to apply target-variable derivatives to the kernel.

abstractmethod get_global_scaling_const() → Expr

A global scaling constant of the kernel.

Typically, this ensures that the kernel is scaled so that \(\mathcal{L}(G)(x) = C \delta(x)\) with a constant of 1, where \(\mathcal{L}\) is the PDE operator associated with the kernel. Not to be confused with rscale, which keeps expansion coefficients benignly scaled.

get_args() → Sequence[KernelArgument]

Returns:

list of KernelArgument instances describing extra arguments used by the kernel.

get_source_args() → Sequence[KernelArgument]

Returns:

list of KernelArgument instances describing extra arguments used by kernel in picking up contributions from point sources.

abstractmethod get_pde_as_diff_op() → LinearPDESystemOperator

Returns:

the PDE for the kernel as a sumpy.expansion.diff_op.LinearPDESystemOperator object \(\mathcal{L}\), where \(\mathcal{L}(u) = 0\) is the PDE.

Symbolic kernels

class sumpy.kernel.ExpressionKernel(dim: int, expression: Expression, global_scaling_const: Expression)

Bases: Kernel, ABC

expression: Expression

A pymbolic expression depending on variables d_1 through d_N where N equals dim. These variables match what is returned from pymbolic.primitives.make_sym_vector() with argument “d”. Any variable that is not d or a SpatialConstant will be viewed as potentially spatially varying.

global_scaling_const: Expression

A constant pymbolic expression for the global scaling of the kernel. Typically, this ensures that the kernel is scaled so that \(\mathcal{L}(G)(x)=C\delta(x)\) with a constant of 1, where \(\mathcal{L}\) is the PDE operator associated with the kernel. Not to be confused with rscale, which keeps expansion coefficients benignly scaled.

mapper_method: ClassVar[str] = 'map_expression_kernel'

The name of the mapper method called for the kernel.

PDE kernels

class sumpy.kernel.LaplaceKernel(dim: int)

Bases: ExpressionKernel

A kernel for the Laplace equation (see e.g. Theorem 6.2 from [Kress2013]).

\[\Delta K(\mathbf{x}, \mathbf{y}) = \delta(\mathbf{x} - \mathbf{y}).\]

mapper_method: ClassVar[str] = 'map_laplace_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.BiharmonicKernel(dim: int)

Bases: ExpressionKernel

A kernel for the biharmonic equation.

\[\Delta^2 K(\mathbf{x}, \mathbf{y}) = \delta(\mathbf{x} - \mathbf{y}).\]

mapper_method: ClassVar[str] = 'map_biharmonic_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.HelmholtzKernel(dim: int, helmholtz_k_name: str = 'k', allow_evanescent: bool = False)

Bases: ExpressionKernel

A kernel for the Helmholtz equation (see e.g. Example 12.14 in [Kress2013]).

\[\Delta K(\mathbf{x}, \mathbf{y}) + k^2 K(\mathbf{x}, \mathbf{y}) = \delta(\mathbf{x} - \mathbf{y}).\]

helmholtz_k_name: str

The argument name to use for the Helmholtz parameter when generating functions to evaluate this kernel.

allow_evanescent: bool

mapper_method: ClassVar[str] = 'map_helmholtz_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.YukawaKernel(dim: int, yukawa_lambda_name: str = 'lam')

Bases: ExpressionKernel

A kernel for the Yukawa equation.

\[\Delta K(\mathbf{x}, \mathbf{y}) - \lambda^2 K(\mathbf{x}, \mathbf{y}) = \delta(\mathbf{x} - \mathbf{y}).\]

yukawa_lambda_name: str

The argument name to use for the Yukawa parameter when generating functions to evaluate this kernel.

mapper_method: ClassVar[str] = 'map_yukawa_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.StokesletKernel(dim: int, icomp: int, jcomp: int, viscosity_mu_name: str = 'mu')

Bases: ExpressionKernel

A kernel for the Stokes equations (see e.g. Chapter 2 in [Pozrikidis1992]).

\[\begin{split}\begin{cases} -\mu \Delta K_{ij}(\mathbf{x}, \mathbf{y}) + \nabla_i P_j(\mathbf{x}, \mathbf{y}) = \delta_{ij} \delta(\mathbf{x} - \mathbf{y}), \\ \nabla_i K_{ij}(\mathbf{x}, \mathbf{y}) = 0, \\ \end{cases}\end{split}\]

where pressure kernel \(P_j = \partial_j K\) is the derivative of the Laplace kernel. This kernel is often called the Stokeslet or the Oseen-Burgers tensor and it represents the velocity field.

icomp: int

Component index for the kernel.

jcomp: int

Component index for the kernel.

viscosity_mu_name: str

The argument name to use for the dynamic viscosity \(\mu\) when generating functions to evaluate this kernel.

mapper_method: ClassVar[str] = 'map_stokeslet_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.StressletKernel(dim: int, icomp: int, jcomp: int, kcomp: int, viscosity_mu_name: str = 'mu')

Bases: ExpressionKernel

A kernel for the Stokes equations (see e.g. Chapter 2 in [Pozrikidis1992]).

\[K_{ijk}(\mathbf{x}, \mathbf{y}) = -P_j \delta_{ik} + \mu (\partial_k K_{ij} + \partial_i K_{kj})\]

where the two-index \(K_{ij}\) is the StokesletKernel. This kernel is often called the Stresslet and it represents the stress tensor.

icomp: int

Component index for the kernel.

jcomp: int

Component index for the kernel.

kcomp: int

Component index for the kernel.

viscosity_mu_name: str

The argument name to use for the dynamic viscosity \(\mu\) when generating functions to evaluate this kernel.

mapper_method: ClassVar[str] = 'map_stresslet_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.ElasticityKernel(dim: int, icomp: int, jcomp: int, viscosity_mu_name: str = 'mu', poisson_ratio_name: str = 'nu')

Bases: ExpressionKernel

A kernel for the linear elasticity (Navier-Cauchy) equations (see e.g. Section 2.2 in [Hsiao2008]).

\[\mu \Delta K_{ij}(\mathbf{x}, \mathbf{y}) + \frac{\mu}{1 - 2 \nu} \nabla (\nabla \cdot K_{ij}(\mathbf{x}, \mathbf{y})) = \delta_{ij} \delta(\mathbf{x} - \mathbf{y}).\]

icomp: int

Component index for the kernel.

jcomp: int

Component index for the kernel.

viscosity_mu_name: str

The argument name to use for the dynamic viscosity \(\mu\) when generating functions to evaluate this kernel.

poisson_ratio_name: str

The argument name to use for Poisson’s ratio \(\nu\) when generating functions to evaluate this kernel.

mapper_method: ClassVar[str] = 'map_elasticity_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.LineOfCompressionKernel(dim: int = 3, axis: int = 2, viscosity_mu_name: str = 'mu', poisson_ratio_name: str = 'nu')

Bases: ExpressionKernel

A kernel for the line of compression or dilatation of constant strength along an axis from zero to negative infinity.

This is used for the explicit solution to half-space linear elasticity problem. See [Mindlin1936] for details.

[Mindlin1936]

R. D. Mindlin (1936). Force at a Point in the Interior of a Semi-Infinite Solid. Physics. 7 (5): 195-202. doi:10.1063/1.1745385.

axis: int

Axis number (defaulting to 2 for the z axis).

viscosity_mu_name: str

The argument name to use for the dynamic viscosity \(\mu\) when generating functions to evaluate this kernel.

poisson_ratio_name: str

The argument name to use for Poisson’s ratio \(\nu\) when generating functions to evaluate this kernel.

mapper_method: ClassVar[str] = 'map_line_of_compression_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.BrinkmanletKernel(dim: int, icomp: int, jcomp: int, viscosity_mu_name: str = 'mu', darcy_impermeability_name: str = 'k')

Bases: ExpressionKernel

A kernel for the Brinkman equations.

\[\begin{split}\begin{cases} -\mu (\Delta K_{ij}(\mathbf{x}, \mathbf{y}) - k^2 K_{ij}(\mathbf{x}, \mathbf{y})) + \nabla_i P_j(\mathbf{x}, \mathbf{y}) = \delta_{ij}(\mathbf{x} - \mathbf{y}), \\ \nabla_i K_{ij} = 0, \end{cases}\end{split}\]

where \(P_j\) is the pressure kernel.

mapper_method: ClassVar[str] = 'map_brinkmanlet_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.BrinkmanStressKernel(dim: int, icomp: int, jcomp: int, kcomp: int, viscosity_mu_name: str = 'mu', darcy_impermeability_name: str = 'k')

Bases: ExpressionKernel

A kernel for the Brinkman equations.

\[K_{ijk} = -p_j \delta_{ik} + \mu (\partial_k K_{ij} + \partial_i K_{jk}),\]

where the two-index \(K_{ij}\) is the BrinkmanletKernel and \(P_j\) is the pressure kernel.

mapper_method: ClassVar[str] = 'map_brinkman_stress_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.HeatKernel(spatial_dims: int, heat_alpha_name: str = 'alpha')

Bases: ExpressionKernel

The Green’s function for the heat equation given by \(e^{-r^2/{4 \alpha t}}/\sqrt{(4 \pi \alpha t)^d}\) where \(d\) is the number of spatial dimensions.

Note

This kernel cannot be used in an FMM yet and can only be used in expansions and evaluations that occur forward in the time dimension.

mapper_method: ClassVar[str] = 'map_heat_kernel'

The name of the mapper method called for the kernel.

[Pozrikidis1992] (1,2)

C. Pozrikidis, Boundary Integral and Singularity Methods for Linearized Viscous Flow, Cambridge University Press, 1992.

[Hsiao2008]

G. C. Hsiao, W. L. Wendland, Boundary Integral Equations, Springer, 2008.

[Kress2013] (1,2)

R. Kress, Linear Integral Equations, Springer Science & Business Media, 2013.

Derivatives

These objects wrap other kernels and take derivatives of them in the process.

class sumpy.kernel.DerivativeBase(inner_kernel: Kernel)

Bases: Kernel

inner_kernel: Kernel

The kernel that is being wrapped (to take a derivative of, etc.).

abstractmethod replace_inner_kernel(new_inner_kernel: Kernel) → Kernel

Replace the inner kernel of this wrapper.

This is essentially the same as Kernel.replace_base_kernel(), but it does not recurse.

class sumpy.kernel.AxisTargetDerivative(axis: int, inner_kernel: Kernel)

Bases: DerivativeBase

axis: int

mapper_method: ClassVar[str] = 'map_axis_target_derivative'

The name of the mapper method called for the kernel.

target_array_name: ClassVar[str] = 'targets'

class sumpy.kernel.AxisSourceDerivative(axis: int, inner_kernel: Kernel)

Bases: DerivativeBase

axis: int

Direction axis for the source derivative.

mapper_method: ClassVar[str] = 'map_axis_source_derivative'

The name of the mapper method called for the kernel.

class sumpy.kernel.DirectionalDerivative(inner_kernel: Kernel, dir_vec_name: str | None = None)

Bases: DerivativeBase

dir_vec_name: str

Name of the vector used for the direction.

directional_kind: ClassVar[Literal['src', 'tgt']]

The kind of this directional derivative (can only be a source or target).

class sumpy.kernel.DirectionalSourceDerivative(inner_kernel: Kernel, dir_vec_name: str | None = None)

Bases: DirectionalDerivative

directional_kind: ClassVar[Literal['src', 'tgt']] = 'src'

The kind of this directional derivative (can only be a source or target).

mapper_method: ClassVar[str] = 'map_directional_source_derivative'

The name of the mapper method called for the kernel.

Transforming kernels

class sumpy.kernel.TargetPointMultiplier(axis: int, inner_kernel: Kernel)

Bases: Kernel

Wraps a kernel \(G(x, y)\) and outputs \(x_j G(x, y)\) where \(x, y\) are targets and sources respectively.

axis: int

Coordinate axis with which to multiply the kernel.

mapper_method: ClassVar[str] = 'map_target_point_multiplier'

The name of the mapper method called for the kernel.

target_array_name: ClassVar[str] = 'targets'

class sumpy.kernel.ResultT

alias of TypeVar(‘ResultT’)

class sumpy.kernel.KernelMapper

Bases: Generic[ResultT]

__call__(kernel: Kernel) → ResultT

Call self as a function.

class sumpy.kernel.KernelCombineMapper

Bases: KernelMapper[ResultT], ABC

abstractmethod combine(values: Iterable[ResultT]) → ResultT

class sumpy.kernel.KernelIdentityMapper

Bases: KernelMapper[Kernel]

class sumpy.kernel.AxisSourceDerivativeRemover

Bases: KernelIdentityMapper

Removes all axis source derivatives from the kernel.

class sumpy.kernel.AxisTargetDerivativeRemover

Bases: KernelIdentityMapper

Removes all axis target derivatives from the kernel.

class sumpy.kernel.SourceDerivativeRemover

Bases: AxisSourceDerivativeRemover

Removes all source derivatives from the kernel.

class sumpy.kernel.TargetDerivativeRemover

Bases: AxisTargetDerivativeRemover

Removes all target derivatives from the kernel.

class sumpy.kernel.TargetTransformationRemover

Bases: TargetDerivativeRemover

Removes all target transformations from the kernel.

class sumpy.kernel.DerivativeCounter

Bases: KernelCombineMapper[int]

Counts the number of derivatives in the kernel.