fft2d.h

Go to the documentation of this file.

/**
 * @file fft2d.h
 * @brief Declares the two-dimensional FFT utility used by spectral quantum propagators and diagnostics.
 * @ingroup qpe_math
 *
 * Source: @c core/math/fft2d.h. This file is part of Quantum Phenomena Explorer (QPE),
 * maintained by Officina Turini. See LICENSE_IT.txt / LICENSE.txt for the
 * QPE freeware source-available terms and THIRD_PARTY_NOTICES.txt for
 * third-party components.
 */
 
#pragma once
 
#include "complexfield2d.h"
 
#include <cstddef>
 
namespace qpe {
 
// Lightweight radix-2 FFT backend used by the first TDSE solver.
//
// Conventions:
//   forward: X[k] = sum_n x[n] exp(-i 2*pi*k*n/N)
//   inverse: x[n] = (1/N) sum_k X[k] exp(+i 2*pi*k*n/N)
//
// The 2D transform is separable: rows followed by columns. Therefore the
// inverse 2D transform is normalized by 1/(width*height) in total.
/**
 * @brief In-place separable radix-2 complex FFT for QPE Cartesian fields.
 *
 * The forward convention is
 * \f[
 *   X_k = \sum_n x_n e^{-i2\pi kn/N}.
 * \f]
 * while the inverse carries the `1/N` factor. A 2D transform applies the 1D
 * transform to rows and then columns, giving total inverse normalization
 * `1/(width*height)`. The current implementation requires power-of-two grid
 * dimensions, matching QPE's real-time 256x256/512x512 design target.
 */
class FFT2D
{
public:
    /** @brief Selects forward or inverse Fourier-transform convention. */
    enum class Direction
    {
        Forward,
        Inverse
    };
 
    // Current implementation is radix-2, so both dimensions must be powers
    // of two. This is intentional: 256x256 and 512x512 are the target grids
    // for the real-time explorer.
    /**
     * @brief Tests whether an integer is a non-zero power of two.
     * @param value Integer dimension to test.
     */
    static bool isPowerOfTwo(std::size_t value) noexcept;
    /**
     * @brief Returns whether both grid dimensions are supported by the radix-2 backend.
     * @param width Number of samples along X.
     * @param height Number of samples along Y.
     */
    static bool supportsSize(std::size_t width, std::size_t height) noexcept;
 
    /**
     * @brief Applies an in-place 2D Fourier transform.
     * @param field Complex grid transformed in place.
     * @param direction Forward or inverse transform convention.
     */
    static void transform(ComplexField2D &field, Direction direction);
    /** @brief Convenience wrapper for an in-place forward transform. @param field Complex grid transformed in place. */
    static void forward(ComplexField2D &field);
    /** @brief Convenience wrapper for an in-place normalized inverse transform. @param field Complex grid transformed in place. */
    static void inverse(ComplexField2D &field);
 
private:
    /**
     * @brief Carries out transform 1 d.
     * @param base The base value used by the operation.
     * @param count The count value used by the operation.
     * @param stride The stride value used by the operation.
     * @param direction The direction value used by the operation.
     */
    static void transform1D(ComplexField2D::Value *base,
                            std::size_t count,
                            std::size_t stride,
                            Direction direction);
};
 
} // namespace qpe