quantumrevivals2d.h

Go to the documentation of this file.

/**
 * @file quantumrevivals2d.h
 * @brief Declares the quantumrevivals2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/quantumrevivals2d.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 <string>
#include <vector>
 
namespace qpe {
 
/**
 * @brief Data structure used by the Quantum Box Geometry2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumBoxGeometry2D
{
    bool valid = false;
    double centerX = 0.0;
    double centerY = 0.0;
    double innerWidth = 0.0;
    double innerHeight = 0.0;
    double wallThicknessX = 0.0;
    double wallThicknessY = 0.0;
    double wallPotential = 0.0;
};
 
/**
 * @brief Data structure used by the Quantum Revival Sample2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumRevivalSample2D
{
    double time = 0.0;
    double fidelity = 0.0;
    std::vector<float> marginalX;
};
 
/**
 * @brief Implements the Quantum Revivals2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumRevivals2D
{
public:
    // Identify a Step-30 style rectangular box made from four positive
    // Rectangle walls: two vertical plus two horizontal.
    /**
     * @brief Returns identify box.
     * @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 identifyBox(const PotentialScene2D &scene,
                            QuantumBoxGeometry2D &geometry,
                            std::string *reason = nullptr) noexcept;
 
    // Infinite-square-well reference recurrence time for one dimension:
    // E_n = n^2*pi^2*hbar^2/(2*m*L^2), T_rev = 4*m*L^2/(pi*hbar).
    // The finite barriers used by the real 2D solver can shift the measured
    // recurrence slightly; the formula is therefore a tutor/reference layer.
    /**
     * @brief Performs revival time.
     * @param boxLength The box length value used by the operation.
     * @param mass The mass value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static double revivalTime(double boxLength,
                              double mass,
                              double hbar = 1.0) noexcept;
 
    /**
     * @brief Performs revival time x.
     * @param geometry The geometry value used by the operation.
     * @param mass The mass value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static double revivalTimeX(const QuantumBoxGeometry2D &geometry,
                               double mass,
                               double hbar = 1.0) noexcept;
    /**
     * @brief Performs revival time y.
     * @param geometry The geometry value used by the operation.
     * @param mass The mass value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static double revivalTimeY(const QuantumBoxGeometry2D &geometry,
                               double mass,
                               double hbar = 1.0) noexcept;
 
    // Integral over y of |psi(x,y)|^2. The returned samples are densities in x
    // and therefore sum to norm/dx rather than to one without the dx factor.
    /**
     * @brief Performs marginal probability x.
     * @param field Field data to read or modify.
     */
    static std::vector<float> marginalProbabilityX(const ComplexField2D &field);
 
    // |<reference|field>|^2, normalized by both field norms. This makes the
    // diagnostic robust to small norm loss while never altering either field.
    /**
     * @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;
};
 
// Small diagnostic history for the quantum-carpet plot. It keeps one initial
// reference field plus 1D probability marginals, never a time history of full
// 2D wavefunctions. It is analysis-only and cannot evolve psi.
/**
 * @brief Implements the Quantum Revival History2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumRevivalHistory2D
{
public:
    /**
     * @brief Constructs a Quantum Revival History 2D instance.
     * @param maximumSamples The maximum samples value used by the operation.
     */
    explicit QuantumRevivalHistory2D(std::size_t maximumSamples = 1200u);
 
    /**
     * @brief Clears stored state and returns the component to its empty/default state.
     */
    void clear() noexcept;
    /**
     * @brief Carries out capture reference.
     * @param field Field data to read or modify.
     */
    bool captureReference(const ComplexField2D &field);
    /**
     * @brief Returns whether reference.
     * @param empty The empty value used by the operation.
     */
    bool hasReference() const noexcept { return !reference_.empty(); }
 
    /**
     * @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<QuantumRevivalSample2D> &samples() const noexcept
    {
        return samples_;
    }
 
    /**
     * @brief Returns size.
     * @param size The size value used by the operation.
     */
    std::size_t size() const noexcept { return samples_.size(); }
    /**
     * @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 Returns the X-axis grid spacing.
     * @param dx The dx value used by the operation.
     */
    float dx() const noexcept { return reference_.dx(); }
    /**
     * @brief Carries out grid width.
     * @param width The width value used by the operation.
     */
    std::size_t gridWidth() const noexcept { return reference_.width(); }
 
private:
    /**
     * @brief Carries out trim to limit.
     */
    void trimToLimit();
 
    std::size_t maximumSamples_ = 1200u;
    ComplexField2D reference_;
    std::vector<QuantumRevivalSample2D> samples_;
};
 
} // namespace qpe