timedependentpotential2d.h

Go to the documentation of this file.

/**
 * @file timedependentpotential2d.h
 * @brief Declares the timedependentpotential2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/timedependentpotential2d.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/potentialscene2d.h"
 
#include <cstdint>
 
namespace qpe {
 
// A compact vocabulary for parameters that may be controlled by H(t).
/**
 * @brief Enumerates the supported Time Potential Parameter2D values.
 *
 * The enumeration is part of the typed interface used to keep experiment configuration and analysis routing explicit.
 */
enum class TimePotentialParameter2D
{
    ObjectValue = 0,
    CenterX = 1,
    CenterY = 2,
    HarmonicCurvatureX = 3,
    HarmonicCurvatureY = 4,
    HarmonicCurvatureXY = 5,
    LinearSlopeX = 6,
    LinearSlopeY = 7
};
 
// Step 21: abrupt one-shot change.
/**
 * @brief Configuration values for Quantum Quench2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct QuantumQuench2DConfig
{
    bool enabled = false;
    std::uint64_t targetObjectId = 0;
    TimePotentialParameter2D parameter = TimePotentialParameter2D::HarmonicCurvatureXY;
    double quenchTime = 2.0;
    double beforeValue = 0.25;
    double afterValue = 1.0;
};
 
/**
 * @brief Data record containing Quantum Quench2D State.
 *
 * The structure carries computed data without coupling the numerical component to the GUI or renderer.
 */
struct QuantumQuench2DState
{
    bool valid = false;
    bool fired = false;
    double currentValue = 0.0;
};
 
// Step 22: smooth sinusoidal drive. The controlled parameter follows
// q(t)=meanValue+amplitude*sin(angularFrequency*t+phase).
/**
 * @brief Configuration values for Periodic Potential Drive2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct PeriodicPotentialDrive2DConfig
{
    bool enabled = false;
    std::uint64_t targetObjectId = 0;
    TimePotentialParameter2D parameter = TimePotentialParameter2D::CenterX;
    double meanValue = 0.0;
    double amplitude = 0.75;
    double angularFrequency = 0.5;
    double phaseDegrees = 0.0;
};
 
/**
 * @brief Data record containing Periodic Potential Drive2D State.
 *
 * The structure carries computed data without coupling the numerical component to the GUI or renderer.
 */
struct PeriodicPotentialDrive2DState
{
    bool valid = false;
    double currentValue = 0.0;
    double phaseRadians = 0.0;
};
 
// Step 24: finite linear sweep. The controlled parameter is held at
// startValue before startTime, ramps linearly to endValue during duration,
// then remains at endValue. This is the drive used for adiabatic passage /
// Landau-Zener experiments.
/**
 * @brief Configuration values for Linear Potential Sweep2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct LinearPotentialSweep2DConfig
{
    bool enabled = false;
    std::uint64_t targetObjectId = 0;
    TimePotentialParameter2D parameter = TimePotentialParameter2D::LinearSlopeX;
    double startValue = 0.35;
    double endValue = -0.35;
    double startTime = 0.0;
    double duration = 40.0;
 
    // Step 25: optional return passage for Landau-Zener-Stueckelberg
    // interferometry. When enabled, the parameter ramps Start -> End during
    // duration, waits at End for holdDuration, then ramps End -> Start during
    // returnDuration. Step-24 one-way sweeps keep this disabled.
    bool returnEnabled = false;
    double holdDuration = 0.0;
    double returnDuration = 4.0;
};
 
 
// Step 26: Ramsey pulse sequence. Two finite sinusoidal pulses are separated
// by a field-free evolution interval. Each pulse starts with its own local
// phase reference, so the otherwise invisible phase accumulated by psi during
// the free interval is converted into a final population difference.
/**
 * @brief Configuration values for Ramsey Pulse Sequence2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct RamseyPulseSequence2DConfig
{
    bool enabled = false;
    std::uint64_t targetObjectId = 0;
    TimePotentialParameter2D parameter = TimePotentialParameter2D::LinearSlopeX;
    double meanValue = 0.0;
    double amplitude = 0.10;
    double angularFrequency = 0.305536;
    double firstPulsePhaseDegrees = 0.0;
    double secondPulsePhaseDegrees = 0.0;
    double startTime = 0.0;
    double pulseDuration = 14.35;
    double freeEvolutionDuration = 5.5;
 
    // Step 27: optional Hahn-echo refocusing pulse. When enabled the free
    // interval is split in half and a pi pulse is inserted between the two
    // halves: pi/2 -> tau/2 -> pi -> tau/2 -> pi/2.
    bool echoEnabled = false;
    double echoPulseDuration = 28.70;
    double echoPulsePhaseDegrees = 0.0;
};
 
/**
 * @brief Enumerates the supported Ramsey Pulse Segment2D values.
 *
 * The enumeration is part of the typed interface used to keep experiment configuration and analysis routing explicit.
 */
enum class RamseyPulseSegment2D
{
    Before = 0,
    FirstPulse = 1,
    FreeEvolution = 2,
    EchoFreeFirst = 3,
    EchoPulse = 4,
    EchoFreeSecond = 5,
    SecondPulse = 6,
    Finished = 7
};
 
/**
 * @brief Data record containing Ramsey Pulse Sequence2D State.
 *
 * The structure carries computed data without coupling the numerical component to the GUI or renderer.
 */
struct RamseyPulseSequence2DState
{
    bool valid = false;
    RamseyPulseSegment2D segment = RamseyPulseSegment2D::Before;
    double currentValue = 0.0;
    double localPulseTime = 0.0;
    double progress = 0.0;
};
 
/**
 * @brief Data record containing Linear Potential Sweep2D State.
 *
 * The structure carries computed data without coupling the numerical component to the GUI or renderer.
 */
struct LinearPotentialSweep2DState
{
    bool valid = false;
    bool finished = false;
    bool returning = false;
    bool holding = false;
    double currentValue = 0.0;
    double progress = 0.0;
};
 
/**
 * @brief Implements the Time Dependent Potential2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class TimeDependentPotential2D
{
public:
    /**
     * @brief Performs validate.
     * @param scene The scene value used by the operation.
     * @param config Configuration to apply.
     */
    static bool validate(const PotentialScene2D &scene,
                         const QuantumQuench2DConfig &config) noexcept;
 
    /**
     * @brief Validates periodic.
     * @param scene The scene value used by the operation.
     * @param config Configuration to apply.
     */
    static bool validatePeriodic(const PotentialScene2D &scene,
                                 const PeriodicPotentialDrive2DConfig &config) noexcept;
 
    /**
     * @brief Validates sweep.
     * @param scene The scene value used by the operation.
     * @param config Configuration to apply.
     */
    static bool validateSweep(const PotentialScene2D &scene,
                              const LinearPotentialSweep2DConfig &config) noexcept;
 
    /**
     * @brief Validates ramsey.
     * @param scene The scene value used by the operation.
     * @param config Configuration to apply.
     */
    static bool validateRamsey(const PotentialScene2D &scene,
                               const RamseyPulseSequence2DConfig &config) noexcept;
 
    /**
     * @brief Applies parameter.
     * @param object The object value used by the operation.
     * @param parameter The parameter value used by the operation.
     * @param value Value to assign or evaluate.
     */
    static bool applyParameter(PotentialObject2D &object,
                               TimePotentialParameter2D parameter,
                               double value) noexcept;
 
    /**
     * @brief Performs parameter value.
     * @param object The object value used by the operation.
     * @param parameter The parameter value used by the operation.
     * @param value Value to assign or evaluate.
     */
    static bool parameterValue(const PotentialObject2D &object,
                               TimePotentialParameter2D parameter,
                               double &value) noexcept;
 
    /**
     * @brief Performs periodic value.
     * @param config Configuration to apply.
     * @param time Simulation time in solver units.
     */
    static double periodicValue(const PeriodicPotentialDrive2DConfig &config,
                                double time) noexcept;
 
    /**
     * @brief Performs sweep value.
     * @param config Configuration to apply.
     * @param time Simulation time in solver units.
     */
    static double sweepValue(const LinearPotentialSweep2DConfig &config,
                             double time) noexcept;
 
    /**
     * @brief Performs sweep total duration.
     * @param config Configuration to apply.
     */
    static double sweepTotalDuration(const LinearPotentialSweep2DConfig &config) noexcept;
 
    /**
     * @brief Performs ramsey value.
     * @param config Configuration to apply.
     * @param time Simulation time in solver units.
     */
    static double ramseyValue(const RamseyPulseSequence2DConfig &config,
                              double time) noexcept;
 
    /**
     * @brief Performs ramsey total duration.
     * @param config Configuration to apply.
     */
    static double ramseyTotalDuration(const RamseyPulseSequence2DConfig &config) noexcept;
 
    /**
     * @brief Performs ramsey segment.
     * @param config Configuration to apply.
     * @param time Simulation time in solver units.
     * @param localPulseTime Time value expressed in the units documented by the calling component.
     */
    static RamseyPulseSegment2D ramseySegment(
        const RamseyPulseSequence2DConfig &config,
        double time,
        double *localPulseTime = nullptr) noexcept;
 
    // Rasterize the scene at a requested simulation time. For t < quenchTime
    // the configured beforeValue is used; for t >= quenchTime afterValue is
    // used. This makes reset/replay deterministic and also lets the solver use
    // the midpoint time of a split step when deciding whether the quench has
    // happened.
    /**
     * @brief Performs rasterize.
     * @param baseScene The base 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 QuantumQuench2DState rasterize(const PotentialScene2D &baseScene,
                                          const QuantumQuench2DConfig &config,
                                          double time,
                                          PotentialField2D &target);
 
    // Rasterize a sinusoidally driven scene without modifying baseScene.
    /**
     * @brief Performs rasterize periodic.
     * @param baseScene The base 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 PeriodicPotentialDrive2DState rasterizePeriodic(
        const PotentialScene2D &baseScene,
        const PeriodicPotentialDrive2DConfig &config,
        double time,
        PotentialField2D &target);
 
    /**
     * @brief Performs rasterize sweep.
     * @param baseScene The base 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 LinearPotentialSweep2DState rasterizeSweep(
        const PotentialScene2D &baseScene,
        const LinearPotentialSweep2DConfig &config,
        double time,
        PotentialField2D &target);
 
 
    /**
     * @brief Performs rasterize ramsey.
     * @param baseScene The base 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 RamseyPulseSequence2DState rasterizeRamsey(
        const PotentialScene2D &baseScene,
        const RamseyPulseSequence2DConfig &config,
        double time,
        PotentialField2D &target);
};
 
} // namespace qpe