absorbingboundary2d.h

Go to the documentation of this file.

/**
 * @file absorbingboundary2d.h
 * @brief Declares the absorbingboundary2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/absorbingboundary2d.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 "core/math/complexfield2d.h"
 
#include <cstddef>
#include <vector>
 
namespace qpe {
 
/**
 * @brief Parameters controlling QPE's smooth complex absorbing boundary.
 *
 * The absorber is a numerical open-boundary device applied after each physical
 * propagation step. It intentionally removes norm near the edge of the finite
 * FFT domain; that norm loss represents probability leaving the simulated
 * region rather than non-unitarity of the interior propagator.
 */
struct AbsorbingBoundary2DParams
{
    bool enabled = true;          ///< Enables/disables damping while retaining the same API path.
    float widthFraction = 0.15f;  ///< Fraction of each domain edge occupied by the absorbing layer.
    float strength = 8.0f;        ///< Dimensionless damping strength in the exponential mask.
    float exponent = 3.0f;        ///< Smoothness exponent controlling how damping rises toward the edge.
};
 
// Smooth absorbing boundary for FFT-based propagation.
//
// The split-step FFT solver itself remains periodic.  This class suppresses
// the artificial wrap-around by multiplying psi after every physical time
// step by a smooth non-unitary mask:
//
//   psi <- psi * exp[-eta * dt * f(x,y)]
//
// where f is zero in the interior and rises smoothly inside a peripheral
// layer.  This is equivalent to a simple complex absorbing potential (CAP).
// Norm loss is therefore intentional and represents probability leaving the
// simulated open region.
/**
 * @brief Precomputed smooth absorber for FFT domains that should behave as open.
 *
 * For an edge profile `f(x,y)`, the post-step mask has the form
 * \f[
 *   \psi \leftarrow \psi\,\exp[-\eta\,\Delta t\,f(x,y)].
 * \f]
 * The class keeps this numerical device separate from physical scalar
 * potentials so analysis can distinguish intended CAP norm loss.
 */
class AbsorbingBoundary2D
{
public:
    /**
     * @brief Performs absorbing boundary2 d.
     */
    AbsorbingBoundary2D() = default;
 
    /**
     * @brief Returns configure.
     * @param field Field data to read or modify.
     * @param dt Time increment in solver units.
     * @param params Parameter block to apply.
     */
    void configure(const ComplexField2D &field,
                   float dt,
                   const AbsorbingBoundary2DParams &params);
 
    /**
     * @brief Returns parameters.
     */
    const AbsorbingBoundary2DParams &parameters() const noexcept;
    /**
     * @brief Performs enabled.
     */
    bool enabled() const noexcept;
    /**
     * @brief Returns whether prepared for.
     * @param field Field data to read or modify.
     */
    bool isPreparedFor(const ComplexField2D &field) const noexcept;
 
    /**
     * @brief Performs apply.
     * @param field Field data to read or modify.
     */
    void apply(ComplexField2D &field) const;
 
    /**
     * @brief Performs minimum mask.
     */
    float minimumMask() const noexcept;
    /**
     * @brief Performs maximum mask.
     */
    float maximumMask() const noexcept;
 
private:
    /**
     * @brief Performs validate.
     * @param dt Time increment in solver units.
     * @param params Parameter block to apply.
     */
    static void validate(float dt, const AbsorbingBoundary2DParams &params);
 
    AbsorbingBoundary2DParams params_;
    std::size_t width_ = 0;
    std::size_t height_ = 0;
    float dx_ = 0.0f;
    float dy_ = 0.0f;
    float dt_ = 0.0f;
    float minimumMask_ = 1.0f;
    float maximumMask_ = 1.0f;
    std::vector<float> mask_;
};
 
} // namespace qpe