driventwolevel2d.h

Go to the documentation of this file.

/**
 * @file driventwolevel2d.h
 * @brief Declares the driventwolevel2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/driventwolevel2d.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 <complex>
 
namespace qpe {
 
class ComplexField2D;
struct BoundStateSpectrum1D;
struct PeriodicPotentialDrive2DConfig;
 
/**
 * @brief Data structure used by the Driven Two Level Projection2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct DrivenTwoLevelProjection2D
{
    bool valid = false;
    std::complex<double> amplitudeA;
    std::complex<double> amplitudeB;
    double populationA = 0.0;
    double populationB = 0.0;
    double capturedPopulation = 0.0;
    double blochX = 0.0;
    double blochY = 0.0;
    double blochZ = 0.0;
};
 
/**
 * @brief Data structure used by the Driven Two Level Theory2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct DrivenTwoLevelTheory2D
{
    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 generalizedRabiAngularFrequency = 0.0;
    double maximumTransferProbability = 0.0;
    double firstMaximumTime = 0.0;
    double rabiPeriod = 0.0;
};
 
// Analysis helper for a periodically driven pair of stationary bound states.
// The full application still evolves psi(x,y) with the 2D split-step solver;
// this module only projects that field onto a selected stationary basis and
// provides the rotating-wave two-level reference curve.
/**
 * @brief Implements the Driven Two Level2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class DrivenTwoLevel2D
{
public:
    /**
     * @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 matrix element x.
     * @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 double matrixElementX(const BoundStateSpectrum1D &spectrum,
                                 int stateA = 0,
                                 int stateB = 1) noexcept;
 
    /**
     * @brief Performs analyze.
     * @param spectrum The spectrum value used by the operation.
     * @param drive The drive 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 DrivenTwoLevelTheory2D analyze(const BoundStateSpectrum1D &spectrum,
                                           const PeriodicPotentialDrive2DConfig &drive,
                                           int stateA = 0,
                                           int stateB = 1,
                                           double hbar = 1.0) noexcept;
 
    // RWA transition probability from A to B when the initial state is A.
    /**
     * @brief Performs reference population b.
     * @param theory The theory value used by the operation.
     * @param time Simulation time in solver units.
     */
    static double referencePopulationB(const DrivenTwoLevelTheory2D &theory,
                                       double time) noexcept;
};
 
} // namespace qpe