NFSOFT - Nonequispaced fast SO(3) Fourier transform

This module implements nonuniform fast SO(3) Fourier transforms. More...

## Macros

#define | NFSOFT_NORMALIZED (1U << 0)
#define | NFSOFT_USE_NDFT (1U << 1)
#define | NFSOFT_USE_DPT (1U << 2)
#define | NFSOFT_MALLOC_X (1U << 3)
#define | NFSOFT_REPRESENT (1U << 4)
#define | NFSOFT_MALLOC_F_HAT (1U << 5)
#define | NFSOFT_MALLOC_F (1U << 6)
#define | NFSOFT_PRESERVE_F_HAT (1U << 7)
#define | NFSOFT_PRESERVE_X (1U << 8)
#define | NFSOFT_PRESERVE_F (1U << 9)
#define | NFSOFT_DESTROY_F_HAT (1U << 10)
#define | NFSOFT_DESTROY_X (1U << 11)
#define | NFSOFT_DESTROY_F (1U << 12)
#define | NFSOFT_NO_STABILIZATION (1U << 13)
#define | NFSOFT_CHOOSE_DPT (1U << 14)
#define | NFSOFT_SOFT (1U << 15)
#define | NFSOFT_ZERO_F_HAT (1U << 16)
#define | NFSOFT_INDEX(m, n, l, B) (((l)+((B)+1))+(2*(B)+2)*(((n)+((B)+1))+(2*(B)+2)*((m)+((B)+1))))
#define | NFSOFT_F_HAT_SIZE(B) (((B)+1)*(4*((B)+1)*((B)+1)-1)/3)

## Functions

void | nfsoft_precompute (nfsoft_plan *plan)
void | nfsoft_init (nfsoft_plan *plan, int N, int M)
void | nfsoft_init_advanced (nfsoft_plan *plan, int N, int M, unsigned int nfsoft_flags)
void | nfsoft_init_guru (nfsoft_plan *plan, int N, int M, unsigned int nfsoft_flags, unsigned int nfft_flags, int nfft_cutoff, int fpt_kappa)
void | nfsoft_init_guru_advanced (nfsoft_plan *plan, int N, int M, unsigned int nfsoft_flags, unsigned int nfft_flags, int nfft_cutoff, int fpt_kappa, int nn_oversampled)
void | nfsoft_trafo (nfsoft_plan *plan_nfsoft)
void | nfsoft_adjoint (nfsoft_plan *plan_nfsoft)
void | nfsoft_finalize (nfsoft_plan *plan)

## Detailed Description

This module implements nonuniform fast SO(3) Fourier transforms.

In the following, we abbreviate the term "nonuniform fast SO(3) Fourier transform" by NFSOFT.

## Macro Definition Documentation

#define NFSOFT_NORMALIZED (1U << 0)

By default, all computations are performed with respect to the unnormalized basis functions

If this flag is set, all computations are carried out using the - normalized basis functions

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 685 of file nfft3.h.

Referenced by nfsoft_adjoint(), and nfsoft_trafo().

#define NFSOFT_USE_NDFT (1U << 1)

If this flag is set, the fast NFSOFT algorithms (see nfsoft_trafo, nfsoft_adjoint) will use internally the exact but usually slower direct NDFT algorithm in favor of fast but approximative NFFT algorithm.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 686 of file nfft3.h.

Referenced by nfsoft_adjoint(), and nfsoft_trafo().

#define NFSOFT_USE_DPT (1U << 2)

If this flag is set, the fast NFSOFT algorithms (see nfsoft_trafo, nfsoft_adjoint) will use internally the usually slower direct DPT algorithm in favor of the fast FPT algorithm.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 687 of file nfft3.h.

Referenced by nfsoft_init_guru_advanced().

#define NFSOFT_MALLOC_X (1U << 3)

If this flag is set, the init methods (see nfsoft_init , nfsoft_init_advanced , and nfsoft_init_guru) will allocate memory and the method nfsoft_finalize will free the array `x` for you. Otherwise, you have to assure by yourself that `x` points to an array of proper size before excuting a transform and you are responsible for freeing the corresponding memory before program termination.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 688 of file nfft3.h.

Referenced by nfsoft_finalize(), nfsoft_init(), and nfsoft_init_guru_advanced().

#define NFSOFT_REPRESENT (1U << 4)

If this flag is set, the Wigner-D functions will be normed such that they satisfy the representation property of the spherical harmonics as defined in the NFFT software package, i.e. for every rotation matrix `A` with Euler angles and every unit vector `x` the Wigner-D functions will be normed such that

Author
  Antje Vollrath

Definition at line 689 of file nfft3.h.

Referenced by nfsoft_adjoint(), and nfsoft_trafo().

#define NFSOFT_MALLOC_F_HAT (1U << 5)

If this flag is set, the init methods (see nfsoft_init , nfsoft_init_advanced , and nfsoft_init_guru) will allocate memory and the method nfsoft_finalize will free the array `f_hat` for you. Otherwise, you have to assure by yourself that `f_hat` points to an array of proper size before excuting a transform and you are responsible for freeing the corresponding memory before program termination.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 690 of file nfft3.h.

Referenced by nfsoft_finalize(), nfsoft_init(), and nfsoft_init_guru_advanced().

#define NFSOFT_MALLOC_F (1U << 6)

If this flag is set, the init methods (see nfsoft_init , nfsoft_init_advanced , and nfsoft_init_guru) will allocate memory and the method nfsoft_finalize will free the array `f` for you. Otherwise, you have to assure by yourself that `f` points to an array of proper size before excuting a transform and you are responsible for freeing the corresponding memory before program termination.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 691 of file nfft3.h.

Referenced by nfsoft_finalize(), nfsoft_init(), and nfsoft_init_guru_advanced().

#define NFSOFT_PRESERVE_F_HAT (1U << 7)

If this flag is set, it is guaranteed that during an execution of nfsoft_trafo the content of `f_hat` remains unchanged.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 692 of file nfft3.h.

#define NFSOFT_PRESERVE_X (1U << 8)

If this flag is set, it is guaranteed that during an execution of nfsoft_trafo or nfsoft_adjoint the content of `x` remains unchanged.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 693 of file nfft3.h.

#define NFSOFT_PRESERVE_F (1U << 9)

If this flag is set, it is guaranteed that during an execution of ndsoft_adjoint or nfsoft_adjoint the content of `f` remains unchanged.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 694 of file nfft3.h.

#define NFSOFT_DESTROY_F_HAT (1U << 10)

If this flag is set, it is explicitely allowed that during an execution of nfsoft_trafo the content of `f_hat` may be changed.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 695 of file nfft3.h.

#define NFSOFT_DESTROY_X (1U << 11)

If this flag is set, it is explicitely allowed that during an execution of nfsoft_trafo or nfsoft_adjoint the content of `x` may be changed.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 696 of file nfft3.h.

#define NFSOFT_DESTROY_F (1U << 12)

If this flag is set, it is explicitely allowed that during an execution of ndsoft_adjoint or nfsoft_adjoint the content of `f` may be changed.

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 697 of file nfft3.h.

#define NFSOFT_NO_STABILIZATION (1U << 13)

If this flag is set, the fast NFSOFT algorithms (see nfsoft_trafo, nfsoft_adjoint) will use internally the FPT algorithm without the stabilization scheme and thus making bigger errors for higher bandwidth but becoming significantly faster

Author
  Antje Vollrath

Definition at line 700 of file nfft3.h.

Referenced by nfsoft_init_guru_advanced().

#define NFSOFT_CHOOSE_DPT (1U << 14)

If this flag is set, the fast NFSOFT algorithms (see nfsoft_trafo, nfsoft_adjoint) will decide whether to use the DPT or FPT algorithm depending on which is faster for the chosen orders.

not yet included in the checked-in version

Author
  Antje Vollrath

Definition at line 701 of file nfft3.h.

#define NFSOFT_SOFT (1U << 15)

If this flag is set, the fast NFSOFT algorithms (see nfsoft_trafo, nfsoft_adjoint) becomes a SOFT, i.e., we use equispaced nodes. The FFTW will be used instead of the NFFT.–>not included yet

See also
  nfsoft_init
  nfsoft_init_advanced
  nfsoft_init_guru

Author
  Antje Vollrath

Definition at line 702 of file nfft3.h.

#define NFSOFT_ZERO_F_HAT (1U << 16)

If this flag is set, the transform nfsoft_adjoint sets all unused entries in `f_hat` not corresponding to SO(3) Fourier coefficients to zero.

Author
  Antje Vollrath

Definition at line 703 of file nfft3.h.

#define NFSOFT_INDEX | ( |  | m,
|  |  | n,
|  |  | l,
|  |  | B
| ) |  | (((l)+((B)+1))+(2*(B)+2)*(((n)+((B)+1))+(2*(B)+2)*((m)+((B)+1))))

This macro expands to the index corresponding to the SO(3) Fourier coefficient for , with

Definition at line 706 of file nfft3.h.

Referenced by nfsoft_adjoint(), and nfsoft_init_guru_advanced().

#define NFSOFT_F_HAT_SIZE | ( |  | B | ) | (((B)+1)*(4*((B)+1)*((B)+1)-1)/3)

This macro expands to the logical size of a SO(3) Fourier coefficients array for a bandwidth B.

Definition at line 707 of file nfft3.h.

## Function Documentation

void nfsoft_precompute | ( | nfsoft_plan * | plan | ) |

Does all node-dependent and node-independent precomputations needed for the NFSOFT.

- plan a pointer to a nfsoft_plan structure

Definition at line 382 of file nfsoft.c.

References FG_PSI, nfft_plan::M_total, nfsoft_plan_::M_total, nfft_precompute_one_psi(), nfsoft_plan_::p_nfft, PRE_PSI, nfft_plan::x, and nfsoft_plan_::x.

void nfsoft_init | ( | nfsoft_plan * | plan,
|  | int | N,
|  | int | M
| ) |  |

Creates a NFSOFT transform plan.

- plan a pointer to a nfsoft_plan structure
- N the bandwidth
- M the number of nodes

Author
  Antje Vollrath

Definition at line 45 of file nfsoft.c.

References nfsoft_init_advanced(), NFSOFT_MALLOC_F, NFSOFT_MALLOC_F_HAT, and NFSOFT_MALLOC_X.

void nfsoft_init_advanced | ( | nfsoft_plan * | plan,
|  | int | N,
|  | int | M,
|  | unsigned int | nfsoft_flags
| ) |  |

Creates a NFSOFT transform plan.

- plan a pointer to a nfsoft_plan structure
- N the bandwidth
- M the number of nodes
- nfsoft_flags the NFSOFT flags

Author
  Antje Vollrath

Definition at line 51 of file nfsoft.c.

References FFTW_INIT, MALLOC_F, MALLOC_F_HAT, MALLOC_X, nfsoft_init_guru(), PRE_PHI_HUT, and PRE_PSI.

Referenced by nfsoft_init().

void nfsoft_init_guru | ( | nfsoft_plan * | plan,
|  | int | N,
|  | int | M,
|  | unsigned int | nfsoft_flags,
|  | unsigned int | nfft_flags,
|  | int | nfft_cutoff,
|  | int | fpt_kappa
| ) |  |

Creates a NFSOFT transform plan.

- plan a pointer to a nfsoft_plan structure
- N the bandwidth
- M the number of nodes
- nfsoft_flags the NFSFT flags
- nfft_flags the NFFT flags
- fpt_kappa a parameter contolling the accuracy of the FPT
- nfft_cutoff the NFFT cutoff parameter

Author
  Antje Vollrath

Definition at line 59 of file nfsoft.c.

References nfsoft_init_guru_advanced().

Referenced by nfsoft_init_advanced().

void nfsoft_init_guru_advanced | ( | nfsoft_plan * | plan,
|  | int | N,
|  | int | M,
|  | unsigned int | nfsoft_flags,
|  | unsigned int | nfft_flags,
|  | int | nfft_cutoff,
|  | int | fpt_kappa,
|  | int | fftw_size
| ) |  |

Creates a NFSOFT transform plan.

- plan a pointer to a nfsoft_plan structure
- N the bandwidth
- M the number of nodes
- nfsoft_flags the NFSFT flags
- nfft_flags the NFFT flags
- fpt_kappa a parameter contolling the accuracy of the FPT
- nfft_cutoff the NFFT cutoff parameter
- fftw_size the size of the 3D FFTW transform inside the NFFT ( fftw_size , where is the oversampling factor)

Definition at line 66 of file nfsoft.c.

References nfsft_wisdom::alpha, nfsoft_plan_::aux, nfsft_wisdom::beta, c2e(), nfsoft_plan_::cheby, nfsoft_plan_::f, nfft_plan::f_hat, nfsoft_plan_::f_hat, nfsoft_plan_::flags, FPT_FUNCTION_VALUES, fpt_init(), FPT_NO_DIRECT_ALGORITHM, FPT_NO_FAST_ALGORITHM, FPT_NO_STABILIZATION, fpt_precompute(), fpt_transposed(), nfsft_wisdom::gamma, nfsoft_plan_::internal_fpt_set, nfsoft_plan_::M_total, nfsoft_plan_::mv_adjoint, nfsoft_plan_::mv_trafo, nfsoft_plan_::N_total, nfft_malloc(), nfft_precompute_lin_psi(), nfsoft_adjoint(), NFSOFT_INDEX, NFSOFT_MALLOC_F, NFSOFT_MALLOC_F_HAT, NFSOFT_MALLOC_X, NFSOFT_NO_STABILIZATION, nfsoft_trafo(), NFSOFT_USE_DPT, nfsoft_plan_::nthreads, nfsoft_plan_::p_nfft, PRE_LIN_PSI, SO3_alpha_row(), SO3_beta_row(), SO3_gamma_row(), nfsoft_plan_::wig_coeffs, X, and nfsoft_plan_::x.

Referenced by nfsoft_init_guru().

void nfsoft_trafo | ( | nfsoft_plan * | plan_nfsoft | ) |

Executes a NFSOFT, i.e. computes for

- plan_nfsoft the plan

Author
  Antje Vollrath

Definition at line 416 of file nfsoft.c.

References c2e(), nfft_plan::f, nfsoft_plan_::f, nfft_plan::f_hat, nfsoft_plan_::f_hat, nfsoft_plan_::flags, nfsoft_plan_::internal_fpt_set, nfsoft_plan_::M_total, nfft_plan::N_total, nfsoft_plan_::N_total, nfft_trafo(), NFSOFT_NORMALIZED, NFSOFT_REPRESENT, NFSOFT_USE_NDFT, nfsoft_plan_::nthreads, nfsoft_plan_::p_nfft, and X.

Referenced by nfsoft_init_guru_advanced().

void nfsoft_adjoint | ( | nfsoft_plan * | plan_nfsoft | ) |

Executes an adjoint NFSOFT, i.e. computes for

- plan_nfsoft the plan

Author
  Antje Vollrath

Definition at line 545 of file nfsoft.c.

References nfft_plan::f, nfsoft_plan_::f, nfft_plan::f_hat, nfsoft_plan_::f_hat, nfsoft_plan_::flags, nfsoft_plan_::internal_fpt_set, nfsoft_plan_::M_total, nfsoft_plan_::N_total, nfft_adjoint(), NFSOFT_INDEX, NFSOFT_NORMALIZED, NFSOFT_REPRESENT, NFSOFT_USE_NDFT, nfsoft_plan_::p_nfft, and X.

Referenced by nfsoft_init_guru_advanced().

void nfsoft_finalize | ( | nfsoft_plan * | plan | ) |

Destroys a plan.

- plan the plan to be destroyed

Author
  Antje Vollrath

Definition at line 645 of file nfsoft.c.

References nfsoft_plan_::f, nfsoft_plan_::f_hat, nfsoft_plan_::flags, nfsoft_plan_::internal_fpt_set, nfft_finalize(), nfft_free(), NFSOFT_MALLOC_F, NFSOFT_MALLOC_F_HAT, NFSOFT_MALLOC_X, nfsoft_plan_::nthreads, nfsoft_plan_::p_nfft, and nfsoft_plan_::x.