ramseyinterferometry2d.h

Go to the documentation of this file.

/**
 * @file ramseyinterferometry2d.h
 * @brief Declares the ramseyinterferometry2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/ramseyinterferometry2d.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/driventwolevel2d.h"
 
#include <vector>
 
namespace qpe {
 
struct BoundStateSpectrum1D;
struct RamseyPulseSequence2DConfig;
 
/**
 * @brief Data structure used by the Ramsey Theory2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct RamseyTheory2D
{
    bool valid = false;
    int stateA = 0;
    int stateB = 1;
    double energyA = 0.0;
    double energyB = 0.0;
    double transitionAngularFrequency = 0.0;
    double driveAngularFrequency = 0.0;
    double detuning = 0.0;
    double couplingMatrixElementX = 0.0;
    double resonantRabiAngularFrequency = 0.0;
    double idealPiOver2Duration = 0.0;
    double firstPulseEnd = 0.0;
    bool echoEnabled = false;
    double echoPulseStart = 0.0;
    double echoPulseEnd = 0.0;
    double secondPulseStart = 0.0;
    double secondPulseEnd = 0.0;
    double freePhaseRadians = 0.0;
    double predictedFinalPopulationA = 0.0;
    double predictedFinalPopulationB = 0.0;
};
 
/**
 * @brief Data structure used by the Ramsey Fringe Sample2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct RamseyFringeSample2D
{
    double freeEvolutionDuration = 0.0;
    double phaseRadians = 0.0;
    double populationA = 0.0;
    double populationB = 0.0;
};
 
// Step 28: analysis-only ensemble with a Gaussian distribution of static
// transition-frequency offsets.  It never changes the application's psi,
// potential, solver clock or measurement probabilities.  Each ensemble
// member is a separate two-level reference system whose detuning remains
// constant for the complete pulse sequence.
/**
 * @brief Configuration values for Ramsey Ensemble2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct RamseyEnsemble2DConfig
{
    bool enabled = false;
    double detuningStdDev = 0.06; // angular-frequency sigma, same units as omega
    int memberCount = 41;
};
 
/**
 * @brief Data structure used by the Ramsey Ensemble Result2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct RamseyEnsembleResult2D
{
    bool valid = false;
    int memberCount = 0;
    double detuningStdDev = 0.0;
    double meanPopulationA = 0.0;
    double meanPopulationB = 0.0;
    double minimumPopulationB = 0.0;
    double maximumPopulationB = 0.0;
};
 
/**
 * @brief Data structure used by the Ramsey Ensemble Fringe Sample2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct RamseyEnsembleFringeSample2D
{
    double freeEvolutionDuration = 0.0;
    double meanPopulationA = 0.0;
    double meanPopulationB = 0.0;
};
 
// Steps 26-28 diagnostic for Ramsey interferometry. The real application
// still evolves psi(x,y) with the full split-step solver. This helper projects
// that field onto the two lowest stationary states and integrates the same
// pulse recipe only as a compact two-level reference / fringe predictor.
/**
 * @brief Implements the Ramsey Interferometry2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class RamseyInterferometry2D
{
public:
    /**
     * @brief Performs analyze.
     * @param spectrum The spectrum value used by the operation.
     * @param sequence The sequence value used by the operation.
     * @param stateA The state a value used by the operation.
     * @param stateB The state b value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static RamseyTheory2D analyze(const BoundStateSpectrum1D &spectrum,
                                  const RamseyPulseSequence2DConfig &sequence,
                                  int stateA = 0,
                                  int stateB = 1,
                                  double hbar = 1.0) noexcept;
 
    /**
     * @brief Performs project.
     * @param field Field data to read or modify.
     * @param spectrum The spectrum value used by the operation.
     * @param stateA The state a value used by the operation.
     * @param stateB The state b value used by the operation.
     */
    static DrivenTwoLevelProjection2D project(const ComplexField2D &field,
                                              const BoundStateSpectrum1D &spectrum,
                                              int stateA = 0,
                                              int stateB = 1);
 
    /**
     * @brief Performs scan free evolution.
     * @param spectrum The spectrum value used by the operation.
     * @param sequence The sequence value used by the operation.
     * @param minimumFreeTime Time value expressed in the units documented by the calling component.
     * @param maximumFreeTime Time value expressed in the units documented by the calling component.
     * @param sampleCount The sample count value used by the operation.
     * @param stateA The state a value used by the operation.
     * @param stateB The state b value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static std::vector<RamseyFringeSample2D> scanFreeEvolution(
        const BoundStateSpectrum1D &spectrum,
        const RamseyPulseSequence2DConfig &sequence,
        double minimumFreeTime,
        double maximumFreeTime,
        int sampleCount,
        int stateA = 0,
        int stateB = 1,
        double hbar = 1.0);
 
    /**
     * @brief Validates ensemble config.
     * @param config Configuration to apply.
     */
    static bool validateEnsembleConfig(const RamseyEnsemble2DConfig &config) noexcept;
 
    /**
     * @brief Performs analyze static detuning ensemble.
     * @param spectrum The spectrum value used by the operation.
     * @param sequence The sequence value used by the operation.
     * @param ensemble The ensemble value used by the operation.
     * @param stateA The state a value used by the operation.
     * @param stateB The state b value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static RamseyEnsembleResult2D analyzeStaticDetuningEnsemble(
        const BoundStateSpectrum1D &spectrum,
        const RamseyPulseSequence2DConfig &sequence,
        const RamseyEnsemble2DConfig &ensemble,
        int stateA = 0,
        int stateB = 1,
        double hbar = 1.0);
 
    /**
     * @brief Performs scan free evolution ensemble.
     * @param spectrum The spectrum value used by the operation.
     * @param sequence The sequence value used by the operation.
     * @param ensemble The ensemble value used by the operation.
     * @param minimumFreeTime Time value expressed in the units documented by the calling component.
     * @param maximumFreeTime Time value expressed in the units documented by the calling component.
     * @param sampleCount The sample count value used by the operation.
     * @param stateA The state a value used by the operation.
     * @param stateB The state b value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static std::vector<RamseyEnsembleFringeSample2D> scanFreeEvolutionEnsemble(
        const BoundStateSpectrum1D &spectrum,
        const RamseyPulseSequence2DConfig &sequence,
        const RamseyEnsemble2DConfig &ensemble,
        double minimumFreeTime,
        double maximumFreeTime,
        int sampleCount,
        int stateA = 0,
        int stateB = 1,
        double hbar = 1.0);
};
 
} // namespace qpe