Point Cloud

Core SPH operations and PointCloud class for particle-based computations.

class smudgy.pointcloud.PointCloud(positions: ndarray[tuple[Any, ...], dtype[floating]], weights: ndarray[tuple[Any, ...], dtype[floating]] | None = None, boxsize: float | Sequence[float] | None = None, verbose: bool = True)[source]

Bases: object

Represent a collection of particles for operations.

global_setup(structure: Literal['separable', 'isotropic', 'anisotropic'] | None = None, kernel_name: str | None = None, num_neighbors: int | None = None) → PointCloud[source]

Set global parameters for SPH computations.

Parameters:

  • structure (Structure, optional) – Smoothing structure (‘separable’, ‘isotropic’, or ‘anisotropic’).

  • kernel_name (str, optional) – Name of the SPH kernel to use globally.

  • num_neighbors (int, optional) – Number of neighbors for smoothing length computation.

Returns:

The current instance for method chaining.

Return type:

PointCloud

compute_smoothing(query_positions: ArrayLike | None = None, num_neighbors: int | None = None, structure: Literal['separable', 'isotropic', 'anisotropic'] | None = None) → None[source]

Compute smoothing lengths for SPH calculations.

Parameters:

  • query_positions (npt.ArrayLike, optional) – Positions where smoothing is evaluated. If None, uses particle positions.

  • num_neighbors (int, optional) – Number of neighbors for smoothing length computation.

  • structure (Structure, optional) – Smoothing structure for computation.

Return type:

None

Notes

Results are stored in the smoothing attribute.

set_smoothing(structure: Literal['separable', 'isotropic', 'anisotropic'] | None = None, smoLens: ArrayLike | None = None, smoTens: ArrayLike | None = None, smoTens_eigvals: ArrayLike | None = None, smoTens_eigvecs: ArrayLike | None = None) → None[source]

Manually assign smoothing lengths or tensors to particles.

Parameters:

  • structure (Structure, optional) – Smoothing structure. Required if setting smoLens or smoTens.

  • smoLens (npt.ArrayLike, optional) – Isotropic smoothing lengths, shape (N,).

  • smoTens (npt.ArrayLike, optional) – Anisotropic smoothing tensors, shape (N, D, D).

  • smoTens_eigvals (npt.ArrayLike, optional) – Eigenvalues of the smoothing tensors, shape (N, D).

  • smoTens_eigvecs (npt.ArrayLike, optional) – Eigenvectors of the smoothing tensors, shape (N, D, D).

add_fields(names: str | list[str], values: ArrayLike | list[ArrayLike]) → None[source]

Add one or multiple custom fields to the PointCloud instance.

Parameters:

  • names (str or list of str) – Name(s) of the field(s) to add.

  • values (array_like or list of array_like) – Field values. Each array must have shape (N,) or (N, num_components).

delete_fields(names: str | list[str]) → None[source]

Delete one or multiple custom fields from the PointCloud instance.

Parameters:

names (str or list of str) – Name(s) of the field(s) to delete.

compute_density(kernel_name: str | None = None, structure: Literal['separable', 'isotropic', 'anisotropic'] | None = None) → None[source]

Compute particle densities using SPH kernels.

Parameters:

  • kernel_name (str, optional) – Name of the SPH kernel to use for density computation.

  • structure (Structure, optional) – Smoothing structure specifier.

Notes

Results are stored in the smoothing attribute.

interpolate_fields(fields: ArrayLike | str | list[str], query_positions: ArrayLike = None, compute_gradients: bool = False, structure: Literal['separable', 'isotropic', 'anisotropic'] | None = None) → ndarray[tuple[Any, ...], dtype[floating]][source]

Interpolate particle fields to query positions using SPH.

Parameters:

  • fields (Union[npt.ArrayLike, str, List[str]]) – Field data to interpolate. Can be an array, string name, or list of both.

  • query_positions (npt.ArrayLike, optional) – Array of shape (M, D) with positions where fields are interpolated.

  • compute_gradients (bool, default False) – Whether to compute field gradients instead of values.

  • structure (Structure, optional) – Smoothing structure for interpolation.

Returns:

Interpolated field values (shape M, F) or gradients (shape M, F, D).

Return type:

npt.NDArray[np.floating]

interpolate_gradient_fields(fields: ArrayLike, query_positions: ArrayLike, structure: Literal['separable', 'isotropic', 'anisotropic'] | None = None) → ndarray[tuple[Any, ...], dtype[floating]][source]

Compute gradients of particle fields at query positions using SPH.

Parameters:

  • fields (npt.ArrayLike) – Field data to differentiate.

  • query_positions (npt.ArrayLike) – Positions where gradients are evaluated.

  • structure (Structure, optional) – Smoothing structure for interpolation.

Returns:

Interpolated field gradients, shape (M, F, D).

Return type:

npt.NDArray[np.floating]

deposit_to_grid(fields: ArrayLike | str | list[str], averaged: bool | Sequence[bool], gridnums: int | Sequence[int], extent: Sequence[Sequence[float]] | None = None, kernel_name: str | None = None, structure: Literal['separable', 'isotropic', 'anisotropic'] | None = None, adaptive: bool = True, plane_projection: list[int] | None = None, plane_projection_basis: list[Sequence[float] | ndarray[tuple[Any, ...], dtype[float32]]] | None = None, integration_method: str = 'midpoint', num_kernel_evaluations_per_axis: int = 4, eta_crit: float = 1.0, return_weights: bool = False, use_python: bool = False, use_openmp: bool = True, omp_threads: int | None = None) → ndarray[tuple[Any, ...], dtype[floating]] | tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]][source]

Deposit particle fields onto a structured grid using SPH.

Parameters:

  • fields (Union[npt.ArrayLike, str, List[str]]) – Field data to deposit.

  • averaged (Union[bool, Sequence[bool]]) – Whether to divide the result by weights for each field component.

  • gridnums (Union[int, Sequence[int]]) – Number of cells along each axis.

  • extent (Optional[Sequence[Sequence[float]]], optional) – Domain bounds [[xmin, xmax], [ymin, ymax], …]. If None, uses boxsize.

  • kernel_name (str, optional) – SPH kernel name.

  • structure (Structure, optional) – Smoothing structure for deposition.

  • adaptive (bool, default False) – Whether to use adaptive smoothing from the instance.

  • plane_projection (List[int], optional) – Indices of the axes to project onto for 3D to 2D deposition.

  • plane_projection_basis (List[Sequence[float] | npt.NDArray[np.float32]], optional) – This feature is currently not supported. Placeholder for future functionality to specify a custom projection basis.

  • integration_method (str, default 'midpoint') – Kernel integration method.

  • num_kernel_evaluations_per_axis (int, default 4) – Resolution for kernel integration.

  • eta_crit (float, default 1.0) – Anti-aliasing threshold to switch from sampled to full numerical quadrature.

  • return_weights (bool, default False) – If True, returns the weights (density) grid as well.

  • use_python (bool, default False) – Whether to force the Python instead of the C++ backend.

  • use_openmp (bool, default True) – Whether to use multi-threading in the C++ backend.

  • omp_threads (int, optional) – Number of threads for OpenMP.

Returns:

Deposited field grid, and optionally the weights grid.

Return type:

Union[npt.NDArray[np.floating], tuple[npt.NDArray[np.floating], npt.NDArray[np.floating]]]