probabilitystreamlines2d.h

Go to the documentation of this file.

/**
 * @file probabilitystreamlines2d.h
 * @brief Declares the probabilitystreamlines2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/probabilitystreamlines2d.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/probabilitycurrent2d.h"
 
#include <cstddef>
#include <vector>
 
namespace qpe {
 
/**
 * @brief Data structure used by the Streamline Point2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct StreamlinePoint2D
{
    float x = 0.0f;
    float y = 0.0f;
};
 
/**
 * @brief Data structure used by the Probability Streamline2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct ProbabilityStreamline2D
{
    std::vector<StreamlinePoint2D> points;
};
 
/**
 * @brief Configuration values for Probability Streamline Params.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct ProbabilityStreamlineParams
{
    float stepLength = 0.08f;
    std::size_t maxSteps = 120;
    float minRelativeMagnitude = 0.015f;
};
 
// Builds integral curves of the probability-current field.  Streamlines are
// visualization geometry only: they never feed back into psi or the solver.
/**
 * @brief Implements the Probability Streamlines2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class ProbabilityStreamlines2D
{
public:
    /**
     * @brief Samples bilinear.
     * @param current The current value used by the operation.
     * @param x X coordinate/value.
     * @param y Y coordinate/value.
     * @param jx The jx value used by the operation.
     * @param jy The jy value used by the operation.
     */
    static bool sampleBilinear(const ProbabilityCurrentField2D &current,
                               float x,
                               float y,
                               float &jx,
                               float &jy);
 
    /**
     * @brief Performs trace.
     * @param current The current value used by the operation.
     * @param seedX The seed x value used by the operation.
     * @param seedY The seed y value used by the operation.
     * @param params Parameter block to apply.
     */
    static ProbabilityStreamline2D trace(const ProbabilityCurrentField2D &current,
                                         float seedX,
                                         float seedY,
                                         const ProbabilityStreamlineParams &params);
};
 
} // namespace qpe