sparseSpatialSampling.s_cube module

Implementation of the sparse spatial sampling algorithm (\(S^3\)) for 2D and 3D CFD data.

class sparseSpatialSampling.s_cube.Cell(index, parent, nb, center, level, children=None, metric=None, gain=None, dimensions=2, node_idx=None)[source]

Bases: object

Initialize a cell object.

Note

All cells are rectangular (len_x == len_y == len_z). Each cell has attributes describing its position, refinement level, neighbors, and metric values.

Parameters:

  • index (int) – Index of the cell (cell number)

  • parent (Cell | None) – Parent cell from which this cell was derived

  • nb (list[Cell]) – List of neighboring cells

  • center (pt.Tensor) – Coordinates of the cell center

  • level (int) – Refinement level (how many times an initial cell must be divided to obtain this cell)

  • children (list[Cell] | None) – Child cells of this cell, if any

  • metric (float | None) – Prediction for the metric made by the KNN based on the cell centers

  • gain (float | None) – Value indicating the benefit from refining this cell

  • dimensions (int) – Number of physical dimensions (2 for 2D, 3 for 3D)

  • node_idx (list[int] | None) – Indices of the cell’s vertices

Returns:

None

Return type:

None

leaf_cell()[source]

Check if the cell is a leaf cell (i.e., has no children).

Returns:

True if the cell has no children, False otherwise

Return type:

bool

class sparseSpatialSampling.s_cube.SamplingTree(vertices, target, geometry_obj, n_cells=None, uniform_level=5, min_metric=0.75, max_delta_level=False, n_cells_iter_start=None, n_cells_iter_end=None, n_jobs=1, relTol=0.001, reach_at_least=0.75, pre_select=False)[source]

Bases: object

Initialize a sampling tree for sparse spatial refinement (\(S^3\)).

This class sets up the KNN-based prediction, refinement parameters, and creates the initial root cell. The root cell is then refined iteratively using the refine methods to generate an adaptive grid based on the target metric.

Parameters:

  • vertices (pt.Tensor) – Node coordinates of the original mesh (from CFD)

  • target (pt.Tensor) – Metric that guides the grid refinement (e.g., standard deviation of pressure with respect to time)

  • geometry_obj (list[dict] | list[Geometry]) – List of geometry objects defining the computational domain

  • n_cells (int | None) – Maximum number of cells; if None, refinement stops automatically when the target metric is reached

  • uniform_level (int) – Number of uniform refinement cycles to perform before adaptive refinement

  • min_metric (float) – Minimum percentage of the target metric that the generated grid should capture relative to the original mesh; if None, the maximum number of cells is used as the stopping criterion

  • max_delta_level (bool) – If True, enforce that adjacent cells differ by at most one refinement level, which is important for computing gradients across cells

  • n_cells_iter_start (int | None) – Number of cells to refine per iteration at the beginning

  • n_cells_iter_end (int | None) – Number of cells to refine per iteration at the end

  • n_jobs (int | None) – Number of CPUs to use; if None, all available CPUs will be used

  • relTol (int | float) – Minimum improvement required between two consecutive iterations

  • reach_at_least (float) – Minimum percentage of the target metric or number of cells to reach before activating the relTol stopping criterion

  • pre_select (bool) – Optimization for geometry objects (e.g., GeometrySTL3D or GeometryCoordinates2D) that reduces runtime when most cells are expected to be outside the geometry’s bounding box

Returns:

None

Return type:

None

property geometry: list

Return a list of all geometry objects stored in \(S^3\).

Returns:

List of geometry objects

Return type:

list

property n_dimensions: int

Get the number of physical dimensions of the mesh.

Returns:

Number of dimensions (2 for 2D, 3 for 3D)

Return type:

int

refine()[source]

Generate the metric-based grid based on the original grid and the specified metric.

Returns:

None

Return type:

None

property width: torch.Tensor

Return the width of the initial cell along its largest dimension.

Returns:

Tensor containing the cell widths

Return type:

pt.Tensor

sparseSpatialSampling.s_cube.check_nb_node(_cell, nb_no)[source]

Check whether a specific neighbor of a cell exists, is a leaf cell, and has the same refinement level.

This check is performed after neighbors have been updated but before assigning node indices, to ensure neighbor consistency is maintained.

Parameters:

  • _cell (Cell) – The current cell to check

  • nb_no (int) – Index of the neighbor to check in the cell’s neighbor list

Returns:

True if the neighbor exists, is a leaf cell, and has the same level; False otherwise

Return type:

bool

sparseSpatialSampling.s_cube.parent_or_child(nb, check, nb_idx, child_idx)[source]

Retrieve the neighbor cell of a newly created child cell.

If the parent neighbor has children, return the appropriate child; otherwise, return the parent neighbor itself.

Parameters:

  • nb (list[Cell]) – List of neighbor cells of the current parent cell

  • check (bool) – Flag indicating whether the current parent cell has children

  • nb_idx (int) – Index of the neighbor to check

  • child_idx (int) – Index of the possible child, which may be the neighbor of the current child cell

Returns:

The neighbor child cell if present; otherwise, the parent neighbor cell

Return type:

Cell

sparseSpatialSampling.s_cube.renumber_node_indices_parallel(all_idx, all_nodes, unused_idx, dims)

Remove unused nodes and their corresponding coordinates, and re-number the remaining node indices.

This is a parallelized version for improved performance on large grids.

Parameters:

  • all_idx (np.ndarray) – Array containing all node indices used within the grid

  • all_nodes (np.ndarray) – Array of all node coordinates created during the refinement process

  • unused_idx (set[int]) – Set of node indices that are no longer present in the final grid

  • dims (int) – Number of physical dimensions (2 for 2D, 3 for 3D)

Returns:

  • Array of unique node coordinates used in the final grid

  • Array of re-numbered node indices pointing to these coordinates

Return type:

Tuple[np.ndarray, np.ndarray]