quantummoshinsky2d.h

Go to the documentation of this file.

/**
 * @file quantummoshinsky2d.h
 * @brief Declares the quantummoshinsky2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/quantummoshinsky2d.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 <cstdint>
#include <string>
#include <vector>
 
namespace qpe {
 
// Step 41: Moshinsky shutter / diffraction in time.
// A truncated matter wave occupies x < shutterX at t=0.  The shutter potential
// is removed suddenly, and the released edge develops Fresnel-like oscillations
// in time at a fixed downstream detector.
/**
 * @brief Configuration values for Quantum Moshinsky Initial State2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct QuantumMoshinskyInitialState2DConfig
{
    bool enabled = false;
    double shutterX = 0.0;
    double envelopeCenterX = -8.0;
    double envelopeSigmaX = 8.0;
    double centerY = 0.0;
    double transverseSigmaY = 3.2;
    double momentumX = 3.0;
    double edgeWidth = 0.18;
};
 
/**
 * @brief Configuration values for Quantum Moshinsky2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct QuantumMoshinsky2DConfig
{
    bool enabled = false;
    std::uint64_t shutterObjectId = 0;
    double openTime = 0.0;
    double detectorX = 4.0;
    double analysisEndTime = 6.0;
};
 
/**
 * @brief Data structure used by the Quantum Moshinsky Geometry2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumMoshinskyGeometry2D
{
    bool valid = false;
    std::uint64_t shutterObjectId = 0;
    double shutterX = 0.0;
    double shutterCenterY = 0.0;
    double shutterLength = 0.0;
    double shutterThickness = 0.0;
    double closedHeight = 0.0;
};
 
/**
 * @brief Data structure used by the Quantum Moshinsky Potential State2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumMoshinskyPotentialState2D
{
    bool valid = false;
    bool opened = false;
    double shutterHeight = 0.0;
};
 
/**
 * @brief Data structure used by the Quantum Moshinsky Sample2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumMoshinskySample2D
{
    double time = 0.0;
    bool shutterOpened = false;
    double detectorSignal = 0.0;    // x-marginal density at detectorX
    double frontProbability = 0.0;  // integral over x > shutterX
    double meanX = 0.0;
    std::vector<float> marginalX;   // integral dy |psi(x,y)|^2
};
 
class PotentialField2D;
 
/**
 * @brief Implements the Quantum Moshinsky2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumMoshinsky2D
{
public:
    /**
     * @brief Validates initial state.
     * @param config Configuration to apply.
     * @param reason The reason value used by the operation.
     */
    static bool validateInitialState(const QuantumMoshinskyInitialState2DConfig &config,
                                     const char **reason = nullptr) noexcept;
 
    /**
     * @brief Initializes ialize.
     * @param field Field data 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 initialize(ComplexField2D &field,
                           const QuantumMoshinskyInitialState2DConfig &config,
                           double hbar,
                           std::string *reason = nullptr);
 
    /**
     * @brief Returns identify shutter.
     * @param scene The scene value used by the operation.
     * @param shutterObjectId Stable identifier of the requested object.
     * @param geometry The geometry value used by the operation.
     * @param reason The reason value used by the operation.
     */
    static bool identifyShutter(const PotentialScene2D &scene,
                                std::uint64_t shutterObjectId,
                                QuantumMoshinskyGeometry2D &geometry,
                                const char **reason = nullptr) noexcept;
 
    /**
     * @brief Validates config.
     * @param scene The scene value used by the operation.
     * @param config Configuration to apply.
     * @param geometry The geometry value used by the operation.
     * @param reason The reason value used by the operation.
     */
    static bool validateConfig(const PotentialScene2D &scene,
                               const QuantumMoshinsky2DConfig &config,
                               QuantumMoshinskyGeometry2D *geometry = nullptr,
                               const char **reason = nullptr) noexcept;
 
    // Rasterizes a temporary scene.  At the exact reset instant t=openTime the
    // shutter is still drawn closed; the first positive midpoint sample opens
    // it. This makes the physical operation visible without evolving against a
    // closed shutter for a finite pre-release interval.
    /**
     * @brief Performs rasterize.
     * @param scene The scene 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 QuantumMoshinskyPotentialState2D rasterize(
        const PotentialScene2D &scene,
        const QuantumMoshinsky2DConfig &config,
        double time,
        PotentialField2D &target) noexcept;
 
    /**
     * @brief Performs marginal x.
     * @param field Field data to read or modify.
     * @param out The out value used by the operation.
     */
    static bool marginalX(const ComplexField2D &field,
                          std::vector<float> &out) noexcept;
 
    /**
     * @brief Performs detector signal.
     * @param field Field data to read or modify.
     * @param marginal The marginal value used by the operation.
     * @param detectorX The detector x value used by the operation.
     */
    static double detectorSignal(const ComplexField2D &field,
                                 const std::vector<float> &marginal,
                                 double detectorX) noexcept;
 
    /**
     * @brief Performs front probability.
     * @param field Field data to read or modify.
     * @param marginal The marginal value used by the operation.
     * @param shutterX The shutter x value used by the operation.
     */
    static double frontProbability(const ComplexField2D &field,
                                   const std::vector<float> &marginal,
                                   double shutterX) noexcept;
 
    /**
     * @brief Performs mean x.
     * @param field Field data to read or modify.
     * @param marginal The marginal value used by the operation.
     */
    static double meanX(const ComplexField2D &field,
                        const std::vector<float> &marginal) noexcept;
};
 
/**
 * @brief Implements the Quantum Moshinsky History2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumMoshinskyHistory2D
{
public:
    /**
     * @brief Constructs a Quantum Moshinsky History 2D instance.
     * @param maximumSamples The maximum samples value used by the operation.
     */
    explicit QuantumMoshinskyHistory2D(std::size_t maximumSamples = 520u);
 
    /**
     * @brief Clears stored state and returns the component to its empty/default state.
     */
    void clear() noexcept;
    /**
     * @brief Returns configure.
     * @param config Configuration to apply.
     * @param geometry The geometry value used by the operation.
     * @param field Field data to read or modify.
     */
    bool configure(const QuantumMoshinsky2DConfig &config,
                   const QuantumMoshinskyGeometry2D &geometry,
                   const ComplexField2D &field);
    /**
     * @brief Carries out append.
     * @param time Simulation time in solver units.
     * @param shutterOpened The shutter opened value used by the operation.
     * @param field Field data to read or modify.
     */
    bool append(double time,
                bool shutterOpened,
                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 Returns config.
     */
    const QuantumMoshinsky2DConfig &config() const noexcept { return config_; }
    /**
     * @brief Carries out geometry.
     */
    const QuantumMoshinskyGeometry2D &geometry() const noexcept { return geometry_; }
    /**
     * @brief Samples s.
     */
    const std::vector<QuantumMoshinskySample2D> &samples() const noexcept { return samples_; }
    /**
     * @brief Carries out grid width.
     */
    std::size_t gridWidth() const noexcept { return width_; }
    /**
     * @brief Carries out grid dx.
     */
    float gridDx() const noexcept { return dx_; }
    /**
     * @brief Carries out x coordinate.
     * @param x X coordinate/value.
     */
    double xCoordinate(std::size_t x) const noexcept;
 
private:
    /**
     * @brief Carries out trim to limit.
     */
    void trimToLimit();
 
    std::size_t maximumSamples_ = 520u;
    bool configured_ = false;
    std::size_t width_ = 0u;
    std::size_t height_ = 0u;
    float dx_ = 1.0f;
    float dy_ = 1.0f;
    QuantumMoshinsky2DConfig config_;
    QuantumMoshinskyGeometry2D geometry_;
    std::vector<QuantumMoshinskySample2D> samples_;
};
 
} // namespace qpe