Distributions

Initialize AbstractCustomDistribution.

Parameters:

Compute the probability density function at given points.

Parameters:

Returns:

Calculate the integral of the probability density function.

Parameters:

Returns:

Normalize the PDF such that its integral is 1.

Parameters:

Returns:

Initialize a Dirac distribution with given Dirac locations and weights.

Parameters:

Normalize the weights in-place to ensure they sum to 1.

Apply a function to the Dirac locations and return a new distribution.

Parameters:

Returns:

Convert or approximate this distribution as target_type.

This is a convenience wrapper around :func:pyrecest.distributions.convert_distribution. target_type may be either a concrete distribution class or a registered conversion alias.

Parameters

target_type Concrete target representation class or conversion alias. return_info If true, return a ConversionResult containing metadata. **kwargs Conversion parameters required by the target representation.

Alias for :meth:convert_to emphasizing approximate conversions.

Initialize the class with a center and shape matrix.

Parameters:

Calculate the size of the manifold.

Returns:

Convert or approximate this distribution as target_type.

This is a convenience wrapper around :func:pyrecest.distributions.convert_distribution. target_type may be either a concrete distribution class or a registered conversion alias such as "particles" or "gaussian".

Parameters

target_type Concrete target representation class or conversion alias. return_info If true, return a ConversionResult containing metadata. **kwargs Conversion parameters required by the target representation.

Alias for :meth:convert_to emphasizing approximate conversions.

Convenient access to a reasonable "mean" for different manifolds.

Returns:

Set the mode of the distribution

Obtain n samples from the distribution.

Metropolis Hastings sampling algorithm.

Initialize the distribution.

Parameters:

Abstract method to normalize the distribution. Implementation required in subclasses.

Abstract method to get value of the distribution for given input. Implementation required in subclasses.

Parameters:

Normalizes the distribution.

Returns:

Calculates probability density function for the given input.

Parameters:

Returns:

Convenient access to mean_direction to have a consistent interface throughout manifolds.

Returns:

Abstract method to compute the mean direction of the distribution.

Returns

mean_direction: The mean direction of the distribution.

Visualize just a point in the SE(3) domain (no uncertainties are considered)

Compute the probability density function at each point in xs.

Parameters:

Returns:

Compute the size of the distribution's manifold.

Returns:

Mode is not defined for a uniform distribution.

Parameters: f_ (callable) pdf of the distribution bound_dim (int) dimension of the bounded part of the manifold lin_dim (int) dimension of the linear part of the manifold

Returns reasonable integration boundaries for the specific distribution based on the mode and covariance.

Find the mode of the distribution by calling mode_numerical.

Calculates the linear covariance, or calls linear_covariance_numerical if a non-numerical solution doesn't exist.

Parameters: - approximate_mean : ndarray, optional The approximate mean to be used. If None, uses NaNs to flag for calculation.

Returns: - C : ndarray The linear covariance.

Numerically calculates the linear covariance.

Parameters: - approximate_mean : ndarray, optional The approximate mean to be used. If None, calculates the mean.

Returns: - C : ndarray The linear covariance.

Condition on linear.

Parameters: lin_input : ndarray Input array. normalize : bool, optional If True (default), normalizes the distribution.

Returns: dist : CustomHypertoroidalDistribution The distribution after conditioning.

Conditions the distribution on periodic variables

Arguments: input_periodic: ndarray Input data, assumed to have shape (self.bound_dim,) normalize: bool If True, normalizes the distribution

Returns: dist: CustomLinearDistribution CustomLinearDistribution instance

Find the mode of the distribution numerically.

Parameters: starting_point : ndarray, optional The starting point for the optimization. If None, uses [pi * ones(self.bound_dim); zeros(self.lin_dim)]

Returns: m : ndarray The mode of the distribution.

Parameters: bound_dim (int) number of bounded (e.g., periodic or hyperrectangular) dimensions lin_dim (int) number of linear dimensions

Convenient access to hybrid_mean() to have a consistent interface throughout manifolds.

Returns:

Convenient access to hybrid_mean() to have a consistent interface throughout manifolds.

Returns:

Constructor, it is the user's responsibility to ensure that f is a valid hypertoroidal density and takes arguments of the same form as .pdf, i.e., it needs to be vectorized.

Parameters: f (function handle) pdf of the distribution bound_dim (scalar) dimension of the hypertorus lin_dim (scalar) linear dimension

Create a CustomHypercylindricalDistribution from another AbstractHypercylindricalDistribution.

Parameters: dist (AbstractHypercylindricalDistribution) The distribution to convert into a CustomHypercylindricalDistribution

Returns: chhd (CustomHypercylindricalDistribution) The created CustomHypercylindricalDistribution

Initialize a Dirac distribution with given Dirac locations and weights.

Parameters:

Return locations with shape (n, n_hemispheres, dim_hemisphere + 1).

Return locations with shape (n, (dim_hemisphere + 1) * n_hemispheres).

Return Dirac locations for one hyperhemisphere component.

Return weighted second moments for the product components.

Return weighted principal axes for the product components.

Apply a function to the Dirac locations and return a new distribution.

Parameters:

Returns:

Needs to be overwritten to allow the specification of bound_dim for Cartesian products of bounded and Euclidean manifolds

Parameters: mu (scalar): linear mean mu0 (scalar): circular mean (wrapped to [0, 2π)) kappa (positive scalar): circular concentration rho1 (scalar): first correlation parameter rho2 (scalar): second correlation parameter sigma (positive scalar): linear standard deviation

Compute the conditional mean and std of the linear variable given circular values.

Parameters: xa_circular: circular variable values

Returns: muc: conditional mean of the linear variable (same shape as xa_circular) sigmac: conditional std of the linear variable (positive scalar)

Evaluate the pdf at each row of xs.

Parameters: xs (..., 2): locations where to evaluate the pdf; first column is circular (θ), second is linear (x)

Returns: p (...,): value of the pdf at each location

Return the mode of the distribution.

Returns: m (2,): mode [mu0, mu] (circular first, then linear)

Obtain n samples from the distribution.

Parameters: n (int): number of samples

Returns: s (n, 2): n samples on [0, 2π) × R (circular first, then linear)

Return the intrinsic linear variance as a (1, 1) matrix.

Returns: C (1, 1): [[sigma^2]]

Return the marginal circular distribution.

The marginal over the linear variable is a Von Mises distribution since the conditional Gaussian integrates to one.

Returns: vm: VonMisesDistribution(mu0, kappa)

Return the marginal linear distribution by integrating out the circular variable.

Returns: dist: CustomLinearDistribution representing the marginal over the linear variable

Determines the mode of the distribution, i.e., the point where the pdf is largest. Returns: m (lin_dim + bound_dim,) vector: the mode

Return a copy of this distribution with the location parameter shifted to new_mean.

For bounded dimensions, the mean is wrapped into [0, 2*pi) to stay on the manifold.

Calculates mean of [x1, x2, .., x_lin_dim, cos(x_(linD+1), sin(x_(linD+1)), ..., cos(x_(linD+boundD), sin(x_(lin_dim+bound_dim))] Returns: mu (linD+2): expectation value of [x1, x2, .., x_lin_dim, cos(x_(lin_dim+1), sin(x_(lin_dim+1)), ..., cos(x_(lin_dim+bound_dim), sin(x_(lin_dim+bound_dim))]

Sample n points from the distribution Parameters: n (int): number of points to sample

Create an SE2BinghamDistribution.

Parameters

C : array_like, shape (4, 4) or (2, 2) If C2 and C3 are not provided, this is the full 4x4 parameter matrix. Otherwise it is the 2x2 Bingham (rotational) part C1. C2 : array_like, shape (2, 2), optional Coupling matrix between rotation and translation. C3 : array_like, shape (2, 2), optional Symmetric negative-definite matrix for the translational part.

Evaluate the probability density at the given points.

Parameters

xs : array_like, shape (N, 4) or (N, 3) Evaluation points in dual quaternion (N x 4) or angle-pos (N x 3) representation.

Returns

p : array, shape (N,) Density values.

Compute one mode of the distribution.

Because of antipodal symmetry, -mode is equally valid.

Returns

m : array, shape (4,) Mode in dual quaternion representation.

Draw n samples from the distribution.

Sampling uses a two-step procedure: 1. Sample the rotational part from the Bingham marginal. 2. Sample the translational part from the Gaussian conditional.

Parameters

n : int Number of samples.

Returns

s : array, shape (n, 4) Samples in dual quaternion representation.

Return the marginal distribution over the periodic (rotational) part.

The marginal is the Bingham distribution corresponding to the Schur complement BM = C1 - C2^T * C3^{-1} * C2.

Returns

b : BinghamDistribution Marginal Bingham distribution on S^1.

Return the marginal distribution over the linear (translational) part.

The marginal is computed by numerically integrating out the rotational component.

Returns

dist : CustomLinearDistribution Marginal distribution over R^2.

Estimate SE2BinghamDistribution parameters from samples.

Parameters

samples : array_like, shape (N, 4) or (N, 3) Samples in dual quaternion (N x 4) or angle-pos (N x 3) form. weights : array_like, shape (N,), optional Non-negative weights (need not sum to 1). Defaults to uniform.

Returns

dist : SE2BinghamDistribution Fitted distribution.

Return the 4-D moment E[cos(x1), sin(x1), x2, x3].

Returns

array of shape (4,)

Return the analytical 4-D covariance of [cos(x1), sin(x1), x2, x3].

Returns

array of shape (4, 4)

Estimate the 4-D covariance of [cos(x1), sin(x1), x2, x3] from samples.

Parameters

n_samples : int Number of samples to draw for the estimate.

Returns

array of shape (4, 4)

Fit an SE2PWNDistribution from samples via moment matching.

Parameters

samples : array of shape (n, 3) Samples on [0, 2*pi) x R^2.

Returns

SE2PWNDistribution

Parameters

gd : AbstractGridDistribution Grid-based distribution for the periodic/bounded part. Its grid_values represent (unnormalized) marginal weights over the grid points. linear_distributions : list One distribution per grid point representing the conditional distribution of the linear state given that grid point.

Returns the hybrid mean, i.e. the concatenation of the mean direction of the periodic part and the mean of the linear marginal.

Marginalise out the linear dimensions, returning a distribution over the periodic/bounded part only.

Marginalise out the periodic/bounded dimensions, returning a distribution over the linear part only.

Parameters

gd : AbstractGridDistribution Grid-based distribution for the periodic/bounded part. gaussians : list of GaussianDistribution One Gaussian per grid point of gd.

Return the grid distribution (marginalised over the linear part).

Marginalise over the periodic/bounded dimensions.

Returns a GaussianMixture whose components are the conditional Gaussians and whose weights are the (normalised) grid values.

Compute the mean of the marginal linear distribution by treating the state as a Gaussian mixture.

Returns

mu : array, shape (lin_dim,)

Compute the covariance of the marginal linear distribution by treating the state as a Gaussian mixture.

Returns

C : array, shape (lin_dim, lin_dim)

Multiply two StateSpaceSubdivisionGaussianDistributions.

Both operands must be defined on the same grid. For each grid point the conditional Gaussians are multiplied (Bayesian update). The grid weights are updated by the likelihood factors that arise from the overlap of the two conditional Gaussians.

Parameters

other : StateSpaceSubdivisionGaussianDistribution

Returns

StateSpaceSubdivisionGaussianDistribution

Compute the (approximate) joint mode.

The mode is found by maximising the product of the conditional Gaussian peak value and the grid weight at each grid point. Only the discrete grid is searched (no interpolation).

Returns

m : array, shape (bound_dim + lin_dim,) Concatenation of the periodic mode (grid point) and the linear mode (mean of the conditional Gaussian at that grid point).

Warns

UserWarning If the density appears multimodal (i.e. another grid point has a joint value within a factor of 1.001 of the maximum).

Calculates the cumulative distribution function.

Args: xs (): The 1D array to calculate the CDF on. starting_point (float, optional): Defaults to 0.

Returns: : The computed CDF as a numpy array.

Calculates the Kullback-Leibler divergence numerically.

Args: other (AbstractCircularDistribution): Distribution to compare against.

Returns: : The Kullback-Leibler divergence D_KL(self || other).

Convert to von Mises by trigonometric moment matching.

Returns: vm (VMDistribution): Distribution with the same first trigonometric moment.

Convert to wrapped normal by trigonometric moment matching.

Returns: wn (WrappedNormalDistribution): Distribution with the same first trigonometric moment.

Initializes a CircularDiracDistribution instance.

Args: d (): The Dirac locations. w (Optional[]): The weights for each Dirac location.

Raises an exception since interpolation is not available for WDDistribution.

Creates a new circular mixture.

Args: dists: The list of distributions. w: The weights of the distributions. They must have the same shape as 'dists' and the sum of all weights must be 1.

Evaluate cumulative distribution function

Parameters

xa : (1, n) points where the cdf should be evaluated starting_point : scalar point where the cdf is zero (starting point can be [0, 2pi) on the circle, default 0

Returns

val : (1, n) cdf evaluated at columns of xa

Initializes a new instance of the CustomCircularDistribution class.

Args: f_ (callable): The function to be used for the distribution. scale_by (float, optional): The scale factor for the distribution. Defaults to 1. shift_by (float, optional): The shift for the distribution. Defaults to 0.

Note: It is the user's responsibility to ensure that f_ is a valid circular density, i.e., 2pi-periodic, nonnegative and normalized.

Computes the probability density function at xs.

Args: xs (): The values at which to evaluate the pdf.

Returns: : The value of the pdf at xs.

Computes the integral of the pdf over the given boundaries.

Args: integration_boundaries (, optional): The boundaries of the integral. Defaults to [0, 2 * pi].

Returns: float: The value of the integral.

Evaluate the unnormalized pdf at each point in xs.

Parameters

xs : array_like, shape (n,) Points where the pdf is evaluated.

Returns

p : array, shape (n,) Unnormalized pdf values.

Evaluate the pdf at each point in xs.

Parameters

xs : array_like, shape (n,) Points where the pdf is evaluated.

Returns

p : array, shape (n,) Pdf values.

Initialize with a weight vector that is automatically normalized.

Parameters

w : array_like, shape (n,) Weight for each interval (will be normalized to form a valid pdf).

Evaluate the pdf at each point in xs.

Parameters

xs : array_like, shape (n,) Points at which to evaluate the pdf.

Returns

p : ndarray, shape (n,) Pdf values at each point.

Calculate the n-th trigonometric moment analytically.

Parameters

n : int Moment order.

Returns

m : complex n-th trigonometric moment.

Calculate the entropy analytically.

Returns

e : float Entropy of the distribution.

Draw n random samples from the distribution.

Parameters

n : int Number of samples to draw.

Returns

samples : ndarray, shape (n,) Samples in [0, 2*pi).

Left border of the m-th interval (1-indexed) for n total intervals.

Parameters

m : int Interval index (1-indexed). n : int Total number of intervals.

Returns

float Left border of the m-th interval.

Right border of the m-th interval (1-indexed) for n total intervals.

Parameters

m : int Interval index (1-indexed). n : int Total number of intervals.

Returns

float Right border of the m-th interval.

Center of the m-th interval (1-indexed) for n total intervals.

Parameters

m : int Interval index (1-indexed). n : int Total number of intervals.

Returns

float Center of the m-th interval.

Calculate weights by numerically integrating a given pdf over each interval.

Parameters

pdf_func : callable Pdf of a circular density; accepts a 1-D array and returns a 1-D array. n : int Number of discretization intervals.

Returns

w : ndarray, shape (n,) Weights of the corresponding PiecewiseConstantDistribution.

Initialize the sine-skewed distribution with a central location parameter mu and a skewness parameter lambda_.

Compute the base probability density function (PDF) for the wrapped distribution without skewness. This method must be implemented by subclasses.

Compute the skewed probability density function (PDF) for the distribution.

Draw samples from the von Mises distribution.

Set the mean direction of the distribution.

Parameters: mu : scalar New mean direction to set.

Evaluate cumulative distribution function

Parameters: xs : (n) points where the cdf should be evaluated starting_point : scalar, optional, default: 0 point where the cdf is zero (starting point can be [0, 2pi) on the circle, default is 0)

Returns: val : (n) cdf evaluated at columns of xs

Obtain a VM distribution from a given first trigonometric moment.

Parameters: m (scalar): First trigonometric moment (complex number).

Returns: vm (VMDistribution): VM distribution obtained by moment matching.

Initialize a wrapped normal distribution with mean mu and standard deviation sigma.

Common initialisation for conditional grid distributions.

Parameters

grid : array of shape (n_points, d) Grid points on the individual manifold. grid_values : array of shape (n_points, n_points) Conditional pdf values; grid_values[i, j] = f(grid[i] | grid[j]). enforce_pdf_nonnegative : bool Whether to require non-negative grid_values.

No-op – returns self for compatibility.

Element-wise multiply two conditional grid distributions.

The resulting distribution is not normalized.

Parameters

other : AbstractConditionalDistribution Must be defined on the same grid.

Returns

AbstractConditionalDistribution Same concrete type as self.

Parameters

grid : array of shape (n_points, 3) Grid points on S². grid_values : array of shape (n_points, n_points) Conditional pdf values: grid_values[i, j] = f(grid[i] | grid[j]). enforce_pdf_nonnegative : bool Whether non-negativity of grid_values is required.

Marginalize out one of the two spheres.

Returns a :class:SphericalGridDistribution (S²-specific).

Parameters

first_or_second : int (1 or 2)

Return the conditional slice for a fixed grid point.

Returns a :class:SphericalGridDistribution (S²-specific).

Parameters

first_or_second : int (1 or 2) point : array of shape (3,)

Construct an :class:S2CondS2GridDistribution from a callable.

Parameters

fun : callable Conditional pdf f(a, b) – see :meth:SdCondSdGridDistribution.from_function for the fun_does_cartesian_product convention. no_of_grid_points : int Number of grid points for each sphere. fun_does_cartesian_product : bool If True, fun is called with the full grids of shape (n_points, 3) and must return (n_points, n_points). If False (default), fun receives paired rows and must return a 1-D array. grid_type : str Grid type passed to the sampler. Defaults to 'leopardi'.

Returns

S2CondS2GridDistribution

Parameters

grid : array of shape (n_points, d) Grid points on the sphere. All coordinate values must lie in [-1, 1] (unit sphere). grid_values : array of shape (n_points, n_points) Conditional pdf values: grid_values[i, j] = f(grid[i] | grid[j]). Must be non-negative. enforce_pdf_nonnegative : bool Whether non-negativity of grid_values is required.

Marginalize out one of the two spheres.

Parameters

first_or_second : int (1 or 2) 1 marginalizes out the first dimension (sums over rows); 2 marginalizes out the second dimension (sums over columns).

Returns

HypersphericalGridDistribution

Return the conditional slice for a fixed grid point.

The supplied point must be an existing grid point.

Parameters

first_or_second : int (1 or 2) 1 fixes the first argument at point and returns values over the second sphere; 2 fixes the second argument and returns values over the first sphere. point : array of shape (d,) Grid point at which to evaluate.

Returns

HypersphericalGridDistribution

Construct a :class:SdCondSdGridDistribution from a callable.

Parameters

fun : callable Conditional pdf function f(a, b).

*   When ``fun_does_cartesian_product=False`` (default): ``fun``
    is called once with two arrays of shape ``(n_pairs, d)``
    containing all ``n_points²`` pairs, and must return a 1-D
    array of length ``n_points²``.
*   When ``fun_does_cartesian_product=True``: ``fun`` is called
    with both full grids of shape ``(n_points, d)`` and must
    return an array of shape ``(n_points, n_points)``.

no_of_grid_points : int Number of grid points for each sphere. fun_does_cartesian_product : bool See fun description above. grid_type : str Grid type passed to :func:~pyrecest.sampling.hyperspherical_sampler.get_grid_hypersphere. Defaults to 'leopardi'. dim : int Embedding dimension of the Cartesian product space (2 * embedding_dim_of_individual_sphere). Defaults to 6 (S2 × S2).

Returns

SdCondSdGridDistribution

Parameters

grid : array of shape (n_points, d) Grid points on the upper hemisphere. All coordinate values must lie in [-1, 1] and the last coordinate must be >= 0. grid_values : array of shape (n_points, n_points) Conditional pdf values. enforce_pdf_nonnegative : bool Whether non-negativity of grid_values is required.

Return the grid array.

Marginalize out one of the two hemispheres.

Parameters

first_or_second : int (1 or 2)

Returns

HyperhemisphericalGridDistribution

Return the conditional slice for a fixed grid point.

Returns

HyperhemisphericalGridDistribution

Construct a :class:SdHalfCondSdHalfGridDistribution from a callable.

Parameters

fun : callable Conditional pdf function f(a, b). When fun_does_cartesian_product=False: called with pairs of shape (n_pairs, d) and must return array of length n_pairs. When fun_does_cartesian_product=True: called with both grids of shape (n_points, d) and must return (n_points, n_points). no_of_grid_points : int Number of grid points for each hemisphere. fun_does_cartesian_product : bool See fun description above. grid_type : str Grid type for hemisphere. Defaults to 'leopardi_symm'. dim : int Embedding dimension of the Cartesian product space (2 * embedding_dim_of_individual_hemisphere). Default 4 for circles; use 6 for S2-half.

Returns

SdHalfCondSdHalfGridDistribution

Parameters

grid : array of shape (n_points, d) Grid points on the torus. grid_values : array of shape (n_points, n_points) Conditional pdf values: grid_values[i, j] = f(grid[i] | grid[j]). Must be non-negative when enforce_pdf_nonnegative=True. enforce_pdf_nonnegative : bool Whether non-negativity of grid_values is required.

Marginalize out one of the two tori.

Parameters

first_or_second : int (1 or 2) 1 marginalizes out the first dimension (sums over rows); 2 marginalizes out the second dimension (sums over columns).

Returns

HypertoroidalGridDistribution

Return the conditional slice for a fixed grid point.

The supplied point must be an existing grid point.

Parameters

first_or_second : int (1 or 2) 1 fixes the first argument at point and returns values over the second torus; 2 fixes the second argument and returns values over the first torus. point : array of shape (d,) Grid point at which to evaluate.

Returns

HypertoroidalGridDistribution

Construct a :class:TdCondTdGridDistribution from a callable.

Parameters

fun : callable Conditional pdf function f(a, b).

*   When ``fun_does_cartesian_product=False`` (default): ``fun``
    is called once with two arrays of shape ``(n_pairs, d)``
    containing all ``n_points²`` pairs, and must return a 1-D
    array of length ``n_points²``.
*   When ``fun_does_cartesian_product=True``: ``fun`` is called
    with both full grids of shape ``(n_points, d)`` and must
    return an array of shape ``(n_points, n_points)``.

no_of_grid_points : int Number of grid points for each torus. fun_does_cartesian_product : bool See fun description above. grid_type : str Grid type passed to :meth:~pyrecest.distributions.hypertorus.hypertoroidal_grid_distribution.HypertoroidalGridDistribution.generate_cartesian_product_grid. Defaults to 'CartesianProd'. dim : int Dimension of the Cartesian product space (2 * dim_of_individual_torus). Defaults to 2 (T1 × T1).

Returns

TdCondTdGridDistribution

Initialize DiskUniformDistribution.

The center of the disk is at [0, 0] and the shape matrix of the ellipsoid is an identity covariance matrix.

Initialize EllipsoidalBallUniformDistribution.

Parameters:

Compute the probability density function at given points.

Parameters:

Returns:

Generate samples from the distribution.

Parameters:

Returns:

Parameters

complex_dim : int Complex dimension d of the ambient space C^d (d >= 1).

Surface area of the real sphere S^{2d-1} = 2*pi^d / (d-1)!

Probability density at the given point(s) on the complex unit sphere.

Initializes a new instance of the AbstractHemisphericalDistribution class.

Convenient access to axis to have a consistent interface throughout manifolds.

Returns:

Approximate a hypersphere-subset distribution as weighted Diracs.

Grid distributions are converted deterministically by reusing their grid points as Dirac locations and their grid values as weights. Non-grid distributions fall back to the generic sampling-based Dirac conversion and therefore require n_particles.

Returns the principal axis of the Dirac mixture on the hypersphere. Because ±v represent the same axis, the sign of the returned vector is arbitrary.

Generate the PDF in hyperspherical coordinates.

Returns:

integration_boundaries have to be given in (hyper)spherical coordinates

Calculates the probability density function over the subset of the hypersphere.

Args: xs (): Input data points.

Returns: : Probability density at the given data points.

Convenient access to mean_direction to have a consistent interface throughout manifolds.

Returns:

Sample from the distribution using Metropolis-Hastings algorithm.

Args: n (int): Number of samples. burn_in (int, optional): Number of samples to discard at the start. Defaults to 10. skipping (int, optional): Number of samples to skip between each kept sample. Defaults to 5. proposal (function, optional): Proposal distribution for the Metropolis-Hastings algorithm. Defaults to None. start_point (, optional): Starting point for the Metropolis-Hastings algorithm. Defaults to None.

Returns: : Sampled points.

Initialize the AbstractSphereSubsetDistribution instance.

Convert spherical coordinates to Cartesian coordinates. For different convetions, see https://en.wikipedia.org/wiki/Spherical_coordinate_system Supported convetions: inclination and azimuth (θ_inc, φ_az,right) azimuth, and colatitude Refer to the respective functions for more information.

Convert Cartesian coordinates to spherical coordinates.

Args: x (): X coordinates. y (): Y coordinates. z (): Z coordinates.

Returns: tuple: Spherical coordinates.

Uses analytical method. Supports 2-D and 4-D distributions.

Returns the principal axis of the Bingham distribution as a unit vector in R^{dim+1}. Because of antipodal symmetry, v and -v represent the same axis; this method returns one of them.

Returns: S (numpy.ndarray): scatter/covariance matrix in R^d

Returns the mode of the Bingham distribution.

The mode is the eigenvector corresponding to Z=0 (the maximum), i.e., the last column of M.

Returns: mode (numpy.ndarray): mode as a unit vector in R^{dim+1}

Returns deterministic sigma-point samples and weights.

Generates 2*(dim+1) sigma points as ±columns of M with weights derived from the normalized moments, so that the weighted scatter matrix equals the distribution's moment matrix.

Parameters: _spread (float): spread parameter reserved for future use (e.g., tuning the sigma-point placement); currently the samples are always ±M columns

Returns: samples (numpy.ndarray): shape (dim+1, 2(dim+1)), columns are samples weights (numpy.ndarray): shape (2(dim+1),), non-negative weights summing to 1

Compose two Bingham distributions via complex or quaternion multiplication.

Computes the Bingham distribution approximating the scatter matrix of the product x*y, where x ~ self and y ~ B2 are independent.

Parameters: B2 (BinghamDistribution): second distribution

Returns: BinghamDistribution: composed distribution

Fit a Bingham distribution to a given scatter/moment matrix.

Finds Z and M such that the moment of B(Z, M) matches S.

Parameters: S (numpy.ndarray): symmetric positive semi-definite matrix with trace 1 (or will be normalized)

Returns: BinghamDistribution: fitted distribution

Initialize the distribution.

Parameters

C : array-like of shape (d, d) Hermitian positive definite parameter matrix.

Evaluate the pdf at each row of za.

Parameters

za : array-like of shape (n, d) or (d,) Points on the complex unit sphere. Each row is a complex unit vector.

Returns

p : array-like of shape (n,) or scalar PDF values at each row of za.

Sample n points from the distribution.

Parameters

n : int Number of samples.

Returns

Z : array-like of shape (n, d) Complex unit vectors sampled from the distribution.

Fit distribution to data Z using fixed-point iterations.

Parameters

Z : array-like of shape (n, d) Complex unit vectors (each row is a sample). n_iterations : int, optional Number of fixed-point iterations (default 100).

Returns

dist : ComplexAngularCentralGaussianDistribution

Estimate the parameter matrix from data using fixed-point iterations.

Parameters

Z : array-like of shape (n, d) Complex unit vectors (each row is a sample). n_iterations : int, optional Number of iterations (default 100).

Returns

C : array-like of shape (d, d) Estimated Hermitian parameter matrix.

Construct a ComplexBinghamDistribution.

Parameters

B : array_like, shape (d, d) Hermitian parameter matrix (B == B^H must hold).

Evaluate the pdf at one or more points on the complex unit sphere.

Parameters

xs : array_like, shape (d,) or (d, n) Each column (or the single vector) is a point on the complex unit sphere.

Returns

array, shape (n,) or float Pdf value(s).

Draw samples from the complex Bingham distribution.

Uses the rejection-sampling algorithm of Kent, Constable & Er (2004) "Simulation for the complex Bingham distribution", Statistics and Computing, 14, 53-57.

Parameters

n : int Number of samples.

Returns

array, shape (d, n), dtype complex128 Sampled unit vectors (each column has unit norm).

Compute the negative log normalization constant -log C(B).

The formula used is (Kent 1994, eq. 2.3) after eigenvalue shift:

C(lambda) = 2*pi^d * sum_j exp(lambda_j) / prod_{k!=j}(lambda_j - lambda_k)

For nearly-equal eigenvalues a small perturbation is applied so that the Vandermonde denominators remain well-conditioned, matching the approach in the original MATLAB implementation.

Parameters

B : array_like, shape (d, d) Hermitian parameter matrix.

Returns

float Negative log normalization constant.

Maximum-likelihood fit of a complex Bingham distribution to data.

Parameters

Z : array_like, shape (d, n) Complex unit vectors (columns); it is assumed that ||z_i|| = 1.

Returns

ComplexBinghamDistribution

Cauchy-Schwarz divergence between two complex Bingham distributions.

D_CS(p, q) = half * [log C(2B1) + log C(2B2)] - log C(B1+B2) >= 0

Using the stored negative log normalization (log_norm = -log C):

D_CS = log_norm(B1+B2) - half * [log_norm(2*B1) + log_norm(2*B2)]

This matches the MATLAB libDirectional CauchySchwarzDivergence convention.

Parameters

cB1, cB2 : ComplexBinghamDistribution or array_like Distributions or Hermitian parameter matrices.

Returns

float Non-negative divergence value.

Parameters: mu: 1-D complex array of shape (D,), must be a unit vector kappa: scalar concentration parameter

Return the mean direction (mode) of the distribution.

Evaluate the pdf at each row of za.

Parameters: za: complex array of shape (N, D) or (D,) for a single point

Returns: Real-valued array of shape (N,) or a scalar

Sample from the complex Watson distribution.

Uses the complex Bingham distribution sampling algorithm described in Mardia, K. V. & Jupp, P. E., Directional Statistics, Wiley, 2009, p. 336.

Parameters: n: number of samples

Returns: complex array of shape (n, D)

Fit a complex Watson distribution to data using MLE.

Parameters: Z: complex array of shape (N, D) weights: optional 1-D real array of shape (N,)

Returns: ComplexWatsonDistribution

Estimate parameters of the complex Watson distribution via MLE.

Following Mardia & Dryden (1999).

Parameters: Z: complex array of shape (N, D) weights: optional 1-D real array of shape (N,)

Returns: tuple (mu_hat, kappa_hat)

Compute the log normalization constant log(C_D(kappa)).

Uses three numerical regimes for stability (Mardia & Dryden 1999).

Parameters: D: feature-space dimension (integer >= 1) kappa: concentration parameter – scalar or array-like

Returns: log(C_D(kappa)); same shape as kappa (scalar if scalar input)

Initialize a CustomHyperhemisphericalDistribution.

Parameters:

Calculate the probability density function at given points.

Parameters:

Returns:

Integrate the pdf over given boundaries.

Parameters:

Returns:

Create a CustomHyperhemisphericalDistribution from another distribution.

Parameters:

Returns:

Raises:

For hyperhemispheres this method returns the mode (grid point with maximum weight) rather than the true mean direction.

Using the spherical mean would bias the result toward [0; ...; 0; 1], since the lower half of the sphere is not represented.

Convert hemisphere to full sphere.

The grid is mirrored, and the values are halved to keep the resulting hyperspherical distribution normalized.

Return the closest grid point(s) on the hemisphere, taking the symmetry x ~ -x into account.

Parameters

xs : array_like Either a single point of shape (dim,), or an array of shape (n_points, dim).

Returns

points : ndarray Closest grid point(s), shape (dim,). indices : ndarray or int Indices of the closest grid points.

Multiply two hyperhemispherical grid distributions that share the same grid.

1. Convert both to full-sphere grid distributions.
2. Multiply them as HypersphericalGridDistribution objects.
3. Restrict back to the hemisphere and rescale.

Parameters

other : HyperhemisphericalGridDistribution

Returns

HyperhemisphericalGridDistribution

Raises

ValueError If the grids are not identical (up to numerical tolerance).

Construct a hyperhemispherical grid distribution from a callable.

Parameters

fun : callable A function mapping an array of shape (batch_dim, space_dim) to a 1-D array of pdf values. In particular this matches your Python convention pdf(x) with x.shape == (batch, dim). no_of_grid_points : int Number of grid points on the hemisphere. dim : int, optional Ambient dimension (space_dim). Default is 2 for S². grid_type : {'leopardi_symm', 'healpix'}

Notes

For 'leopardi*' types, the grid is deterministic and only depends on (dim, no_of_grid_points, grid_type). For 'healpix', only dim == 3 is supported and healpy must be installed.

Sample n points from the hyperhemispherical distribution.

Args: n: number of points to sample.

Returns: numpy.ndarray: n sampled points.

Compute the size of the manifold.

Returns: float: size of the manifold.

Mean direction on the hypersphere.

Piecewise-constant interpolated pdf.

xs can be: - shape (dim,) - shape (batch, dim)

Returns: - scalar if input is 1D - (batch,) if input is 2D

Make the grid distribution antipodally symmetric.

Requires a symmetric grid: the second half of the grid is the negation of the first half.

New grid_values are the average of each pair, copied to both points.

Convert a symmetric full-sphere grid distribution to a HyperhemisphericalGridDistribution on the upper hemisphere.

If the density appears asymmetric (pairwise grid values differ by more than tol), the hemisphere values are formed by summing symmetric pairs instead of 2 * first_half.

Return closest grid point(s) in Euclidean distance.

xs can be: - shape (dim,) - shape (batch, dim)

Returns

points : ndarray Shape (dim,) for single query or (batch, dim) for multiple. indices : int or ndarray Index/indices of closest grid points.

Multiply two hyperspherical grid distributions defined on the same grid.

This method simply checks grid compatibility and then delegates to the superclass multiply implementation.

Construct a HypersphericalGridDistribution from a callable.

Parameters

fun : callable Function taking an array of shape (batch_dim, space_dim) and returning a 1D array of pdf values. no_of_grid_points : int Grid parameter (interpreted as number of points for 'leopardi' and total number of points for symmetric schemes). dim : int Ambient space dimension (>= 2). grid_type : str Type of grid to use. See get_grid_hypersphere for options. enforce_pdf_nonnegative : bool Whether to enforce non-negativity of grid values in base class.

Initializes the HypersphericalMixture with a list of distributions and weights.

Args: dists (List[AbstractHypersphericalDistribution]): The list of hyperspherical distributions. w (List[float]): The list of weights for each distribution.

Normalize the grid-based pdf.

If grid_type == 'sh_grid', we still normalize but warn because the grid may not be into equally-sized areas.

Plot interpolated pdf.

use_harmonics = False -> piecewise constant interpolation via self.pdf(..., False). use_harmonics = True -> spherical harmonics interpolation (currently unsupported).

Pdf on S².

Parameters

xa : array_like (batch_dim, 3). use_harmonics : bool If True: interpolate via spherical harmonics (preferred). If False: piecewise constant interpolation on the grid.

Construct a SphericalGridDistribution from an AbstractHypersphericalDistribution.

Construct from a function fun(x) where x has shape (batch_dim, 3).

grid_type: - 'leopardi' : Leopardi equal point set on S² - 'sh_grid' : spherical harmonics grid (lat/lon mesh).

Approximate dist by a degree-degree SHD using a DH grid.

This is faster than :meth:from_distribution_via_integral because it uses the discrete spherical-harmonic transform instead of numerical quadrature.

Spherical convolution with a zonal distribution other.

For the 'identity' transformation the standard frequency-domain formula is used (exact for bandlimited functions). For the 'sqrt' transformation a grid-based approach with a 2× finer intermediate grid is used so that squaring the sqrt functions introduces no aliasing.

Pointwise multiplication in physical space (Bayesian update step).

Works for both 'identity' and 'sqrt' transformations. For 'sqrt': sqrt(p) * sqrt(q) = sqrt(p*q) which is the correct sqrt-transformed product density.

Rotate the distribution by ZYZ Euler angles (in radians).

Parameters

alpha : float First rotation angle around Z (radians). beta : float Second rotation angle around Y (radians). gamma : float Third rotation angle around Z (radians).

Create a von Mises-Fisher distribution.

Parameters

mu : array-like, shape (d,) Unit mean direction in the embedding space. kappa : float Positive concentration parameter. Larger values concentrate more mass around mu.

Evaluate the density at unit vectors.

Parameters

xs : array-like, shape (d,) or (..., d) Unit-vector evaluation point or batch of points in the embedding space.

Return the unit mean direction with shape (d,).

Generate random unit vectors from the distribution.

Parameters

n : int Number of samples to generate.

Returns

array-like, shape (n, d) Random samples on the unit hypersphere.

Notes

Sampling currently requires the NumPy backend and SciPy's vonmises_fisher implementation.

Return deterministic sigma points matched to the mean direction.

Return an orthogonal matrix whose first column is mu.

Return the mean resultant vector with shape (d,).

Fit a von Mises-Fisher distribution to mean-resultant information.

Create a distribution from a mean resultant vector.

Parameters

m : array-like, shape (d,) Mean resultant vector. Its direction becomes mu and its norm is inverted to estimate kappa.

Return the modal direction, equal to mu.

Replace the mean direction and return the distribution.

Replace the modal direction and return the distribution.

Multiply two vMF densities and return the normalized product.

Convolve with a zonal vMF distribution.

other must be zonal around the final coordinate axis.

Return the ratio of modified Bessel functions used by vMF moments.

Numerically invert :meth:a_d for dimension d and value x.

Initializes a new instance of the WatsonDistribution class.

Args: mu (): The mean direction of the distribution. kappa (float): The concentration parameter of the distribution.

Computes the probability density function at xs.

Args: xs: The values at which to evaluate the pdf.

Returns: np.generic: The value of the pdf at xs.

Shift the distribution by a given vector.

Parameters:

Returns:

Raises:

Calculates the complex trignometric moments. Since nquad does not support complex functions, the calculation is split up (as used in the alternative representation of trigonometric polonymials involving the two real numbers alpha and beta

Calculates the angular error between alpha and beta.

Parameters: alpha (float or numpy array): The first angle(s) in radians. beta (float or numpy array): The second angle(s) in radians.

Returns: float or numpy array: The angular error(s) in radians.

Convenient access to mean_direction to have a consistent interface throughout manifolds.

Returns:

Calculates the 4D mean of [cos(x1), sin(x1), cos(x2), sin(x2)]

Returns: mu (4 x 1) expectation value of [cos(x1), sin(x1), cos(x2), sin(x2)]

Can set dim manually to tell apart number of samples vs dimension for 1-D arrays.

Create a hypertoroidal Dirac approximation from a distribution.

Grid distributions are converted deterministically by using every grid point as a Dirac location and normalized grid values as weights. Other hypertoroidal distributions are approximated by sampling and need n_particles.

Calculate the mean direction of the HypertoroidalDiracDistribution.

Parameters:

Returns:

Calculate the trigonometric moment of the HypertoroidalDiracDistribution.

Parameters:

Returns:

Evaluate the underlying (pre-transformation) Fourier series at xs.

Parameters

xs : array_like, shape (n_eval, dim) or (dim,) Points on the hypertorus in radians.

Returns

val : array, shape (n_eval,) Complex-valued series evaluation (real up to numerical error).

Normalize the coefficients so that the implied pdf integrates to 1.

Truncate or pad the coefficient tensor to a desired size, centered.

n_coefficients : int or sequence of ints Desired number of complex coefficients along each dimension. Must be odd and >1 except possibly in the 1-D case.

force_normalization : bool If True, ensures the resulting distribution is normalized even if the transformation is 'identity'.

Transform the representation (e.g., square the underlying function) directly in coefficient space, where supported.

Currently supports only desired_transformation == 'square'.

Multiply two hypertoroidal Fourier distributions (same transformation).

Compute the n-th trigonometric moment for each angular component.

Returns a vector m of length self.dim where

m[d] = E[exp(i * n * x_d)],  for d = 0..dim-1

Construct a Fourier distribution by sampling a function on a grid.

Parameters

fun : callable Takes 'dim' arrays as input (each axis of the grid) and returns an array of the same shape representing the (possibly unnormalized) pdf on the grid. n_coefficients : tuple[int] Desired number of Fourier coefficients along each dimension. desired_transformation : str Transformation to apply to the function values before computing Fourier coefficients. One of 'sqrt', 'log', 'identity'.

Creates Fourier distribution from function values on a regular grid.

fvals : n-D array Values of the (possibly unnormalized) density on a regular grid.

n_coefficients : tuple[int, ...], optional Desired number of Fourier coefficients along each dimension. If None, defaults to size(fvals) plus 1 in even-dimension sizes.

Approximate a given hypertoroidal distribution with a Fourier series.

n_coefficients can be a single integer (broadcast to all dimensions) or a sequence with length equal to distribution.dim.

Transform the distribution by: 1) Going to state space via IFFT (using current 'identity' coeffs), 2) Applying the desired transformation (sqrt / log / identity / custom), 3) Recomputing Fourier coeffs via FFT and truncating.

Convolution of two hypertoroidal Fourier distributions.

Shift distribution by shift_by (on the hypertorus).

Parameters

shift_by : array_like, shape (dim,) Shift in radians for each angular dimension.

Return the closest grid point (toroidal distance) to x.

Parameters

x : array_like, shape (dim,) or (1, dim)

Generate a Cartesian product grid on [0, 2π)^dim.

Parameters

n_grid_points : int or sequence of int Number of grid points along each dimension.

Evaluate the pdf at given query points.

Parameters

xs : array_like (backend compatible), shape (n_points_eval, dim) or (dim,)

Return pdf values of the closest grid point for each query.

Parameters

xa : array_like, shape (n_eval, dim) or (dim,)

Create a grid distribution from an existing hypertoroidal distribution.

Construct a grid distribution by sampling a function on a grid. You need to provide the number of grid points along each dimension. Dimensionality of the torus is determined by the length of n_grid_points.

Parameters

fun : callable Function handle representing a (possibly unnormalized) pdf. Must accept an array of shape (n_eval, dim) and return shape (n_eval,). n_grid_points : int or sequence of int Number of grid points along each dimension.

Return a weighted Dirac distribution on the grid points.

Constructor

Parameters:

Calculate n-th trigonometric moment

Parameters:

Returns:

Shifts the distribution by shift_by.

Parameters:

Returns:

Convert to a circular mixture (only in 1D case)

Returns:

Convert to a toroidal mixture (only in 2D case)

Returns:

Returns the Probability Density Function evaluated at xs

Parameters:

Returns:

Returns the n-th trigonometric moment

Parameters:

Returns:

Returns the entropy of the distribution

Returns:

Returns the mean of the circular uniform distribution. Since it doesn't have a unique mean, this function always raises a ValueError.

Raises:

Returns a sample of size n from the distribution

Parameters:

Returns:

Shifts the distribution by shift_by. Since this is a uniform distribution, the shift does not change the distribution.

Parameters:

Returns:

Returns the integral of the distribution over the specified boundaries

Parameters:

Returns:

Initialize HypertoroidalWrappedNormalDistribution.

Parameters:

Raises:

Set the mean of the distribution.

Parameters: mu (numpy array): The new mean.

Returns: HypertoroidalWNDistribution: A new instance of the distribution with the updated mean.

Compute the PDF at given points.

Parameters:

Returns:

Shift distribution by the given angles

Parameters:

Returns:

Raises:

Set the mode of the distribution.

Parameters: m (numpy array): The new mode.

Returns: HypertoroidalWNDistribution: A new instance of the distribution with the updated mode.

Calculate the trigonometric moment of the HypertoroidalWNDistribution.

Parameters:

Returns:

Initialize ToroidalDiracDistribution.

Parameters:

Calculate the circular correlation according to Jammalamadaka's definition

Returns:

Compute the 4D covariance matrix.

Returns:

Compute the integral of the pdf over the given rectangular region.

Parameters

integration_boundaries : array-like, shape (2, 2), optional [[l1, r1], [l2, r2]]. Defaults to [[0, 2π], [0, 2π]].

Returns

float Value of the integral.

Compute the 4×4 covariance of [cos x1, sin x1, cos x2, sin x2].

Delegates to the numerical implementation from AbstractToroidalDistribution.

Jammalamadaka–SenGupta circular correlation, computed analytically from the Fourier coefficients.

Approximate this distribution with a Toroidal Wrapped Normal.

Uses the moment-matching formula via Fourier coefficients.

Returns

ToroidalWrappedNormalDistribution The best-fitting TWN.

Construct a ToroidalFourierDistribution from a function on the torus.

Parameters

fun : callable Function of two arrays (x1_grid, x2_grid) returning pdf values. n_coefficients : int or tuple[int, int] Number of Fourier coefficients per dimension (must be odd ≥ 3). desired_transformation : str 'sqrt', 'identity', or 'log'.

Construct a ToroidalFourierDistribution from function values on a grid.

Parameters

fvals : 2-D array Function values on a regular grid over [0, 2π)^2. n_coefficients : tuple[int, int] or None If None, inferred from fvals shape. desired_transformation : str already_transformed : bool

Approximate a given toroidal distribution with a ToroidalFourierDistribution.

Parameters

distribution : AbstractHypertoroidalDistribution Distribution to approximate (must have dim == 2). n_coefficients : int or tuple[int, int] Number of Fourier coefficients per dimension. desired_transformation : str

Constructor

Parameters:

Multiply two ToroidalVMMatrixDistributions (exact product).

Get marginal distribution in the given dimension (0 or 1, 0-indexed).

Integrates out the other dimension analytically using the Bessel function identity for the von-Mises-type integral.

Return a copy of this distribution shifted by shift_by.

Compute the 4D mean of the distribution.

Returns: array: The 4D mean.

Compute the 4D covariance of the distribution.

Returns: array: The 4D covariance.

Integrate the probability density function over given boundaries. If no boundaries are provided, default to self.bounds.

Args: integration_boundaries (tuple): A tuple of two elements, each of which can be either a scalar or an array. If a scalar, it represents a single boundary value. If an array, it represents multiple boundary values.

Returns: float: The result of the integration.

Returns suggested limits for integration over the whole density.

The linear part should be integrated from -Inf to Inf but Python's numerical integration does not handle that well. When we can obtain the covariance of the linear part easily, we integrate from mu-10sigma to mu+scaling_factorsigma, which contains almost the entire probability mass. The circular part is integrated form 0 to 2pi.

Returns: l (numpy.ndarray): lower integration bound (shape: (linD+boundD,)) r (numpy.ndarray): upper integration bound (shape: (linD+boundD,))

Constructor, it is the user's responsibility to ensure that f is a valid linear density.

Parameters: f_ (function handle) pdf of the distribution dim_ (scalar) dimension of the Euclidean space

Creates a CustomLinearDistribution from some other distribution

Parameters: dist (AbstractLinearDistribution) distribution to convert

Returns: chd (CustomLinearDistribution) CustomLinearDistribution with identical pdf

Return a copy with a replaced mean vector.

Parameters

new_mean : array-like, shape (n,) New mean vector.

Evaluate the probability density.

Parameters

xs : array-like, shape (n,) or (..., n) Evaluation point or batch of evaluation points. For a one-dimensional Gaussian, one-dimensional arrays are interpreted as a batch of scalar evaluation points.

Returns

array-like Density values with one value per evaluation point.

Return a copy with its mean shifted by shift_by.

Parameters

shift_by : array-like, shape (n,) or scalar Additive shift for the mean vector.

Return the mean vector with shape (n,).

Return the mode of the Gaussian, equal to the mean vector.

Return a copy with a replaced mode.

For a Gaussian distribution, the mode and mean are identical.

Return the covariance matrix with shape (n, n).

Multiply two Gaussian densities and return the normalized product.

Parameters

other : GaussianDistribution Gaussian distribution with the same dimension as self.

Returns

GaussianDistribution Gaussian proportional to the pointwise product of both densities.

Convolve two independent Gaussian distributions.

Parameters

other : GaussianDistribution Gaussian distribution with the same dimension as self.

Returns

GaussianDistribution Gaussian whose mean and covariance are the sums of both operands.

Return the marginal distribution after dropping dimensions.

Parameters

dimensions : int or iterable of int Zero-based state dimensions to remove from the distribution.

Draw n random samples with shape (n, dim).

Approximate or convert another distribution as a Gaussian.

Gaussian mixtures are converted with to_gaussian. Other distributions must expose mean and covariance information compatible with :class:GaussianDistribution.