PRIVATE: Internals related to the Korteweg-de Vries equation

Files
file	fnft__kdv_discretization.h
	Properties of the discretizations for the Korteweg-de Vries equation.
file	fnft__kdv_finvscatter.h
	Recovers the signal from a scattering matrix.
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_SQUARED , fnft__kdvv_testcases_SECH_SQUARED_LOW_BANDWIDTH , fnft__kdvv_testcases_NEGATIVE_RECT }

Functions
FNFT_UINT	fnft__kdv_discretization_degree (fnft_kdv_discretization_t kdv_discretization)
	This routine returns the max degree \(d\) of the polynomials in a single scattering matrix or zero if the discretization is unknown.
FNFT_REAL	fnft__kdv_discretization_boundary_coeff (fnft_kdv_discretization_t kdv_discretization)
	This routine returns the boundary coefficient based on the discretization.
FNFT_UINT	fnft__kdv_discretization_upsampling_factor (fnft_kdv_discretization_t kdv_discretization)
	This routine returns the scaling for effective number of samples based on the discretization.
FNFT_UINT	fnft__kdv_discretization_method_order (fnft_kdv_discretization_t kdv_discretization)
	This routine returns the order of the method based on the 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.
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 kdv_discretization)
	This routine maps \(\lambda\) from continuous-time domain to \(z\) in the discrete-time domain based on the discretization.
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 kdv_discretization)
	This routine maps \(z\) from the discrete-time domain to \(\lambda\) in the continuous-time domain based on the discretization.
FNFT_INT	fnft__kdv_discretization_phase_factor_rho (const FNFT_REAL eps_t, const FNFT_REAL T1, FNFT_REAL *const phase_factor_rho, fnft_kdv_discretization_t kdv_discretization)
	This routine returns the phase factor for reflection coefficient ( \(\rho\)). It is required for applying boundary conditions to the transfer_matrix based on the discretization.
FNFT_INT	fnft__kdv_discretization_phase_factor_a (const FNFT_REAL eps_t, const FNFT_UINT D, FNFT_REAL const *const T, FNFT_REAL *const phase_factor_a, fnft_kdv_discretization_t kdv_discretization)
	This routine returns the phase factor for a coefficient. It is required for applying boundary conditions to the transfer_matrix based on the discretization.
FNFT_INT	fnft__kdv_discretization_phase_factor_b (const FNFT_REAL eps_t, const FNFT_UINT D, FNFT_REAL const *const T, FNFT_REAL *const phase_factor_b, fnft_kdv_discretization_t kdv_discretization)
	This routine returns the phase factor for b coefficient. It is required for applying boundary conditions to the transfer_matrix based on the discretization.
FNFT_INT	fnft__kdv_discretization_preprocess_signal (const FNFT_UINT D, FNFT_COMPLEX const *const q, FNFT_REAL const eps_t, const FNFT_INT kappa, FNFT_UINT *const Dsub_ptr, FNFT_COMPLEX **q_preprocessed_ptr, FNFT_COMPLEX **r_preprocessed_ptr, FNFT_UINT *const first_last_index, fnft_kdv_discretization_t kdv_discretization)
	This routine preprocesses the signal by resampling and subsampling based on the discretization. The preprocessing is necessary for higher-order methods.
FNFT_INT	fnft__kdv_discretization_method_weights (FNFT_COMPLEX **qr_weights_ptr, FNFT_COMPLEX **eps_t_weights_ptr, fnft_kdv_discretization_t const kdv_discretization)
	This routine computes various weights required by some methods based on the discretization.
FNFT_INT	fnft__kdv_finvscatter (const FNFT_UINT deg, FNFT_COMPLEX *const transfer_matrix, FNFT_COMPLEX *const q, const FNFT_REAL eps_t, const fnft_kdv_discretization_t discretization)
	Recovers the samples that corresponding to a transfer matrix fast.
FNFT_INT	fnft__kdv_fscatter (const FNFT_UINT D, FNFT_COMPLEX const *const q, FNFT_COMPLEX const *const r, const FNFT_REAL eps_t, const FNFT_INT kappa, FNFT_COMPLEX *const result, FNFT_UINT *const deg_ptr, FNFT_INT *const W_ptr, fnft_kdv_discretization_t const discretization)
	Fast computation of polynomial approximation of the combined scattering matrix.
FNFT_INT	fnft__kdv_scatter_bound_states (const FNFT_UINT D, FNFT_COMPLEX const *const q, FNFT_COMPLEX const *const r, FNFT_REAL const *const T, FNFT_UINT const K, FNFT_COMPLEX *const bound_states, FNFT_COMPLEX *const a_vals, FNFT_COMPLEX *const aprime_vals, FNFT_COMPLEX *const b, FNFT_INT *const Ws, fnft_kdv_discretization_t const discretization, FNFT_UINT const skip_b_flag)
	Computes \(a(\lambda)\), \( a'(\lambda) = \frac{\partial a(\lambda)}{\partial \lambda}\) and \(b(\lambda)\) for complex values \(\lambda\) assuming that they are very close to the true bound-states.
FNFT_INT	fnft__kdv_scatter_matrix (const FNFT_UINT D, FNFT_COMPLEX const *const q, FNFT_COMPLEX const *const r, const FNFT_REAL eps_t, const FNFT_INT kappa, const FNFT_UINT K, FNFT_COMPLEX const *const lambda, FNFT_COMPLEX *const result, FNFT_INT *const W, fnft_kdv_discretization_t const discretization, const FNFT_UINT derivative_flag)
	Computes the scattering matrix and its derivative.
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.

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

kdv_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]

kdv_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

kdv_discretization

)

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

Parameters

[in]

kdv_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	kdv_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]	kdv_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_method_order()

FNFT_UINT fnft__kdv_discretization_method_order

(

fnft_kdv_discretization_t

kdv_discretization

)

This routine returns the order of the method based on the discretization.

Different numerical methods have different orders of accuray. This routine returns the order of the order based on the discretization of type fnft_kdv_discretization_t. When the step-size of the signal samples is reduced by a factor \(s\), the error in the computed values is expected to decrease by a factor \(s^{order}\).

Parameters

[in]

kdv_discretization

The type of discretization to be used. Should be of type fnft_kdv_discretization_t.

Returns

the method_order value, or 0.

fnft__kdv_discretization_method_weights()

FNFT_INT fnft__kdv_discretization_method_weights	(	FNFT_COMPLEX **	qr_weights_ptr,
		FNFT_COMPLEX **	eps_t_weights_ptr,
		fnft_kdv_discretization_t const	kdv_discretization
	)

This routine computes various weights required by some methods based on the discretization.

This routing computes the special weights required for the higher-order methods CF \(^{[4]}_2\), CF \(^{[4]}_3\), CF \(^{[5]}_3\) and CF \(^{[6]}_4\). The weights are used in fnft__kdv_discretization_preprocess_signal, fnft__akns_scatter_matrix and fnft__kdv_scatter_bound_states. The weights for CF \(^{[4]}_3\) are taken from Alvermann and Fehske (Journal of Computational Phys. 230, 2011) and the weights for the others are from Blanes, Casas and Thalhammer(Computer Phys. Comm. 220, 2017). The weights are mentioned as matrices in the references. This routine returns them in row-major order.

Parameters

[in,out]	qr_weights_ptr	Pointer to the starting location of potential weights.
[in,out]	eps_t_weights_ptr	Pointer to the starting location of potential weights.
[in]	kdv_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_phase_factor_a()

FNFT_INT fnft__kdv_discretization_phase_factor_a	(	const FNFT_REAL	eps_t,
		const FNFT_UINT	D,
		FNFT_REAL const *const	T,
		FNFT_REAL *const	phase_factor_a,
		fnft_kdv_discretization_t	kdv_discretization
	)

This routine returns the phase factor for a coefficient. It is required for applying boundary conditions to the transfer_matrix based on the discretization.

This routine computes the phase correction factor for the computation of the a coefficient from the transfer_matrix. phase_factor_a = -eps_t*D + (T[1]+eps_t*boundary_coeff) - (T[0]-eps_t*boundary_coeff), where eps_t is the step-size, D is the number of samples used to build the transfer_matrix, T is the 2-element time vector defining the signal support and boundary_coeff is based on the discretization of type fnft_kdv_discretization_t.

Parameters

[in]	eps_t	Real-valued discretization step-size.
[in]	D	Positive interger number of samples used to build transfer_matrix.
[in]	T	Real-valued 2-element time vector defining the signal support.
[in,out]	phase_factor_a	Pointer to real-valued variable where the computed phase factor will be stored.
[in]	kdv_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_phase_factor_b()

FNFT_INT fnft__kdv_discretization_phase_factor_b	(	const FNFT_REAL	eps_t,
		const FNFT_UINT	D,
		FNFT_REAL const *const	T,
		FNFT_REAL *const	phase_factor_b,
		fnft_kdv_discretization_t	kdv_discretization
	)

This routine returns the phase factor for b coefficient. It is required for applying boundary conditions to the transfer_matrix based on the discretization.

This routine computes the phase correction factor for the computation of the a coefficient from the transfer_matrix. phase_factor_b = -eps_t*D - (T[1]+eps_t*boundary_coeff) - (T[0]-eps_t*boundary_coeff), where eps_t is the step-size, D is the number of samples used to build the transfer_matrix, T is the 2-element time vector defining the signal support and boundary_coeff is based on the discretization of type fnft_kdv_discretization_t.

Parameters

[in]	eps_t	Real-valued discretization step-size.
[in]	D	Positive interger number of samples used to build transfer_matrix.
[in]	T	Real-valued 2-element time vector defining the signal support.
[in,out]	phase_factor_b	Pointer to real-valued variable where the computed phase factor will be stored.
[in]	kdv_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_phase_factor_rho()

FNFT_INT fnft__kdv_discretization_phase_factor_rho	(	const FNFT_REAL	eps_t,
		const FNFT_REAL	T1,
		FNFT_REAL *const	phase_factor_rho,
		fnft_kdv_discretization_t	kdv_discretization
	)

This routine returns the phase factor for reflection coefficient ( \(\rho\)). It is required for applying boundary conditions to the transfer_matrix based on the discretization.

This routine computes the phase correction factor for the computation of the reflection coefficient from the transfer_matrix. phase_factor_rho = -2.0*(T1 + eps_t*boundary_coeff), where eps_t is the step-size, T1 is the time at the right-boundary and boundary_coeff is based on the discretization of type fnft_kdv_discretization_t.

Parameters

[in]	eps_t	Real-valued discretization step-size.
[in]	T1	Real-valued time at the right-boundary.
[in,out]	phase_factor_rho	Pointer to real-valued variable where the computed phase factor will be stored.
[in]	kdv_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_preprocess_signal()

FNFT_INT fnft__kdv_discretization_preprocess_signal	(	const FNFT_UINT	D,
		FNFT_COMPLEX const *const	q,
		FNFT_REAL const	eps_t,
		const FNFT_INT	kappa,
		FNFT_UINT *const	Dsub_ptr,
		FNFT_COMPLEX **	q_preprocessed_ptr,
		FNFT_COMPLEX **	r_preprocessed_ptr,
		FNFT_UINT *const	first_last_index,
		fnft_kdv_discretization_t	kdv_discretization
	)

This routine preprocesses the signal by resampling and subsampling based on the discretization. The preprocessing is necessary for higher-order methods.

This routine preprocess q to generate q_preprocessed and r_preprocessed based on the discretization. The preprocessing may involve resampling and sub-sampling. The routine is based on the following papers:

• Chimmalgi, Prins and Wahls, " Fast Nonlinear Fourier Transform Algorithms Using Higher Order Exponential Integrators," IEEE Access 7, 2019.
• Medvedev, Vaseva, Chekhovskoy and Fedoruk, " Exponential fourth order schemes for direct Zakharov-Shabat problem," Optics Express, vol. 28, pp. 20–39, 2020.

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	Real-valued discretization step-size.
[in]	kappa	unused
[out]	q_preprocessed_ptr	Pointer to the starting location of preprocessed signal q_preprocessed.
[out]	r_preprocessed_ptr	Pointer to the starting location of preprocessed signal r_preprocessed.
[in,out]	Dsub_ptr	Pointer to number of processed 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 used to build q_preprocessed.
[in]	kdv_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

kdv_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]

kdv_discretization

The type of discretization to be used. Should be of type fnft_kdv_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	kdv_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]	kdv_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_finvscatter()

FNFT_INT fnft__kdv_finvscatter	(	const FNFT_UINT	deg,
		FNFT_COMPLEX *const	transfer_matrix,
		FNFT_COMPLEX *const	q,
		const FNFT_REAL	eps_t,
		const fnft_kdv_discretization_t	discretization
	)

Recovers the samples that corresponding to a transfer matrix fast.

Parameters

	deg	Degree of the polynomials in the transfer matrix.
[in]	transfer_matrix	A transfer matrix in the same format as used by fnft__kdv_fscatter.
[out]	q	Array with D=deg/base_deg entries in which the samples are stored, where base_deg is the output of fnft__kdv_discretization_degree.
[in]	eps_t	See fnft__kdv_fscatter.
[in]	discretization	See fnft__kdv_fscatter. Currently, only the 2SPLIT2_MODAL and 2SPLIT2A discretizations are supported.

fnft__kdv_fscatter()

FNFT_INT fnft__kdv_fscatter	(	const FNFT_UINT	D,
		FNFT_COMPLEX const *const	q,
		FNFT_COMPLEX const *const	r,
		const FNFT_REAL	eps_t,
		const FNFT_INT	kappa,
		FNFT_COMPLEX *const	result,
		FNFT_UINT *const	deg_ptr,
		FNFT_INT *const	W_ptr,
		fnft_kdv_discretization_t const	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]	r	Array of length D, contains samples \( r(t_n)=r(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 auxiliary potential in the AKNS framework in ascending order (i.e., \( r(t_0), r(t_1), \dots, r(t_{D-1}) \))
[in]	eps_t	Step-size, eps_t \(= (T[1]-T[0])/(D-1) \).
[in]	kappa	unused.
[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.
[out]	W_ptr	Pointer to normalization flag fnft_kdvv_opts_t::normalization_flag.
[in]	discretization	The type of discretization to be used. Should be of type fnft_kdv_discretization_t. Not all fnft_kdv_discretization_t discretizations are supported. 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_scatter_bound_states()

FNFT_INT fnft__kdv_scatter_bound_states	(	const FNFT_UINT	D,
		FNFT_COMPLEX const *const	q,
		FNFT_COMPLEX const *const	r,
		FNFT_REAL const *const	T,
		FNFT_UINT const	K,
		FNFT_COMPLEX *const	bound_states,
		FNFT_COMPLEX *const	a_vals,
		FNFT_COMPLEX *const	aprime_vals,
		FNFT_COMPLEX *const	b,
		FNFT_INT *const	Ws,
		fnft_kdv_discretization_t const	discretization,
		FNFT_UINT const	skip_b_flag
	)

Computes \(a(\lambda)\), \( a'(\lambda) = \frac{\partial a(\lambda)}{\partial \lambda}\) and \(b(\lambda)\) for complex values \(\lambda\) assuming that they are very close to the true bound-states.

The function performs slow direct scattering and is primarily based on the references

• Boffetta and Osborne, " Computation of the direct scattering transform for the nonlinear Schroedinger equation," J. Comput. Phys. 102(2), 1992.
• Chimmalgi, Prins and Wahls, " Fast Nonlinear Fourier Transform Algorithms Using Higher Order Exponential Integrators," IEEE Access 7, 2019.
• Medvedev, Vaseva, Chekhovskoy and Fedoruk, " Exponential fourth order schemes for direct Zakharov-Shabat problem," Optics Express, vol. 28, pp. 20–39, 2020.
• Prins and Wahls, " Soliton Phase Shift Calculation for the Korteweg–De Vries Equation," IEEE Access, vol. 7, pp. 122914–122930, July 2019.

Parameters

[in]	D	Number of samples
[in]	q	Array of length D, contains samples \( q_n\) for \(n=0,1,\dots,D-1\) in ascending order (i.e., \( q_0, q_1, \dots, q_{D-1} \)). The values should be specifically precalculated based on the chosen discretization.
[in,out]	r	Array of length D, contains samples \( r_n\) for \(n=0,1,\dots,D-1\) in ascending order (i.e., \( r_0, r_1, \dots, r_{D-1} \)). The values should be specifically precalculated based on the chosen discretization. Alternatively NULL can be passed. When NULL is passed the routine allocates memory, assigns it to the pointer and calculates \( r_n\) from \( q_n\).
[in]	T	Array of length 2, contains the position in time of the first and of the last sample. It should be T[0]<T[1].
[in]	K	Number of bound-states.
[in]	bound_states	Array of length K, contains the bound-states \(\lambda\).
[out]	a_vals	Array of length K, contains the values of \(a(\lambda)\).
[out]	aprime_vals	Array of length K, contains the values of \( a'(\lambda) = \frac{\partial a(\lambda)}{\partial \lambda}\).
[out]	b	Array of length K, contains the values of \(b(\lambda)\). The \(b(\lambda)\) are calculated using the criterion from Prins and Wahls, " Soliton Phase Shift Calculation for the Korteweg–De Vries Equation,".
[in,out]	Ws	Pass an array of size K. Upon exit, it contains scaling factors that arise due to an internal normalization of the scattering process (to deal with potential overflow issues). The returned values for a and a_prime still have to be multiplied with corresponding power of two (i.e. POW(2, Ws[i])) to obtain the final values. Note that this is not required for the values of b. No normalization is carried out if NULL is passed.
[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]	skip_b_flag	If set to 1 the routine will not compute \(b(\lambda)\).

Returns

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

fnft__kdv_scatter_matrix()

FNFT_INT fnft__kdv_scatter_matrix	(	const FNFT_UINT	D,
		FNFT_COMPLEX const *const	q,
		FNFT_COMPLEX const *const	r,
		const FNFT_REAL	eps_t,
		const FNFT_INT	kappa,
		const FNFT_UINT	K,
		FNFT_COMPLEX const *const	lambda,
		FNFT_COMPLEX *const	result,
		FNFT_INT *const	W,
		fnft_kdv_discretization_t const	discretization,
		const FNFT_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_n\) for \(n=0,1,\dots,D-1\) in ascending order (i.e., \( q_0, q_1, \dots, q_{D-1} \)). The values should be specifically precalculated based on the chosen discretization.
[in,out]	r	Array of length D, contains samples \( r_n\) for \(n=0,1,\dots,D-1\) in ascending order (i.e., \( r_0, r_1, \dots, r_{D-1} \)). The values should be specifically precalculated based on the chosen discretization. Alternatively NULL can be passed. When NULL is passed the routine allocates memory, assigns it to the pointer and calculates \( r_n\) from \( q_n\).
[in]	eps_t	Step-size, eps_t \(= (T[1]-T[0])/(D-1) \).
[in]	kappa	Unused.
[in]	K	Number of values of \(\lambda\).
[in]	lambda	Array of length K, contains the values of \(\lambda\).
[out]	result	Array of length 8*K or 4*K, 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 4*K or 8*K accordingly.
[in,out]	W	Pass an array of size K. Upon exit, it contains scaling factors that arise due to an internal normalization of the scattering matrix (to deal with potential overflow issues). The result has to be scaled by the power of 2 to obtain the final values. No normalization is carried out if NULL is passed.
[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).