Core

flooder.core

Implementation of flooder core functionality.

flood_complex

flood_complex(
    points: Tensor,
    landmarks: Union[int, Tensor],
    max_dimension: Union[None, int] = None,
    points_per_edge: Union[None, int] = 30,
    num_rand: int = None,
    batch_size: Union[None, int] = 256,
    use_triton: bool = True,
    return_simplex_tree: bool = False,
    fps_h: Union[None, int] = None,
    start_idx: Union[int, None] = 0,
) -> Union[dict, gudhi.SimplexTree]

Constructs a Flood complex from a set of witness points and landmarks.

Parameters:

Name	Type	Description	Default
`points`	`Tensor`	A (N, d) tensor containing witness points used as sources in the flood process.	required
`landmarks`	`Union[int, Tensor]`	Either an integer indicating the number of landmarks to randomly sample from `points`, or a tensor of shape (N_l, d) specifying explicit landmark coordinates.	required
`max_dimension`	`Union[None, int]`	The top dimension of the simplices to construct. Defaults to None resulting in the dimension of the ambient space.	`None`
`points_per_edge`	`Union[None, int]`	Specifies resolution on simplices used for computing filtration values. Tradeoff in accuracy vs. speed. Defaults to 30.	`30`
`num_rand`	`Union[None, int]`	If specified, filtration values are computed from a fixed number of random points per simplex. Defaults to None.	`None`
`batch_size`	`int`	Number of simplices to process per batch. Defaults to 32.	`256`
`use_triton`	`bool`	If True, Triton kernel is used. Defaults to True.	`True`
`fps_h`	`Union[None, int]`	h parameter (depth of kdtree) that is used for farthest point sampling to select the landmarks. If None, then h is selected based on the size of the point cloud. Defaults to None.	`None`
`return_simplex_tree`	`bool`	I true, a gudhi.SimplexTree is returned, else a dictionary. Defaults to False	`False`
`start_idx`	`int \| None`	If provided, FPS starts from this index in the point cloud. If not, the start index will be randomly picked from the point cloud. Defaults to 0.	`0`

Returns:

Type	Description
`Union[dict, SimplexTree]`	Union[dict, gudhi.SimplexTree] Depending on the return_simplex_tree argument either a gudhi.SimplexTree or a dictionary is returned, mapping simplices to their estimated covering radii (i.e., filtration value). Each key is a tuple of landmark indices (e.g., (i, j) for an edge), and each value is a float radius.

generate_grid

generate_grid(
    n: int, dim: int, device: device
) -> Tuple[
    torch.Tensor, List[torch.Tensor], List[torch.Tensor]
]

Generates a grid of points on the unit simplex based on the number of points per edge.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of points per edge.	required
`dim`	`int`	Dimension of the simplex.	required
`device`	`device`	Device to create the tensors on.	required

Returns:

Name	Type	Description
`tuple`	`Tuple[Tensor, List[Tensor], List[Tensor]]`	grid (torch.Tensor): Tensor of shape (C, dim + 1), containing the grid points (coordinate weights). vertex_ids (list of torch.Tensor): A list of tensors, each containing the vertex indices for each face. face_ids (list of torch.Tensor): A list of tensors, each containing the face indices for each face.

generate_landmarks

generate_landmarks(
    points: Tensor,
    n_lms: int,
    fps_h: Union[None, int] = None,
    start_idx: Union[int, None] = None,
) -> torch.Tensor

Selects landmarks using Farthest-Point Sampling (bucket FPS).

This method implements a variant of Farthest-Point Sampling from here.

Parameters:

Name	Type	Description	Default
`points`	`Tensor`	A (P, d) tensor representing a point cloud. The tensor may reside on any device (CPU or GPU) and be of any floating-point dtype.	required
`n_lms`	`int`	The number of landmarks to sample (must be <= P and > 0).	required
`fps_h`	`Union[None, int]`	h parameter (depth of kdtree) that is used for farthest point sampling to select the landmarks. If None, then h is selected based on the size of the point cloud. Defaults to None.	`None`
`start_idx`	`int \| None`	If provided, the sampling starts from this index in the point cloud. If not, the start index will be randomly picked from the point cloud.	`None`

Returns:

Type	Description
`Tensor`	torch.Tensor: A (n_l, d) tensor containing a subset of the input `points`, representing the sampled landmarks. Returned tensor is on the same device and has the same dtype as the input.

generate_uniform_weights

generate_uniform_weights(num_rand, dim, device)

Generates num_rand points from a uniform distribution on the unit simplex.

Parameters:

Name	Type	Description	Default
`num_rand`	`int`	Number of random points to generate.	required
`dim`	`int`	Dimension of the simplex.	required
`device`	`device`	Device to create the tensor on.	required

Returns: torch.Tensor: A tensor of shape [num_rand, dim + 1] containing the random points (coordinate weights).