Files
file	fnft__misc.h
	Miscellaneous functions used in the FNFT library.

Functions
void	fnft__misc_print_buf (const FNFT_UINT len, FNFT_COMPLEX const const buf, char const const varname)
	Helper function for debugging. Prints an array in MATLAB style.

FNFT_REAL	fnft__misc_rel_err (const FNFT_UINT len, FNFT_COMPLEX const const vec_numer, FNFT_COMPLEX const const vec_exact)
	Relative l1 error between two vectors.

FNFT_REAL	fnft__misc_hausdorff_dist (const FNFT_UINT lenA, FNFT_COMPLEX const const vecA, const FNFT_UINT lenB, FNFT_COMPLEX const const vecB)
	Hausdorff distance between two vectors.

FNFT_COMPLEX	fnft__misc_sech (FNFT_COMPLEX Z)
	Hyperbolic secant.

FNFT_REAL	fnft__misc_l2norm2 (const FNFT_UINT N, FNFT_COMPLEX const *const Z, const FNFT_REAL a, const FNFT_REAL b)
	Squared l2 norm.

FNFT_INT	fnft__misc_filter (FNFT_UINT const N, FNFT_COMPLEX const vals, FNFT_COMPLEX const rearrange_as_well, FNFT_REAL const const bounding_box)
	Filters array by retaining elements inside a bounding box.

FNFT_INT	fnft__misc_filter_nonreal (FNFT_UINT N_ptr, FNFT_COMPLEX const vals, const FNFT_REAL tol_im)
	Filter array based on specified tolerance.

FNFT_INT	fnft__misc_filter_inv (FNFT_UINT const N_ptr, FNFT_COMPLEX const vals, FNFT_COMPLEX const rearrange_as_well, FNFT_REAL const const bounding_box)
	Filters array by retaining elements outside a bounding box.

FNFT_INT	fnft__misc_merge (FNFT_UINT N_ptr, FNFT_COMPLEX const vals, FNFT_REAL tol)
	Merges elements in an array with distance lower than tol.

FNFT_INT	fnft__misc_downsample (const FNFT_UINT D, FNFT_COMPLEX const const q, FNFT_UINT const Dsub_ptr, FNFT_COMPLEX *qsub_ptr, FNFT_UINT const first_last_index)
	Downsamples an array.

static FNFT_COMPLEX	fnft__misc_CSINC (FNFT_COMPLEX x)
	Sinc function for complex arguments.

static FNFT_COMPLEX	fnft__misc_CSINC_derivative (FNFT_COMPLEX x)
	Derivative of sinc function for complex arguments.

FNFT_UINT	fnft__misc_nextpowerof2 (const FNFT_UINT number)
	Closest larger or equal number that is a power of two.

FNFT_INT	fnft__misc_resample (const FNFT_UINT D, const FNFT_REAL eps_t, FNFT_COMPLEX const const q, const FNFT_REAL delta, FNFT_COMPLEX const q_new)
	Resamples an array.

static void	fnft__misc_matrix_mult (const FNFT_UINT n, const FNFT_UINT m, const FNFT_UINT p, FNFT_COMPLEX const const A, FNFT_COMPLEX const const B, FNFT_COMPLEX *const C)
	Multiples two complex valued matrices of any compatible size.

static void	fnft__misc_mat_mult_2x2 (FNFT_COMPLEX const U, FNFT_COMPLEX const T)
	Multiples two square matrices of size 2.

static void	fnft__misc_mat_mult_4x4 (FNFT_COMPLEX const U, FNFT_COMPLEX const T)
	Multiples two square matrices of size 4.

static FNFT_REAL	fnft__misc_legendre_poly (const FNFT_UINT n, const FNFT_REAL x)
	This routine returns the nth degree Legendre polynomial at x.

static FNFT_INT	fnft__misc_normalize_vector (const FNFT_UINT len, FNFT_COMPLEX *const v)
	Normalizes a complex vector so that the maximum absolute value is >=1 and <2.

Detailed Description

Function Documentation

◆ fnft__misc_CSINC()

static FNFT_COMPLEX fnft__misc_CSINC ( FNFT_COMPLEX x )

inlinestatic

Sinc function for complex arguments.

Function computes the sinc function sin(x)/x for FNFT_COMPLEX argument. If x is close to 0, the calculation is approximated with sinc(x) = cos(x/sqrt(3)) + O(x^4)

Parameters

[in] x FNFT_COMPLEX argument.

Returns: sinc(x).

◆ fnft__misc_CSINC_derivative()

static FNFT_COMPLEX fnft__misc_CSINC_derivative ( FNFT_COMPLEX x )

inlinestatic

Derivative of sinc function for complex arguments.

Function computes the derivative of the sinc function sin(x)/x for FNFT_COMPLEX argument. This derivative can be expressed analytically as d/dx sinc(x) = 0 if x=0, and (cos(x) - sinc(x)) / x otherwise. However, if x is close to 0, a numerical implementation like that results in catastrophic cancellation. Therefore we use its Taylor approximation instead: \( \frac{d}{dx} \text{sinc}(x) = \sum_{n=0}^\infty \frac{x^{2n+1} (-1)^{n+1}}{(2n+3)(2*n+1)!} )\) of which we use the first 9 terms, i.e. a 18-th order Taylor approximation. This polynomial is computed with Horner's method.

Parameters

[in] x FNFT_COMPLEX argument.

Returns: d/dx sinc(x).

◆ fnft__misc_downsample()

FNFT_INT fnft__misc_downsample	(	const FNFT_UINT	D,
		FNFT_COMPLEX const *const	q,
		FNFT_UINT *const	Dsub_ptr,
		FNFT_COMPLEX **	qsub_ptr,
		FNFT_UINT *const	first_last_index
	)

Downsamples an array.

Computes a subsampled version of q. The length of q is D>=2. The routine will allocate memory for the subsampled signal qsub and updates the pointer *qsub_ptr such that it points to the newly allocated qsub. The user is responsible to freeing the memory later.

Parameters

[in]	D	Number of samples in array q.
[in]	q	Complex valued array to be subsampled.
[out]	qsub_ptr	Pointer to the starting location of subsampled signal.
[out]	Dsub_ptr	Pointer to new number of samples. Upon entry, Dsub_ptr should contain a desired number of samples. Upon exit, Dsub_ptr has been overwritten with the actual number of samples that the routine has chosen. It is usually close to the desired one.
[out]	first_last_index	Vector of length two. Upon exit, it contains the original index of the first and the last sample in qsub. That is, qsub[0]=q[first_last_index[0]] and qsub[Dsub-1]=q[first_last_index[1]].

Returns: Returns SUCCESS or an error code.

◆ fnft__misc_filter()

FNFT_INT fnft__misc_filter	(	FNFT_UINT *const	N,
		FNFT_COMPLEX *const	vals,
		FNFT_COMPLEX *const	rearrange_as_well,
		FNFT_REAL const *const	bounding_box
	)

Filters array by retaining elements inside a bounding box.

This function filters the array vals. Only values that satisfy

 bounding_box[0] <= real(val) <= bounding_box[1]

and

 bounding_box[2] <= imag(val) <= bounding_box[3]

are kept.

Parameters

[in,out]	N	It is the pointer to the number of values to be filtered. On exit *N is overwritten with the number of values that have survived fitering. Their values will be moved to the beginning of vals.
[in,out]	vals	Complex valued array with elements to be filtered.
[in]	rearrange_as_well	Complex valued array. If the array rearrange_as_well is not NULL, then the values in there are rearranged together with the values in vals.
[in]	bounding_box	A real array of 4 elements. The elements determine the corners of the bounding box being used for filtering.

Returns: Returns SUCCESS or an error code.

◆ fnft__misc_filter_inv()

FNFT_INT fnft__misc_filter_inv	(	FNFT_UINT *const	N_ptr,
		FNFT_COMPLEX *const	vals,
		FNFT_COMPLEX *const	rearrange_as_well,
		FNFT_REAL const *const	bounding_box
	)

Filters array by retaining elements outside a bounding box.

This function filters the array vals. Only values OUTSIDE the bounding box are kept.

Parameters

[in,out]	N_ptr	It is the pointer to the number of values to be filtered. On exit *N_ptr is overwritten with the number of values that have survived fitering. Their values will be moved to the beginning of vals.
[in,out]	vals	Complex valued array with elements to be filtered.
[in]	rearrange_as_well	Complex valued array. If the array rearrange_as_well is not NULL, then the values in there are rearranged together with the values in vals.
[in]	bounding_box	A real array of 4 elements. The elements determine the corners of the bounding box being used for filtering.

Returns: Returns SUCCESS or an error code.

◆ fnft__misc_filter_nonreal()

FNFT_INT fnft__misc_filter_nonreal	(	FNFT_UINT *	N_ptr,
		FNFT_COMPLEX *const	vals,
		const FNFT_REAL	tol_im
	)

Filter array based on specified tolerance.

This function removes all entries from the array vals with |Im(val)|>tol_im.

Parameters

[in,out]	N_ptr	Pointer to number of values to be filtered. On exit *N_ptr is overwritten with the number of values that have survived fitering. Their values will be moved to the beginning of vals.
[in,out]	vals	Complex valued array with elements to be filtered.
[in]	tol_im	Real valued tolerance.

Returns: Returns SUCCESS or an error code.

◆ fnft__misc_hausdorff_dist()

FNFT_REAL fnft__misc_hausdorff_dist	(	const FNFT_UINT	lenA,
		FNFT_COMPLEX const *const	vecA,
		const FNFT_UINT	lenB,
		FNFT_COMPLEX const *const	vecB
	)

Hausdorff distance between two vectors.

This function computes the Hausdorff distance between two vectors vecA and vecB.

Parameters

[in]	lenA	Length of vector vecA.
[in]	vecA	Complex vector of length lenA.
[in]	lenB	length of vector vecB.
[in]	vecB	Complex vector of length lenB.

Returns: Returns the real valued Hausdorff distance between the vectors vecA and vecB.

◆ fnft__misc_l2norm2()

FNFT_REAL fnft__misc_l2norm2	(	const FNFT_UINT	N,
		FNFT_COMPLEX const *const	Z,
		const FNFT_REAL	a,
		const FNFT_REAL	b
	)

Squared l2 norm.

This function computes the quantity
\( val = \frac{b-a}{N} \sum_{i=0}^{i=N-1}|Z[i]|^2\).

Parameters

[in]	N	Number of elements in the array.
[in]	Z	Complex valued array of length N.
[in]	a	Real number corresponding to the left boundary of the first element of Z.
[in]	b	Real number corresponding to right boundary of the last element of Z.

Returns: Returns the quantity val. Returns NAN if N==0 or a>=b.

◆ fnft__misc_legendre_poly()

static FNFT_REAL fnft__misc_legendre_poly	(	const FNFT_UINT	n,
		const FNFT_REAL	x
	)

inlinestatic

This routine returns the nth degree Legendre polynomial at x.

Calculates the the nth degree Legendre polynomial at x using a recursive relation (Online, Accessed July 2020)

Parameters

[in]	n	Positive integer that is the order of the Legendre polynomial.
[in]	x	Real scalar value at which the value of the polynomial is to be calculated.

Returns: Returns the value of nth degree Legendre polynomial at x.

◆ fnft__misc_mat_mult_2x2()

static void fnft__misc_mat_mult_2x2	(	FNFT_COMPLEX *const	U,
		FNFT_COMPLEX *const	T
	)

inlinestatic

Multiples two square matrices of size 2.

Multiples two square matrices U and T of size 2. T is replaced by the result U*T.

Parameters

[in]	U	Pointer to the first element of complex values 2x2 matrix U.
[in,out]	T	Pointer to the first element of complex values 2x2 matrix T. Contains the result U*T on return.

◆ fnft__misc_mat_mult_4x4()

static void fnft__misc_mat_mult_4x4	(	FNFT_COMPLEX *const	U,
		FNFT_COMPLEX *const	T
	)

inlinestatic

Multiples two square matrices of size 4.

Multiples two square matrices U and T of size 4. T is replaced by the result U*T.

Parameters

[in]	U	Pointer to the first element of complex values 4x4 matrix U.
[in,out]	T	Pointer to the first element of complex values 4x4 matrix T. Contains the result U*T on return.

◆ fnft__misc_matrix_mult()

static void fnft__misc_matrix_mult	(	const FNFT_UINT	n,
		const FNFT_UINT	m,
		const FNFT_UINT	p,
		FNFT_COMPLEX const *const	A,
		FNFT_COMPLEX const *const	B,
		FNFT_COMPLEX *const	C
	)

inlinestatic

Multiples two complex valued matrices of any compatible size.

Right-multiples an nxm matrix A by an mxp matrix B. The resulting nxp matrix is stored in C.

Parameters

[in]	n	Positive integer that is the number of rows of A and C.
[in]	m	Positive integer that is the number of columns of A and the number of rows of B.
[in]	p	Positive integer that is the number of columns of B and C.
[in]	A	Pointer to the first element of complex valued nxm matrix A.
[in]	B	Pointer to the first element of complex valued mxp matrix B.
[out]	C	Pointer to the first element of complex valued nxp matrix C which will contain the result C=AB on return. The user should allocate memory for C, different from the memory that contains A and B.

◆ fnft__misc_merge()

FNFT_INT fnft__misc_merge	(	FNFT_UINT *	N_ptr,
		FNFT_COMPLEX *const	vals,
		FNFT_REAL	tol
	)

Merges elements in an array with distance lower than tol.

This function filters an array by merging elements if distance between the elements is less than tol.

Parameters

[in,out]	N_ptr	It is the pointer to the number of elements to be filtered. On exit *N_ptr is overwritten with the number of values that have survived fitering. Their values will be moved to the beginning of vals.
[in,out]	vals	Complex valued array with elements to be filtered.
[in]	tol	Real valued tolerance.

Returns: Returns SUCCESS or an error code.

◆ fnft__misc_nextpowerof2()

FNFT_UINT fnft__misc_nextpowerof2 ( const FNFT_UINT number )

Closest larger or equal number that is a power of two.

Parameters

[in] number

Returns: min{r >= number : exists d such that r = 2^d}

◆ fnft__misc_normalize_vector()

static FNFT_INT fnft__misc_normalize_vector	(	const FNFT_UINT	len,
		FNFT_COMPLEX *const	v
	)

inlinestatic

Normalizes a complex vector so that the maximum absolute value is >=1 and <2.

Parameters

[in]	len	Length of the vector.
[in,out]	v	Complex vector to be normalized. Is overwritten with the result.

Returns: Returns an integer a. Two to the power -a is the scaling factor used for the normalization. That is, v_out = 2^(-a)*v_in.

◆ fnft__misc_print_buf()

void fnft__misc_print_buf	(	const FNFT_UINT	len,
		FNFT_COMPLEX const *const	buf,
		char const *const	varname
	)

Helper function for debugging. Prints an array in MATLAB style.

This function prints an array in MATLAB style.

Parameters

[in]	len	Length of the array to be printed.
[in]	buf	Array to be printed.
[in]	varname	Name of the array being printed.

◆ fnft__misc_rel_err()

FNFT_REAL fnft__misc_rel_err	(	const FNFT_UINT	len,
		FNFT_COMPLEX const *const	vec_numer,
		FNFT_COMPLEX const *const	vec_exact
	)

Relative l1 error between two vectors.

This function computes the relative l1 error between two vectors.
\(err = \frac{\sum_{i=0}^{i=len-1} |vec\_numer[i]-vec\_exact[i]|}{\sum_{i=0}^{i=len-1} |vec\_exact[i]|}\).

Parameters

[in]	len	Length of the vectors
[in]	vec_numer	Complex array of numerically computed result of length len.
[in]	vec_exact	Complex array of exact result of length len.

Returns: Returns the real valued relative error err.

◆ fnft__misc_resample()

FNFT_INT fnft__misc_resample	(	const FNFT_UINT	D,
		const FNFT_REAL	eps_t,
		FNFT_COMPLEX const *const	q,
		const FNFT_REAL	delta,
		FNFT_COMPLEX *const	q_new
	)

Resamples an array.

Computes a resampled version of q. The length of q is D>=2. Performs bandlimited interpolation to obtain signal samples at new locations \(q(t_{n}+\delta)\) from samples given at \(q(t_{n})\) for \(n=0,1,...,D-1\). This is required for the CF4_2, CF4_3, CF5_3, CF6_4, 4SPLIT4A and 4SPLIT4B discretizations. The routine checks the difference between the l2-norm of the complete spectrum and approximately 90% of the spectrum. The following warning is issued if the difference is high. "Signal does not appear to be bandlimited. Interpolation step may be inaccurate. Try to reduce the step size, or switch to a discretization that does not require interpolation".

Parameters

[in]	D	Number of samples in array q.
[in]	eps_t	Step-size of t.
[in]	q	Complex valued array to be resampled.
[in]	delta	Real valued shift to be applied during resampling.
[out]	q_new	Complex valued array of resampled signal.

Returns: Returns SUCCESS or an error code.

◆ fnft__misc_sech()

FNFT_COMPLEX fnft__misc_sech ( FNFT_COMPLEX Z )

Hyperbolic secant.

This function returns the hyperbolic secant of a FNFT_COMPLEX.

Parameters

[in] Z FNFT_COMPLEX argument.

Returns: hyperbolic secant of Z.

Files

Functions

Detailed Description

Function Documentation

◆ fnft__misc_CSINC()

◆ fnft__misc_CSINC_derivative()

◆ fnft__misc_downsample()

◆ fnft__misc_filter()

◆ fnft__misc_filter_inv()

◆ fnft__misc_filter_nonreal()

◆ fnft__misc_hausdorff_dist()

◆ fnft__misc_l2norm2()

◆ fnft__misc_legendre_poly()

◆ fnft__misc_mat_mult_2x2()

◆ fnft__misc_mat_mult_4x4()

◆ fnft__misc_matrix_mult()

◆ fnft__misc_merge()

◆ fnft__misc_nextpowerof2()

◆ fnft__misc_normalize_vector()

◆ fnft__misc_print_buf()

◆ fnft__misc_rel_err()

◆ fnft__misc_resample()

◆ fnft__misc_sech()