u1gaugefield2d.h

Go to the documentation of this file.

/**
 * @file u1gaugefield2d.h
 * @brief Declares the U(1) lattice gauge field used by magnetic-flux, Landau, and Hall-edge experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/u1gaugefield2d.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 <complex>
#include <cstddef>
#include <vector>
 
namespace qpe {
 
class ComplexField2D;
 
// U(1) link field on the regular simulation lattice.
// linkX(x,y) parallel-transports psi from (x+1,y) back to (x,y), and
// linkY(x,y) does the same along +Y.  Storing gauge links instead of A itself
// makes the finite-difference kinetic operator exactly gauge covariant on the
// sampled lattice and is reusable for Aharonov-Bohm, uniform B/Landau and
// edge-state experiments.
/**
 * @brief Discrete U(1) gauge connection for gauge-covariant Schrodinger experiments.
 *
 * The field stores unit-modulus link variables rather than a sampled vector
 * potential. `linkX(x,y)` parallel-transports a neighboring sample from
 * `(x+1,y)` back to `(x,y)`; `linkY` does the analogous operation along Y.
 * For charge `q`, a continuum connection corresponds schematically to
 * \f[
 *   U_x = \exp[-i(q/\hbar)\int_x^{x+\Delta x} A_x\,dx].
 * \f]
 * This representation lets the finite-difference kinetic operator transform
 * covariantly under a sampled U(1) gauge transformation.
 */
class U1GaugeField2D
{
public:
    using Link = std::complex<float>;
 
    /** @brief Constructs an empty gauge-link field. */
    U1GaugeField2D() = default;
    /**
     * @brief Constructs an identity-link field on a Cartesian grid.
     * @param width Number of lattice sites along X.
     * @param height Number of lattice sites along Y.
     * @param dx Lattice spacing along X.
     * @param dy Lattice spacing along Y.
     */
    U1GaugeField2D(std::size_t width, std::size_t height,
                   float dx = 1.0f, float dy = 1.0f);
 
    /**
     * @brief Resizes the lattice and resets all links to the identity phase.
     * @param width Number of lattice sites along X.
     * @param height Number of lattice sites along Y.
     * @param dx Lattice spacing along X.
     * @param dy Lattice spacing along Y.
     */
    void resize(std::size_t width, std::size_t height,
                float dx = 1.0f, float dy = 1.0f);
    /** @brief Releases the link arrays and resets the geometry. */
    void clear() noexcept;
    /** @brief Sets every X/Y link to complex unity (zero gauge phase). */
    void fillIdentity() noexcept;
 
    /** @brief Returns whether the lattice contains no links. */
    bool empty() const noexcept;
    /** @brief Tests whether dimensions and spacing match a scalar field. @param field Scalar field whose grid is compared. */
    bool matchesGrid(const ComplexField2D &field) const noexcept;
 
    /** @brief Returns the number of lattice sites along X. */
    std::size_t width() const noexcept { return width_; }
    /** @brief Returns the number of lattice sites along Y. */
    std::size_t height() const noexcept { return height_; }
    /** @brief Returns the X lattice spacing. */
    float dx() const noexcept { return dx_; }
    /** @brief Returns the Y lattice spacing. */
    float dy() const noexcept { return dy_; }
 
    /** @brief Returns the +X parallel-transport link at a site. @param x X site index. @param y Y site index. */
    Link linkX(std::size_t x, std::size_t y) const noexcept;
    /** @brief Returns the +Y parallel-transport link at a site. @param x X site index. @param y Y site index. */
    Link linkY(std::size_t x, std::size_t y) const noexcept;
    /** @brief Assigns the +X link at a lattice site. @param x X site index. @param y Y site index. @param value Complex link phase. */
    void setLinkX(std::size_t x, std::size_t y, Link value) noexcept;
    /** @brief Assigns the +Y link at a lattice site. @param x X site index. @param y Y site index. @param value Complex link phase. */
    void setLinkY(std::size_t x, std::size_t y, Link value) noexcept;
 
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
    { return y * width_ + x; }
 
    std::size_t width_ = 0;
    std::size_t height_ = 0;
    float dx_ = 1.0f;
    float dy_ = 1.0f;
    std::vector<Link> xLinks_;
    std::vector<Link> yLinks_;
};
 
} // namespace qpe