gm_to_dirac_even_binf< T > Class Template Reference

bMax-free Gaussian-to-Dirac approximation for an even-dimensional standard normal target More...

#include <gm_to_dirac_even_binf.h>

Public Types
using	GSLVectorType = typename GSLTemplateTypeAlias< T >::VectorType
using	GSLMatrixType = typename GSLTemplateTypeAlias< T >::MatrixType

Public Member Functions
bool	approximate (size_t L, size_t N, T *x, const T *wX=nullptr, GslminimizerResult *result=nullptr, const ApproximateOptions &options=ApproximateOptions{})
	approximate a standard normal by L Dirac components
void	modified_van_mises_distance_sq (T *distance, size_t L, size_t N, T *x, const T *wX=nullptr)
	true bMax-free mCvM distance, K_k included
void	modified_van_mises_distance_sq_derivative (T *gradient, size_t L, size_t N, T *x, const T *wX=nullptr)
	gradient of the true bMax-free mCvM distance w.r.t. the SAMPLES
bool	approximate (size_t L, size_t N, GSLVectorType *x, const GSLVectorType *wX=nullptr, GslminimizerResult *result=nullptr, const ApproximateOptions &options=ApproximateOptions{})
	approximate a standard normal by L Dirac components
void	modified_van_mises_distance_sq (T *distance, size_t L, size_t N, GSLVectorType *x, const GSLVectorType *wX=nullptr)
	true bMax-free mCvM distance, K_k included
void	modified_van_mises_distance_sq_derivative (GSLVectorType *gradient, size_t L, size_t N, GSLVectorType *x, const GSLVectorType *wX=nullptr)
	gradient of the true bMax-free mCvM distance w.r.t. the SAMPLES
bool	approximate (size_t L, size_t N, GSLMatrixType *x, const GSLVectorType *wX=nullptr, GslminimizerResult *result=nullptr, const ApproximateOptions &options=ApproximateOptions{})
	approximate a standard normal by L Dirac components
void	modified_van_mises_distance_sq (T *distance, size_t L, size_t N, GSLMatrixType *x, const GSLVectorType *wX=nullptr)
	true bMax-free mCvM distance, K_k included
void	modified_van_mises_distance_sq_derivative (GSLMatrixType *gradient, size_t L, size_t N, GSLMatrixType *x, const GSLVectorType *wX=nullptr)
	gradient of the true bMax-free mCvM distance w.r.t. the SAMPLES
bool	approximate (size_t L, size_t N, gsl_vector_float *x, const gsl_vector_float *wX, GslminimizerResult *result, const ApproximateOptions &options)
void	modified_van_mises_distance_sq (float *distance, size_t L, size_t N, gsl_vector_float *x, const gsl_vector_float *wX)
void	modified_van_mises_distance_sq_derivative (gsl_vector_float *gradient, size_t L, size_t N, gsl_vector_float *x, const gsl_vector_float *wX)
bool	approximate (size_t L, size_t N, gsl_vector *x, const gsl_vector *wX, GslminimizerResult *result, const ApproximateOptions &options)
void	modified_van_mises_distance_sq (double *distance, size_t L, size_t N, gsl_vector *x, const gsl_vector *wX)
void	modified_van_mises_distance_sq_derivative (gsl_vector *gradient, size_t L, size_t N, gsl_vector *x, const gsl_vector *wX)
bool	approximate (size_t L, size_t N, gsl_vector_float *x, const gsl_vector_float *wX, GslminimizerResult *result, const ApproximateOptions &options)
bool	approximate (size_t L, size_t N, gsl_vector *x, const gsl_vector *wX, GslminimizerResult *result, const ApproximateOptions &options)
void	modified_van_mises_distance_sq (float *distance, size_t L, size_t N, gsl_vector_float *x, const gsl_vector_float *wX)
void	modified_van_mises_distance_sq (double *distance, size_t L, size_t N, gsl_vector *x, const gsl_vector *wX)
void	modified_van_mises_distance_sq_derivative (gsl_vector_float *gradient, size_t L, size_t N, gsl_vector_float *x, const gsl_vector_float *wX)
void	modified_van_mises_distance_sq_derivative (gsl_vector *gradient, size_t L, size_t N, gsl_vector *x, const gsl_vector *wX)

Detailed Description

template<typename T>
class gm_to_dirac_even_binf< T >

bMax-free Gaussian-to-Dirac approximation for an even-dimensional standard normal target

Same objective family as gm_to_dirac_even_closed_form, but the limit bMax -> infinity has been taken analytically (see lcd_even_binf_closed_form.h), so no integration bound appears anywhere in the API.

Note

PRECONDITIONS

• N must be EVEN and >= 2 and L >= 1. approximate() returns false and the void-returning entry points write NaN to their output rather than leaving a stale buffer.
• The target must be the STANDARD normal N(0, I).
• The sample set must have ZERO MEAN, sum_i w_i s_i = 0. The limit exists only there; for a non-zero mean the closed form still evaluates to a finite number that is NOT the distance.

The minimizer optimises over an unconstrained t and every objective and gradient evaluation begins by projecting

s = t - 1 * (w^T t)

with the assembled gradient chain-ruled back by

grad_{t,q} = grad_{s,q} - w_q * sum_i grad_{s,i}

so no iterate can ever leave the zero-mean manifold and the finite non-distance is unreachable. The same projection runs inside the standalone distance and derivative entry points, which therefore report the value for the MEAN-CORRECTED input rather than for the raw input.

Note

DEGENERATE SAMPLE SETS. phi_k is undefined at c = 0 and evaluating it there reaches lcd_ei(0), which GSL's default error handler turns into a process abort. Any input whose projection puts a sample exactly on the origin is therefore refused the same way odd N is: approximate() returns false before the minimizer starts and the void entry points write NaN. That covers L == 1, whose only zero-mean sample set is the single point 0 and inputs such as L identical locations.

Template Parameters

T	float or double; computation is always performed in double and cast at the interface boundary

Member Function Documentation

approximate() [1/3]

template<typename T >

bool gm_to_dirac_even_binf< T >::approximate	(	size_t	L,
		size_t	N,
		GSLMatrixType *	x,
		const GSLVectorType *	wX = nullptr,
		GslminimizerResult *	result = nullptr,
		const ApproximateOptions &	options = ApproximateOptions{}
	)

approximate a standard normal by L Dirac components

Parameters

L	number of Dirac components, must be >= 1
N	dimension, must be even and >= 2
x	initial guess and output locations (L rows, N columns)
wX	weights, nullptr for uniform
result	minimizer result
options	minimizer options; ApproximateOptions::bMax is IGNORED

Returns

true on success, false otherwise (including odd N)

approximate() [2/3]

template<typename T >

bool gm_to_dirac_even_binf< T >::approximate	(	size_t	L,
		size_t	N,
		GSLVectorType *	x,
		const GSLVectorType *	wX = nullptr,
		GslminimizerResult *	result = nullptr,
		const ApproximateOptions &	options = ApproximateOptions{}
	)

approximate a standard normal by L Dirac components

Parameters

L	number of Dirac components, must be >= 1
N	dimension, must be even and >= 2
x	initial guess and output locations (L * N)
wX	weights, nullptr for uniform
result	minimizer result
options	minimizer options; ApproximateOptions::bMax is IGNORED

Returns

true on success, false otherwise (including odd N)

approximate() [3/3]

template<typename T >

bool gm_to_dirac_even_binf< T >::approximate	(	size_t	L,
		size_t	N,
		T *	x,
		const T *	wX = nullptr,
		GslminimizerResult *	result = nullptr,
		const ApproximateOptions &	options = ApproximateOptions{}
	)

approximate a standard normal by L Dirac components

On return x holds the projected, zero-mean sample set s, not the raw optimizer variable t.

Parameters

L	number of Dirac components, must be >= 1
N	dimension, must be even and >= 2
x	initial guess and output locations (L * N)
wX	weights, nullptr for uniform
result	minimizer result
options	minimizer options; ApproximateOptions::bMax is IGNORED, there is no integration bound on this path

Returns

true on success, false otherwise (including odd N)

modified_van_mises_distance_sq() [1/3]

template<typename T >

void gm_to_dirac_even_binf< T >::modified_van_mises_distance_sq	(	T *	distance,
		size_t	L,
		size_t	N,
		GSLMatrixType *	x,
		const GSLVectorType *	wX = nullptr
	)

true bMax-free mCvM distance, K_k included

Parameters

distance	output distance; set to NaN if the preconditions fail
L	number of Dirac components, must be >= 1
N	dimension, must be even and >= 2
x	sample locations (L rows, N columns)
wX	weights, nullptr for uniform

modified_van_mises_distance_sq() [2/3]

template<typename T >

void gm_to_dirac_even_binf< T >::modified_van_mises_distance_sq	(	T *	distance,
		size_t	L,
		size_t	N,
		GSLVectorType *	x,
		const GSLVectorType *	wX = nullptr
	)

true bMax-free mCvM distance, K_k included

Parameters

distance	output distance; set to NaN if the preconditions fail
L	number of Dirac components, must be >= 1
N	dimension, must be even and >= 2
x	sample locations (L * N)
wX	weights, nullptr for uniform

modified_van_mises_distance_sq() [3/3]

template<typename T >

void gm_to_dirac_even_binf< T >::modified_van_mises_distance_sq	(	T *	distance,
		size_t	L,
		size_t	N,
		T *	x,
		const T *	wX = nullptr
	)

true bMax-free mCvM distance, K_k included

Reports the distance of the mean-corrected sample set

Parameters

distance	output distance; set to NaN if the preconditions fail
L	number of Dirac components, must be >= 1
N	dimension, must be even and >= 2
x	sample locations (L * N)
wX	weights, nullptr for uniform

modified_van_mises_distance_sq_derivative() [1/3]

template<typename T >

void gm_to_dirac_even_binf< T >::modified_van_mises_distance_sq_derivative	(	GSLMatrixType *	gradient,
		size_t	L,
		size_t	N,
		GSLMatrixType *	x,
		const GSLVectorType *	wX = nullptr
	)

gradient of the true bMax-free mCvM distance w.r.t. the SAMPLES

Returns grad_s, not the minimizer's grad_t; see the raw-pointer overload.

Parameters

gradient	output gradient (L rows, N columns); filled with NaN if the preconditions fail
L	number of Dirac components, must be >= 1
N	dimension, must be even and >= 2
x	sample locations (L rows, N columns)
wX	weights, nullptr for uniform

modified_van_mises_distance_sq_derivative() [2/3]

template<typename T >

void gm_to_dirac_even_binf< T >::modified_van_mises_distance_sq_derivative	(	GSLVectorType *	gradient,
		size_t	L,
		size_t	N,
		GSLVectorType *	x,
		const GSLVectorType *	wX = nullptr
	)

gradient of the true bMax-free mCvM distance w.r.t. the SAMPLES

Returns grad_s, not the minimizer's grad_t; see the raw-pointer overload.

Parameters

gradient	output gradient (L * N); filled with NaN if the preconditions fail
L	number of Dirac components, must be >= 1
N	dimension, must be even and >= 2
x	sample locations (L * N)
wX	weights, nullptr for uniform

modified_van_mises_distance_sq_derivative() [3/3]

template<typename T >

void gm_to_dirac_even_binf< T >::modified_van_mises_distance_sq_derivative	(	T *	gradient,
		size_t	L,
		size_t	N,
		T *	x,
		const T *	wX = nullptr
	)

gradient of the true bMax-free mCvM distance w.r.t. the SAMPLES

Returns grad_s, the derivative with respect to the sample locations themselves:

grad_s,q = -4 w_q phi_k'(c_q) s_q
         + 0.5 w_q sum_{j != q, T_qj > 0} w_j (s_q - s_j)
                                        * (ln(T_qj / 4) + 1)

This is NOT the gradient the minimizer works with. approximate() varies the unconstrained t behind s = t - 1 * (w^T t) and therefore uses grad_t,q = grad_s,q - w_q * sum_i grad_s,i. The two agree only up to that projection; grad_s is exposed here because it is the derivative of the distance as a function of the sample set, which is what a caller asking for "the gradient at x" means.

Parameters

gradient	output gradient (L * N); filled with NaN if the preconditions fail
L	number of Dirac components, must be >= 1
N	dimension, must be even and >= 2
x	sample locations (L * N)
wX	weights, nullptr for uniform

---

The documentation for this class was generated from the following files:

• lib/gm_to_dirac_even_binf/gm_to_dirac_even_binf.h
• lib/gm_to_dirac_even_binf/gm_to_dirac_even_binf.cpp