quantumzitterbewegung2d.h

Go to the documentation of this file.

/**
 * @file quantumzitterbewegung2d.h
 * @brief Declares the quantumzitterbewegung2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/quantumzitterbewegung2d.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/quantum/diracspinor2d.h"
 
#include <cstddef>
#include <string>
#include <vector>
 
namespace qpe {
 
/**
 * @brief Configuration values for Quantum Zitterbewegung2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct QuantumZitterbewegung2DConfig
{
    bool enabled = false;
    double lightSpeed = 1.0;
    double restMass = 0.5;
    double centerX = -6.0;
    double centerY = 0.0;
    double sigma = 3.5;
    double momentumX = 0.5;
    double momentumY = 0.0;
    // 0 = pure upper spinor (positive/negative energy mixture, visible ZB)
    // 1 = positive-energy projected control (ZB strongly suppressed)
    int preparationMode = 0;
    double analysisEndTime = 12.0;
};
 
/**
 * @brief Data structure used by the Quantum Zitterbewegung Sample2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumZitterbewegungSample2D
{
    double time = 0.0;
    double meanX = 0.0;
    double meanY = 0.0;
    double meanVx = 0.0;
    double meanVy = 0.0;
    double residualX = 0.0;
    double residualY = 0.0;
    double upperPopulation = 0.0;
    double lowerPopulation = 0.0;
    double norm = 0.0;
};
 
/**
 * @brief Data structure used by the Dirac Energy Fractions2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct DiracEnergyFractions2D
{
    double positive = 0.0;
    double negative = 0.0;
};
 
/**
 * @brief Implements the Quantum Zitterbewegung2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumZitterbewegung2D
{
public:
    /**
     * @brief Validates config.
     * @param config Configuration to apply.
     * @param reason The reason value used by the operation.
     */
    static bool validateConfig(const QuantumZitterbewegung2DConfig &config,
                               std::string *reason = nullptr) noexcept;
 
    /**
     * @brief Prepares state.
     * @param spinor Dirac spinor state to read or modify.
     * @param config Configuration to apply.
     * @param hbar The hbar value used by the operation.
     * @param reason The reason value used by the operation.
     */
    static bool prepareState(DiracSpinor2D &spinor,
                             const QuantumZitterbewegung2DConfig &config,
                             double hbar,
                             std::string *reason = nullptr);
 
    /**
     * @brief Returns energy fractions.
     * @param spinor Dirac spinor state to read or modify.
     * @param config Configuration to apply.
     * @param hbar The hbar value used by the operation.
     */
    static DiracEnergyFractions2D energyFractions(const DiracSpinor2D &spinor,
                                                   const QuantumZitterbewegung2DConfig &config,
                                                   double hbar) noexcept;
 
    /**
     * @brief Performs measure.
     * @param spinor Dirac spinor state to read or modify.
     * @param config Configuration to apply.
     * @param hbar The hbar value used by the operation.
     * @param time Simulation time in solver units.
     * @param initialMeanX The initial mean x value used by the operation.
     * @param initialMeanY The initial mean y value used by the operation.
     */
    static QuantumZitterbewegungSample2D measure(const DiracSpinor2D &spinor,
                                                  const QuantumZitterbewegung2DConfig &config,
                                                  double hbar,
                                                  double time,
                                                  double initialMeanX,
                                                  double initialMeanY) noexcept;
 
    /**
     * @brief Performs central energy.
     * @param config Configuration to apply.
     */
    static double centralEnergy(const QuantumZitterbewegung2DConfig &config) noexcept;
    /**
     * @brief Performs predicted zitter omega.
     * @param config Configuration to apply.
     * @param hbar The hbar value used by the operation.
     */
    static double predictedZitterOmega(const QuantumZitterbewegung2DConfig &config,
                                       double hbar) noexcept;
    /**
     * @brief Performs predicted zitter period.
     * @param config Configuration to apply.
     * @param hbar The hbar value used by the operation.
     */
    static double predictedZitterPeriod(const QuantumZitterbewegung2DConfig &config,
                                        double hbar) noexcept;
    /**
     * @brief Performs predicted drift x.
     * @param config Configuration to apply.
     */
    static double predictedDriftX(const QuantumZitterbewegung2DConfig &config) noexcept;
    /**
     * @brief Performs predicted drift y.
     * @param config Configuration to apply.
     */
    static double predictedDriftY(const QuantumZitterbewegung2DConfig &config) noexcept;
};
 
/**
 * @brief Implements the Quantum Zitterbewegung History2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumZitterbewegungHistory2D
{
public:
    /**
     * @brief Constructs a Quantum Zitterbewegung History 2D instance.
     * @param maximumSamples The maximum samples value used by the operation.
     */
    explicit QuantumZitterbewegungHistory2D(std::size_t maximumSamples = 640u)
        : maximumSamples_(maximumSamples) {}
 
    /**
     * @brief Clears stored state and returns the component to its empty/default state.
     */
    void clear();
    /**
     * @brief Returns configure.
     * @param spinor Dirac spinor state to read or modify.
     * @param config Configuration to apply.
     * @param hbar The hbar value used by the operation.
     */
    bool configure(const DiracSpinor2D &spinor,
                   const QuantumZitterbewegung2DConfig &config,
                   double hbar);
    /**
     * @brief Carries out append.
     * @param time Simulation time in solver units.
     * @param spinor Dirac spinor state to read or modify.
     */
    void append(double time, const DiracSpinor2D &spinor);
 
    /**
     * @brief Returns configured.
     */
    bool configured() const noexcept { return configured_; }
    /**
     * @brief Returns config.
     */
    const QuantumZitterbewegung2DConfig &config() const noexcept { return config_; }
    /**
     * @brief Samples s.
     */
    const std::vector<QuantumZitterbewegungSample2D> &samples() const noexcept { return samples_; }
    /**
     * @brief Carries out positive energy fraction.
     */
    double positiveEnergyFraction() const noexcept { return energyFractions_.positive; }
    /**
     * @brief Carries out negative energy fraction.
     */
    double negativeEnergyFraction() const noexcept { return energyFractions_.negative; }
    /**
     * @brief Initializes ial mean x.
     */
    double initialMeanX() const noexcept { return initialMeanX_; }
    /**
     * @brief Initializes ial mean y.
     */
    double initialMeanY() const noexcept { return initialMeanY_; }
    /**
     * @brief Carries out maximum abs residual x.
     */
    double maximumAbsResidualX() const noexcept { return maximumAbsResidualX_; }
    /**
     * @brief Carries out fitted drift x.
     */
    double fittedDriftX() const noexcept { return fittedDriftX_; }
    /**
     * @brief Carries out fitted drift y.
     */
    double fittedDriftY() const noexcept { return fittedDriftY_; }
    /**
     * @brief Carries out hbar.
     */
    double hbar() const noexcept { return hbar_; }
 
private:
    /**
     * @brief Carries out trim.
     */
    void trim();
 
    std::size_t maximumSamples_ = 640u;
    bool configured_ = false;
    QuantumZitterbewegung2DConfig config_;
    double hbar_ = 1.0;
    double initialMeanX_ = 0.0;
    double initialMeanY_ = 0.0;
    double maximumAbsResidualX_ = 0.0;
    double fittedDriftX_ = 0.0;
    double fittedDriftY_ = 0.0;
    DiracEnergyFractions2D energyFractions_;
    std::vector<QuantumZitterbewegungSample2D> samples_;
};
 
} // namespace qpe