positionmeasurement2d.h

Go to the documentation of this file.

/**
 * @file positionmeasurement2d.h
 * @brief Declares the positionmeasurement2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/positionmeasurement2d.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 <cstdint>
#include <vector>
 
namespace qpe {
 
class ComplexField2D;
 
/**
 * @brief Data record containing Position Measurement2D Point.
 *
 * The structure carries computed data without coupling the numerical component to the GUI or renderer.
 */
struct PositionMeasurement2DPoint
{
    float x = 0.0f;
    float y = 0.0f;
};
 
// Samples ideal position measurements from the discrete in-domain density
// P(x,y) = |psi(x,y)|^2. The wavefunction is never modified.
//
// If an absorbing boundary has reduced the field norm below one, sampling is
// conditional on the particle still being inside the simulated domain.
/**
 * @brief Implements the Position Measurement2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class PositionMeasurement2D
{
public:
    /**
     * @brief Performs sample.
     * @param field Field data to read or modify.
     * @param shots The shots value used by the operation.
     */
    static std::vector<PositionMeasurement2DPoint> sample(
        const ComplexField2D &field,
        std::size_t shots);
 
    // Deterministic overload used by tests and reproducible demonstrations.
    /**
     * @brief Samples seeded.
     * @param field Field data to read or modify.
     * @param shots The shots value used by the operation.
     * @param seed The seed value used by the operation.
     */
    static std::vector<PositionMeasurement2DPoint> sampleSeeded(
        const ComplexField2D &field,
        std::size_t shots,
        std::uint32_t seed);
};
 
} // namespace qpe