quantumberryphase2d.h

Go to the documentation of this file.

/**
 * @file quantumberryphase2d.h
 * @brief Declares the quantumberryphase2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/quantumberryphase2d.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 "core/quantum/potentialscene2d.h"
 
#include <complex>
#include <cstddef>
#include <vector>
 
namespace qpe {
 
// Step 39: cyclic quadrupole deformation of an otherwise isotropic 2D
// harmonic trap.  The pair (q1,q2) winds around the exact first-excited-state
// degeneracy at q1=q2=0:
//
//   V_q = q1 (x^2-y^2) + 2 q2 x y
//   q1 = A cos(theta), q2 = A sin(theta)
//
// The principal axes of the trap rotate by theta/2.  A complete 2*pi loop in
// parameter space therefore rotates the physical anisotropy by pi, bringing V
// back to itself.  The lowest p-like excited eigenstate changes sign in the
// adiabatic limit: Berry phase = pi modulo 2*pi.
/**
 * @brief Configuration values for Quantum Berry Loop2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct QuantumBerryLoop2DConfig
{
    bool enabled = false;
    double anisotropy = 0.35;
    double startTime = 0.0;
    double duration = 240.0;
    int winding = 1; // +1 counter-clockwise in (q1,q2), -1 clockwise.
};
 
/**
 * @brief Data structure used by the Quantum Berry Trap2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumBerryTrap2D
{
    bool valid = false;
    double centerX = 0.0;
    double centerY = 0.0;
    double offset = 0.0;
    double baseCurvature = 1.0;
};
 
/**
 * @brief Data record containing Quantum Berry Loop2D State.
 *
 * The structure carries computed data without coupling the numerical component to the GUI or renderer.
 */
struct QuantumBerryLoop2DState
{
    bool valid = false;
    bool active = false;
    bool finished = false;
    double progress = 0.0;             // 0..1
    double parameterAngle = 0.0;       // theta, radians
    double principalAxisAngle = 0.0;   // theta/2, radians
    double q1 = 0.0;
    double q2 = 0.0;
};
 
/**
 * @brief Data structure used by the Quantum Berry Sample2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumBerrySample2D
{
    double time = 0.0;
    double progress = 0.0;
    double parameterAngle = 0.0;
    double principalAxisAngle = 0.0;
    double q1 = 0.0;
    double q2 = 0.0;
    double returnFidelity = 0.0;
    double adjacentFidelity = 0.0;
    double geometricPhase = 0.0; // wrapped to [-pi,+pi]
    bool geometricPhaseValid = false;
};
 
class PotentialField2D;
 
/**
 * @brief Implements the Quantum Berry Phase2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumBerryPhase2D
{
public:
    /**
     * @brief Validates config.
     * @param config Configuration to apply.
     * @param trap The trap value used by the operation.
     * @param reason The reason value used by the operation.
     */
    static bool validateConfig(const QuantumBerryLoop2DConfig &config,
                               const QuantumBerryTrap2D &trap,
                               const char **reason = nullptr) noexcept;
 
    // For this guided experiment the base scene is intentionally minimal:
    // exactly one enabled, isotropic Harmonic object and no other enabled
    // terms.  This keeps the degeneracy and analytic initial state explicit.
    /**
     * @brief Returns identify trap.
     * @param scene The scene value used by the operation.
     * @param trap The trap value used by the operation.
     * @param reason The reason value used by the operation.
     */
    static bool identifyTrap(const PotentialScene2D &scene,
                             QuantumBerryTrap2D &trap,
                             const char **reason = nullptr) noexcept;
 
    /**
     * @brief Performs state.
     * @param config Configuration to apply.
     * @param time Simulation time in solver units.
     */
    static QuantumBerryLoop2DState state(const QuantumBerryLoop2DConfig &config,
                                         double time) noexcept;
 
    // Rebuild V(x,y,t) from the immutable base scene plus the quadrupole term.
    // The Potential Scene itself is never mutated.
    /**
     * @brief Performs rasterize.
     * @param baseScene The base scene value used by the operation.
     * @param trap The trap value used by the operation.
     * @param config Configuration to apply.
     * @param time Simulation time in solver units.
     * @param target The target value used by the operation.
     */
    static QuantumBerryLoop2DState rasterize(const PotentialScene2D &baseScene,
                                              const QuantumBerryTrap2D &trap,
                                              const QuantumBerryLoop2DConfig &config,
                                              double time,
                                              PotentialField2D &target);
 
    // Prepare the lower member of the first excited doublet at theta=0.  For
    // positive anisotropy the Y oscillator is softer, hence psi ~ y times the
    // anisotropic Gaussian ground envelope.
    /**
     * @brief Prepares first excited.
     * @param field Field data to read or modify.
     * @param trap The trap value used by the operation.
     * @param config Configuration to apply.
     * @param mass The mass value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static bool prepareFirstExcited(ComplexField2D &field,
                                    const QuantumBerryTrap2D &trap,
                                    const QuantumBerryLoop2DConfig &config,
                                    double mass,
                                    double hbar) noexcept;
 
    /**
     * @brief Returns normalized overlap.
     * @param a The a value used by the operation.
     * @param b The b value used by the operation.
     */
    static std::complex<double> normalizedOverlap(const ComplexField2D &a,
                                                  const ComplexField2D &b) noexcept;
 
    /**
     * @brief Performs wrap phase.
     * @param radians The radians value used by the operation.
     */
    static double wrapPhase(double radians) noexcept;
    /**
     * @brief Performs expected berry phase.
     * @param config Configuration to apply.
     */
    static double expectedBerryPhase(const QuantumBerryLoop2DConfig &config) noexcept;
    /**
     * @brief Performs doublet gap.
     * @param trap The trap value used by the operation.
     * @param config Configuration to apply.
     * @param mass The mass value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static double doubletGap(const QuantumBerryTrap2D &trap,
                             const QuantumBerryLoop2DConfig &config,
                             double mass,
                             double hbar = 1.0) noexcept;
    /**
     * @brief Performs adiabatic ratio.
     * @param trap The trap value used by the operation.
     * @param config Configuration to apply.
     * @param mass The mass value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static double adiabaticRatio(const QuantumBerryTrap2D &trap,
                                 const QuantumBerryLoop2DConfig &config,
                                 double mass,
                                 double hbar = 1.0) noexcept;
};
 
/**
 * @brief Implements the Quantum Berry History2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumBerryHistory2D
{
public:
    /**
     * @brief Constructs a Quantum Berry History 2D instance.
     * @param maximumSamples The maximum samples value used by the operation.
     */
    explicit QuantumBerryHistory2D(std::size_t maximumSamples = 1200u);
 
    /**
     * @brief Clears stored state and returns the component to its empty/default state.
     */
    void clear() noexcept;
    /**
     * @brief Returns configure.
     * @param reference The reference value used by the operation.
     * @param trap The trap value used by the operation.
     * @param config Configuration to apply.
     */
    bool configure(const ComplexField2D &reference,
                   const QuantumBerryTrap2D &trap,
                   const QuantumBerryLoop2DConfig &config);
    /**
     * @brief Carries out append.
     * @param time Simulation time in solver units.
     * @param loopState The loop state value used by the operation.
     * @param field Field data to read or modify.
     */
    bool append(double time,
                const QuantumBerryLoop2DState &loopState,
                const ComplexField2D &field);
 
    /**
     * @brief Returns configured.
     */
    bool configured() const noexcept { return configured_; }
    /**
     * @brief Returns whether the object contains no data.
     * @param empty The empty value used by the operation.
     */
    bool empty() const noexcept { return samples_.empty(); }
    /**
     * @brief Carries out trap.
     */
    const QuantumBerryTrap2D &trap() const noexcept { return trap_; }
    /**
     * @brief Returns config.
     */
    const QuantumBerryLoop2DConfig &config() const noexcept { return config_; }
    /**
     * @brief Samples s.
     */
    const std::vector<QuantumBerrySample2D> &samples() const noexcept { return samples_; }
 
private:
    /**
     * @brief Carries out trim to limit.
     */
    void trimToLimit();
 
    std::size_t maximumSamples_ = 1200u;
    bool configured_ = false;
    ComplexField2D reference_;
    ComplexField2D previous_;
    QuantumBerryTrap2D trap_;
    QuantumBerryLoop2DConfig config_;
    std::complex<double> transportPhase_ = std::complex<double>(1.0, 0.0);
    bool havePrevious_ = false;
    std::vector<QuantumBerrySample2D> samples_;
};
 
} // namespace qpe