synthbold.sampling

Shared random-sampling helpers.

synthbold.sampling.sample_1d(value: Tensor | None, name: str, size: int, low: float, high: float, device: device, generator: Generator, polar: bool = False) → Tensor

Return value moved to device, or sample it if value is None.

Parameters:

  • value – Optional externally supplied tensor to use instead of sampling.

  • name – Name of the parameter, used in the raised error message.

  • size – Expected length of value, or number of values to sample when value is None.

  • low – Lower bound of the sampling range.

  • high – Upper bound of the sampling range.

  • device – Target compute device.

  • generator – Random number generator for reproducibility.

  • polar – If True, treat low/high as a polar angle range and sample cos(theta) uniformly instead of theta itself, so that the resulting angles are isotropic on the sphere (the solid angle element scales with sin(theta), so uniform-in-angle sampling is not uniform-on-sphere).

Returns:

Tensor of shape (size,) moved to device.

Raises:

ValueError – If value is given and is not a 1D tensor of length size.

synthbold.sampling.sample_log_uniform(size: int | tuple[int, ...], low: float, high: float, device: device, generator: Generator) → Tensor

Sample values log-uniformly from [low, high).

Values are drawn uniformly in log-space and exponentiated back, giving even coverage across orders of magnitude instead of concentrating draws near high, as plain uniform sampling does when the range spans multiple decades.

Parameters:

  • size – Number of values to sample.

  • low – Lower bound of the sampling range. Must be strictly positive.

  • high – Upper bound of the sampling range. Must be strictly positive.

  • device – Target compute device.

  • generator – Random number generator for reproducibility.

Returns:

Tensor of shape (size,).

Raises:

ValueError – If low or high is not strictly positive.

synthbold.sampling.sample_polar(size: int | tuple[int, ...], low: float, high: float, device: device, generator: Generator) → Tensor

Sample polar angles isotropically distributed on the sphere.

Sampling cos(theta) uniformly, rather than theta itself, is what makes the resulting angles isotropic on the sphere: the solid angle element scales with sin(theta), so uniform-in-angle sampling would oversample near the poles.

Parameters:

  • size – Number of angles to sample.

  • low – Lower bound of the polar angle range, in radians.

  • high – Upper bound of the polar angle range, in radians.

  • device – Target compute device.

  • generator – Random number generator for reproducibility.

Returns:

Tensor of shape (size,) containing polar angles in [low, high].

synthbold.sampling.sample_uniform(size: int | tuple[int, ...], low: float, high: float, device: device, generator: Generator) → Tensor

Sample values uniformly from [low, high).

Parameters:

  • size – Number of values to sample.

  • low – Lower bound of the sampling range.

  • high – Upper bound of the sampling range.

  • device – Target compute device.

  • generator – Random number generator for reproducibility.

Returns:

Tensor of shape (size,).