Properties of the discretizations for the Korteweg-de Vries equation. More...

#include "fnft__akns_discretization_t.h"
#include "fnft__errwarn.h"
#include "fnft__misc.h"

Include dependency graph for fnft__akns_discretization.h:

This graph shows which files directly or indirectly include this file:

Functions
FNFT_UINT	fnft__akns_discretization_degree (fnft__akns_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.

FNFT_REAL	fnft__akns_discretization_boundary_coeff (fnft__akns_discretization_t discretization)
	This routine returns the boundary coefficient based on the discretization.

FNFT_UINT	fnft__akns_discretization_upsampling_factor (fnft__akns_discretization_t discretization)
	This routine returns the scaling for effective number of samples based on the discretization.

FNFT_UINT	fnft__akns_discretization_method_order (fnft__akns_discretization_t discretization)
	This routine returns the order of the method based on the discretization.

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

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

FNFT_INT	fnft__akns_discretization_method_weights (FNFT_COMPLEX qr_weights_ptr, FNFT_COMPLEX eps_t_weights_ptr, fnft__akns_discretization_t const akns_discretization)
	This routine computes various weights required by some methods based on the discretization.

FNFT_INT	fnft__akns_discretization_preprocess_signal (FNFT_UINT const D, FNFT_COMPLEX const const q, FNFT_COMPLEX(r_from_q[3])(FNFT_COMPLEX const), FNFT_REAL const eps_t, FNFT_UINT const Dsub_ptr, FNFT_COMPLEX q_preprocessed_ptr, FNFT_COMPLEX r_preprocessed_ptr, FNFT_UINT const first_last_index, fnft__akns_discretization_t 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__akns_discretization_change_of_basis_matrix_to_S (FNFT_COMPLEX *const T, FNFT_COMPLEX const xi, FNFT_UINT const derivative_flag, FNFT_REAL const eps_t, fnft__akns_discretization_t const akns_discretization, FNFT_UINT vanilla_flag, fnft__akns_pde_t const PDE)
	This routine returns the change of basis matrix from the basis of the discretization to S.

FNFT_INT	fnft__akns_discretization_change_of_basis_matrix_from_S (FNFT_COMPLEX *const T, FNFT_COMPLEX const xi, FNFT_UINT const derivative_flag, FNFT_REAL const eps_t, fnft__akns_discretization_t const akns_discretization, FNFT_UINT vanilla_flag, fnft__akns_pde_t const PDE)
	This routine returns the change of basis matrix from the S basis to the basis of the discretization.

Detailed Description

Properties of the discretizations for the Korteweg-de Vries equation.

Function Documentation

◆ fnft__akns_discretization_boundary_coeff()

FNFT_REAL fnft__akns_discretization_boundary_coeff ( fnft__akns_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__akns_discretization_t.

Parameters

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

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

◆ fnft__akns_discretization_change_of_basis_matrix_from_S()

FNFT_INT fnft__akns_discretization_change_of_basis_matrix_from_S	(	FNFT_COMPLEX *const	T,
		FNFT_COMPLEX const	xi,
		FNFT_UINT const	derivative_flag,
		FNFT_REAL const	eps_t,
		fnft__akns_discretization_t const	akns_discretization,
		FNFT_UINT	vanilla_flag,
		fnft__akns_pde_t const	PDE
	)

This routine returns the change of basis matrix from the S basis to the basis of the discretization.

Parameters

[out]	T	2x2 or 4x4 matrix. Left multiplication of a vector in the S basis of the discretization by T changes it to the equivalent vector in the basis of the discretization.
[in]	xi	spectral parameter \( \xi \).
[in]	derivative_flag	When 0, T is 2x2. When 1 T is 4x4, to include the derivatives.
[in]	eps_t	Real-valued discretization step-size.
[in]	akns_discretization	Discretization of type fnft__akns_discretization_t.
[in]	vanilla_flag	For calculations for the KdV equation, pass 1 for the original mapping to the AKNS framework with r=-1. Pass 0 for the alternative mapping with q=-1. Unused for NSE.
[in]	PDE	PDE of type fnft__akns_pde_t.

◆ fnft__akns_discretization_change_of_basis_matrix_to_S()

FNFT_INT fnft__akns_discretization_change_of_basis_matrix_to_S	(	FNFT_COMPLEX *const	T,
		FNFT_COMPLEX const	xi,
		FNFT_UINT const	derivative_flag,
		FNFT_REAL const	eps_t,
		fnft__akns_discretization_t const	akns_discretization,
		FNFT_UINT	vanilla_flag,
		fnft__akns_pde_t const	PDE
	)

This routine returns the change of basis matrix from the basis of the discretization to S.

Parameters

[out]	T	2x2 or 4x4 matrix. Left multiplication of a vector in the basis of the discretization by T changes it to the equivalent vector in S basis.
[in]	xi	spectral parameter \( \xi \).
[in]	derivative_flag	When 0, T is 2x2. When 1 T is 4x4, to include the derivatives.
[in]	eps_t	Real-valued discretization step-size.
[in]	akns_discretization	Discretization of type fnft__akns_discretization_t.
[in]	vanilla_flag	For calculations for the KdV equation, pass 1 for the original mapping to the AKNS framework with r=-1. Pass 0 for the alternative mapping with q=-1. Unused for NSE.
[in]	PDE	PDE of type fnft__akns_pde_t.

◆ fnft__akns_discretization_degree()

FNFT_UINT fnft__akns_discretization_degree ( fnft__akns_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__akns_fscatter.

◆ fnft__akns_discretization_lambda_to_z()

FNFT_INT fnft__akns_discretization_lambda_to_z	(	const FNFT_UINT	n,
		const FNFT_REAL	eps_t,
		FNFT_COMPLEX *const	vals,
		fnft__akns_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__akns_discretization_t.

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__akns_discretization_t.

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

◆ fnft__akns_discretization_method_order()

FNFT_UINT fnft__akns_discretization_method_order ( fnft__akns_discretization_t 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__akns_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] discretization The type of discretization to be used. Should be of type fnft__akns_discretization_t.

Returns: the method_order value, or 0 for unknown discretization.

◆ fnft__akns_discretization_method_weights()

FNFT_INT fnft__akns_discretization_method_weights	(	FNFT_COMPLEX **	qr_weights_ptr,
		FNFT_COMPLEX **	eps_t_weights_ptr,
		fnft__akns_discretization_t const	akns_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__nse_discretization_preprocess_signal, fnft__akns_scatter_matrix and fnft__nse_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 step size weights.
[in]	akns_discretization	Discretization of type fnft__akns_discretization_t.

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

◆ fnft__akns_discretization_preprocess_signal()

FNFT_INT fnft__akns_discretization_preprocess_signal	(	FNFT_UINT const	D,
		FNFT_COMPLEX const *const	q,
		FNFT_COMPLEX(*[3])(FNFT_COMPLEX const)	r_from_q,
		FNFT_REAL const	eps_t,
		FNFT_UINT *const	Dsub_ptr,
		FNFT_COMPLEX **	q_preprocessed_ptr,
		FNFT_COMPLEX **	r_preprocessed_ptr,
		FNFT_UINT *const	first_last_index,
		fnft__akns_discretization_t	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]	r_from_q	A function pointer array of length 3. `r_from_q[0](q)` has to return the value of an r-sample given the corresponding q-sample, before preprocessing. `r_from_q[1](q)` and `r_from_q[2](q)` have to return respectively the sample of the first/second derivative of r given the corresponding sample of the first/second derivative of q.
[in]	eps_t	Real-valued discretization step-size.
[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]	discretization	Discretization of type fnft__akns_discretization_t.

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

◆ fnft__akns_discretization_upsampling_factor()

FNFT_UINT fnft__akns_discretization_upsampling_factor ( fnft__akns_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__akns_discretization_t. D_effective = upsampling_factor * D.

Parameters

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

Returns: the upsampling_factor value, or 0 for unknown discretizations.

◆ fnft__akns_discretization_z_to_lambda()

FNFT_INT fnft__akns_discretization_z_to_lambda	(	const FNFT_UINT	n,
		const FNFT_REAL	eps_t,
		FNFT_COMPLEX *const	vals,
		fnft__akns_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__akns_discretization_t.

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__akns_discretization_t.

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

Functions

Detailed Description

Function Documentation

◆ fnft__akns_discretization_boundary_coeff()

◆ fnft__akns_discretization_change_of_basis_matrix_from_S()

◆ fnft__akns_discretization_change_of_basis_matrix_to_S()

◆ fnft__akns_discretization_degree()

◆ fnft__akns_discretization_lambda_to_z()

◆ fnft__akns_discretization_method_order()

◆ fnft__akns_discretization_method_weights()

◆ fnft__akns_discretization_preprocess_signal()

◆ fnft__akns_discretization_upsampling_factor()

◆ fnft__akns_discretization_z_to_lambda()