"""Public protocols for influence-kernel implementations."""
from __future__ import annotations
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import TypeVar
from buffalo_panel.families.element_family import ElementFamily
from buffalo_panel.geometry.line2d import LineKernelGeometry2D
from buffalo_panel.type_aliases import FloatArray, FloatInput
GeometryT = TypeVar("GeometryT", bound=LineKernelGeometry2D)
[docs]
@dataclass(frozen=True, slots=True)
class KernelEvaluationOptions:
"""
Runtime options for evaluating influence kernels.
These options describe the evaluation convention selected by a formulation
or post-processing path.
They are intentionally separate from the registry key because they do not
change the mathematical kernel identity or implementation backend.
"""
top: bool = True
"""
Select the upper-side branch value for targets on a panel branch cut.
Use ``top=True`` for exterior-side surface velocity, pressure, and field
recovery conventions.
Formulations that enforce an interior-side velocity condition may select
``top=False`` when assembling the corresponding influence blocks.
"""
[docs]
class ElementKernel[GeometryT: LineKernelGeometry2D](ABC):
"""
Base class for element influence kernels.
Concrete kernels override the block-building methods that are supported by
their singularity, basis, and backend.
Unsupported methods raise ``NotImplementedError`` from this base class so
a failure points to the requested operation on the concrete kernel object.
"""
[docs]
@abstractmethod
def build_normal_block(
self,
family: ElementFamily,
geometry: GeometryT,
options: KernelEvaluationOptions,
) -> FloatArray:
"""Build one normal-velocity influence block.
Parameters
----------
family : ElementFamily
Source element family whose family-local coefficients define the
block columns.
geometry : LinePanelGeometry2D
Two-dimensional line-panel geometry that defines the target
collocation points, panel normals, and source panel coordinates.
options : KernelEvaluationOptions
Runtime evaluation convention.
Returns
-------
FloatArray
Normal-velocity influence block with one row per target panel and
one or more columns per family-local coefficient, depending on the
family's basis and degree-of-freedom layout.
"""
[docs]
@abstractmethod
def build_tangent_block(
self,
family: ElementFamily,
geometry: GeometryT,
options: KernelEvaluationOptions,
) -> FloatArray:
"""Build one tangential-velocity influence block.
Parameters
----------
family : ElementFamily
Source element family whose family-local coefficients define the
block columns.
geometry : LinePanelGeometry2D
Two-dimensional line-panel geometry that defines the target
collocation points, panel tangents, and source panel coordinates.
options : KernelEvaluationOptions
Runtime evaluation convention.
Returns
-------
FloatArray
Tangential-velocity influence block with one row per target panel
and one or more columns per family-local coefficient, depending on
the family's basis and degree-of-freedom layout.
"""
[docs]
@abstractmethod
def build_potential_block(
self,
family: ElementFamily,
geometry: GeometryT,
options: KernelEvaluationOptions,
) -> FloatArray:
"""Build one velocity-potential influence block.
Parameters
----------
family : ElementFamily
Source element family whose family-local coefficients define the
block columns.
geometry : LinePanelGeometry2D
Two-dimensional line-panel geometry that defines the target
collocation points and source panel coordinates.
options : KernelEvaluationOptions
Runtime evaluation convention.
Returns
-------
FloatArray
Potential influence block with one row per target panel and one or
more columns per family-local coefficient, depending on the
family's basis and degree-of-freedom layout.
"""
[docs]
@abstractmethod
def build_stream_function_block(
self,
family: ElementFamily,
geometry: GeometryT,
options: KernelEvaluationOptions,
) -> FloatArray:
"""Build one stream-function influence block.
Parameters
----------
family : ElementFamily
Source element family whose family-local coefficients define the
block columns.
geometry : LinePanelGeometry2D
Two-dimensional line-panel geometry that defines the target
collocation points and source panel coordinates.
options : KernelEvaluationOptions
Runtime evaluation convention.
Returns
-------
FloatArray
Stream-function influence block with one row per target panel and
one or more columns per family-local coefficient, depending on the
family's basis and degree-of-freedom layout.
"""
[docs]
@abstractmethod
def build_field_velocity_blocks(
self,
family: ElementFamily,
geometry: GeometryT,
x: FloatInput,
y: FloatInput,
options: KernelEvaluationOptions,
) -> tuple[FloatArray, FloatArray]:
"""Build global velocity-component influence blocks at field points.
Parameters
----------
family : ElementFamily
Source element family whose family-local coefficients define the
block columns.
geometry : LinePanelGeometry2D
Two-dimensional line-panel geometry that defines the source panel
coordinates.
x : FloatInput
Field-point x-coordinates.
y : FloatInput
Field-point y-coordinates.
options : KernelEvaluationOptions
Runtime evaluation convention.
Returns
-------
FloatArray
X-velocity influence block with one column per family-local
coefficient.
FloatArray
Y-velocity influence block with one column per family-local
coefficient.
"""
[docs]
@abstractmethod
def build_field_potential_block(
self,
family: ElementFamily,
geometry: GeometryT,
x: FloatInput,
y: FloatInput,
options: KernelEvaluationOptions,
) -> FloatArray:
"""
Build velocity-potential influence blocks at field points.
Parameters
----------
family : ElementFamily
Source element family whose family-local coefficients define the
block columns.
geometry : LinePanelGeometry2D
Two-dimensional line-panel geometry that defines the source panel
coordinates.
x : FloatInput
Field-point x-coordinates.
y : FloatInput
Field-point y-coordinates.
options : KernelEvaluationOptions
Runtime evaluation convention.
Returns
-------
FloatArray
Velocity-potential influence block with one column per
family-local coefficient.
"""
[docs]
@abstractmethod
def build_field_stream_function_block(
self,
family: ElementFamily,
geometry: GeometryT,
x: FloatInput,
y: FloatInput,
options: KernelEvaluationOptions,
) -> FloatArray:
"""
Build stream-function influence blocks at field points.
Parameters
----------
family : ElementFamily
Source element family whose family-local coefficients define the
block columns.
geometry : LinePanelGeometry2D
Two-dimensional line-panel geometry that defines the source panel
coordinates.
x : FloatInput
Field-point x-coordinates.
y : FloatInput
Field-point y-coordinates.
options : KernelEvaluationOptions
Runtime evaluation convention.
Returns
-------
FloatArray
Stream-function influence block with one column per
family-local coefficient.
"""