Files
file	fnft__kdv_discretization.h
	Properties of the discretizations for the Korteweg-de Vries equation.

file	fnft__kdv_fscatter.h
	Computes the polynomial approximation of the combined scattering matrix.

file	fnft__kdv_scatter.h
	Slow forward scattering.

file	fnft__kdvv_testcases.h
	Provides test cases for the tests of fnft_kdvv.

Enumerations
enum	fnft__kdvv_testcases_t { fnft__kdvv_testcases_SECH, fnft__kdvv_testcases_RECT, fnft__kdvv_testcases_NEGATIVE_RECT }

Functions
FNFT_UINT	fnft__kdv_discretization_degree (fnft_kdv_discretization_t discretization)
	This routine returns the max degree \(d\) of the polynomials in a single scattering matrix or zero if the discretization is unknown. More...

FNFT_REAL	fnft__kdv_discretization_boundary_coeff (fnft_kdv_discretization_t discretization)
	This routine returns the boundary coefficient based on the discretization. More...

FNFT_INT	fnft__kdv_discretization_to_akns_discretization (fnft_kdv_discretization_t kdv_discretization, fnft__akns_discretization_t *const akns_discretization)
	This routine returns akns discretization related to the given kdv discretization. More...

FNFT_UINT	fnft__kdv_discretization_upsampling_factor (fnft_kdv_discretization_t discretization)
	This routine returns the scaling for effective number of samples based on the discretization. More...

FNFT_INT	fnft__kdv_discretization_lambda_to_z (const FNFT_UINT n, const FNFT_REAL eps_t, FNFT_COMPLEX *const vals, fnft_kdv_discretization_t discretization)
	This routine maps \(\lambda\) from continuous-time domain to \(z\) in the discrete-time domain based on the discretization. More...

FNFT_INT	fnft__kdv_discretization_z_to_lambda (const FNFT_UINT n, const FNFT_REAL eps_t, FNFT_COMPLEX *const vals, fnft_kdv_discretization_t discretization)
	This routine maps \(z\) from the discrete-time domain to \(\lambda\) in the continuous-time domain based on the discretization. More...

FNFT_UINT	fnft__kdv_fscatter_numel (FNFT_UINT D, fnft_kdv_discretization_t discretization)
	Returns the length of transfer_matrix to be allocated based on the number of samples and discretization. More...

FNFT_INT	fnft__kdv_fscatter_zero_freq_scatter_matrix (FNFT_COMPLEX *M, const FNFT_REAL eps_t, const FNFT_REAL q)
	Returns the scattering matrix for a single step at frequency zero. More...

FNFT_INT	fnft__kdv_fscatter (const FNFT_UINT D, FNFT_COMPLEX const const q, const FNFT_REAL eps_t, FNFT_COMPLEX const result, FNFT_UINT const deg_ptr, INT const W_ptr, fnft_kdv_discretization_t discretization)
	Fast computation of polynomial approximation of the combined scattering matrix. More...

FNFT_INT	fnft__kdv_scatter_matrix (const FNFT_UINT D, FNFT_COMPLEX const const q, const FNFT_REAL eps_t, const FNFT_UINT K, FNFT_COMPLEX const const lambda, FNFT_COMPLEX *const result, fnft_kdv_discretization_t discretization, const UINT derivative_flag)
	Computes the scattering matrix and its derivative. More...

FNFT_INT	fnft__kdvv_testcases_test_fnft (fnft__kdvv_testcases_t tc, FNFT_UINT D, const FNFT_REAL eb[6], fnft_kdvv_opts_t *const opts)
	Routine to run tests for fnft_kdvv. More...

Detailed Description

Enumeration Type Documentation

◆ fnft__kdvv_testcases_t

enum fnft__kdvv_testcases_t

List of currently implemented test cases for the KdV with vanishing boundary conditions.

fnft__kdvv_testcases_SECH - A squared sech potential.
fnft__kdvv_testcases_RECT - A rectangular potential, amplitude=1.
fnft__kdvv_testcases_NEGATIVE_RECT - A rectangular potential, amplitude=-1.

Function Documentation

◆ fnft__kdv_discretization_boundary_coeff()

FNFT_REAL fnft__kdv_discretization_boundary_coeff ( fnft_kdv_discretization_t discretization )

This routine returns the boundary coefficient based on the discretization.

The boundary coefficient is the fraction of the step size that a discretized potential extends beyond the last sample. This routine returns this value based on the discretization of type fnft_kdv_discretization_t.

Parameters

[in] discretization The type of discretization to be used. Should be of type fnft_kdv_discretization_t.

Returns: the boundary coefficient, or NAN for discretizations not supported by fnft__kdv_fscatter.

◆ fnft__kdv_discretization_degree()

FNFT_UINT fnft__kdv_discretization_degree ( fnft_kdv_discretization_t discretization )

This routine returns the max degree \(d\) of the polynomials in a single scattering matrix or zero if the discretization is unknown.

It defines the step size of the frequency grid \(z = \text{e}^{2j\xi\epsilon_t d}\) based on the discretization type.

Parameters

[in] discretization The type of discretization to be used. Should be of type fnft_kdv_discretization_t.

Returns: polynomial degree, or 0 for discretizations not supported by fnft__kdv_fscatter.

◆ fnft__kdv_discretization_lambda_to_z()

FNFT_INT fnft__kdv_discretization_lambda_to_z	(	const FNFT_UINT	n,
		const FNFT_REAL	eps_t,
		FNFT_COMPLEX *const	vals,
		fnft_kdv_discretization_t	discretization
	)

This routine maps \(\lambda\) from continuous-time domain to \(z\) in the discrete-time domain based on the discretization.

This routine maps continuous-time domain value \(\lambda\) to discrete-time domain value \(z = e^{2j\lambda\epsilon_t degree1step}\), where degree1step is based on the discretization of type fnft_kdv_discretization_t. Changes discretization to fnft__akns_discretization_t type and calls fnft__akns_discretization_lambda_to_z.

Parameters

[in]	n	Number of values to be mapped.
[in]	eps_t	Real-valued discretization step-size.
[in,out]	vals	Pointer to location of first element of array containing complex-valued continuous-time domain spectral parameter \(\lambda\). The values are replaced with discrete-time domain values \(z\).
[in]	discretization	Discretization of type fnft_kdv_discretization_t.

Returns: FNFT_SUCCESS or one of the FNFT_EC_... error codes defined in fnft_errwarn.h.

◆ fnft__kdv_discretization_to_akns_discretization()

FNFT_INT fnft__kdv_discretization_to_akns_discretization	(	fnft_kdv_discretization_t	kdv_discretization,
		fnft__akns_discretization_t *const	akns_discretization
	)

This routine returns akns discretization related to the given kdv discretization.

The function is used by kdv specific functions to convert discretization type from fnft_kdv_discretization_t to fnft__akns_discretization_t.

Parameters

[in]	kdv_discretization	The type of kdv discretization. Should be of type fnft_kdv_discretization_t.
[out]	akns_discretization	The pointer to the converted discretization of type fnft__akns_discretization_t.

Returns: FNFT_SUCCESS or one of the FNFT_EC_... error codes defined in fnft_errwarn.h.

◆ fnft__kdv_discretization_upsampling_factor()

FNFT_UINT fnft__kdv_discretization_upsampling_factor ( fnft_kdv_discretization_t discretization )

This routine returns the scaling for effective number of samples based on the discretization.

Higher order methods use more than one sample per integration step. This routine returns the value upsampling_factor based on the discretization of type fnft_kdv_discretization_t. D_effective = upsampling_factor * D.

Parameters

[in] discretization The type of discretization to be used. Should be of type fnft_nse_discretization_t.

Returns: the upsampling_factor value, or 0 for discretizations not supported by fnft__kdv_fscatter.

◆ fnft__kdv_discretization_z_to_lambda()

FNFT_INT fnft__kdv_discretization_z_to_lambda	(	const FNFT_UINT	n,
		const FNFT_REAL	eps_t,
		FNFT_COMPLEX *const	vals,
		fnft_kdv_discretization_t	discretization
	)

This routine maps \(z\) from the discrete-time domain to \(\lambda\) in the continuous-time domain based on the discretization.

This routine maps discrete-time domain value \(z\) to continuous-time domain value \(\lambda = degree1step\log(z)/(2j\epsilon_t)\), where degree1step is based on the discretization of type fnft_kdv_discretization_t. Changes discretization to fnft__akns_discretization_t type and calls fnft__akns_discretization_z_to_lambda.

Parameters

[in]	n	Number of values to be mapped.
[in]	eps_t	Real-valued discretization step-size.
[in,out]	vals	Pointer to location of first element of array containing complex-valued discrete-time domain spectral parameter \(z\). The values are replaced with continuous-time domain values \(\lambda\).
[in]	discretization	Discretization of type fnft_kdv_discretization_t.

Returns: FNFT_SUCCESS or one of the FNFT_EC_... error codes defined in fnft_errwarn.h.

◆ fnft__kdv_fscatter()

FNFT_INT fnft__kdv_fscatter	(	const FNFT_UINT	D,
		FNFT_COMPLEX const *const	q,
		const FNFT_REAL	eps_t,
		FNFT_COMPLEX *const	result,
		FNFT_UINT *const	deg_ptr,
		INT *const	W_ptr,
		fnft_kdv_discretization_t	discretization
	)

Fast computation of polynomial approximation of the combined scattering matrix.

This routine computes the polynomial approximation of the combined scattering matrix by multipying together individual scattering matrices.
Individual scattering matrices depend on the chosen discretization.

The main reference is Wahls and Poor (Proc. ICASSP 2013 ).

Parameters

[in]	D	Number of samples
[in]	q	Array of length D, contains samples \( q(t_n)=q(x_0, t_n) \), where \( t_n = T[0] + n(T[1]-T[0])/(D-1) \) and \(n=0,1,\dots,D-1\), of the to-be-transformed signal in ascending order (i.e., \( q(t_0), q(t_1), \dots, q(t_{D-1}) \))
[in]	eps_t	Step-size, eps_t \(= (T[1]-T[0])/(D-1) \).
[out]	result	array of length `kdv_fscatter_numel(D,discretization)`, will contain the combined scattering matrix. Result needs to be pre-allocated with `malloc(kdv_fscatter_numel(D,discretization)*sizeof(COMPLEX))`.
[out]	deg_ptr	Pointer to variable containing degree of the discretization. Determined based on discretization by fnft__kdv_discretization_degree.
[in]	W_ptr	Normalization flag. Polynomial coefficients are normalized if W_ptr is non-zero.
[in]	discretization	The type of discretization to be used. Should be of type fnft_kdv_discretization_t. Check fnft_kdv_discretization_t for list of supported types.

Returns: FNFT_SUCCESS or one of the FNFT_EC_... error codes defined in fnft_errwarn.h.

◆ fnft__kdv_fscatter_numel()

FNFT_UINT fnft__kdv_fscatter_numel	(	FNFT_UINT	D,
		fnft_kdv_discretization_t	discretization
	)

Returns the length of transfer_matrix to be allocated based on the number of samples and discretization.

This routine returns the length to be allocated based on the number of samples and discretization of type discretization.

Parameters

[in]	D	Number of samples.
[in]	discretization	Type of discretization from fnft_kdv_discretization_t.

Returns: Returns the length to be allocated. Returns 0 for unknown discretizations.

◆ fnft__kdv_fscatter_zero_freq_scatter_matrix()

FNFT_INT fnft__kdv_fscatter_zero_freq_scatter_matrix	(	FNFT_COMPLEX *	M,
		const FNFT_REAL	eps_t,
		const FNFT_REAL	q
	)

Returns the scattering matrix for a single step at frequency zero.

This routine returns the matrix

\[ \mathbf{M} = \text{exp}\left(\begin{bmatrix} 0 & q \\ -1 & 0 \end{bmatrix}\epsilon_t\right) = \begin{bmatrix} \cos(\epsilon_t\sqrt{q}) & q\epsilon_t\text{sinc}(\epsilon_t\sqrt{q}) \\ -\epsilon_t\text{sinc}(\epsilon_t\sqrt{q}) & \cos(\epsilon_t\sqrt{q}) \end{bmatrix}\,. \]

Parameters

[out]	M	Result Array of length 3, contains \(\{M_{11}=M_{22},M_{12},M_{21}\}\), needs to be pre-allocated as an Array of length 3.
[in]	eps_t	Step-size, eps_t \(= (T[1]-T[0])/(D-1) \).
[in]	q	(Locally) constant potential for this step.

◆ fnft__kdv_scatter_matrix()

FNFT_INT fnft__kdv_scatter_matrix	(	const FNFT_UINT	D,
		FNFT_COMPLEX const *const	q,
		const FNFT_REAL	eps_t,
		const FNFT_UINT	K,
		FNFT_COMPLEX const *const	lambda,
		FNFT_COMPLEX *const	result,
		fnft_kdv_discretization_t	discretization,
		const UINT	derivative_flag
	)

Computes the scattering matrix and its derivative.

The function computes the scattering matrix and the derivative of the scattering matrix with respect to \(\lambda\). The function performs slow direct scattering and is primarily based on the reference Boffetta and Osborne (J. Comput. Physics 1992 ).

Parameters

[in]	D	Number of samples
[in]	q	Array of length D, contains samples \( q(t_n)=q(x_0, t_n) \), where \( t_n = T[0] + n(T[1]-T[0])/(D-1) \) and \(n=0,1,\dots,D-1\), of the to-be-transformed signal in ascending order (i.e., \( q(t_0), q(t_1), \dots, q(t_{D-1}) \))
[in]	eps_t	Step-size, eps_t \(= (T[1]-T[0])/(D-1) \).
[in]	K	Number of values of \(\lambda\).
[in]	lambda	Array of length K, contains the values of \(\lambda\).
[out]	result	Array of length 8K or 4K, If derivative_flag=0 returns [S11 S12 S21 S22] in result where S = [S11, S12; S21, S22] is the scattering matrix computed using the chosen discretization. If derivative_flag=1 returns [S11 S12 S21 S22 S11' S12' S21' S22'] in result where S11' is the derivative of S11 w.r.t to lambda. Should be preallocated with size 4K or 8K accordingly.
[in]	discretization	The type of discretization to be used. Should be of type fnft_kdv_discretization_t. Not all kdv_discretization_t discretizations are supported. Check fnft_kdv_discretization_t for list of supported types.
[in]	derivative_flag	Should be set to either 0 or 1. If set to 1 the derivatives [S11' S12' S21' S22'] are calculated. result should be preallocated with size 8*K if flag is set to 1.

Returns: FNFT_SUCCESS or one of the FNFT_EC_... error codes defined in fnft_errwarn.h.

◆ fnft__kdvv_testcases_test_fnft()

FNFT_INT fnft__kdvv_testcases_test_fnft	(	fnft__kdvv_testcases_t	tc,
		FNFT_UINT	D,
		const FNFT_REAL	eb[6],
		fnft_kdvv_opts_t *const	opts
	)

Routine to run tests for fnft_kdvv.

This routine is used by the tests for fnft_kdvv. It runs the specified test case tc with the specified number of samples D and the options opts, and tests if several errors stay below the provided error bounds in eb.

Parameters

[in]	tc	Type of test case.
[in]	D	Number of samples.
[in]	eb	Real valued array with 6 elements corresponding to various error bounds.
[in]	opts	fnft_kdvv_opts_t options for the tests.

Returns: If all errors stay below bounds the routine FNFT_SUCCESS. Otherwise, it returns an error code (normally, FNFT_EC_TEST_FAILED).

Files

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ fnft__kdvv_testcases_t

Function Documentation

◆ fnft__kdv_discretization_boundary_coeff()

◆ fnft__kdv_discretization_degree()

◆ fnft__kdv_discretization_lambda_to_z()

◆ fnft__kdv_discretization_to_akns_discretization()

◆ fnft__kdv_discretization_upsampling_factor()

◆ fnft__kdv_discretization_z_to_lambda()

◆ fnft__kdv_fscatter()

◆ fnft__kdv_fscatter_numel()

◆ fnft__kdv_fscatter_zero_freq_scatter_matrix()

◆ fnft__kdv_scatter_matrix()

◆ fnft__kdvv_testcases_test_fnft()