quantumanderson2d.h

Go to the documentation of this file.

/**
 * @file quantumanderson2d.h
 * @brief Declares the quantumanderson2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/quantumanderson2d.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 Configuration values for Quantum Anderson Initial State2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct QuantumAndersonInitialState2DConfig
{
    double centerX = 0.0;
    double cleanLaneY = 4.0;
    double disorderLaneY = -4.0;
    double sigma = 0.35;
    double relativePhaseDegrees = 0.0;
};
 
/**
 * @brief Data structure used by the Quantum Anderson Lattice2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumAndersonLattice2D
{
    bool valid = false;
    double cleanLaneY = 0.0;
    double disorderLaneY = 0.0;
    double spacing = 0.0;
    double siteSigmaX = 0.0;
    double siteSigmaY = 0.0;
    double cleanDepth = 0.0;
    double disorderDepthMean = 0.0;
    double disorderDepthStdDev = 0.0;
    std::vector<double> siteX;
    std::vector<double> cleanDepths;
    std::vector<double> disorderDepths;
};
 
/**
 * @brief Data structure used by the Quantum Anderson Lane Sample2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumAndersonLaneSample2D
{
    double probability = 0.0;
    double meanX = 0.0;
    double sigmaX = 0.0;
    double siteParticipation = 0.0;
    double centralSiteProbability = 0.0;
    double localizationLength = 0.0;
    bool localizationLengthValid = false;
    double profileXMin = 0.0;
    double profileDx = 0.0;
    std::vector<float> marginalX;
};
 
/**
 * @brief Data structure used by the Quantum Anderson Sample2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumAndersonSample2D
{
    double time = 0.0;
    QuantumAndersonLaneSample2D clean;
    QuantumAndersonLaneSample2D disorder;
    double norm = 0.0;
};
 
/**
 * @brief Implements the Quantum Anderson2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumAnderson2D
{
public:
    /**
     * @brief Validates config.
     * @param config Configuration to apply.
     * @param reason The reason value used by the operation.
     */
    static bool validateConfig(const QuantumAndersonInitialState2DConfig &config,
                               std::string *reason = nullptr);
    /**
     * @brief Initializes dual lane.
     * @param field Field data to read or modify.
     * @param config Configuration to apply.
     * @param reason The reason value used by the operation.
     */
    static bool initializeDualLane(ComplexField2D &field,
                                   const QuantumAndersonInitialState2DConfig &config,
                                   std::string *reason = nullptr);
    /**
     * @brief Returns identify lattice.
     * @param scene The scene value used by the operation.
     * @param lattice The lattice value used by the operation.
     * @param reason The reason value used by the operation.
     */
    static bool identifyLattice(const PotentialScene2D &scene,
                                QuantumAndersonLattice2D &lattice,
                                std::string *reason = nullptr);
    /**
     * @brief Measures lane.
     * @param field Field data to read or modify.
     * @param lattice The lattice value used by the operation.
     * @param cleanLane The clean lane value used by the operation.
     */
    static QuantumAndersonLaneSample2D measureLane(const ComplexField2D &field,
                                                   const QuantumAndersonLattice2D &lattice,
                                                   bool cleanLane);
    /**
     * @brief Performs free gaussian sigma.
     * @param time Simulation time in solver units.
     * @param sigma0 The sigma0 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 freeGaussianSigma(double time, double sigma0,
                                    double mass, double hbar) noexcept;
};
 
/**
 * @brief Implements the Quantum Anderson History2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumAndersonHistory2D
{
public:
    /**
     * @brief Performs quantum anderson history2 d.
     * @param maxSamples The max samples value used by the operation.
     */
    explicit QuantumAndersonHistory2D(std::size_t maxSamples = 1200u);
 
    /**
     * @brief Performs clear.
     */
    void clear();
    /**
     * @brief Returns configure.
     * @param config Configuration to apply.
     * @param lattice The lattice value used by the operation.
     */
    void configure(const QuantumAndersonInitialState2DConfig &config,
                   const QuantumAndersonLattice2D &lattice);
    /**
     * @brief Returns configured.
     */
    bool configured() const noexcept;
    /**
     * @brief Performs empty.
     */
    bool empty() const noexcept;
    /**
     * @brief Performs append.
     * @param time Simulation time in solver units.
     * @param field Field data to read or modify.
     */
    void append(double time, const ComplexField2D &field);
 
    /**
     * @brief Returns config.
     */
    const QuantumAndersonInitialState2DConfig &config() const noexcept;
    /**
     * @brief Performs lattice.
     */
    const QuantumAndersonLattice2D &lattice() const noexcept;
    /**
     * @brief Samples s.
     */
    const std::vector<QuantumAndersonSample2D> &samples() const noexcept;
 
private:
    /**
     * @brief Performs trim.
     */
    void trim();
 
    std::size_t maxSamples_ = 1200u;
    bool configured_ = false;
    QuantumAndersonInitialState2DConfig config_;
    QuantumAndersonLattice2D lattice_;
    std::vector<QuantumAndersonSample2D> samples_;
};
 
} // namespace qpe