boundstates1d.h

Go to the documentation of this file.

/**
 * @file boundstates1d.h
 * @brief Declares the boundstates1d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/boundstates1d.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 <cstddef>
#include <cstdint>
#include <string>
#include <vector>
 
namespace qpe {
 
class ComplexField2D;
class PotentialField2D;
 
/**
 * @brief Data structure used by the Bound State1D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct BoundState1D
{
    int quantumNumber = 0;
    double energy = 0.0;
    int nodeCount = 0;
    std::vector<float> amplitude;
};
 
/**
 * @brief Data structure used by the Bound State Spectrum1D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct BoundStateSpectrum1D
{
    bool valid = false;
    std::string message;
    double dx = 0.0;
    double mass = 1.0;
    double hbar = 1.0;
    double continuumThreshold = 0.0;
    std::uint64_t sourceSignature = 0;
    std::vector<double> x;
    std::vector<double> potential;
    std::vector<BoundState1D> states;
};
 
/**
 * @brief Configuration values for Bound State Solver1D Params.
 *
 * The structure groups parameters that are passed together so the associated numerical/analysis component can be configured reproducibly.
 */
struct BoundStateSolver1DParams
{
    double mass = 1.0;
    double hbar = 1.0;
    double imaginaryTimeStep = 0.02;
    int maxIterations = 2600;
    int maxStates = 5;
    double energyTolerance = 1.0e-10;
    double yInvarianceTolerance = 1.0e-5;
};
 
// Bound-state extractor for potentials that are (approximately) invariant in Y.
// The X eigenmodes are obtained by imaginary-time split-step evolution with a
// radix-2 spectral kinetic operator, followed by Gram-Schmidt deflation.
// This deliberately mirrors the real-time solver's spectral philosophy rather
// than introducing an unrelated textbook-only discretization.
/**
 * @brief Implements the Bound States1D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class BoundStates1D
{
public:
    /**
     * @brief Performs solve.
     * @param potential Potential field used by the operation.
     * @param params Parameter block to apply.
     */
    static BoundStateSpectrum1D solve(const PotentialField2D &potential,
                                      const BoundStateSolver1DParams &params);
 
    /**
     * @brief Returns whether y invariant.
     * @param potential Potential field used by the operation.
     * @param tolerance The tolerance value used by the operation.
     */
    static bool isYInvariant(const PotentialField2D &potential,
                             double tolerance = 1.0e-5) noexcept;
 
    /**
     * @brief Performs potential signature.
     * @param potential Potential field used by the operation.
     */
    static std::uint64_t potentialSignature(const PotentialField2D &potential) noexcept;
 
    /**
     * @brief Performs matches.
     * @param spectrum The spectrum value used by the operation.
     * @param potential Potential field used by the operation.
     * @param mass The mass value used by the operation.
     * @param hbar The hbar value used by the operation.
     */
    static bool matches(const BoundStateSpectrum1D &spectrum,
                        const PotentialField2D &potential,
                        double mass,
                        double hbar = 1.0) noexcept;
 
    /**
     * @brief Prepares eigenstate.
     * @param field Field data to read or modify.
     * @param spectrum The spectrum value used by the operation.
     * @param stateIndex Zero-based index used to select the requested item.
     */
    static bool prepareEigenstate(ComplexField2D &field,
                                  const BoundStateSpectrum1D &spectrum,
                                  int stateIndex);
 
    /**
     * @brief Prepares superposition.
     * @param field Field data to read or modify.
     * @param spectrum The spectrum value used by the operation.
     * @param stateIndexA The state index a value used by the operation.
     * @param stateIndexB The state index b value used by the operation.
     * @param relativePhaseRadians The relative phase radians value used by the operation.
     */
    static bool prepareSuperposition(ComplexField2D &field,
                                     const BoundStateSpectrum1D &spectrum,
                                     int stateIndexA,
                                     int stateIndexB,
                                     double relativePhaseRadians = 0.0);
};
 
} // namespace qpe