biem_helmholtz_sphere package¶

class biem_helmholtz_sphere.BIEMKwargs[source]¶

Bases: TypedDict

The kwargs for the BIEM.

centers: Array¶: The centers of the spheres. The first dimension corresponds to the vector of the centers. The second dimension corresponds to the number of the spheres. […, B, v]

eta: NotRequired[Array]¶: The decoupling parameter, by default 1. […]

force_matrix: NotRequired[bool]¶: Whether to use linear equation solver to compute the solution even if there is only one sphere, by default False.

k: Array¶: The wavenumber. […]

kind: NotRequired[Literal['inner', 'outer']]¶: The kind of the scattering problem, by default “outer”.

n_end: int¶: The maximum degree of the spherical harmonics expansion.

radii: Array¶: The radii of the spheres. The first dimension corresponds to the number of the spheres. […, B]

class biem_helmholtz_sphere.BIEMResultCalculator(*, c: SphericalCoordinates[TSpherical, TCartesian], uin: UinCallable | None = None, centers: Array, radii: Array, k: Array, n_end: int, eta: Array, kind: Literal['inner', 'outer'], density: Array | None = None, matrix: Array | None = None)[source]¶

Bases: BIEMResultCalculatorProtocol[TSpherical, TCartesian]

Callable that computes the BIEMResult at the given cartesian coordinates.

c: SphericalCoordinates[TSpherical, TCartesian]¶: The spherical coordinates system.

centers: Array¶: The centers of the spheres of shape (…, B, c.c_ndim).

density: Array | None¶: The flattened density of the BIEM of shape (…, B, harm).

eta: Array¶: The decoupling parameter.

k: Array¶: The wavenumber of shape (…).

kind: Literal['inner', 'outer']¶: The kind of the scattering problem.

matrix: Array | None¶: The flattened matrix of the BIEM of shape (…, B, harm, B’, harm’).

n_end: int¶: The maximum degree of the spherical harmonics expansion.

radii: Array¶: The radii of the spheres of shape (…, B).

uin: UinCallable | None¶: The incident field.

uscat(x: Array, /, far_field: bool = False, per_ball: bool = False, expand_x: bool = True) → Array[source]¶

Return the scattered field at the given cartesian coordinates.

Parameters:

x (Array) – The cartesian coordinates of shape (c.c_ndim, …(x), …(first)) if expand_x is True, or of shape (c.c_ndim, …(x)) if expand_x is False.
far_field (bool, optional) – Whether to compute the far field, by default False.
per_ball (bool, optional) – Whether to return the scattered field per ball, by default False. If False, the scattered field is summed over all balls.
expand_x (bool, optional) – Whether the input x has the …(first) dimensions, by default True. If False, the input x is assumed to have only …(x) dimensions.

Returns:

The scattered field of shape (…(x), …(first)) if per_ball is False, or of shape (…(x), …(first), B) if per_ball is True.

Return type:

Array

class biem_helmholtz_sphere.BIEMResultCalculatorProtocol(*args, **kwargs)[source]¶

Bases: Protocol, Generic

Callable that computes the BIEMResult at the given cartesian coordinates.

c: SphericalCoordinates¶: The spherical coordinates system.

centers: Array¶: The centers of the spheres of shape (…, B, c.c_ndim).

density: Array | None = None¶: The flattened density of the BIEM of shape (…, B, harm).

eta: Array¶: The decoupling parameter.

k: Array¶: The wavenumber of shape (…).

kind: Literal['inner', 'outer']¶: The kind of the scattering problem.

matrix: Array | None = None¶: The flattened matrix of the BIEM of shape (…, B, harm, B’, harm’).

n_end: int¶: The maximum degree of the spherical harmonics expansion.

radii: Array¶: The radii of the spheres of shape (…, B).

uin: UinCallable | None¶: The incident field.

uscat(x: Array, /, far_field: bool = False, per_ball: bool = False, expand_x: bool = True) → Array[source]¶

Return the scattered field at the given cartesian coordinates.

Parameters:

x (Array) – The cartesian coordinates of shape (c.c_ndim, …(x), …(first)) if expand_x is True, or of shape (c.c_ndim, …(x)) if expand_x is False.
far_field (bool, optional) – Whether to compute the far field, by default False.
per_ball (bool, optional) – Whether to return the scattered field per ball, by default False. If False, the scattered field is summed over all balls.
expand_x (bool, optional) – Whether the input x has the …(first) dimensions, by default True. If False, the input x is assumed to have only …(x) dimensions.

Returns:

The scattered field of shape (…(x), …(first)) if per_ball is False, or of shape (…(x), …(first), B) if per_ball is True.

Return type:

Array

class biem_helmholtz_sphere.UinCallable(*args, **kwargs)[source]¶

Bases: Protocol

Callable that computes the incident field at the given cartesian coordinates.

biem_helmholtz_sphere.biem(c: SphericalCoordinates, /, *, centers: Array, radii: Array, k: Array, n_end: int, alpha: Array | complex = 1.0, beta: Array | complex = 0.0, uin: Callable[[Array], Array] | None = None, uin_grad: Callable[[Array], Array] | None = None, eta: Array | None = None, kind: Literal['inner', 'outer'] = 'outer', force_matrix: bool = False, translational_coefficients_method: Literal['gumerov', 'plane_wave', 'triplet'] | None = None) → BIEMResultCalculator[source]¶

Boundary Integral Equation Method (BIEM) for the Helmholtz equation.

Let $d \in \mathbb{N} \setminus \lbrace 1 \rbrace$ be the dimension of the space, $k$ be the wave number, and $\mathbb{S}^{d-1} = \lbrace x \in \mathbb{R}^d \mid \|x\| = 1 \rbrace$ be a unit sphere in $\mathbb{R}^d$. Let $B := {0, ..., }$ be the index set of spheres, $c_b \in \mathbb{R}^d$ be the center of sphere $b \in B$, and $\rho_b > 0$ be the radius of sphere $b \in B$. Assume that the closure of spheres do not overlap, i.e.,

\[ \forall b, b' \in B, b \neq b', \|c_b - c_b'\| > \rho_b + \rho_b' \]

Asuume that $u_\text{in}$ is an incident wave satisfying the Helmholtz equation

$$ Delta u_text{in} + k^2 u_text{in} = 0 $$

and scattered wave $u$ satisfies the following:

$$ begin{cases} Delta u + k^2 u = 0 quad &x in mathbb{R}^d setminus overline{mathbb{S}^{d-1}} \ alpha u + beta nabla u cdot n_x = -alpha u_text{in} -beta nabla u_text{in} cdot n_x quad &x in mathbb{S}^{d-1} \ lim_{|x| to infty} |x|^{frac{d-1}{2}} left( frac{partial u}{partial |x|} - i k u right) = 0 quad &frac{x}{|x|} in mathbb{S}^{d-1} end{cases} $$

Forall $n \in \mathbb{N}_0$, let $\{Y_{n,p}\}_{p \in K(n)}$ be the orthnormal basis of $\mathcal{H}_n (\mathbb{S}^{d-1})$. Then, the scattered wave $u$ can be computed by solving the following linear equation for $\phi_{b',n',p'}$.

\[\begin{split} \newcommand\slc{\operatorname{slc}} \newcommand\dlc{\operatorname{dlc}} \newcommand\blc{\operatorname{blc}} \begin{aligned} \slc_n (\rho) &:= i k^{d-2} \rho^{d-1} j_n (k \rho) \\ \dlc_n (\rho) &:= i k^{d-1} \rho^{d-1} j_n' (k \rho) \\ \blc_n (\rho, \eta) &:= \slc_n (\rho) - i \eta \dlc_n (\rho) \\ A_{b,n,p,b',n',p'} &:= \blc_{n'} (\rho_{b'}, \eta) \times \begin{cases} \delta_{n,n'} \delta_{p,p'} (\alpha h^{(1)}_n (k \rho_b) + \beta {h}^{(1)}_n (k \rho_b)) & b = b' \\ (S|R)_{n',p',n,p} (c_b - c_b') (\alpha j_n (k \rho_b) + \beta j'_n (k \rho_b)) & b \neq b' \end{cases} \\ f_{b,n,p} &:= - \int_{\partial B_b} u_{in} (x) Y_{n,p} \left(\frac{x - c_b}{\|x - c_b\|}\right) dx = - \int_{\mathbb{S}^{d-1}} u_{in} (\rho_b y + c_b) Y_{n,p} (y) \rho_b^{d-1} dy \\ \sum_{b',n',p'} A_{b,n,p,b',n',p'} \phi_{b'n'p'} &= f_{b,n,p} \end{aligned} \end{split}\]

Parameters:

c (SphericalCoordinates[TSpherical, TCartesian]) – The spherical coordinates system.
uin (Callable[[Array], Array], optional) –
The incident field.

Given cartesian coordinates of shape (c.c_ndim, …(any), …), should return the incident field of shape (…(any), …)

Must satisfy the Helmholtz equation with wavenumber k.
uin_grad (Callable[[Array], Array], optional) –
The gradient of the incident field.

Given cartesian coordinates of shape (c.c_ndim, …(any), …), should return the gradient of the incident field of shape (c.c_ndim, …(any), …)
centers (Array) – The centers of the spheres of shape (…, B, c.c_ndim).
radii (Array) – The radii of the spheres of shape (…, B).
k (Array) – The wavenumber of shape (…).
n_end (int) – The maximum degree of the spherical harmonics expansion.
alpha (Array | complex, optional) – The coefficient of the Dirichlet part of the boundary condition of shape (…, B), by default 1.0.
beta (Array | complex, optional) – The coefficient of the Neumann part of the boundary condition of shape (…, B), by default 0.0.
eta (Array , optional) – The decoupling parameter of shape (…), by default 1.
kind (Literal["inner", "outer"], optional) – The kind of the scattering problem, by default “outer”.
force_matrix (bool, optional) – Whether to use linear equation solver to compute the solution even if there is only one sphere, by default False.
translational_coefficients_method (Literal["gumerov", "plane_wave", "triplet"] | None) – The method to compute the translation coefficients. If None, the fastest method is chosen automatically. “gumerov” is only available for branching type “ba”. “plane_wave” is only available when is_type_same is True.

Returns:

The function that computes the incident and scattered fields at the given spherical coordinates.

Return type:

BIEMResultCalculator

biem_helmholtz_sphere.max_memory(*, c_ndim: int, n_end: int, n_balls: int) → int[source]¶

Maximum memory usage in bytes.

Parameters:

c_ndim (int) – The number of cartesian dimensions.
n_end (int) – The maximum degree of the spherical harmonics expansion.
n_balls (int) – The number of balls.

Returns:

The maximum memory usage in bytes.

Return type:

int

biem_helmholtz_sphere.max_n_end(*, c_ndim: int, memory_limit: int, n_balls: int) → int[source]¶

Maximum n_end that fits in the given memory limit.

Parameters:

c_ndim (int) – The number of cartesian dimensions.
memory_limit (int) – The memory limit in bytes.
n_balls (int) – The number of balls.

Returns:

The maximum n_end.

Return type:

int

biem_helmholtz_sphere.plane_wave(*, k: Array, direction: Array) → tuple[Callable[[Array], Array], Callable[[Array], Array]][source]¶

Plane wave.

\[ d := \frac{\text{direction}}{\|\text{direction}\|} \]

\[ u (x) := e^{i k d \cdot x} \]

Parameters:

k (Array) – The wavenumber of shape (…).
direction (Array) –
The direction of the plane wave of shape (c.c_ndim, …).

Will be normalized.

Returns:

Callable[[Array], Array] – Given cartesian coordinates of shape (c.c_ndim, …(any), …), returns the incident field of shape (…(any), …)
Callable[[Array], Array] – Given cartesian coordinates of shape (c.c_ndim, …(any), …), returns the gradient of the incident field of shape (c.c_ndim, …(any), …)

biem_helmholtz_sphere.point_source(*, k: Array, source: Array, n: int) → tuple[Callable[[Array], Array], Callable[[Array], Array]][source]¶

Point source.

\[ u (x) := h^{(1)}_n (k \|x - \text{source}\|) \]

Parameters:

k (Array) – The wavenumber of shape (…).
source (Array) – The position of the point source of shape (c.c_ndim, …).
n (int) – The order of the Hankel function.

Returns:

Callable[[Array], Array] – Given cartesian coordinates of shape (c.c_ndim, …(any), …), returns the incident field of shape (…(any), …)
Callable[[Array], Array] – Given cartesian coordinates of shape (c.c_ndim, …(any), …), returns the gradient of the incident field of shape (c.c_ndim, …(any), …)

Submodules¶

biem_helmholtz_sphere.bempp_cl_sphere module¶

biem_helmholtz_sphere.bempp_cl_sphere.bempp_cl_sphere(*, k: float, h: float, centers: Sequence[Sequence[float]], radii: Sequence[float], alpha: complex = 1.0, beta: complex = 0.0) → Callable[[ndarray[tuple[Any, ...], dtype[Any]], ndarray[tuple[Any, ...], dtype[Any]], ndarray[tuple[Any, ...], dtype[Any]]], ndarray[tuple[Any, ...], dtype[Any]]][source]¶

Calculate the scattered field by multiple spheres using bempp-cl.

Uses OBIE, not Burton-Miller formulation.

Parameters:

k (float) – The wavenumber.
h (float) – The element size for the mesh.
centers (Sequence[Sequence[float]]) – The centers of the spheres of shape (B, 3).
radii (Sequence[float]) – The radii of the spheres of shape (B,).
alpha (complex, optional) – The coefficient for the dirichlet part, by default 1.0
beta (complex, optional) – The coefficient for the neumann part, by default 0.0

Returns:

A function that takes x, y, z coordinates and returns the scattered field at those points.

Return type:

Callable[[NDArray[Any], NDArray[Any], NDArray[Any]], NDArray[Any]]

biem_helmholtz_sphere.cli module¶

biem_helmholtz_sphere.gui module¶

biem_helmholtz_sphere.plot module¶

biem_helmholtz_sphere.plot.plot_biem(biem_res: BIEMResultCalculator[Any, Any], /, *, plot_uin: bool = True, plot_uscateach: bool | Sequence[bool] = True, xspace: tuple[float, float, int] | None = None, yspace: tuple[float, float, int] | None = None, n_t: int = 1, xaxis: int = 0, yaxis: int = 1, log: bool = False, **plot_kwargs: Any) → Figure[source]¶

Plot the results of a BIEM calculation.

Parameters:

biem_res (BIEMResult) – The result of a BIEM calculation.
plot_uin (bool, optional) – Whether to plot the input field, by default True
plot_uscateach (bool | Sequence[bool], optional) – Whether to plot the scattered field for each frequency, by default True
xspace (tuple[float, float, int], optional) – The linspace arguments for the x-axis, by default None
yspace (tuple[float, float, int], optional) – The linspace arguments for the y-axis, by default None
n_t (int, optional) – The number of time steps, by default 1
xaxis (int, optional) – The x-axis index, by default 0
yaxis (int, optional) – The y-axis index, by default 1
log (bool, optional) – Whether to use logarithmic scaling for the color axis, by default False Useful for plotting resonance fields because they diverges as |x| -> ∞.
plot_kwargs (Any, optional) – Additional arguments to pass to plotly express scatter, by default None See https://plotly.com/python-api-reference/generated/plotly.express.scatter.html for more information.

Returns:

The plotly figure.

Return type:

Figure

biem_helmholtz_sphere.plot.plot_biem_far(biem_res: BIEMResultCalculator[Any, Any], /, *, plot_uscateach: bool | Sequence[bool] = True, n_points: int = 100, xaxis: int = 0, yaxis: int = 1, **plot_kwargs: Any) → Figure[source]¶

Plot the far-field results of a BIEM calculation.

Parameters:

biem_res (BIEMResult) – The result of a BIEM calculation.
plot_uscateach (bool | Sequence[bool], optional) – Whether to plot the scattered field for each frequency, by default True
n_points (int, optional) – The number of theta points, by default 100
xaxis (int, optional) – The x-axis index, by default 0
yaxis (int, optional) – The y-axis index, by default 1
plot_kwargs (Any, optional) – Additional arguments to pass to plotly express scatter, by default None See https://plotly.com/python-api-reference/generated/plotly.express.scatter.html for more information.

Returns:

The plotly figure.

Return type:

Figure