quantumscar2d.h

Go to the documentation of this file.

/**
 * @file quantumscar2d.h
 * @brief Declares the quantumscar2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/quantumscar2d.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 <cstddef>
#include <complex>
#include <string>
#include <vector>
 
namespace qpe {
 
/**
 * @brief Data structure used by the Quantum Scar Geometry2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumScarGeometry2D
{
    bool valid = false;
    double centerX = 0.0;
    double centerY = 0.0;
    double straightLength = 0.0;
    double radius = 0.0;
    double wallPotential = 0.0;
};
 
/**
 * @brief Data structure used by the Quantum Scar Config2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumScarConfig2D
{
    bool enabled = false;
    // Half-width of the band used to quantify concentration around the
    // horizontal axial periodic orbit of the stadium.
    double orbitBandHalfWidth = 0.75;
 
    // Central energy used by the finite-time spectral projection
    // Phi_E ~ integral psi(t) exp(+i E t / hbar) dt. A non-positive value asks
    // the caller to supply an energy inferred from the prepared packet.
    double referenceEnergy = 0.0;
};
 
/**
 * @brief Data structure used by the Quantum Scar Sample2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumScarSample2D
{
    double time = 0.0;
    double fidelity = 0.0;
    double instantaneousOrbitEnhancement = 0.0;
    double filteredOrbitEnhancement = 0.0;
};
 
/**
 * @brief Implements the Quantum Scars2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumScars2D
{
public:
    /**
     * @brief Validates config.
     * @param config Configuration to apply.
     * @param reason The reason value used by the operation.
     */
    static bool validateConfig(const QuantumScarConfig2D &config,
                               std::string *reason = nullptr) noexcept;
 
    /**
     * @brief Returns identify.
     * @param scene The scene value used by the operation.
     * @param geometry The geometry value used by the operation.
     * @param reason The reason value used by the operation.
     */
    static bool identify(const PotentialScene2D &scene,
                         QuantumScarGeometry2D &geometry,
                         std::string *reason = nullptr) noexcept;
 
    /**
     * @brief Performs inside.
     * @param geometry The geometry value used by the operation.
     * @param x X coordinate/value.
     * @param y Y coordinate/value.
     */
    static bool inside(const QuantumScarGeometry2D &geometry,
                       double x,
                       double y) noexcept;
 
    /**
     * @brief Performs accessible area.
     * @param geometry The geometry value used by the operation.
     */
    static double accessibleArea(const QuantumScarGeometry2D &geometry) noexcept;
    /**
     * @brief Performs orbit band area.
     * @param geometry The geometry value used by the operation.
     * @param halfWidth The half width value used by the operation.
     */
    static double orbitBandArea(const QuantumScarGeometry2D &geometry,
                                double halfWidth) noexcept;
    /**
     * @brief Performs axial orbit round trip length.
     * @param geometry The geometry value used by the operation.
     */
    static double axialOrbitRoundTripLength(const QuantumScarGeometry2D &geometry) noexcept;
    /**
     * @brief Performs axial orbit period.
     * @param geometry The geometry value used by the operation.
     * @param speed The speed value used by the operation.
     */
    static double axialOrbitPeriod(const QuantumScarGeometry2D &geometry,
                                   double speed) noexcept;
 
    /**
     * @brief Performs fidelity.
     * @param reference The reference value used by the operation.
     * @param field Field data to read or modify.
     */
    static double fidelity(const ComplexField2D &reference,
                           const ComplexField2D &field) noexcept;
 
    /**
     * @brief Performs orbit enhancement.
     * @param field Field data to read or modify.
     * @param geometry The geometry value used by the operation.
     * @param halfWidth The half width value used by the operation.
     */
    static double orbitEnhancement(const ComplexField2D &field,
                                   const QuantumScarGeometry2D &geometry,
                                   double halfWidth) noexcept;
};
 
// Analysis-only accumulator. The authoritative evolution remains the full 2D
// psi owned by MainWindow/SplitStepFourierSolver2D. This class only records
// diagnostics and a finite-time spectral projection of the already-computed
// psi sequence; it never feeds anything back into the Hamiltonian.
/**
 * @brief Implements the Quantum Scar History2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumScarHistory2D
{
public:
    /**
     * @brief Constructs a Quantum Scar History 2D instance.
     * @param maximumSamples The maximum samples value used by the operation.
     */
    explicit QuantumScarHistory2D(std::size_t maximumSamples = 1600u);
 
    /**
     * @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 geometry The geometry value used by the operation.
     * @param config Configuration to apply.
     * @param referenceEnergy The reference energy value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    bool configure(const ComplexField2D &reference,
                   const QuantumScarGeometry2D &geometry,
                   const QuantumScarConfig2D &config,
                   double referenceEnergy,
                   double hbar = 1.0);
 
    /**
     * @brief Returns configured.
     */
    bool configured() const noexcept { return configured_; }
    /**
     * @brief Sets maximum samples.
     * @param maximumSamples The maximum samples value used by the operation.
     */
    void setMaximumSamples(std::size_t maximumSamples);
    /**
     * @brief Carries out maximum samples.
     */
    std::size_t maximumSamples() const noexcept { return maximumSamples_; }
 
    /**
     * @brief Carries out append.
     * @param time Simulation time in solver units.
     * @param field Field data to read or modify.
     */
    bool append(double time, const ComplexField2D &field);
 
    /**
     * @brief Samples s.
     */
    const std::vector<QuantumScarSample2D> &samples() const noexcept { return samples_; }
    /**
     * @brief Carries out mean probability density.
     */
    const std::vector<float> &meanProbabilityDensity() const noexcept { return meanDensity_; }
    /**
     * @brief Carries out filtered probability density.
     */
    const std::vector<float> &filteredProbabilityDensity() const noexcept { return filteredDensity_; }
 
    /**
     * @brief Carries out geometry.
     */
    const QuantumScarGeometry2D &geometry() const noexcept { return geometry_; }
    /**
     * @brief Returns config.
     */
    const QuantumScarConfig2D &config() const noexcept { return config_; }
    /**
     * @brief Carries out reference energy.
     */
    double referenceEnergy() const noexcept { return referenceEnergy_; }
    /**
     * @brief Carries out hbar.
     */
    double hbar() const noexcept { return hbar_; }
 
    /**
     * @brief Carries out grid width.
     * @param width The width value used by the operation.
     */
    std::size_t gridWidth() const noexcept { return reference_.width(); }
    /**
     * @brief Carries out grid height.
     * @param height The height value used by the operation.
     */
    std::size_t gridHeight() const noexcept { return reference_.height(); }
    /**
     * @brief Returns the X-axis grid spacing.
     * @param dx The dx value used by the operation.
     */
    float dx() const noexcept { return reference_.dx(); }
    /**
     * @brief Returns the Y-axis grid spacing.
     * @param dy The dy value used by the operation.
     */
    float dy() const noexcept { return reference_.dy(); }
    /**
     * @brief Carries out accumulated frames.
     */
    std::size_t accumulatedFrames() const noexcept { return accumulatedFrames_; }
    /**
     * @brief Returns whether the object contains no data.
     * @param empty The empty value used by the operation.
     */
    bool empty() const noexcept { return samples_.empty(); }
 
private:
    /**
     * @brief Carries out trim to limit.
     */
    void trimToLimit();
    /**
     * @brief Carries out filtered enhancement.
     */
    double filteredEnhancement() const noexcept;
 
    std::size_t maximumSamples_ = 1600u;
    bool configured_ = false;
    ComplexField2D reference_;
    QuantumScarGeometry2D geometry_;
    QuantumScarConfig2D config_;
    double referenceEnergy_ = 0.0;
    double hbar_ = 1.0;
    std::vector<QuantumScarSample2D> samples_;
    std::vector<double> meanDensitySum_;
    std::vector<std::complex<double>> spectralAccumulator_;
    std::vector<float> meanDensity_;
    std::vector<float> filteredDensity_;
    std::size_t accumulatedFrames_ = 0u;
    double lastAccumulationTime_ = 0.0;
    double totalTimeWeight_ = 0.0;
    bool hasAccumulationTime_ = false;
};
 
} // namespace qpe