experimentdocument2d.h

Go to the documentation of this file.

/**
 * @file experimentdocument2d.h
 * @brief Declares the schema-28 experiment persistence document and JSON conversion API.
 * @ingroup qpe_experiments
 *
 * Source: @c core/experiments/experimentdocument2d.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 "core/quantum/timedependentpotential2d.h"
#include "core/quantum/ramseyinterferometry2d.h"
#include "core/quantum/quantumtalbot2d.h"
#include "core/quantum/quantumvortex2d.h"
#include "core/quantum/quantumanderson2d.h"
#include "core/quantum/quantumkickedrotor2d.h"
#include "core/quantum/quantumzeno2d.h"
#include "core/quantum/quantumscar2d.h"
#include "core/quantum/quantumberryphase2d.h"
#include "core/quantum/quantumloschmidt2d.h"
#include "core/quantum/quantummoshinsky2d.h"
#include "core/quantum/quantumkapitzadirac2d.h"
#include "core/quantum/quantumaharonovbohm2d.h"
#include "core/quantum/quantumlandau2d.h"
#include "core/quantum/quantumhalledge2d.h"
#include "core/quantum/quantumbackflow2d.h"
#include "core/quantum/quantumzitterbewegung2d.h"
#include "core/quantum/quantumkleintunneling2d.h"
 
#include <QMap>
#include <QString>
#include <QVariant>
 
class QJsonObject;
 
namespace qpe {
 
// Portable configuration document for a reproducible Quantum Phenomena Explorer
// experiment.  It intentionally stores controls/parameters, not the evolved
// wavefunction, sampled hits, detector accumulation or analysis history.
/**
 * @brief Serializable experiment document used by QPE schema 28.
 *
 * This type is the persistence boundary between GUI controls and saved experiment JSON. Parsing is intentionally strict enough to reject structurally incomplete documents instead of silently inventing simulation controls.
 */
struct ExperimentDocument2D
{
    static const int CurrentSchemaVersion = 28;
 
    int schemaVersion = CurrentSchemaVersion;
    QString name;
    QString sourcePreset;
    QMap<QString, QVariant> controls;
 
    // Step 15+: optional multi-object potential scene. Schema v1 documents do
    // not contain it. Schema v3 adds smooth analytic-object parameters while
    // remaining backward-compatible with schema v2 geometric scenes.
    bool potentialSceneActive = false;
    PotentialScene2D potentialScene;
 
    // Step 18: preparation is still a reproducible configuration, not an
    // evolved snapshot. Bound eigenstates are recomputed from V(x) on load.
    int initialPreparationMode = 0; // 0 Gaussian, 1 eigenstate, 2 superposition, 3 Talbot comb, 4 vortex, 5 Anderson dual lane, 6 kicked rotor, 7 quantum Zeno dual lane, 8 Berry first-excited doublet state, 9 Moshinsky shutter edge, 10 Kapitza-Dirac beam, 11 Aharonov-Bohm incident beam, 12 Landau magnetic state, 13 quantum Hall edge packet, 14 quantum backflow positive-momentum state, 15 Dirac/Zitterbewegung spinor state, 16 Dirac/Klein incident state
    int boundStateA = 0;
    int boundStateB = 3;
    double boundRelativePhaseDegrees = 90.0;
 
    // Step 19: configuration only. A collapse outcome itself is transient and
    // is never persisted as an evolved wavefunction snapshot.
    double collapseResolution = 0.65;
 
    // Step 21: deterministic recipe for a one-shot Hamiltonian quench.
    QuantumQuench2DConfig quench;
 
    // Step 22: deterministic sinusoidal drive recipe.
    PeriodicPotentialDrive2DConfig periodicDrive;
 
    // Step 24/25: deterministic finite linear sweep recipe. Schema 9 extends
    // it with an optional return leg and turnaround hold for Stueckelberg
    // interferometry.
    LinearPotentialSweep2DConfig linearSweep;
 
    // Step 26/27: deterministic Ramsey sequence, optionally with Hahn-echo pi pulse.
    RamseyPulseSequence2DConfig ramseySequence;
 
    // Step 28: analysis-only Gaussian static-detuning ensemble.
    RamseyEnsemble2DConfig ramseyEnsemble;
 
    // Step 32: reproducible periodic-comb initial preparation.
    QuantumTalbotInitialState2DConfig talbotInitialState;
 
    // Step 34: reproducible off-axis vortex initial preparation.
    QuantumVortexInitialState2DConfig vortexInitialState;
 
    // Step 35: reproducible equal two-lane Anderson comparison preparation.
    QuantumAndersonInitialState2DConfig andersonInitialState;
 
    // Step 36: reproducible kicked-rotor preparation and kick train.
    QuantumKickedRotor2DConfig kickedRotor;
    QuantumKickedRotorInitialState2DConfig kickedRotorInitialState;
 
    // Step 37: reproducible watched-escape preparation and measurement train.
    QuantumZeno2DConfig quantumZeno;
    QuantumZenoInitialState2DConfig quantumZenoInitialState;
 
    // Step 38: reproducible quantum-scar analysis settings.
    QuantumScarConfig2D quantumScar;
 
    // Step 39: reproducible geometric-phase loop settings.
    QuantumBerryLoop2DConfig quantumBerry;
 
    // Step 40: reproducible quantum time-reversal / Loschmidt-echo settings.
    QuantumLoschmidt2DConfig quantumLoschmidt;
 
    // Step 41: reproducible Moshinsky shutter preparation and release settings.
    QuantumMoshinskyInitialState2DConfig moshinskyInitialState;
    QuantumMoshinsky2DConfig quantumMoshinsky;
 
    // Step 42: reproducible Kapitza-Dirac beam and standing-wave pulse settings.
    QuantumKapitzaDiracInitialState2DConfig kapitzaDiracInitialState;
    QuantumKapitzaDirac2DConfig quantumKapitzaDirac;
 
    // Step 43: gauge-covariant Aharonov-Bohm flux tube.
    QuantumAharonovBohm2DConfig quantumAharonovBohm;
 
    // Step 44: uniform-B Landau/cyclotron configuration.
    QuantumLandau2DConfig quantumLandau;
 
    // Step 45: chiral quantum Hall edge configuration.
    QuantumHallEdge2DConfig quantumHallEdge;
 
    // Step 46: free positive-momentum quantum-backflow configuration.
    QuantumBackflow2DConfig quantumBackflow;
 
    // Step 47: free Dirac packet with optional positive-energy control projection.
    QuantumZitterbewegung2DConfig quantumZitterbewegung;
 
    // Step 48: Dirac Klein-tunneling scalar barrier.
    QuantumKleinTunneling2DConfig quantumKleinTunneling;
};
 
/**
 * @brief Implements the Experiment Document2D Json component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class ExperimentDocument2DJson
{
public:
    /**
     * @brief Performs format id.
     */
    static QString formatId();
 
    /**
     * @brief Performs to json.
     * @param document The document value used by the operation.
     */
    static QJsonObject toJson(const ExperimentDocument2D &document);
    /**
     * @brief Performs from json.
     * @param json The json value used by the operation.
     * @param document The document value used by the operation.
     * @param errorMessage The error message value used by the operation.
     */
    static bool fromJson(const QJsonObject &json,
                         ExperimentDocument2D &document,
                         QString &errorMessage);
 
    /**
     * @brief Saves file.
     * @param fileName Filesystem name/path.
     * @param document The document value used by the operation.
     * @param errorMessage The error message value used by the operation.
     */
    static bool saveFile(const QString &fileName,
                         const ExperimentDocument2D &document,
                         QString &errorMessage);
    /**
     * @brief Loads file.
     * @param fileName Filesystem name/path.
     * @param document The document value used by the operation.
     * @param errorMessage The error message value used by the operation.
     */
    static bool loadFile(const QString &fileName,
                         ExperimentDocument2D &document,
                         QString &errorMessage);
};
 
} // namespace qpe