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.ScalarKernel(dim: int)

Bases: ABC

Scalar 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() → ScalarKernel

Returns:

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

replace_base_kernel(new_base_kernel: ScalarKernel) → ScalarKernel

Returns:

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

get_pde_system_kernel() → tuple[SystemKernel, tuple[int, ...]]

Returns:

if the kernel is a component kernel of a SystemKernel, this returns the system kernel and the index of the kernel in that system.

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.

class sumpy.kernel.SystemKernel(dim: int)

Bases: ABC

A kernel representing a vector PDE.

mapper_method: ClassVar[str]

The name of the mapper method called for the kernel.

dim: int

Dimension of the space the kernel is defined in.

property ndim: int

The number of indices in the kernel tensor.

abstract property shape: tuple[int, ...]

The shape of the kernel tensor.

__getitem__(index: tuple[int, ...], /) → ScalarKernel

Returns:

the scalar kernel at index.

get_expression(dist_vec: MutableDenseMatrix) → ObjectArray[tuple[int, ...], Expr]

Returns:

a sympy expression for each component the kernel.

abstractmethod get_pde_as_diff_op() → LinearPDESystemOperator

Returns:

the PDE that this kernel satisfies (see ScalarKernel.get_pde_as_diff_op() as the scalar alternative).

Symbolic kernels

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

Bases: ScalarKernel, 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.

class sumpy.kernel.OneKernel(dim: int)

Bases: ExpressionKernel

mapper_method: ClassVar[str] = 'map_expression_kernel'

The name of the mapper method called for the kernel.

Scalar 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.StokesComponentKernelBase(dim: int, expression: Expression, global_scaling_const: Expression, viscosity_mu_name: str)

Bases: ExpressionKernel

Base class for kernels of the Stokes equations (see e.g. Chapter 2 in [Pozrikidis1992]).

viscosity_mu_name: str

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

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

Bases: StokesComponentKernelBase

The velocity 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.

mapper_method: ClassVar[str] = 'map_stokeslet_kernel'

The name of the mapper method called for the kernel.

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

Bases: StokesComponentKernelBase

The stress 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 StokesletComponentKernel. 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.

mapper_method: ClassVar[str] = 'map_stresslet_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.ElasticityComponentKernelBase(dim: int, expression: Expression, global_scaling_const: Expression, viscosity_mu_name: str, poisson_ratio_name: str)

Bases: ExpressionKernel

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

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.

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

Bases: ElasticityComponentKernelBase

The displacement 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.

mapper_method: ClassVar[str] = 'map_elasticity_kernel'

The name of the mapper method called for the kernel.

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

Bases: ElasticityComponentKernelBase

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

\[K_{ijk}(\mathbf{x}, \mathbf{y}) = \lambda \partial_l K_{kl}(\mathbf{x}, \mathbf{y}) \delta_{ij} + \mu (\partial_j K_{ik}(\mathbf{x}, \mathbf{y}) + \partial_i K_{jk}(\mathbf{x}, \mathbf{y})),\]

where the two-index \(K_{ij}\) is the ElasticityComponentKernel.

icomp: int

Component index for the kernel.

jcomp: int

Component index for the kernel.

kcomp: int

Component index for the kernel.

mapper_method: ClassVar[str] = 'map_elasticity_stress_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.BrinkmanComponentKernelBase(dim: int, expression: Expression, global_scaling_const: Expression, viscosity_mu_name: str, darcy_impermeability_name: str)

Bases: ExpressionKernel

Base class for the Brinkman equations.

viscosity_mu_name: str

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

darcy_impermeability_name: str

The argument name to use for the Darcy impermeability when generating functions to evaluate this kernel.

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

Bases: BrinkmanComponentKernelBase

The velocity 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.

icomp: int

Component index for the kernel.

jcomp: int

Component index for the kernel.

mapper_method: ClassVar[str] = 'map_brinkmanlet_kernel'

The name of the mapper method called for the kernel.

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

Bases: BrinkmanComponentKernelBase

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 BrinkmanletComponentKernel and \(P_j\) is the pressure kernel.

icomp: int

Component index for the kernel.

jcomp: int

Component index for the kernel.

kcomp: int

Component index for the 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.

\[\frac{\partial}{\partial t} K(t, \mathbf{x}, \mathbf{y}) - \alpha \Delta K(t, \mathbf{x}, \mathbf{y}) = \delta(t) \delta(\mathbf{x} - \mathbf{y})\]

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.

System PDE Kernels

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

Bases: SystemKernel

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

This kernel uses ElasticityComponentKernel for its components.

viscosity_mu_name: str = 'mu'

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

poisson_ratio_name: str = 'nu'

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

mapper_method: ClassVar[str] = 'map_elasticity_system_kernel'

The name of the mapper method called for the kernel.

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

Bases: SystemKernel

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

This kernel uses ElasticityStressComponentKernel for its components.

viscosity_mu_name: str = 'mu'

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

poisson_ratio_name: str = 'nu'

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

mapper_method: ClassVar[str] = 'map_elasticity_stress_system_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.StokesletSystemKernel(dim: int, viscosity_mu_name: str = 'mu')

Bases: SystemKernel

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

This kernel uses StokesletComponentKernel for its components.

viscosity_mu_name: str = 'mu'

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

mapper_method: ClassVar[str] = 'map_stokeslet_system_kernel'

The name of the mapper method called for the kernel.

class sumpy.kernel.StressletSystemKernel(dim: int, viscosity_mu_name: str = 'mu')

Bases: SystemKernel

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

This kernel uses StressletComponentKernel for its components.

viscosity_mu_name: str = 'mu'

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

mapper_method: ClassVar[str] = 'map_stresslet_system_kernel'

The name of the mapper method called for the kernel.

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

Bases: SystemKernel

A kernel for the Brinkman equations.

This kernel uses BrinkmanletComponentKernel for its components.

viscosity_mu_name: str = 'mu'

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

darcy_impermeability_name: str = 'k'

The argument name to use for the Darcy impermeability when generating functions to evaluate this kernel.

mapper_method: ClassVar[str] = 'map_brinkmanlet_system_kernel'

The name of the mapper method called for the kernel.

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

Bases: SystemKernel

A kernel for the Brinkman equations.

This kernel uses BrinkmanStressComponentKernel for its components.

viscosity_mu_name: str = 'mu'

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

darcy_impermeability_name: str = 'k'

The argument name to use for the Darcy impermeability when generating functions to evaluate this kernel.

mapper_method: ClassVar[str] = 'map_brinkman_stress_system_kernel'

The name of the mapper method called for the kernel.

[Pozrikidis1992] (1,2,3,4,5)

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

[Hsiao2008] (1,2,3,4,5)

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: ScalarKernel)

Bases: ScalarKernel

inner_kernel: ScalarKernel

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

abstractmethod replace_inner_kernel(new_inner_kernel: ScalarKernel) → ScalarKernel

Replace the inner kernel of this wrapper.

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

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

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: ScalarKernel)

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: ScalarKernel, 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: ScalarKernel, 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: ScalarKernel)

Bases: ScalarKernel

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: ScalarKernel) → 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[ScalarKernel]

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.