Synthetic data generators

flooder.synthetic_data_generators

Implementation of synthetic data generators.

generate_annulus_points_2d

generate_annulus_points_2d(
    n: int = 1000,
    center: tensor = torch.tensor([0.0, 0.0]),
    radius: float = 1.0,
    width: float = 0.2,
    seed: int = None,
) -> torch.tensor

Generate 2D points uniformly distributed in the region between two concentric circles.

In particulr, points are sampled uniformly within a ring defined by an outer radius and an inner radius of radius - width, centered at a specified 2D location.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of points to generate. Defaults to 1000.	`1000`
`center`	`Tensor`	Center of the annulus as a tensor of shape (2,). Defaults to [0.0, 0.0].	`tensor([0.0, 0.0])`
`radius`	`float`	Outer radius of the annulus. Must be positive. Defaults to 1.0.	`1.0`
`width`	`float`	Thickness of the annulus. Must be positive and less than `radius`. Defaults to 0.2.	`0.2`
`seed`	`int`	Random seed for reproducibility. If None, randomness is not seeded.	`None`

Returns:

Type	Description
`tensor`	torch.Tensor: A tensor of shape (N, 2) containing the sampled 2D points.

Examples:

>>> center = torch.tensor([0.0, 0.0])
>>> points = generate_annulus_points_2d(n=500, center=center, radius=1.0, width=0.3, seed=42)
>>> points.shape
torch.Size([500, 2])

generate_figure_eight_points_2d

generate_figure_eight_points_2d(
    n: int = 1000,
    r_bounds: Tuple[float, float] = (0.2, 0.3),
    centers: Tuple[
        Tuple[float, float], Tuple[float, float]
    ] = ((0.3, 0.5), (0.7, 0.5)),
    noise_std: float = 0.0,
    noise_kind: Literal["gaussian", "uniform"] = "gaussian",
    seed: int = None,
) -> torch.tensor

Generate 2D points uniformly sampled in a figure-eight shape, with optional noise.

This function samples n_samples points distributed across two circular lobes (forming a figure-eight shape) centered at specified coordinates. Optionally, isotropic Gaussian or uniform noise can be added to the coordinates.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of 2D points to generate. Defaults to 1000.	`1000`
`r_bounds`	`Tuple[float, float]`	Tuple specifying the minimum and maximum radius for sampling within each lobe. Defaults to (0.2, 0.3).	`(0.2, 0.3)`
`centers`	`Tuple[Tuple[float, float], Tuple[float, float]]`	Coordinates of the centers of the two lobes. Defaults to ((0.3, 0.5), (0.7, 0.5)).	`((0.3, 0.5), (0.7, 0.5))`
`noise_std`	`float`	Standard deviation (for Gaussian) or half-width (for uniform) of noise to add to each point. Defaults to 0.0 (no noise).	`0.0`
`noise_kind`	`Literal['gaussian', 'uniform']`	Type of noise distribution to use if `noise_std > 0`. Defaults to "gaussian".	`'gaussian'`
`seed`	`int`	Random seed for reproducibility. If None, randomness is not seeded.	`None`

Returns:

Type	Description
`tensor`	torch.Tensor: A tensor of shape (n_samples, 2) containing the sampled 2D points.

generate_noisy_torus_points_3d

generate_noisy_torus_points_3d(
    n=1000,
    R: float = 3.0,
    r: float = 1.0,
    noise_std: float = 0.02,
    seed: int = None,
) -> torch.tensor

Generate 3D points on a torus with added Gaussian noise.

Points are uniformly sampled on the surface of a torus defined by a major radius R and a minor radius r. Gaussian noise with standard deviation noise_std is added to each point independently in x, y, and z dimensions.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of points to generate. Defaults to 1000. R (float, optional): Major radius of the torus (distance from the center of the tube to the center of the torus). Must be positive. Defaults to 3.0.	`1000`
`r`	`float`	Minor radius of the torus (radius of the tube). Must be positive. Defaults to 1.0.	`1.0`
`noise_std`	`float`	Standard deviation of the Gaussian noise added to the points. Defaults to 0.02.	`0.02`
`seed`	`int`	Random seed for reproducibility. If None, randomness is not seeded.	`None`

Returns:

Type	Description
`tensor`	torch.Tensor: A tensor of shape (num_points, 3) containing the generated noisy 3D points.

Examples:

>>> points = generate_noisy_torus_points_3d(
        n=500, R=3.0, r=1.0, noise_std=0.05, seed=123)
>>> points.shape
torch.Size([500, 3])

generate_swiss_cheese_points

generate_swiss_cheese_points(
    n: int = 1000,
    rect_min: tuple = (0.0, 0.0, 0.0),
    rect_max: tuple = (1.0, 1.0, 1.0),
    k: int = 6,
    void_radius_range: tuple = (0.1, 0.2),
    seed: int = None,
    *,
    device="cpu",
    batch_factor=4,
) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]

Generate points in a high-dimensional rectangular region with randomly placed spherical voids, forming a "Swiss cheese" structure.

Points are sampled uniformly within the bounding box defined by rect_min and rect_max, excluding k randomly positioned spherical voids with radii sampled from void_radius_range.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of points to generate. Defaults to 1000.	`1000`
`rect_min`	`tuple`	Minimum coordinates of the rectangular region. Defaults to a tuple of three zeros.	`(0.0, 0.0, 0.0)`
`rect_max`	`tuple`	Maximum coordinates of the rectangular region. Defaults to a tuple of three ones.	`(1.0, 1.0, 1.0)`
`k`	`int`	Number of spherical voids to generate. Defaults to 6.	`6`
`void_radius_range`	`Tuple[float, float]`	Range `(min_radius, max_radius)` for the void radii. Defaults to (0.1, 0.2).	`(0.1, 0.2)`
`seed`	`int`	Random seed for reproducibility. If None, randomness is not seeded.	`None`
`device`	`device`	Device to perform computations on. Defaults to 'cpu'.	`'cpu'`
`batch_factor`	`int`	How many candidates to shoot each round. Defaults to 4.	`4`

Returns:

Type	Description
`Tuple[Tensor, Tensor, Tensor]`	Tuple[torch.Tensor, torch.Tensor]: A tuple containing: - `points` (torch.Tensor): Tensor of shape (N, dim) with generated sample points. - `void_radii` (torch.Tensor): Tensor of shape (k,) with the radii of the voids.

Examples:

>>> rect_min = (0.0, 0.0, 0.0)
>>> rect_max = (1.0, 1.0, 1.0)
>>> void_radius_range = (0.1, 0.2)
>>> k = 5
>>> points, _ = generate_swiss_cheese_points(
...     1000000, rect_min, rect_max, k, void_radius_range
... )
>>> points.shape
torch.Size([1000000, 3])