sage.data.waveform.distributions.angular

Filename : angular.py Description : Short description of the file

Created on 2026-02-16 10:45:51

__author__ = Narenraju Nagarajan __copyright__ = Copyright 2026, ProjectName __license__ = MIT Licence __version__ = 0.0.1 __maintainer__ = Narenraju Nagarajan __affiliation__ = N/A __email__ = N/A __status__ = [‘inProgress’, ‘Archived’, ‘inUsage’, ‘Debugging’]

GitHub Repository: NULL

Documentation: NULL

Classes

UniformAngle	GPU-friendly uniform distribution with optional arbitrary bounds and cyclic domain.
SinAngle	Isotropic polar-angle sampler for inclination-like parameters.
CosAngle	Isotropic azimuthal-like angle sampler for declination-type parameters.
UniformSolidAngle	Joint sampler for a pair of angles that is uniform over the full sphere.

Module Contents

class UniformAngle(lower=0.0, upper=2 * torch.pi, cyclic_domain=True)

GPU-friendly uniform distribution with optional arbitrary bounds and cyclic domain.

Parameters:

• lower (float) – lower bound (radians)

• upper (float) – upper bound (radians)

• cyclic_domain (bool) – whether to wrap samples into [lower, upper)

lower = 0.0

upper = 6.283185307179586

cyclic = True

range = 6.283185307179586

sample(shape, device=None, dtype=torch.float32, generator=None)

Draw shape samples uniformly from [lower, upper).

wrap(x)

Wrap values into [lower, upper)

class SinAngle(low=0.0, high=torch.pi)

Bases: UniformAngle

Isotropic polar-angle sampler for inclination-like parameters.

Draws samples from the distribution whose PDF is proportional to sin(theta) over [low, high]. This is the correct prior for an angle that is uniform over a sphere (e.g. binary inclination, source sky polar angle). Sampling is done via the inverse-CDF method in cos(theta) space.

Parameters:

• low (float) – Lower bound in radians (default 0).

• high (float) – Upper bound in radians (default pi).

:param : :type : param lower: lower bound (radians) :param : :type : type lower: float :param : :type : param upper: upper bound (radians) :param : :type : type upper: float :param : :type : param cyclic_domain: whether to wrap samples into [lower, upper) :param : :type : type cyclic_domain: bool

PI = 3.141592653589793

low

high

cos_low

cos_high

sample(shape, device=None, dtype=torch.float32, generator=None)

Draw shape polar angles with the sin-angle prior (isotropic sphere).

class CosAngle(low=-torch.pi / 2, high=torch.pi / 2)

Bases: SinAngle

Isotropic azimuthal-like angle sampler for declination-type parameters.

Draws samples whose PDF is proportional to cos(theta) over [-pi/2, pi/2] — the correct isotropic prior for declination or elevation angles. Sampling uses the inverse-CDF method in sin(theta) space, which is the dual of SinAngle.

Parameters:

• low (float) – Lower bound in radians (default -pi/2).

• high (float) – Upper bound in radians (default pi/2).

:param : :type : param lower: lower bound (radians) :param : :type : type lower: float :param : :type : param upper: upper bound (radians) :param : :type : type upper: float :param : :type : param cyclic_domain: whether to wrap samples into [lower, upper) :param : :type : type cyclic_domain: bool

HALF_PI = 1.5707963267948966

low

high

sin_low

sin_high

sample(shape, device=None, dtype=torch.float32, generator=None)

Draw shape declination angles with the cos-angle prior (isotropic sphere).

class UniformSolidAngle(polar_name='theta', azimuthal_name='phi', polar_bounds=(0.0, torch.pi), azimuthal_bounds=(0.0, 2 * torch.pi))

Joint sampler for a pair of angles that is uniform over the full sphere.

Combines SinAngle for the polar angle (inclination / sky colatitude) and UniformAngle for the azimuthal angle (right ascension / polarisation) to produce an isotropic orientation prior. The sample method returns a dict keyed by the names given at construction, making it easy to merge into a broader parameter dict.

Parameters:

• polar_name (str) – Key for the polar-angle output (default "theta").

• azimuthal_name (str) – Key for the azimuthal-angle output (default "phi").

• polar_bounds (tuple[float, float]) – (low, high) in radians for the polar angle (default (0, pi)).

• azimuthal_bounds (tuple[float, float]) – (low, high) in radians for the azimuthal angle (default (0, 2*pi)).

polar_name = 'theta'

azimuthal_name = 'phi'

polar_sampler

azimuth_sampler

sample(shape, device=None, dtype=torch.float32, generator=None)

Draw shape angle pairs and return them as a dict.

Returns:

{polar_name: theta, azimuthal_name: phi} each of shape shape.

Return type:

dict[str, torch.Tensor]