volumential.gaussian

Gaussian source fixtures and exports for free-space volume-potential demos.

class volumential.gaussian.GaussianComponent(amplitude: float, center: tuple[float, ...], alpha: float)

Bases: object

One isotropic Gaussian component amplitude * exp(-alpha * |x-c|^2).

amplitude: float

center: tuple[float, ...]

alpha: float

property dim: int

Spatial dimension of this component.

as_metadata() → dict[str, Any]

Return a JSON-friendly description of this component.

class volumential.gaussian.GaussianMixture(name: str, components: tuple[GaussianComponent, ...])

Bases: object

A named collection of compatible GaussianComponent objects.

name: str

components: tuple[GaussianComponent, ...]

property dim: int

Common spatial dimension of the mixture’s components.

as_metadata() → dict[str, Any]

Return a JSON-friendly description of this mixture.

volumential.gaussian.default_overlapping_gaussian_mixture(dim: int = 3) → GaussianMixture

Return a deterministic positive overlapping mixture for smoke demos.

volumential.gaussian.evaluate_gaussian_mixture(mixture: GaussianMixture, points: ndarray) → ndarray

Evaluate the source density at points.

volumential.gaussian.evaluate_gaussian_laplacian_power(mixture: GaussianMixture, points: ndarray, *, order: int) → ndarray

Evaluate Delta**order of an isotropic Gaussian mixture.

Orders through three are provided because the fourth-order DMK residual effective-density correction needs Delta rho, Delta**2 rho, and Delta**3 rho for a Gaussian source.

volumential.gaussian.dmk_gaussian_split_sigma(box_side_length: float, epsilon: float) → float

Return the DMK-style Gaussian split scale for one box level.

Jiang–Greengard DMK chooses a Gaussian kernel-splitting scale proportional to r_l / sqrt(log(1/epsilon)) for box side length r_l and requested precision epsilon. This helper records that normalization for controlled diagnostics; it does not include the separate residual sum-of-Gaussians fit.

volumential.gaussian.gaussian_filter_mixture(mixture: GaussianMixture, sigma: float) → GaussianMixture

Convolve mixture with a normalized isotropic Gaussian filter.

The filter is

gamma_sigma(x) = (2*pi*sigma**2)^(-d/2) exp(-|x|**2/(2*sigma**2))

and has Fourier multiplier exp(-sigma**2 |k|**2 / 2) under the convention where the 3D Laplace Green’s function 1/(4*pi*r) has multiplier 1/|k|**2. Convolving each A exp(-alpha |x-c|^2) component preserves its mass and maps it to another Gaussian with

alpha_eff = alpha / (1 + 2 alpha sigma**2).

volumential.gaussian.laplace3d_gaussian_potential(mixture: GaussianMixture, points: ndarray, *, kernel_scale: float = 1.0) → ndarray

Evaluate the full-space 3D Laplace potential of mixture.

The default kernel_scale=1 gives the unnormalized kernel K(x, y) = 1 / |x-y|. Use kernel_scale=1/(4*pi) for the classical Green’s function normalization used by Sumpy’s 3D Laplace global scaling.

volumential.gaussian.gaussian_mixture_tail_report(mixture: GaussianMixture, bbox: ndarray) → dict[str, Any]

Report signed and absolute Gaussian mass omitted outside bbox.

class volumential.gaussian.SliceGrid(points: ndarray, shape: tuple[int, int], axes: tuple[int, int], fixed_axis: int, fixed_value: float, axis_values: tuple[ndarray, ndarray])

Bases: object

A 2D Cartesian grid embedded in a 3D box, with its axis metadata.

points: ndarray

shape: tuple[int, int]

axes: tuple[int, int]

fixed_axis: int

fixed_value: float

axis_values: tuple[ndarray, ndarray]

volumential.gaussian.axis_aligned_slice_grid(bbox: ndarray, *, fixed_axis: int = 2, fixed_value: float = 0.0, axes: tuple[int, int] | None = None, shape: tuple[int, int] = (64, 64)) → SliceGrid

Create a 2D Cartesian slice grid embedded in a 3D bounding box.

volumential.gaussian.nearest_axis_slice(points: ndarray, fields: dict[str, ndarray] | None = None, *, axis: int = 2, value: float = 0.0, atol: float | None = None) → dict[str, Any]

Extract nodes on the plane nearest to points[:, axis] == value.

volumential.gaussian.mesh_leaf_box_arrays(mesh: Any) → dict[str, ndarray]

Return host arrays describing the active leaf boxes of a Volumential mesh.

volumential.gaussian.write_json_metadata(path: Path, metadata: dict[str, Any]) → None

Write JSON metadata with NumPy values converted to plain Python values.

volumential.gaussian.write_npz(path: Path, **arrays: ndarray) → None

Write NumPy arrays, creating the parent directory when needed.