potentialfield2d.h

Go to the documentation of this file.

/**
 * @file potentialfield2d.h
 * @brief Declares the potentialfield2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/potentialfield2d.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 <cstddef>
#include <cstdint>
#include <vector>
 
namespace qpe {
 
class ComplexField2D;
 
/**
 * @brief Data structure used by the Potential Point2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct PotentialPoint2D
{
    float x = 0.0f;
    float y = 0.0f;
};
 
// Scalar potential V(x,y) sampled on the same regular grid used by psi.
//
// Geometry methods operate in physical coordinates, not pixel/sample indices.
// This is intentional: the exact same geometry can later be drawn by the GUI
// and consumed by the solver without a second coordinate system.
/**
 * @brief Implements the Potential Field2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class PotentialField2D
{
public:
    using Value = float;
 
    /**
     * @brief Performs potential field2 d.
     */
    PotentialField2D() = default;
    /**
     * @brief Performs potential field2 d.
     * @param width The width value used by the operation.
     * @param height The height value used by the operation.
     * @param dx The dx value used by the operation.
     * @param dy The dy value used by the operation.
     */
    PotentialField2D(std::size_t width,
                     std::size_t height,
                     float dx = 1.0f,
                     float dy = 1.0f);
 
    /**
     * @brief Performs resize.
     * @param width The width value used by the operation.
     * @param height The height value used by the operation.
     * @param dx The dx value used by the operation.
     * @param dy The dy value used by the operation.
     */
    void resize(std::size_t width,
                std::size_t height,
                float dx = 1.0f,
                float dy = 1.0f);
 
    /**
     * @brief Performs clear.
     */
    void clear() noexcept;
    /**
     * @brief Performs fill.
     * @param value Value to assign or evaluate.
     */
    void fill(Value value) noexcept;
 
    /**
     * @brief Performs empty.
     */
    bool empty() const noexcept;
 
    /**
     * @brief Returns width.
     */
    std::size_t width() const noexcept;
    /**
     * @brief Returns height.
     */
    std::size_t height() const noexcept;
    /**
     * @brief Returns size.
     */
    std::size_t size() const noexcept;
 
    /**
     * @brief Performs dx.
     */
    float dx() const noexcept;
    /**
     * @brief Performs dy.
     */
    float dy() const noexcept;
 
    /**
     * @brief Returns the potential sample at a grid coordinate without bounds checking.
     * @param x Zero-based X sample index.
     * @param y Zero-based Y sample index.
     * @return Potential value at `(x,y)`.
     */
    Value operator()(std::size_t x, std::size_t y) const noexcept;
    /**
     * @brief Performs at.
     * @param x X coordinate/value.
     * @param y Y coordinate/value.
     */
    Value at(std::size_t x, std::size_t y) const;
 
    /**
     * @brief Performs set.
     * @param x X coordinate/value.
     * @param y Y coordinate/value.
     * @param value Value to assign or evaluate.
     */
    void set(std::size_t x, std::size_t y, Value value) noexcept;
    /**
     * @brief Sets at.
     * @param x X coordinate/value.
     * @param y Y coordinate/value.
     * @param value Value to assign or evaluate.
     */
    void setAt(std::size_t x, std::size_t y, Value value);
 
    // Add another sampled potential defined on the same grid.  This is used
    // by PotentialScene2D to compose independent potential terms without
    // changing the semantics of the existing geometry rasterizers.
    /**
     * @brief Performs accumulate.
     * @param other The other value used by the operation.
     * @param scale The scale value used by the operation.
     */
    void accumulate(const PotentialField2D &other, Value scale = 1.0f);
 
    /**
     * @brief Performs data.
     */
    const Value *data() const noexcept;
 
    /**
     * @brief Performs matches grid.
     * @param field Field data to read or modify.
     */
    bool matchesGrid(const ComplexField2D &field) const noexcept;
 
    /**
     * @brief Performs minimum.
     */
    Value minimum() const noexcept;
    /**
     * @brief Performs maximum.
     */
    Value maximum() const noexcept;
 
    /**
     * @brief Performs revision.
     */
    std::uint64_t revision() const noexcept;
 
    // Physical coordinate of a sample. As for GaussianPacket2D, the grid is
    // centred around (0,0); even-sized grids therefore straddle zero.
    /**
     * @brief Performs x coordinate.
     * @param x X coordinate/value.
     */
    double xCoordinate(std::size_t x) const noexcept;
    /**
     * @brief Performs y coordinate.
     * @param y Y coordinate/value.
     */
    double yCoordinate(std::size_t y) const noexcept;
 
    // Geometry primitives. Every call updates the field in one bulk operation
    // and increments revision() exactly once.
    /**
     * @brief Adds rectangle.
     * @param centerX The center x value used by the operation.
     * @param centerY The center y value used by the operation.
     * @param width The width value used by the operation.
     * @param height The height value used by the operation.
     * @param value Value to assign or evaluate.
     */
    void addRectangle(float centerX,
                      float centerY,
                      float width,
                      float height,
                      Value value);
 
    /**
     * @brief Adds circle.
     * @param centerX The center x value used by the operation.
     * @param centerY The center y value used by the operation.
     * @param radius The radius value used by the operation.
     * @param value Value to assign or evaluate.
     */
    void addCircle(float centerX,
                   float centerY,
                   float radius,
                   Value value);
 
    // Thick finite line segment, useful for arbitrary barriers/walls.
    /**
     * @brief Adds barrier.
     * @param x1 The x1 value used by the operation.
     * @param y1 The y1 value used by the operation.
     * @param x2 The x2 value used by the operation.
     * @param y2 The y2 value used by the operation.
     * @param thickness The thickness value used by the operation.
     * @param value Value to assign or evaluate.
     */
    void addBarrier(float x1,
                    float y1,
                    float x2,
                    float y2,
                    float thickness,
                    Value value);
 
    /**
     * @brief Adds polygon.
     * @param vertices The vertices value used by the operation.
     * @param value Value to assign or evaluate.
     */
    void addPolygon(const std::vector<PotentialPoint2D> &vertices,
                    Value value);
 
    // Vertical full-height wall with one aperture.
    /**
     * @brief Adds single slit.
     * @param centerX The center x value used by the operation.
     * @param barrierWidth The barrier width value used by the operation.
     * @param slitCenterY The slit center y value used by the operation.
     * @param slitHeight The slit height value used by the operation.
     * @param value Value to assign or evaluate.
     */
    void addSingleSlit(float centerX,
                       float barrierWidth,
                       float slitCenterY,
                       float slitHeight,
                       Value value);
 
    // Vertical full-height wall with two apertures. slitSeparation is the
    // centre-to-centre distance between the two openings.
    /**
     * @brief Adds double slit.
     * @param centerX The center x value used by the operation.
     * @param barrierWidth The barrier width value used by the operation.
     * @param slitCenterY The slit center y value used by the operation.
     * @param slitSeparation The slit separation value used by the operation.
     * @param slitHeight The slit height value used by the operation.
     * @param value Value to assign or evaluate.
     */
    void addDoubleSlit(float centerX,
                       float barrierWidth,
                       float slitCenterY,
                       float slitSeparation,
                       float slitHeight,
                       Value value);
 
    // Smooth analytic potentials. These are additive terms sampled directly
    // on the simulation grid. Positive/negative amplitudes naturally produce
    // barriers/wells where applicable.
    /**
     * @brief Adds gaussian.
     * @param centerX The center x value used by the operation.
     * @param centerY The center y value used by the operation.
     * @param sigmaX The sigma x value used by the operation.
     * @param sigmaY The sigma y value used by the operation.
     * @param amplitude The amplitude value used by the operation.
     */
    void addGaussian(float centerX,
                     float centerY,
                     float sigmaX,
                     float sigmaY,
                     Value amplitude);
 
    /**
     * @brief Adds harmonic.
     * @param centerX The center x value used by the operation.
     * @param centerY The center y value used by the operation.
     * @param offset The offset value used by the operation.
     * @param curvatureX The curvature x value used by the operation.
     * @param curvatureY The curvature y value used by the operation.
     */
    void addHarmonic(float centerX,
                     float centerY,
                     Value offset,
                     float curvatureX,
                     float curvatureY);
 
    // Traceless quadratic deformation used by the Berry-phase loop:
    // V += q1[(x-xc)^2-(y-yc)^2] + 2 q2 (x-xc)(y-yc).
    // Together with an isotropic harmonic trap, (q1,q2) rotates a fixed
    // anisotropy without changing its principal curvatures.
    /**
     * @brief Adds quadrupole.
     * @param centerX The center x value used by the operation.
     * @param centerY The center y value used by the operation.
     * @param q1 The q1 value used by the operation.
     * @param q2 The q2 value used by the operation.
     */
    void addQuadrupole(float centerX,
                       float centerY,
                       Value q1,
                       Value q2);
 
    // One-dimensional standing-wave optical lattice used by Kapitza-Dirac
    // diffraction. period is the spatial period of the intensity/potential:
    // V += depth * cos^2(pi*x/period + phase/2).
    /**
     * @brief Adds standing wave x.
     * @param period The period value used by the operation.
     * @param depth The depth value used by the operation.
     * @param phaseDegrees The phase degrees value used by the operation.
     */
    void addStandingWaveX(float period,
                          Value depth,
                          float phaseDegrees = 0.0f);
 
    /**
     * @brief Adds linear.
     * @param centerX The center x value used by the operation.
     * @param centerY The center y value used by the operation.
     * @param offset The offset value used by the operation.
     * @param slopeX The slope x value used by the operation.
     * @param slopeY The slope y value used by the operation.
     */
    void addLinear(float centerX,
                   float centerY,
                   Value offset,
                   float slopeX,
                   float slopeY);
 
    /**
     * @brief Adds softened radial.
     * @param centerX The center x value used by the operation.
     * @param centerY The center y value used by the operation.
     * @param coupling The coupling value used by the operation.
     * @param softening The softening value used by the operation.
     */
    void addSoftenedRadial(float centerX,
                           float centerY,
                           Value coupling,
                           float softening);
 
    // Finite Bunimovich-stadium billiard: V=0 inside the stadium and
    // V=value everywhere outside it. straightLength is the distance between
    // the centres of the two semicircular end caps; radius is the common
    // stadium radius. This primitive is intended for closed quantum billiards.
    /**
     * @brief Adds stadium exterior.
     * @param centerX The center x value used by the operation.
     * @param centerY The center y value used by the operation.
     * @param straightLength The straight length value used by the operation.
     * @param radius The radius value used by the operation.
     * @param value Value to assign or evaluate.
     */
    void addStadiumExterior(float centerX,
                            float centerY,
                            float straightLength,
                            float radius,
                            Value value);
 
private:
    /**
     * @brief Returns index.
     * @param x X coordinate/value.
     * @param y Y coordinate/value.
     */
    std::size_t index(std::size_t x, std::size_t y) const noexcept;
    /**
     * @brief Checks ed index.
     * @param x X coordinate/value.
     * @param y Y coordinate/value.
     */
    std::size_t checkedIndex(std::size_t x, std::size_t y) const;
    /**
     * @brief Performs touch.
     */
    void touch() noexcept;
 
    std::size_t width_ = 0;
    std::size_t height_ = 0;
    float dx_ = 1.0f;
    float dy_ = 1.0f;
    std::vector<Value> data_;
    std::uint64_t revision_ = 0;
};
 
} // namespace qpe