diracspinor2d.h

Go to the documentation of this file.

/**
 * @file diracspinor2d.h
 * @brief Declares the two-component Dirac spinor field container used by QPE.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/diracspinor2d.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>
 
namespace qpe {
 
// Two-component 2D Dirac spinor.  The components share exactly the same
// spatial grid.  For the relativistic branch of QPE this object, not the
// scalar display proxy, is the authoritative wavefunction.
/**
 * @brief Two-component complex spinor field used by the QPE Dirac branch.
 *
 * The container stores both spinor components on the same Cartesian grid and provides the normalization and field-level operations required by the Dirac experiments.
 */
class DiracSpinor2D
{
public:
    /**
     * @brief Constructs a Dirac Spinor 2D instance.
     */
    DiracSpinor2D() = default;
    /**
     * @brief Constructs a Dirac Spinor 2D instance.
     * @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.
     */
    DiracSpinor2D(std::size_t width, std::size_t height, float dx = 1.0f, float dy = 1.0f);
 
    /**
     * @brief Resizes storage and updates the associated grid geometry.
     * @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 Clears stored state and returns the component to its empty/default state.
     */
    void clear() noexcept;
    /**
     * @brief Assigns one value to all stored samples.
     * @param upperValue The upper value value used by the operation.
     * @param lowerValue The lower value value used by the operation.
     */
    void fill(const ComplexField2D::Value &upperValue,
              const ComplexField2D::Value &lowerValue);
 
    /**
     * @brief Returns whether the object contains no data.
     */
    bool empty() const noexcept;
    /**
     * @brief Carries out matches grid.
     * @param field Field data to read or modify.
     */
    bool matchesGrid(const ComplexField2D &field) const noexcept;
 
    /**
     * @brief Returns width.
     * @param width The width value used by the operation.
     */
    std::size_t width() const noexcept { return upper_.width(); }
    /**
     * @brief Returns height.
     * @param height The height value used by the operation.
     */
    std::size_t height() const noexcept { return upper_.height(); }
    /**
     * @brief Returns the X-axis grid spacing.
     * @param dx The dx value used by the operation.
     */
    float dx() const noexcept { return upper_.dx(); }
    /**
     * @brief Returns the Y-axis grid spacing.
     * @param dy The dy value used by the operation.
     */
    float dy() const noexcept { return upper_.dy(); }
 
    /**
     * @brief Carries out upper.
     */
    ComplexField2D &upper() noexcept { return upper_; }
    /**
     * @brief Carries out upper.
     */
    const ComplexField2D &upper() const noexcept { return upper_; }
    /**
     * @brief Carries out lower.
     */
    ComplexField2D &lower() noexcept { return lower_; }
    /**
     * @brief Carries out lower.
     */
    const ComplexField2D &lower() const noexcept { return lower_; }
 
    /**
     * @brief Returns norm2.
     */
    double norm2() const noexcept;
    /**
     * @brief Returns norm.
     */
    double norm() const noexcept;
    /**
     * @brief Returns normalize.
     */
    bool normalize() noexcept;
    /**
     * @brief Carries out upper population.
     */
    double upperPopulation() const noexcept;
    /**
     * @brief Carries out lower population.
     */
    double lowerPopulation() const noexcept;
 
    // Renderer compatibility: writes a scalar field whose |psi|^2 equals the
    // physical total spinor density |upper|^2+|lower|^2 point by point.
    // Its phase is intentionally zero and must not be interpreted physically.
    /**
     * @brief Writes density proxy.
     * @param out The out value used by the operation.
     */
    void writeDensityProxy(ComplexField2D &out) const;
 
private:
    ComplexField2D upper_;
    ComplexField2D lower_;
};
 
} // namespace qpe