probabilitycontours2d.h

Go to the documentation of this file.

/**
 * @file probabilitycontours2d.h
 * @brief Declares the probabilitycontours2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/probabilitycontours2d.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 <cstddef>
#include <vector>
 
namespace qpe {
 
class ComplexField2D;
 
/**
 * @brief Enumerates the supported Probability Contour Spacing2D values.
 *
 * The enumeration is part of the typed interface used to keep experiment configuration and analysis routing explicit.
 */
enum class ProbabilityContourSpacing2D
{
    Linear = 0,
    Logarithmic
};
 
/**
 * @brief Data structure used by the Probability Contour Segment2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct ProbabilityContourSegment2D
{
    float x1 = 0.0f;
    float y1 = 0.0f;
    float x2 = 0.0f;
    float y2 = 0.0f;
    float level = 0.0f;
    float normalizedLevel = 0.0f;
};
 
/**
 * @brief Data record containing Probability Contours2D Result.
 *
 * The structure carries computed data without coupling the numerical component to the GUI or renderer.
 */
struct ProbabilityContours2DResult
{
    std::vector<float> levels;
    std::vector<ProbabilityContourSegment2D> segments;
    float maximumProbability = 0.0f;
    ProbabilityContourSpacing2D spacing = ProbabilityContourSpacing2D::Logarithmic;
    float logDecades = 4.0f;
    std::size_t samplingStride = 1u;
 
    /**
     * @brief Returns whether the object contains no data.
     * @param empty The empty value used by the operation.
     */
    bool empty() const noexcept { return segments.empty(); }
};
 
/**
 * @brief Implements the Probability Contours2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class ProbabilityContours2D
{
public:
    // Extract |psi(x,y)|^2 = constant curves using Marching Squares.
    // Linear spacing distributes levels uniformly between zero and max(|psi|^2).
    // Logarithmic spacing distributes levels over the requested number of decades
    // below the current maximum and is useful for revealing weak wave structure.
    // To keep the live overlay responsive on large grids, extraction automatically
    // downsamples to at most targetSamplesPerAxis samples per axis.
    /**
     * @brief Performs compute.
     * @param field Field data to read or modify.
     * @param requestedLevels The requested levels value used by the operation.
     * @param spacing The spacing value used by the operation.
     * @param logDecades The log decades value used by the operation.
     * @param targetSamplesPerAxis The target samples per axis value used by the operation.
     */
    static ProbabilityContours2DResult compute(
        const ComplexField2D &field,
        std::size_t requestedLevels,
        ProbabilityContourSpacing2D spacing,
        float logDecades = 4.0f,
        std::size_t targetSamplesPerAxis = 384u);
};
 
} // namespace qpe