quantumloschmidt2d.h

Go to the documentation of this file.

/**
 * @file quantumloschmidt2d.h
 * @brief Declares the quantumloschmidt2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/quantumloschmidt2d.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/math/complexfield2d.h"
 
#include <cstddef>
#include <vector>
 
namespace qpe {
 
// Step 40: one-shot time reversal for a scalar wavefunction evolving under a
// real, time-independent Hamiltonian.  At reversalTime the anti-unitary time
// reversal operation reduces to complex conjugation, psi -> psi*.  Optional
// delta-p terms deliberately make the reversal imperfect by applying a small
// additional momentum kick immediately after conjugation.
/**
 * @brief Configuration values for Quantum Loschmidt2D Config.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct QuantumLoschmidt2DConfig
{
    bool enabled = false;
    double reversalTime = 4.0;
    double momentumErrorX = 0.0;
    double momentumErrorY = 0.0;
};
 
/**
 * @brief Data structure used by the Quantum Loschmidt Sample2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct QuantumLoschmidtSample2D
{
    double time = 0.0;
    double meanX = 0.0;
    double meanY = 0.0;
    double densityEcho = 0.0;     // phase-insensitive Bhattacharyya fidelity
    double stateEcho = 0.0;       // |<psi0*|psi(t)>|^2, normalized
    double norm = 0.0;
    bool reversalApplied = false;
};
 
/**
 * @brief Implements the Quantum Loschmidt Echo2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumLoschmidtEcho2D
{
public:
    /**
     * @brief Validates config.
     * @param config Configuration to apply.
     * @param reason The reason value used by the operation.
     */
    static bool validateConfig(const QuantumLoschmidt2DConfig &config,
                               const char **reason = nullptr) noexcept;
 
    // Applies T psi = psi* followed by an optional deterministic momentum
    // mismatch exp[i(delta_px x + delta_py y)/hbar].  The field is renormalized
    // only defensively; the operation itself is norm-preserving.
    /**
     * @brief Applies time reversal.
     * @param field Field data to read or modify.
     * @param config Configuration to apply.
     * @param hbar The hbar value used by the operation.
     */
    static bool applyTimeReversal(ComplexField2D &field,
                                  const QuantumLoschmidt2DConfig &config,
                                  double hbar) noexcept;
 
    /**
     * @brief Performs state echo fidelity.
     * @param reference The reference value used by the operation.
     * @param field Field data to read or modify.
     */
    static double stateEchoFidelity(const ComplexField2D &reference,
                                    const ComplexField2D &field) noexcept;
 
    /**
     * @brief Performs density echo fidelity.
     * @param reference The reference value used by the operation.
     * @param field Field data to read or modify.
     */
    static double densityEchoFidelity(const ComplexField2D &reference,
                                      const ComplexField2D &field) noexcept;
 
    /**
     * @brief Performs centroid.
     * @param field Field data to read or modify.
     * @param meanX The mean x value used by the operation.
     * @param meanY The mean y value used by the operation.
     */
    static bool centroid(const ComplexField2D &field,
                         double &meanX,
                         double &meanY) noexcept;
};
 
/**
 * @brief Implements the Quantum Loschmidt History2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class QuantumLoschmidtHistory2D
{
public:
    /**
     * @brief Constructs a Quantum Loschmidt History 2D instance.
     * @param maximumSamples The maximum samples value used by the operation.
     */
    explicit QuantumLoschmidtHistory2D(std::size_t maximumSamples = 1600u);
 
    /**
     * @brief Clears stored state and returns the component to its empty/default state.
     */
    void clear() noexcept;
    /**
     * @brief Returns configure.
     * @param reference The reference value used by the operation.
     * @param config Configuration to apply.
     */
    bool configure(const ComplexField2D &reference,
                   const QuantumLoschmidt2DConfig &config);
    /**
     * @brief Carries out append.
     * @param time Simulation time in solver units.
     * @param field Field data to read or modify.
     * @param reversalApplied The reversal applied value used by the operation.
     */
    bool append(double time,
                const ComplexField2D &field,
                bool reversalApplied);
 
    /**
     * @brief Returns configured.
     */
    bool configured() const noexcept { return configured_; }
    /**
     * @brief Returns whether the object contains no data.
     * @param empty The empty value used by the operation.
     */
    bool empty() const noexcept { return samples_.empty(); }
    /**
     * @brief Returns config.
     */
    const QuantumLoschmidt2DConfig &config() const noexcept { return config_; }
    /**
     * @brief Samples s.
     */
    const std::vector<QuantumLoschmidtSample2D> &samples() const noexcept { return samples_; }
 
private:
    /**
     * @brief Carries out trim to limit.
     */
    void trimToLimit();
 
    std::size_t maximumSamples_ = 1600u;
    bool configured_ = false;
    ComplexField2D reference_;
    QuantumLoschmidt2DConfig config_;
    std::vector<QuantumLoschmidtSample2D> samples_;
};
 
} // namespace qpe