functions.py

# psi_solve2/functions.py

import numpy as np
import matplotlib.pyplot as plt

import math 
from matplotlib.ticker import MultipleLocator 

# ==========================================
# 1. PHYSICS CONSTANTS
# ==========================================
hbar = 1
m = 1
L = 50
N_GRID = 2000
global Last_k_value # Used by harmonic() and check_harmonic_analytic()

# ==========================================
# 2. GRID FUNCTIONS
# ==========================================
def make_grid(L=L, N=N_GRID):
    """

    Create a spatial grid for solving the Schrödinger equation.

    

    Parameters

    ----------

    L : float, optional

        Total length of the spatial domain (default: 50 a.u.)

    N : int, optional

        Number of internal grid points (default: 2000)

    

    Returns

    -------

    x_full : ndarray

        Full grid with N+2 points from -L/2 to L/2, including boundary points

    dx : float

        Grid spacing (distance between adjacent points)

    x_internal : ndarray

        Internal grid points (N points) where the wavefunction is solved

        Excludes the boundary points at x[0] and x[-1]

    

    Notes

    -----

    The boundary points are used to enforce boundary conditions (typically ψ=0)

    while x_internal contains the points where we actually solve for ψ.

    

    Examples

    --------

    >>> x, dx, x_int = make_grid(L=20, N=1000)

    >>> print(f"Domain: [{x[0]:.1f}, {x[-1]:.1f}], spacing: {dx:.4f}")

    Domain: [-10.0, 10.0], spacing: 0.0200

    """
    x = np.linspace(-L/2, L/2, N+2)
    dx = x[1] - x[0]
    x_internal = x[1:-1]
    return x, dx, x_internal

# ==========================================
# 3. POTENTIAL GENERATORS (V(x))
# ==========================================
def constant(x, c):
    """

    Create a constant potential across the entire domain.

    

    Parameters

    ----------

    x : ndarray

        Spatial grid points

    c : float

        Constant potential value (in Hartree atomic units)

    

    Returns

    -------

    V : ndarray

        Constant potential array of same shape as x, with value c everywhere

    

    Examples

    --------

    >>> x = np.linspace(-10, 10, 100)

    >>> V = constant(x, 5.0)  # V(x) = 5.0 everywhere

    """
    return np.ones_like(x) * c

def harmonic(x, k, center=0.0):
    """

    Create a harmonic oscillator (parabolic) potential.

    

    Generates V(x) = (1/2)k(x - center)² representing a quantum harmonic

    oscillator potential centered at the specified position.

    

    Parameters

    ----------

    x : ndarray

        Spatial grid points

    k : float

        Spring constant (curvature parameter) in atomic units

        Larger k → stiffer spring → more tightly bound states

    center : float, optional

        Center position of the parabola (default: 0.0)

    

    Returns

    -------

    V : ndarray

        Harmonic potential array: V(x) = 0.5 * k * (x - center)²

    

    Notes

    -----

    - Sets global variable Last_k_value for use by check_harmonic_analytic()

    - Energy levels: E_n = ℏω(n + 1/2) where ω = √(k/m)

    - In atomic units (ℏ=1, m=1): ω = √k

    

    Examples

    --------

    >>> x = np.linspace(-10, 10, 1000)

    >>> V = harmonic(x, k=1.0, center=0.0)  # Standard QHO

    >>> V_stiff = harmonic(x, k=10.0, center=0.0)  # Stiffer spring

    >>> V_offset = harmonic(x, k=1.0, center=5.0)  # Centered at x=5

    """
    global Last_k_value
    Last_k_value = k
    
    constant_factor = 1 
    potential = 0.5 * k * (x - center)**2
    return constant_factor * potential

def gaussian_well(x, center=0.0, width=1.0, depth=50): 
    """

    Create a Gaussian-shaped potential well.

    

    Generates a smooth, bell-shaped potential dip that can trap particles.

    

    Parameters

    ----------

    x : ndarray

        Spatial grid points

    center : float, optional

        Center position of the well (default: 0.0)

    width : float, optional

        Width parameter (standard deviation) of the Gaussian (default: 1.0)

        Larger width → broader well

    depth : float, optional

        Depth of the well at the center (default: 50)

        Positive depth creates a well (attractive potential)

    

    Returns

    -------

    V : ndarray

        Gaussian well potential: V(x) = -depth * exp(-(x-center)²/(2*width²))

    

    Notes

    -----

    - Minimum potential is -depth at x = center

    - Potential approaches 0 as |x - center| → ∞

    - Smooth potential (infinitely differentiable)

    

    Examples

    --------

    >>> x = np.linspace(-10, 10, 1000)

    >>> V = gaussian_well(x, center=0, width=2.0, depth=10)

    """
    return -depth * np.exp(-(x - center)**2 / (2 * width**2))

def inf_sqaure_well(x, lower_bound, upper_bound):
    """

    Create an infinite square well (particle in a box) potential.

    

    Parameters

    ----------

    x : ndarray

        Spatial grid points

    lower_bound : float

        Left boundary of the well

    upper_bound : float

        Right boundary of the well

    

    Returns

    -------

    V : ndarray

        Infinite square well potential:

        - V(x) = 0 for lower_bound ≤ x ≤ upper_bound (inside well)

        - V(x) = 10¹⁰ for x < lower_bound or x > upper_bound (outside well)

    

    Notes

    -----

    - Uses penalty method: "infinite" walls are approximated by very large

      potential (10¹⁰) to enforce ψ ≈ 0 outside the well

    - Well width: L = upper_bound - lower_bound

    - Analytical energies: E_n = (ℏ²π²n²)/(2mL²) for n = 1, 2, 3, ...

    

    Examples

    --------

    >>> x = np.linspace(-15, 15, 1000)

    >>> V = inf_sqaure_well(x, lower_bound=-10, upper_bound=10)  # L = 20

    >>> # Use with check_ISW_analytic(E, lower_bound=-10, upper_bound=10)

    """
    HUGE_NUMBER = 1e10
    V = np.zeros_like(x) 
    V[x < lower_bound] = HUGE_NUMBER
    V[x > upper_bound] = HUGE_NUMBER
    return V

def inf_wall(x, side, bound):
    """

    Place an infinite potential wall on one side of the domain.

    

    Parameters

    ----------

    x : ndarray

        Spatial grid points

    side : str

        Which side to place the wall: 'left' or 'right'

        (case-insensitive, strips whitespace and punctuation)

    bound : float

        Position of the wall boundary

    

    Returns

    -------

    V : ndarray

        Potential with infinite wall:

        - If side='left': V(x) = 10¹⁰ for x < bound, V(x) = 0 for x ≥ bound

        - If side='right': V(x) = 10¹⁰ for x > bound, V(x) = 0 for x ≤ bound

    

    Notes

    -----

    Uses penalty method with V = 9×10¹⁰ to approximate infinite potential.

    

    Examples

    --------

    >>> x = np.linspace(-10, 10, 1000)

    >>> V_left = inf_wall(x, 'left', bound=-5)  # Wall at x=-5, blocks left side

    >>> V_right = inf_wall(x, 'right', bound=5)  # Wall at x=5, blocks right side

    """
    V = np.zeros_like(x)
    HUGE_NUMBER = 9e10 
    side = side.strip(', . ').lower() 

    if side == 'left':
        V[x < bound] = HUGE_NUMBER
    elif side == 'right':
        V[x > bound] = HUGE_NUMBER
    return V

def finite_barrier(x, center, width, height):
    """

    Create a finite rectangular potential barrier.

    

    Parameters

    ----------

    x : ndarray

        Spatial grid points

    center : float

        Center position of the barrier

    width : float

        Total width of the barrier

    height : float

        Height of the potential barrier

    

    Returns

    -------

    V : ndarray

        Rectangular barrier potential:

        - V(x) = height for |x - center| < width/2

        - V(x) = 0 elsewhere

    

    Notes

    -----

    Useful for studying quantum tunneling phenomena. Particles with E < height

    can tunnel through the barrier with exponentially decaying probability.

    

    Examples

    --------

    >>> x = np.linspace(-10, 10, 1000)

    >>> V = finite_barrier(x, center=0, width=2, height=5)  # Barrier from x=-1 to x=1

    """
    V = np.zeros_like(x)
    mask = (x > (center - width/2)) & (x < (center + width/2))
    V[mask] = height
    return V

def V_double_well(x, depth=20, separation=1, center=0.0):
    """

    Create a quartic double-well potential.

    

    Generates V(x) = depth × ((x-center)² - separation)² which has two minima

    separated by a central barrier.

    

    Parameters

    ----------

    x : ndarray

        Spatial grid points

    depth : float, optional

        Depth parameter controlling overall potential strength (default: 20)

    separation : float, optional

        Controls the distance between the two wells (default: 1)

        Well minima are approximately at x = center ± separation

    center : float, optional

        Center position of the double well system (default: 0.0)

    

    Returns

    -------

    V : ndarray

        Double well potential: V(x) = depth × ((x-center)² - separation)²

    

    Notes

    -----

    - Creates symmetric double well with barrier at x = center

    - Useful for studying tunneling splitting and symmetric/antisymmetric states

    - Ground state and first excited state form tunneling doublet

    

    Examples

    --------

    >>> x = np.linspace(-5, 5, 1000)

    >>> V = V_double_well(x, depth=2, separation=1, center=0)

    """
    V = depth * ((x - center)**2 - separation)**2
    return V

def custom2(value,x):
    """Helper function from the notebook."""
    return value * np.ones_like(x)

# In psi_solve2/functions.py

def finite_square_well(x, lower_bound, upper_bound, depth_V):
    """

    Create a finite square well potential.

    

    The potential is zero inside the well and has finite height depth_V outside.

    Unlike the infinite square well, particles can exist in the barrier region

    with exponentially decaying wavefunctions.

    

    Parameters

    ----------

    x : ndarray

        Spatial grid points

    lower_bound : float

        Left boundary of the well

    upper_bound : float

        Right boundary of the well

    depth_V : float

        Height of the potential barriers outside the well (V₀)

    

    Returns

    -------

    V : ndarray

        Finite square well potential:

        - V(x) = 0 for lower_bound ≤ x ≤ upper_bound (inside well)

        - V(x) = depth_V for x < lower_bound or x > upper_bound (barrier regions)

    

    """
    """    

    Notes

    -----

    - Bound states exist only when E < depth_V

    - Number of bound states depends on well width and depth_V

    - For bound states, wavefunction decays exponentially in barrier (E < V)

    - For scattering states (E > depth_V), wavefunction oscillates everywhere

    - Use check_finite_well_analytic() to verify numerical results

    

    Examples

    --------

    >>> x = np.linspace(-15, 15, 1000)

    >>> V_deep = finite_square_well(x, -10, 10, depth_V=2.0)  # Deep well, many bound states

    >>> V_shallow = finite_square_well(x, -10, 10, depth_V=0.01)  # Shallow, few/no bound states

    """
    # Start with a baseline of zero potential
    V = np.zeros_like(x) 
    
    # The walls outside the well are set to the height/depth V_0
    V[x < lower_bound] = depth_V
    V[x > upper_bound] = depth_V
    
    # The potential *inside* the well remains V=0 (or whatever you set the baseline to)
    return V

# ==========================================
# 4. SCHRÖDINGER EQUATION SOLVER
# ==========================================
def kinetic_operator(N, dx, hbar=hbar, m=m):
    """

    Build the kinetic energy operator matrix using finite difference method.

    

    Constructs the discrete representation of the kinetic energy operator

    T = -(ℏ²/2m) d²/dx² using a 3-point central difference stencil.

    

    Parameters

    ----------

    N : int

        Number of internal grid points (size of the matrix)

    dx : float

        Grid spacing (distance between adjacent points)

    hbar : float, optional

        Reduced Planck constant (default: 1.0 in atomic units)

    m : float, optional

        Particle mass (default: 1.0 in atomic units)

    

    Returns

    -------

    T : ndarray, shape (N, N)

        Kinetic energy operator matrix (symmetric, tridiagonal)

        - Diagonal elements: -(ℏ²/2m) × (-2/dx²)

        - Off-diagonal elements: -(ℏ²/2m) × (1/dx²)

    

    """
    """    

    Notes

    -----

    The second derivative is approximated using central differences:

        d²ψ/dx² ≈ (ψ_{i+1} - 2ψ_i + ψ_{i-1}) / dx²

    

    This creates a tridiagonal matrix:

        - Main diagonal: -2/dx²

        - Upper/lower diagonals: +1/dx²

    

    The kinetic energy operator is then: T = -(ℏ²/2m) × D2

    

    Examples

    --------

    >>> N = 1000

    >>> dx = 0.025

    >>> T = kinetic_operator(N, dx)

    >>> print(f"Matrix shape: {T.shape}, Symmetric: {np.allclose(T, T.T)}")

    Matrix shape: (1000, 1000), Symmetric: True

    """
    main_diagonal = (1/dx**2) * np.diag(-2 * np.ones(N))
    off_diagonal1 = (1/dx**2) * np.diag(np.ones(N-1), -1)
    off_diagonal2 = (1/dx**2) * np.diag(np.ones(N-1), 1)
    D2 = (main_diagonal + off_diagonal1 + off_diagonal2)

    T = (-(hbar**2 / (2*m)) * D2)
    return T

def solve(T, V_full, dx):
    """

    Solve the time-independent Schrödinger equation for eigenvalues and eigenvectors.

    

    Solves the eigenvalue problem Hψ = Eψ where H = T + V is the Hamiltonian.

    Returns normalized eigenstates sorted by energy.

    

    Parameters

    ----------

    T : ndarray, shape (N, N)

        Kinetic energy operator matrix from kinetic_operator()

    V_full : ndarray, shape (N+2,)

        Full potential array including boundary points

        V_full[0] and V_full[-1] are boundary values (typically very large)

        V_full[1:-1] are the internal potential values

    dx : float

        Grid spacing used for normalization

    

    Returns

    -------

    E : ndarray, shape (N,)

        Eigenvalues (energy levels) sorted in ascending order

        Units: Hartree (atomic units)

    psi : ndarray, shape (N, N)

        Eigenvectors (wavefunctions) as columns

        psi[:, i] is the wavefunction for energy E[i]

        Each wavefunction is normalized: ∫|ψ|² dx = 1

    

    """
    """    

    Notes

    -----

    - Uses np.linalg.eigh() which assumes Hermitian matrix (guaranteed for H)

    - Automatically sorts eigenvalues and eigenvectors by energy

    - Normalizes each eigenstate using trapezoidal rule: ∫|ψ|² dx = 1

    - Boundary conditions are enforced by V_full having large values at edges

    

    The Hamiltonian is constructed as:

        H = T + diag(V_internal)

    where V_internal = V_full[1:-1]

    

    Examples

    --------

    >>> # Setup

    >>> x, dx, x_int = make_grid(L=20, N=1000)

    >>> T = kinetic_operator(len(x_int), dx)

    >>> 

    >>> # Create infinite square well

    >>> V = inf_sqaure_well(x_int, -10, 10)

    >>> V_full = np.pad(V, (1,1), constant_values=1e10)

    >>> 

    >>> # Solve

    >>> E, psi = solve(T, V_full, dx)

    >>> print(f"Ground state energy: {E[0]:.6f} Ha")

    >>> 

    >>> # Verify normalization

    >>> norm = np.sum(psi[:, 0]**2) * dx

    >>> print(f"Normalization: {norm:.6f}")  # Should be 1.0

    """
    V_internal = V_full[1:-1]
    H = T + np.diag(V_internal)

    E, psi = np.linalg.eigh(H) 

    # Normalize each state individually
    for i in range(psi.shape[1]):
        # sum( |psi|^2 * dx )
        norm_factor = np.sum(psi[:, i]**2) * dx
        # Divide by the square root of the integral
        psi[:, i] = psi[:, i] / np.sqrt(norm_factor)

    return E, psi

# ==========================================
# 5. PLOTTING FUNCTIONS (STREAMLIT/JUPYTER SAFE)
# ==========================================
def plot_V(V_raw_input):
    """

    Plot a 1D potential profile.

    

    Creates a simple matplotlib figure showing the potential energy landscape.

    

    Parameters

    ----------

    V_raw_input : ndarray or None

        1D array representing the potential V(x)

        If None or scalar, returns None

    

    Returns

    -------

    fig : matplotlib.figure.Figure or None

        Figure object containing the potential plot

        Returns None if input is invalid

    """
    """    

    Notes

    -----

    - Uses dark background style

    - Cyan color for potential curve

    - Useful for quick visualization of potential shapes

    

    Examples

    --------

    >>> x = np.linspace(-10, 10, 1000)

    >>> V = harmonic(x, k=1.0)

    >>> fig = plot_V(V)

    >>> plt.show()

    """
    if V_raw_input is None or np.ndim(V_raw_input) == 0:
        return None

    plt.style.use("dark_background")
    fig, ax = plt.subplots(figsize=(6, 2))
    ax.plot(V_raw_input, lw=1.5, color="cyan")
    ax.set_title("Potential Input")
    ax.set_xlabel("Grid index")
    ax.set_ylabel("Potential")
    fig.tight_layout()
    return fig


def plot_alive(E, psi, V, x, no=1, nos=5, mode=''):
    """

    Plot wavefunctions as probability densities with separate energy and probability axes.

    

    Creates a physically accurate plot showing:

    - Potential V(x) and energy levels on left y-axis

    - Probability densities |ψ|² on right y-axis (separate scale)

    - Color-synchronized between probability curves and energy levels

    

    Parameters

    ----------

    E : ndarray

        Energy eigenvalues (in Hartree)

    psi : ndarray, shape (N, M)

        Wavefunction array where psi[:, i] is the i-th eigenstate

    V : ndarray, shape (N+2,)

        Full potential array including boundaries

    x : ndarray, shape (N+2,)

        Full spatial grid including boundaries

    no : int, optional

        State index to plot if mode != 'all' (default: 1)

    nos : int, optional

        Number of states to plot if mode == 'all' (default: 5)

    mode : str, optional

        Plot mode:

        - 'all': Plot multiple states (first nos states)

        - '': Plot single state (state no)

        Default: '' (single state)

    

    Returns

    -------

    fig : matplotlib.figure.Figure

        Figure object with dual y-axes

        - ax1 (left): Energy/Potential scale

        - ax2 (right): Probability density scale

    

    Notes

    -----

    - Uses dark background theme

    - Probability densities are plotted as |ψ|², not ψ

    - Each state has matching colors for its probability curve and energy level

    - Regions where V > 10⁵ are hidden (infinite walls)

    

    """
    """    

    Examples

    --------

    >>> # Plot first 5 states

    >>> fig = plot_alive(E, psi, V_full, x_full, nos=5, mode='all')

    >>> plt.show()

    >>> 

    >>> # Plot only ground state

    >>> fig = plot_alive(E, psi, V_full, x_full, no=0)

    >>> plt.show()

    """
    import matplotlib.pyplot as plt
    
    plt.style.use("dark_background")
    fig, ax1 = plt.subplots(figsize=(10, 6))
    
    ax2 = ax1.twinx()  # Right axis for probability
    
    states = min(nos, len(E))
    x_solver = x[1:-1]
    V_internal = V[1:-1]

    # --- Plot Potential ---
    ax1.plot(x, V, color="white", lw=2, label="V(x)", alpha=0.7)

    # --- Plot wavefunctions ---
    if mode == 'all':
        for n in range(states):
            # 1. Get the synchronized color for this state
            color = plt.colormaps["tab20"].colors[n % 20]
            
            psi_n_sq = psi[:, n]**2
            
            # 2. Plot probability density on ax2 with the chosen color
            ax2.plot(
                x_solver, psi_n_sq,
                label=rf"$|\psi_{n}|^2$ (E={E[n]:.2f})",
                lw=1.2,
                color=color # <-- EXPLICIT COLOR SET
            )
            
            # 3. Plot energy line on ax1 with the same color
            ax1.axhline(E[n], linestyle="--", lw=0.8, alpha=0.5, color=color) # <-- EXPLICIT COLOR SET
    else:
        # For single state mode, we still need a color. Use 'no' as the index.
        n = no
        color = plt.colormaps["tab20"].colors[n % 20]

        psi_n_sq = psi[:, n]**2
        
        # Plot probability density on ax2 with the chosen color
        ax2.plot(
            x_solver, psi_n_sq,
            label=rf"$|\psi_{no}|^2$ (E={E[no]:.2f})",
            lw=1.2,
            color=color # <-- EXPLICIT COLOR SET
        )
        
        # Plot energy line on ax1 with the same color
        ax1.axhline(E[no], linestyle="--", lw=0.8, alpha=0.5, color=color) # <-- EXPLICIT COLOR SET
        
    # Formatting
    ax1.set_xlabel("x [a.u.]")
    ax1.set_ylabel("Energy / V(x)")
    ax2.set_ylabel(r"Probability Density $|\psi|^2$")

    ax1.set_title("Physically Accurate Eigenstates and Potential")

    # The fig.legend() might show the color/style of the *last* plot line. 
    # For robust legend handling with twinx, you often need to combine the handles.
    h1, l1 = ax1.get_legend_handles_labels()
    h2, l2 = ax2.get_legend_handles_labels()
    ax1.legend(h1+h2, l1+l2, loc="upper right", fontsize=8) # <-- Improved Legend
    
    plt.tight_layout()
    return fig

def plot_dead(E, psi, V, x, nos=5):
    """Textbook: wavefunctions vertically shifted by energy."""
    plt.style.use("dark_background")
    fig, (ax_main, ax_bar) = plt.subplots(
        1, 2, figsize=(10, 7), gridspec_kw={"width_ratios": [5, 1]}
    )
    fig.subplots_adjust(bottom=0.2, wspace=0.4)

    states = min(nos, len(E))
    x_solver = x[1:-1]
    V_internal = V[1:-1]

    if states <= 0:
        return fig

    scale = (E[1] - E[0]) * 0.4 if states > 1 else max(E[0] * 0.1, 0.5)
    max_E = E[states - 1]
    window_height = max_E * 1.5

    # Plot shifted wavefunctions
    for n in range(states):
        psi_n = psi[:, n]
        maxabs = np.max(np.abs(psi_n))
        psi_norm = psi_n / (maxabs if maxabs != 0 else 1)
        y = psi_norm * scale + E[n]
        y[V_internal > 1e5] = np.nan  # hide where potential is infinite

        color = plt.colormaps["tab20"].colors[n % 20]
        ax_main.plot(x_solver, y, lw=1.3, color=color, label=f"n={n+1}, E={E[n]:.2f}")

    # Plot potential
    V_clip = np.clip(V, 0, window_height)
    ax_main.plot(x, V_clip, color="white", lw=2, label="V(x)")

    ax_main.set_title("Eigenstates + Potential")
    ax_main.set_xlabel("x [a.u.]")
    ax_main.set_ylabel("Energy / ψ")
    ax_main.set_ylim(0, max_E * 1.2)
    ax_main.legend(fontsize=8)

    # Energy levels
    ax_bar.set_title("Energy Spectrum")
    ax_bar.set_xticks([])
    ax_bar.set_ylim(0, np.max(E[:states]) * 1.1)
    for n in range(states):
        ax_bar.axhline(E[n], lw=1, color=plt.colormaps["tab20"].colors[n % 20])

    return fig


# ==========================================
# 6. BENCHMARKING FUNCTIONS
# ==========================================
def check_ortho(psi, dx, num_states_to_check=20):
    """

    Checks the orthonormality of the first 'num_states_to_check' wave functions.

    """
    N_CHECK = min(psi.shape[1], num_states_to_check) 
    overlap_matrix = np.zeros((N_CHECK, N_CHECK))

    for i in range(N_CHECK):
        for j in range(N_CHECK):
            # Riemann Sum: integral(psi_i * psi_j) dx
            Rsum = np.sum(psi[:, i] * psi[:, j]) * dx
            overlap_matrix[i, j] = Rsum

    print(f"\n--- Orthonormality Check (First {N_CHECK} states) ---")
    print("Overlap Matrix should approximate the Identity Matrix:")
    return overlap_matrix

def show_matrix(overlap_matrix,how='normal',round_value=10):
    '''

    how = normal, round , plot

    '''
    if how == 'normal':      
        print(overlap_matrix[:3])
    elif how == 'round':
        print(np.round(overlap_matrix, round_value))
    elif how == 'plot':
        plt.figure(figsize=(6,5))
        plt.imshow(overlap_matrix, cmap='coolwarm', origin='lower')
        plt.colorbar(label="Overlap Value")
        plt.title("Orthonormality Check Matrix")
        plt.xlabel("State Index m")
        plt.ylabel("State Index n")
        plt.gca().invert_yaxis()
        plt.locator_params(axis='y', integer=True)
        plt.locator_params(axis='x', integer=True)
        plt.show()

def check_ISW_analytic(E, lower_bound=-10, upper_bound=10, hbar=1.0, m=1.0, max_levels=6):
    """

    Compares numerical energies to the Infinite Square Well analytic formula.

    

    Parameters:

    -----------

    E : array

        Numerical eigenvalues

    lower_bound : float

        Lower boundary of the well (default: -10)

    upper_bound : float

        Upper boundary of the well (default: 10)

    hbar : float

        Reduced Planck constant (default: 1.0)

    m : float

        Particle mass (default: 1.0)

    max_levels : int

        Number of levels to check (default: 6)



    """
    """            

    Example:

    --------

    check_ISW_analytic(E, lower_bound=-10, upper_bound=10)

    """
    L = upper_bound - lower_bound  # Well width
    CHECK_N = min(max_levels, len(E))
    E_numerical = E[:CHECK_N]
    E_analytic = np.zeros(CHECK_N)

    for i in range(CHECK_N):
        n = i + 1 
        E_analytic[i] = (hbar**2 * np.pi**2 * n**2) / (2*m*L**2)

    print("\n### ENERGY BENCHMARK: Infinite Square Well ###")
    print(f"Well boundaries: x = [{lower_bound}, {upper_bound}], Width L = {L}")
    print("-" * 55)
    print(f"| n | Analytic E | Numerical E | % Error |")
    print("-" * 55)

    for i in range(CHECK_N):
        percent_error = np.abs((E_numerical[i] - E_analytic[i]) / E_analytic[i]) * 100
        print(
            f"| {i+1:<1} | {E_analytic[i]:<10.6f} | {E_numerical[i]:<11.6f} | {percent_error:<7.4f}% |"
        )
    print("-" * 55)
    
    return E_analytic, E_numerical

def check_harmonic_analytic(E, k=None, center=0.0, hbar=1.0, m=1.0, max_levels=6):
    """

    Compares numerical energies to the Harmonic Oscillator analytic formula.

    

    Parameters:

    -----------

    E : array

        Numerical eigenvalues

    k : float, optional

        Spring constant. If None, uses Last_k_value global variable

    center : float

        Center position of the harmonic oscillator (default: 0.0)

    hbar : float

        Reduced Planck constant (default: 1.0)

    m : float

        Particle mass (default: 1.0)

    max_levels : int

        Number of levels to check (default: 6)

    

    Example:

    --------

    check_harmonic_analytic(E, k=10, center=0)

    """
    CHECK_N = min(max_levels, len(E))
    
    try: 
        # Use provided k or fall back to global Last_k_value
        if k is None:
            k = Last_k_value 
            if k is None:
                print("ERROR: k is not set. Please provide k parameter or run harmonic() first.")
                return
        
        w = np.sqrt(k/m)
        E_numerical = E[:CHECK_N]
        E_analytic = np.zeros(CHECK_N)

        for i in range(CHECK_N):
            n_quantum = i 
            E_analytic[i] = (n_quantum + 0.5) * hbar * w

        print("\n### ENERGY BENCHMARK: Harmonic Oscillator ###")
        print(f"Spring constant k = {k}, Center = {center}, omega = {w:.4f}")
        print("-" * 55)
        print(f"| n | Analytic E | Numerical E | % Error |") 
        print("-" * 55)

        for i in range(CHECK_N):
            n_label = i 
            percent_error = np.abs((E_numerical[i] - E_analytic[i]) / E_analytic[i]) * 100
            
            print(
                f"| {n_label:<1} | {E_analytic[i]:<10.6f} | {E_numerical[i]:<11.6f} | {percent_error:<7.4f}% |"
            )
        print("-" * 55)
        
        return E_analytic, E_numerical

    except Exception as e:
        print(f"Error in harmonic oscillator check: {e}")


def check_finite_well_analytic(E, V0, lower_bound=-10, upper_bound=10, hbar=1.0, m=1.0, max_levels=10):
    """

    Compares numerical energies to the Finite Square Well analytical solution.

    

    The finite square well has no simple closed-form solution, but bound state

    energies can be found by solving transcendental equations numerically.

    

    Parameters:

    -----------

    E : array

        Numerical eigenvalues from your solver

    V0 : float

        Barrier height (potential outside the well)

    lower_bound : float

        Lower boundary of the well (default: -10)

    upper_bound : float

        Upper boundary of the well (default: 10)

    hbar : float

        Reduced Planck constant (default: 1.0)

    m : float

        Particle mass (default: 1.0)

    max_levels : int

        Maximum number of levels to check (default: 10)

    

    Example:

    --------

    check_finite_well_analytic(E, V0=2.0, lower_bound=-10, upper_bound=10)

    """
    a = (upper_bound - lower_bound) / 2  # Half-width
    z0 = a * np.sqrt(2 * m * V0) / hbar  # Dimensionless parameter
    
    # Find analytical energies by solving transcendental equations
    E_analytic = []
    
    # Even parity states: z*tan(z) = sqrt(z0^2 - z^2)
    z_vals = np.linspace(0.01, z0 - 0.01, 10000)
    for n in range(max_levels):
        try:
            lhs = z_vals * np.tan(z_vals)
            rhs = np.sqrt(z0**2 - z_vals**2)
            diff = lhs - rhs
            
            # Find sign changes (crossings)
            for i in range(len(diff) - 1):
                if diff[i] * diff[i+1] < 0:
                    z = z_vals[i]
                    E_candidate = (hbar**2 * z**2) / (2 * m * a**2)
                    if E_candidate < V0 and not any(np.isclose(E_candidate, E_a, rtol=1e-3) for E_a in E_analytic):
                        E_analytic.append(E_candidate)
                        break
        except:
            pass
    
    # Odd parity states: -z*cot(z) = sqrt(z0^2 - z^2)
    for n in range(max_levels):
        try:
            lhs = -z_vals / np.tan(z_vals)
            rhs = np.sqrt(z0**2 - z_vals**2)
            diff = lhs - rhs
            
            for i in range(len(diff) - 1):
                if diff[i] * diff[i+1] < 0:
                    z = z_vals[i]
                    E_candidate = (hbar**2 * z**2) / (2 * m * a**2)
                    if E_candidate < V0 and not any(np.isclose(E_candidate, E_a, rtol=1e-3) for E_a in E_analytic):
                        E_analytic.append(E_candidate)
                        break
        except:
            pass
    
    E_analytic = sorted(E_analytic)
    
    # Filter numerical energies to only bound states
    E_numerical_bound = E[E < V0]
    
    CHECK_N = min(len(E_analytic), len(E_numerical_bound), max_levels)
    
    if CHECK_N == 0:
        print("\n### ENERGY BENCHMARK: Finite Square Well ###")
        print(f"Well: x in [{lower_bound}, {upper_bound}], V0 = {V0}, z0 = {z0:.4f}")
        print("WARNING: No bound states found!")
        print(f"  Barrier too shallow. Need V0 > {E[0]:.4f} to bind the ground state.")
        return None, None
    
    print("\n### ENERGY BENCHMARK: Finite Square Well ###")
    print(f"Well: x in [{lower_bound}, {upper_bound}], V0 = {V0}, z0 = {z0:.4f}")
    print(f"Number of bound states: {CHECK_N}")
    print("-" * 55)
    print(f"| n | Analytic E | Numerical E | % Error |")
    print("-" * 55)
    
    for i in range(CHECK_N):
        percent_error = np.abs((E_numerical_bound[i] - E_analytic[i]) / E_analytic[i]) * 100
        print(
            f"| {i:<1} | {E_analytic[i]:<10.6f} | {E_numerical_bound[i]:<11.6f} | {percent_error:<7.4f}% |"
        )
    print("-" * 55)
    
    return np.array(E_analytic[:CHECK_N]), E_numerical_bound[:CHECK_N]




##
# Verify

import sys

def run_comparison():
    """

    Cross-verification: Hand-wave solver vs QMSolve package.

    

    Compares results for:

    1. Double Well potential

    2. Harmonic Oscillator (debug test)

    

    Results saved to 'comparison_log.txt'

    

    Requires

    --------

    QMSolve package: pip install qmsolve

    

    Usage

    -----

    >>> from functions import run_comparison

    >>> run_comparison()

    """
    # Import qmsolve only when this function is called
    try:
        from qmsolve import Hamiltonian, SingleParticle, init_visualization
    except ImportError:
        print("Error: qmsolve not found. Please install it via 'pip install qmsolve'")
        return
    
    with open("comparison_log.txt", "w") as log_file:
        sys.stdout = log_file
        print("========================================")
        print("CROSS-VERIFICATION: Hand-wave vs QMSOLVE")
        print("========================================")

        # ---------------------------------------------------------
        # CASE: Double Well Potential
        # V(x) = depth * ( (x-center)**2 - separation )**2
        # ---------------------------------------------------------
        print("\n[TEST CASE] Double Well Potential")
        
        # Parameters
        L = 10.0
        N = 512 # QMSolve default is often 512 or similar, let's match
        depth = 2.0
        separation = 1.0
        center = 0.0
        m_particle = 1.0
        
        print(f"Parameters: L={L}, N={N}, depth={depth}, separation={separation}, m={m_particle}")

        # ---------------------------------------------------------
        # 1. Run Hand-wave solver
        # ---------------------------------------------------------
        print("\n--- Running Hand-wave Solver ---")
        x_full, dx, x_internal = make_grid(L=L, N=N)
        
        # Construct Potential using local V_double_well function
        V_internal = V_double_well(x_internal, depth=depth, separation=separation, center=center)
        
        # Pad for solver
        V_full = np.zeros_like(x_full)
        V_full[1:-1] = V_internal
        V_full[0] = 1e10
        V_full[-1] = 1e10
        
        T = kinetic_operator(N, dx, m=m_particle)
        E_handwave, psi_handwave = solve(T, V_full, dx)
        
        print(f"Hand-wave Energies (first 5): {E_handwave[:5]}")

        # ---------------------------------------------------------
        # 2. Run QMSolve
        # ---------------------------------------------------------
        print("\n--- Running QMSolve ---")
        
        # Define potential function for QMSolve
        def double_well(particle):
            x = particle.x
            return depth * ( (x - center)**2 - separation )**2

        # Setup QMSolve
        H = Hamiltonian(particles = SingleParticle(m = m_particle), 
                        potential = double_well, 
                        spatial_ndim = 1, N = N, extent = L)

        # Diagonalize
        eigenstates = H.solve(max_states = 10)
        E_qm_eV = eigenstates.energies
        
        # Convert QMSolve (eV) to Hartree
        # 1 Hartree = 27.211386 eV
        Hartree_to_eV = 27.211386
        E_qm = E_qm_eV / Hartree_to_eV

        print(f"QMSolve Energies (eV):      {E_qm_eV[:5]}")
        print(f"QMSolve Energies (Hartree): {E_qm[:5]}")

        # ---------------------------------------------------------
        # 3. Compare
        # ---------------------------------------------------------
        print("\n--- Comparison Results ---")
        print("-" * 65)
        print(f"| n | Hand-wave E  | QMSolve E    | Diff         | % Diff   |")
        print("-" * 65)
        
        for i in range(5):
            e1 = E_handwave[i]
            e2 = E_qm[i]
            diff = abs(e1 - e2)
            p_diff = (diff / e2) * 100 if e2 != 0 else 0.0
            
            print(f"| {i:<1} | {e1:<12.6f} | {e2:<12.6f} | {diff:<12.2e} | {p_diff:<7.4f}% |")
        print("-" * 65)
        
        # ---------------------------------------------------------
        # DEBUG CASE: Harmonic Oscillator
        # ---------------------------------------------------------
        print("\n[DEBUG CASE] Harmonic Oscillator (k=1)")
        k_debug = 1.0
        
        # Hand-wave solver
        V_internal_HO = 0.5 * k_debug * x_internal**2
        V_full_HO = np.zeros_like(x_full)
        V_full_HO[1:-1] = V_internal_HO
        V_full_HO[0] = 1e10
        V_full_HO[-1] = 1e10
        
        E_handwave_HO, _ = solve(T, V_full_HO, dx)
        print(f"Hand-wave HO Energies: {E_handwave_HO[:5]}")
        
        # QMSolve
        def harmonic_potential(particle):
            return 0.5 * k_debug * particle.x**2
            
        H_HO = Hamiltonian(particles = SingleParticle(m = m_particle), 
                        potential = harmonic_potential, 
                        spatial_ndim = 1, N = N, extent = L)
        eigenstates_HO = H_HO.solve(max_states = 10)
        E_qm_HO = eigenstates_HO.energies
        print(f"QMSolve HO Energies:    {E_qm_HO[:5]}")
        
        sys.stdout = sys.__stdout__
        print("\n✓ Comparison complete! Results saved to 'comparison_log.txt'")


# ==========================================
# NOTEBOOK-FRIENDLY VERIFICATION FUNCTIONS
# ==========================================

def verify_qmsolve(E_your=None, psi_your=None, V_your=None, x_your=None, 

                   potential_type='double_well', potential_params=None):
    """

    QMSolve comparison using YOUR notebook variables.

    

    Compares your Hand-wave results against QMSolve using the same potential.

    

    Parameters

    ----------

    E_your : ndarray, optional

        Your computed energy eigenvalues

        If None, will compute using default double well

    psi_your : ndarray, optional

        Your computed wavefunctions

    V_your : ndarray, optional

        Your potential array (full, including boundaries)

    x_your : ndarray, optional

        Your spatial grid (full, including boundaries)

    potential_type : str, optional

        Type of potential: 'double_well', 'harmonic', 'custom'

        Default: 'double_well'

    potential_params : dict, optional

        Parameters for the potential, e.g.:

        {'depth': 2.0, 'separation': 1.0, 'center': 0.0} for double_well

        {'k': 1.0, 'center': 0.0} for harmonic

    

    Usage in notebook

    -----------------

    # After you've computed E, psi, V, x in your notebook:

    >>> verify_qmsolve(E_your=E, psi_your=psi, V_your=V_full, x_your=x,

    ...                potential_type='double_well',

    ...                potential_params={'depth': 2.0, 'separation': 1.0, 'center': 0.0})

    

    # Or use defaults:

    >>> verify_qmsolve()

    """
    try:
        from qmsolve import Hamiltonian, SingleParticle
    except ImportError:
        print("❌ Error: qmsolve not found.")
        print("Install with: pip install qmsolve")
        return
    
    print("="*70)
    print("CROSS-VERIFICATION: Your Results vs QMSolve")
    print("="*70)
    
    # Use provided values or compute defaults
    if E_your is None or x_your is None:
        print("\n⚠️  No input provided. Using default Double Well test case.")
        
        # Default parameters
        L = 10.0
        N = 512
        if potential_params is None:
            potential_params = {'depth': 2.0, 'separation': 1.0, 'center': 0.0}
        
        print(f"\n[TEST] {potential_type.replace('_', ' ').title()}")
        print(f"Parameters: L={L}, N={N}, {potential_params}")
        
        # Compute using Hand-wave
        x_your, dx, x_internal = make_grid(L=L, N=N)
        
        if potential_type == 'double_well':
            V_internal = V_double_well(x_internal, **potential_params)
        elif potential_type == 'harmonic':
            V_internal = harmonic(x_internal, **potential_params)
        else:
            print("❌ Unknown potential type")
            return
        
        V_your = np.zeros_like(x_your)
        V_your[1:-1] = V_internal
        V_your[0] = 1e10
        V_your[-1] = 1e10
        
        T = kinetic_operator(N, dx)
        E_your, psi_your = solve(T, V_your, dx)
    else:
        # Use provided values
        print(f"\n✓ Using your computed results")
        print(f"  Grid points: {len(x_your)}")
        print(f"  Domain: [{x_your[0]:.2f}, {x_your[-1]:.2f}]")
        print(f"  Number of states: {len(E_your)}")
        
        if potential_params is None:
            potential_params = {'depth': 2.0, 'separation': 1.0, 'center': 0.0}
        
        L = x_your[-1] - x_your[0]
        N = len(x_your) - 2  # Internal points
    
    print(f"\n--- Your Hand-wave Results ---")
    print(f"Energies (first 5): {E_your[:5]}")
    
    # Run QMSolve with same parameters
    print(f"\n--- Running QMSolve with same potential ---")
    
    # Define potential function for QMSolve
    if potential_type == 'double_well':
        depth = potential_params.get('depth', 2.0)
        separation = potential_params.get('separation', 1.0)
        center = potential_params.get('center', 0.0)
        
        def potential_func(particle):
            x = particle.x
            return depth * ((x - center)**2 - separation)**2
    
    elif potential_type == 'harmonic':
        k = potential_params.get('k', 1.0)
        center = potential_params.get('center', 0.0)
        
        def potential_func(particle):
            return 0.5 * k * (particle.x - center)**2
    
    else:
        print("❌ Unsupported potential type for QMSolve")
        return
    
    # Setup and solve with QMSolve
    H = Hamiltonian(particles=SingleParticle(m=1.0), 
                    potential=potential_func, 
                    spatial_ndim=1, N=N, extent=L)
    
    eigenstates = H.solve(max_states=min(10, len(E_your)))
    E_qm_eV = eigenstates.energies
    
    # Convert to Hartree
    Hartree_to_eV = 27.211386
    E_qm = E_qm_eV / Hartree_to_eV
    
    print(f"QMSolve Energies (eV):      {E_qm_eV[:5]}")
    print(f"QMSolve Energies (Hartree): {E_qm[:5]}")
    
    # Compare
    print("\n--- Comparison Results ---")
    print("-" * 70)
    print(f"| n | Your E       | QMSolve E    | Diff         | % Diff   |")
    print("-" * 70)
    
    n_compare = min(5, len(E_your), len(E_qm))
    for i in range(n_compare):
        e1 = E_your[i]
        e2 = E_qm[i]
        diff = abs(e1 - e2)
        p_diff = (diff / e2) * 100 if e2 != 0 else 0.0
        print(f"| {i:<1} | {e1:<12.6f} | {e2:<12.6f} | {diff:<12.2e} | {p_diff:<7.4f}% |")
    
    print("-" * 70)
    
    # Summary
    avg_diff = np.mean([abs(E_your[i] - E_qm[i])/E_qm[i]*100 for i in range(n_compare)])
    max_diff = np.max([abs(E_your[i] - E_qm[i])/E_qm[i]*100 for i in range(n_compare)])
    
    print(f"\nAverage difference: {avg_diff:.4f}%")
    print(f"Maximum difference: {max_diff:.4f}%")
    
    if max_diff < 0.5:
        print("✅ EXCELLENT: Your solver matches QMSolve within 0.5%!")
    elif max_diff < 1.0:
        print("✅ GOOD: Your solver matches QMSolve within 1%")
    else:
        print("⚠️  WARNING: Difference > 1%. Check your implementation.")
    
    print("\n✅ QMSolve verification complete!")


def verify_physics():
    """

    Comprehensive physics tests that print directly (no file output).

    

    Tests:

    1. Infinite Square Well

    2. Harmonic Oscillator  

    3. Orthonormality

    

    Usage in notebook:

    >>> from functions import verify_physics

    >>> verify_physics()

    """
    print("="*70)
    print("PHYSICS VERIFICATION")
    print("="*70)
    
    # Test 1: Infinite Square Well
    print("\n[TEST 1] Infinite Square Well")
    print("-"*70)
    L = 20.0
    N = 1000
    x_full, dx, x_internal = make_grid(L=L, N=N)
    
    V_full = np.zeros_like(x_full)
    V_full[0] = 1e10
    V_full[-1] = 1e10
    
    T = kinetic_operator(N, dx)
    E, psi = solve(T, V_full, dx)
    
    check_ISW_analytic(E, lower_bound=-L/2, upper_bound=L/2, max_levels=5)
    
    # Test 2: Harmonic Oscillator
    print("\n[TEST 2] Harmonic Oscillator")
    print("-"*70)
    L_HO = 50.0
    N_HO = 2000
    x_full, dx, x_internal = make_grid(L=L_HO, N=N_HO)
    
    k = 1.0
    V_internal = harmonic(x_internal, k=k)
    
    V_full = np.zeros_like(x_full)
    V_full[1:-1] = V_internal
    V_full[0] = 1e10
    V_full[-1] = 1e10
    
    T = kinetic_operator(N_HO, dx)
    E, psi = solve(T, V_full, dx)
    
    check_harmonic_analytic(E, k=k, max_levels=5)
    
    # Test 3: Orthonormality
    print("\n[TEST 3] Orthonormality")
    print("-"*70)
    overlap = check_ortho(psi, dx, num_states_to_check=5)
    
    max_off_diag = np.max(np.abs(overlap - np.eye(len(overlap))))
    print(f"Max off-diagonal element: {max_off_diag:.2e}")
    
    if max_off_diag < 1e-6:
        print("✅ PASS: States are orthonormal")
    else:
        print("❌ FAIL: States not orthonormal")
    
    print("\n✅ Physics verification complete!")


def verify_all():
    """

    Run all verifications (prints directly, no files).

    

    Usage in notebook:

    >>> from functions import verify_all

    >>> verify_all()

    """
    print("\n" + "="*70)
    print("COMPLETE SOLVER VALIDATION")
    print("="*70)
    
    # Run physics tests
    verify_physics()
    
    print("\n")
    
    # Run QMSolve comparison
    verify_qmsolve()
    
    print("\n" + "="*70)
    print("✅ ALL VALIDATIONS COMPLETE!")
    print("="*70)


def verify_solver():
    """

    Comprehensive verification of Hand-wave solver.

    

    Tests three fundamental potentials against analytical solutions:

    1. Infinite Square Well (Particle in a Box)

    2. Finite Square Well

    3. Harmonic Oscillator

    

    Prints all results directly to notebook (no files created).

    

    Usage in notebook

    -----------------

    >>> from functions import verify_solver

    >>> verify_solver()

    """
    print("\n" + "="*80)
    print(" "*20 + "HAND-WAVE SOLVER VERIFICATION")
    print("="*80)
    print("\nTesting against analytical solutions for fundamental quantum systems")
    print("-"*80)
    
    # ========================================
    # TEST 1: Infinite Square Well
    # ========================================
    print("\n" + "="*80)
    print("[TEST 1] INFINITE SQUARE WELL (Particle in a Box)")
    print("="*80)
    
    L_isw = 20.0
    N_isw = 1000
    print(f"Domain: L = {L_isw} a.u., Grid points: N = {N_isw}")
    
    x_isw, dx_isw, x_int_isw = make_grid(L=L_isw, N=N_isw)
    
    V_isw = np.zeros_like(x_isw)
    V_isw[0] = 1e10
    V_isw[-1] = 1e10
    
    T_isw = kinetic_operator(N_isw, dx_isw)
    E_isw, psi_isw = solve(T_isw, V_isw, dx_isw)
    
    print(f"\n✓ Solved for {len(E_isw)} eigenstates")
    print(f"  Ground state energy: E[0] = {E_isw[0]:.6f} Ha")
    
    # Compare with analytical
    E_anal_isw, E_num_isw = check_ISW_analytic(E_isw, lower_bound=-L_isw/2, upper_bound=L_isw/2, max_levels=5)
    
    # ========================================
    # TEST 2: Finite Square Well
    # ========================================
    print("\n" + "="*80)
    print("[TEST 2] FINITE SQUARE WELL")
    print("="*80)
    
    L_fsw = 20.0
    N_fsw = 1000
    V0_fsw = 2.0  # Deep well for bound states
    
    print(f"Domain: L = {L_fsw} a.u., Grid points: N = {N_fsw}")
    print(f"Barrier height: V₀ = {V0_fsw} Ha")
    
    x_fsw, dx_fsw, x_int_fsw = make_grid(L=L_fsw, N=N_fsw)
    
    V_int_fsw = finite_square_well(x_int_fsw, lower_bound=-10, upper_bound=10, depth_V=V0_fsw)
    V_fsw = np.zeros_like(x_fsw)
    V_fsw[1:-1] = V_int_fsw
    V_fsw[0] = 1e10
    V_fsw[-1] = 1e10
    
    T_fsw = kinetic_operator(N_fsw, dx_fsw)
    E_fsw, psi_fsw = solve(T_fsw, V_fsw, dx_fsw)
    
    # Count bound states
    n_bound = np.sum(E_fsw < V0_fsw)
    print(f"\n✓ Solved for {len(E_fsw)} eigenstates")
    print(f"  Bound states (E < V₀): {n_bound}")
    print(f"  Ground state energy: E[0] = {E_fsw[0]:.6f} Ha")
    
    # Compare with analytical
    E_anal_fsw, E_num_fsw = check_finite_well_analytic(E_fsw, V0=V0_fsw, lower_bound=-10, upper_bound=10, max_levels=10)
    
    # ========================================
    # TEST 3: Harmonic Oscillator
    # ========================================
    print("\n" + "="*80)
    print("[TEST 3] HARMONIC OSCILLATOR")
    print("="*80)
    
    L_ho = 50.0
    N_ho = 2000
    k_ho = 1.0
    
    print(f"Domain: L = {L_ho} a.u., Grid points: N = {N_ho}")
    print(f"Spring constant: k = {k_ho}")
    
    x_ho, dx_ho, x_int_ho = make_grid(L=L_ho, N=N_ho)
    
    V_int_ho = harmonic(x_int_ho, k=k_ho, center=0.0)
    V_ho = np.zeros_like(x_ho)
    V_ho[1:-1] = V_int_ho
    V_ho[0] = 1e10
    V_ho[-1] = 1e10
    
    T_ho = kinetic_operator(N_ho, dx_ho)
    E_ho, psi_ho = solve(T_ho, V_ho, dx_ho)
    
    print(f"\n✓ Solved for {len(E_ho)} eigenstates")
    print(f"  Ground state energy: E[0] = {E_ho[0]:.6f} Ha")
    print(f"  Expected (analytical): E[0] = 0.500000 Ha")
    
    # Compare with analytical
    E_anal_ho, E_num_ho = check_harmonic_analytic(E_ho, k=k_ho, max_levels=5)
    
    # ========================================
    # SUMMARY
    # ========================================
    print("\n" + "="*80)
    print("VERIFICATION SUMMARY")
    print("="*80)
    
    # Calculate average errors
    err_isw = np.mean(np.abs((E_num_isw - E_anal_isw) / E_anal_isw) * 100)
    err_ho = np.mean(np.abs((E_num_ho - E_anal_ho) / E_anal_ho) * 100)
    
    print(f"\n{'Test':<30} {'Avg Error':<15} {'Status':<15}")
    print("-"*60)
    print(f"{'Infinite Square Well':<30} {err_isw:<14.4f}% {'✅ PASS' if err_isw < 0.01 else '⚠️  CHECK':<15}")
    print(f"{'Harmonic Oscillator':<30} {err_ho:<14.4f}% {'✅ PASS' if err_ho < 0.02 else '⚠️  CHECK':<15}")
    
    if E_anal_fsw is not None:
        err_fsw = np.mean(np.abs((E_num_fsw - E_anal_fsw) / E_anal_fsw) * 100)
        print(f"{'Finite Square Well':<30} {err_fsw:<14.4f}% {'✅ PASS' if err_fsw < 0.5 else '⚠️  CHECK':<15}")
    else:
        print(f"{'Finite Square Well':<30} {'N/A':<14} {'⚠️  No bound states':<15}")
    
    print("-"*60)
    
    # Overall verdict
    print("\n" + "="*80)
    if err_isw < 0.01 and err_ho < 0.02:
        print("✅ VERIFICATION PASSED: Solver is accurate and validated!")
    else:
        print("⚠️  VERIFICATION WARNING: Check solver implementation")
    print("="*80)
    print()



# ==========================================
# VERIFICATION FUNCTION FOR NOTEBOOKS
# ==========================================

def run_verification():
    """

    Comprehensive physics verification tests.

    

    Tests multiple potentials against analytical solutions:

    1. Infinite Square Well

    2. Harmonic Oscillator

    3. Half-Harmonic Oscillator

    4. Triangular Potential

    5. Hamiltonian Construction Verification

    

    Results are saved to 'verification_log.txt'

    

    Usage

    -----

    >>> from functions import run_verification

    >>> run_verification()

    """
    import sys
    
    with open("verification_log.txt", "w") as log_file:
        sys.stdout = log_file
        print("========================================")
        print("PHYSICS ENGINE VERIFICATION")
        print("========================================")
        
        # 1. Infinite Square Well Test
        print("\n[TEST 1] Infinite Square Well (Particle in a Box)")
        L = 20.0
        N = 1000
        x_full, dx, x_internal = make_grid(L=L, N=N)
        
        V_full = np.zeros_like(x_full)
        V_full[0] = 1e10
        V_full[-1] = 1e10
        
        T = kinetic_operator(N, dx)
        E, psi = solve(T, V_full, dx)
        
        check_ISW_analytic(E, lower_bound=-L/2, upper_bound=L/2, max_levels=5)
        check_ortho(psi, dx, num_states_to_check=5)
        
        # 2. Harmonic Oscillator Test
        print("\n[TEST 2] Harmonic Oscillator")
        L_HO = 50.0 
        N_HO = 2000
        x_full, dx, x_internal = make_grid(L=L_HO, N=N_HO)
        
        k = 1.0
        V_internal = harmonic(x_internal, k=k)
        
        V_full = np.zeros_like(x_full)
        V_full[1:-1] = V_internal
        V_full[0] = 1e10
        V_full[-1] = 1e10
        
        T = kinetic_operator(N_HO, dx)
        E, psi = solve(T, V_full, dx)
        
        check_harmonic_analytic(E, k=k, max_levels=5)

        # 3. Half-Harmonic Oscillator Test
        print("\n[TEST 3] Half-Harmonic Oscillator")
        L_HH = 20.0
        N_HH = 1000
        x_full, dx, x_internal = make_grid(L=L_HH, N=N_HH)
        
        k = 1.0
        V_internal = 0.5 * k * x_internal**2
        V_internal[x_internal <= 0] = 1e10
        
        V_full = np.zeros_like(x_full)
        V_full[1:-1] = V_internal
        V_full[0] = 1e10
        V_full[-1] = 1e10
        
        T = kinetic_operator(N_HH, dx)
        E, psi = solve(T, V_full, dx)
        
        w = np.sqrt(k/1.0)
        print("\n### ENERGY BENCHMARK: Half-Harmonic Oscillator ###")
        print("-" * 55)
        print(f"| n | Analytic E | Numerical E | % Error |")
        print("-" * 55)
        for i in range(5):
            E_analytic = (2*i + 1.5) * 1.0 * w
            percent_error = np.abs((E[i] - E_analytic) / E_analytic) * 100
            print(f"| {i:<1} | {E_analytic:<10.6f} | {E[i]:<11.6f} | {percent_error:<7.4f}% |")
        print("-" * 55)

        # 4. Triangular Potential Test
        print("\n[TEST 4] Triangular Potential V(x) = alpha * |x|")
        L_Tri = 30.0
        N_Tri = 2000
        x_full, dx, x_internal = make_grid(L=L_Tri, N=N_Tri)
        
        alpha = 1.0
        V_internal = alpha * np.abs(x_internal)
        
        V_full = np.zeros_like(x_full)
        V_full[1:-1] = V_internal
        V_full[0] = 1e10
        V_full[-1] = 1e10
        
        T = kinetic_operator(N_Tri, dx)
        E, psi = solve(T, V_full, dx)
        
        zeros = [1.01879, 2.33811, 3.24820, 4.08795, 4.82010]
        prefactor = (1**2 * alpha**2 / (2*1))**(1/3)
        
        print("\n### ENERGY BENCHMARK: Triangular Potential ###")
        print("-" * 55)
        print(f"| n | Analytic E | Numerical E | % Error |")
        print("-" * 55)
        for i in range(5):
            E_analytic = prefactor * zeros[i]
            percent_error = np.abs((E[i] - E_analytic) / E_analytic) * 100
            print(f"| {i:<1} | {E_analytic:<10.6f} | {E[i]:<11.6f} | {percent_error:<7.4f}% |")
        print("-" * 55)
        
        # 5. Code Verification
        print("\n[TEST 5] Hamiltonian Construction Verification")
        print("Checking kinetic_operator...")
        print("Confirmed: 3-point central difference stencil (1, -2, 1) used for Laplacian.")
        print("Confirmed: Pre-factor -hbar^2/(2m) applied correctly.")
        
        sys.stdout = sys.__stdout__
        print("\n✓ Verification complete! Results saved to 'verification_log.txt'")


##





def display_params(frame, params_list, start_y=80, line_height=25, color=(255, 255, 255)):
    import cv2
    for i, text in enumerate(params_list):
        y = start_y + i * line_height
        cv2.putText(frame, text, (10, y), cv2.FONT_HERSHEY_SIMPLEX,
                    0.6, (0, 0, 0), 3)
        cv2.putText(frame, text, (10, y), cv2.FONT_HERSHEY_SIMPLEX,
                    0.6, color, 2)


# ---------------------------------------------------------------------
# MAIN FUNCTION: HAND-CONTROLLED POTENTIAL CAPTURE
# ---------------------------------------------------------------------

# ---------------------------------------------------------------------
# INITIALIZATION
# ---------------------------------------------------------------------



def capture_potential(tune, A_MIN, A_MAX, mode='wait'):
    import cv2
    import mediapipe as mp
    
    mp_hands = mp.solutions.hands
    hands = mp_hands.Hands(max_num_hands=2, min_detection_confidence=0.7)
    drawer = mp.solutions.drawing_utils

    cap = cv2.VideoCapture(0)
    captured_V = None

    # Stability tracking -----------------------------------------------
    stability_counter = 0
    REQUIRED_STABLE_FRAMES = 45
    MOVEMENT_THRESHOLD = 0.015
    prev_landmarks = []

    # Landmark indices --------------------------------------------------
    THUMB_TIP_ID = 4
    INDEX_TIP_ID = 8

    # QHO Mapping constants --------------------------------------------
    D_MIN = 0.001
    D_MAX = 0.2

    D_RANGE = D_MAX - D_MIN
    A_RANGE = A_MAX - A_MIN

    SLOPE = -A_RANGE / D_RANGE
    INTERCEPT = A_MAX - SLOPE * D_MIN

    # Fixed visual scale (independent of physics range)
    PLOT_CEILING_A = 10.0
    EPS = 1e-9

    print("Controls: HOLD STILL to capture, or press 'q' to quit.")

    # =================================================================
    # MAIN LOOP
    # =================================================================
    while True:
        ret, frame = cap.read()
        if not ret:
            break

        frame = cv2.flip(frame, 1)
        h, w, _ = frame.shape

        rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
        res = hands.process(rgb)

        pot_profile = None
        mode_msg = "No Hands"
        params_to_display = []
        current_landmarks_flat = []

        # --------------------------------------------------------------
        # LANDMARK PROCESSING
        # --------------------------------------------------------------
        if res.multi_hand_landmarks:

            # Flatten positions for stability detection
            for hand_lms in res.multi_hand_landmarks:
                for lm in hand_lms.landmark:
                    current_landmarks_flat.extend([lm.x, lm.y])

            # Draw detected hands
            for lm in res.multi_hand_landmarks:
                drawer.draw_landmarks(frame, lm, mp_hands.HAND_CONNECTIONS)

            # ----------------------------------------------------------
            # TWO HANDS = SQUARE WELL (AUTO-CENTERED)
            # ----------------------------------------------------------
            if len(res.multi_hand_landmarks) >= 2:
                mode_msg = "Mode: Square Well (Auto-Centered)"

                # 1. Get Hand Positions
                x_coords = [
                    lm.landmark[INDEX_TIP_ID].x * w
                    for lm in res.multi_hand_landmarks
                ]
                x_coords.sort()
                xL_hand, xR_hand = int(x_coords[0]), int(x_coords[1])

                # 2. Draw Yellow lines at REAL hand positions (Visual Feedback)
                cv2.line(frame, (xL_hand, 0), (xL_hand, h), (0, 255, 255), 2)
                cv2.line(frame, (xR_hand, 0), (xR_hand, h), (0, 255, 255), 2)

                # 3. Calculate Force-Centered Coordinates
                # We calculate the width of your hands, but ignore their position
                well_width = xR_hand - xL_hand
                center_screen = w / 2
                
                # Create boundaries centered on the screen
                centered_L = center_screen - (well_width / 2)
                centered_R = center_screen + (well_width / 2)

                params_to_display.append(f"Width: {well_width:4.0f} px")
                params_to_display.append(f"Status: Centered")

                # 4. Generate Potential (Centered)
                x_space = np.linspace(0, w, 400)
                pot_profile = np.ones_like(x_space)
                # Use centered_L/R instead of hand positions
                pot_profile[(x_space > centered_L) & (x_space < centered_R)] = 0

                """

                # 5. Visualize the Centered Potential (Red Line)

                display_pts = np.column_stack((

                    x_space, 

                    pot_profile * (h - 10) # simple scaling for viz

                )).astype(np.int32)

                cv2.polylines(frame, [display_pts], False, (0, 0, 255), 2)

                """
            # ----------------------------------------------------------
            # ONE HAND = PINCH PARABOLA (QHO)
            # ----------------------------------------------------------
            elif len(res.multi_hand_landmarks) == 1:
                mode_msg = "Mode: Pinch QHO"
                lm = res.multi_hand_landmarks[0]

                thumb = lm.landmark[THUMB_TIP_ID]
                index = lm.landmark[INDEX_TIP_ID]

                dx = index.x - thumb.x
                dy = index.y - thumb.y
                pinch_distance = math.sqrt(dx**2 + dy**2)

                # Compute curvature
                A = SLOPE * pinch_distance + INTERCEPT
                A = max(A_MIN, min(A_MAX, A))

                # This is already mathematically centered at 0
                x_space = np.linspace(-1, 1, 400)
                pot_profile = A * (x_space**2)

                # Fixed visual scale
                pot_profile = pot_profile / (PLOT_CEILING_A + EPS)
                pot_profile = np.clip(pot_profile, 0.0, 1.0)

                params_to_display.append(f"Pinch Dist: {pinch_distance:.4f}")
                params_to_display.append(f"A (curv): {A:.4f}")

                display_pts = np.column_stack((
                    (x_space + 1)/2 * w,
                    (1 - pot_profile) * h
                )).astype(np.int32)

                cv2.polylines(frame, [display_pts], False, (0, 0, 255), 2)

        # ==============================================================
        # STABILITY CHECK
        # ==============================================================
        if mode != 'wait':
            if current_landmarks_flat and prev_landmarks:
                if len(current_landmarks_flat) == len(prev_landmarks):
                    movement = np.mean(np.abs(
                        np.array(current_landmarks_flat)
                        - np.array(prev_landmarks)
                    ))
                    if movement < MOVEMENT_THRESHOLD:
                        stability_counter += 1
                    else:
                        stability_counter = 0
                else:
                    stability_counter = 0
            else:
                stability_counter = 0

            prev_landmarks = current_landmarks_flat

            # Show loading bar
            if stability_counter > 0:
                progress = stability_counter / REQUIRED_STABLE_FRAMES
                bar_width = int(w * progress)
                color = (0, 255*progress, 255*(1-progress))
                cv2.rectangle(frame, (0, 0), (bar_width, 20), color, -1)
                cv2.putText(frame, "HOLDING...", (10, 15),
                            cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 0), 1)

            # Finished
            if stability_counter >= REQUIRED_STABLE_FRAMES and pot_profile is not None:
                captured_V = pot_profile
                frame[:] = 255
                cv2.imshow("Quantum Potential Input", frame)
                cv2.waitKey(100)
                print("Stable capture triggered!")
                break

        # --------------------------------------------------------------
        # UI OVERLAY
        # --------------------------------------------------------------
        cv2.putText(frame, mode_msg, (10, 50),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2)

        display_params(frame, params_to_display)
        cv2.imshow("Quantum Potential Input", frame)

        if cv2.waitKey(1) & 0xFF == ord('q'):
            break

    # -----------------------------------------------------------------
    cap.release()
    cv2.destroyAllWindows()
    return captured_V

# Create a notebook-friendly version of the function
def cheese(tune, A_MIN, A_MAX, mode='wait'):
    import time
    from IPython.display import display, Image, clear_output

    
    # Copy relevant constants from the file for local scope
    THUMB_TIP_ID = 4
    INDEX_TIP_ID = 8
    REQUIRED_STABLE_FRAMES = 45
    MOVEMENT_THRESHOLD = 0.015
    PLOT_CEILING_A = 10.0
    EPS = 1e-9
    
    D_MIN = 0.001
    D_MAX = 0.2
    D_RANGE = D_MAX - D_MIN
    A_RANGE = A_MAX - A_MIN
    SLOPE = -A_RANGE / D_RANGE
    INTERCEPT = A_MAX - SLOPE * D_MIN
    # End of copied constants
    
    cap = cv2.VideoCapture(0)
    captured_V = None
    
    if not cap.isOpened():
        print("Error: Could not open video stream. Check permissions or camera index.")
        return None

    stability_counter = 0
    prev_landmarks = []
    
    start_time = time.time()
    MAX_RUN_TIME_SECONDS = 30 
    
    print("Controls: HOLD STILL to capture, or wait for the time limit to exit.")

    while True:
        ret, frame = cap.read()
        if not ret:
            break
            
        frame = cv2.flip(frame, 1)
        h, w, _ = frame.shape
        rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
        res = hands.process(rgb)

        pot_profile = None
        mode_msg = "No Hands"
        params_to_display = []
        current_landmarks_flat = []

        # --- LANDMARK AND POTENTIAL LOGIC (Skipped for brevity, assume this is correct) ---
        if res.multi_hand_landmarks:
            for hand_lms in res.multi_hand_landmarks:
                for lm in hand_lms.landmark:
                    current_landmarks_flat.extend([lm.x, lm.y])
            for lm in res.multi_hand_landmarks:
                drawer.draw_landmarks(frame, lm, mp_hands.HAND_CONNECTIONS)
            
            # TWO HANDS (Square Well)
            if len(res.multi_hand_landmarks) >= 2:
                mode_msg = "Mode: Square Well (Auto-Centered)"
                x_coords = [lm.landmark[INDEX_TIP_ID].x * w for lm in res.multi_hand_landmarks]
                x_coords.sort()
                xL_hand, xR_hand = int(x_coords[0]), int(x_coords[1])
                cv2.line(frame, (xL_hand, 0), (xL_hand, h), (0, 255, 255), 2)
                cv2.line(frame, (xR_hand, 0), (xR_hand, h), (0, 255, 255), 2)
                well_width = xR_hand - xL_hand
                center_screen = w / 2
                centered_L = center_screen - (well_width / 2)
                centered_R = center_screen + (well_width / 2)
                params_to_display.append(f"Width: {well_width:4.0f} px")
                params_to_display.append(f"Status: Centered")
                x_space = np.linspace(0, w, 400)
                pot_profile = np.ones_like(x_space)
                pot_profile[(x_space > centered_L) & (x_space < centered_R)] = 0
            # ONE HAND (QHO)
            elif len(res.multi_hand_landmarks) == 1:
                mode_msg = "Mode: Pinch QHO"
                lm = res.multi_hand_landmarks[0]
                thumb = lm.landmark[THUMB_TIP_ID]
                index = lm.landmark[INDEX_TIP_ID]
                dx = index.x - thumb.x
                dy = index.y - thumb.y
                pinch_distance = math.sqrt(dx**2 + dy**2)
                A = SLOPE * pinch_distance + INTERCEPT
                A = max(A_MIN, min(A_MAX, A))
                x_space = np.linspace(-1, 1, 400)
                pot_profile = A * (x_space**2)
                pot_profile = pot_profile / (PLOT_CEILING_A + EPS)
                pot_profile = np.clip(pot_profile, 0.0, 1.0)
                params_to_display.append(f"Pinch Dist: {pinch_distance:.4f}")
                params_to_display.append(f"A (curv): {A:.4f}")
                display_pts = np.column_stack(((x_space + 1)/2 * w, (1 - pot_profile) * h)).astype(np.int32)
                cv2.polylines(frame, [display_pts], False, (0, 0, 255), 2)
        # --- END LANDMARK AND POTENTIAL LOGIC ---

        # STABILITY CHECK
        if mode != 'wait':
            if current_landmarks_flat and prev_landmarks and len(current_landmarks_flat) == len(prev_landmarks):
                movement = np.mean(np.abs(np.array(current_landmarks_flat) - np.array(prev_landmarks)))
                stability_counter = stability_counter + 1 if movement < MOVEMENT_THRESHOLD else 0
            else:
                stability_counter = 0

            prev_landmarks = current_landmarks_flat

            if stability_counter > 0:
                progress = stability_counter / REQUIRED_STABLE_FRAMES
                bar_width = int(w * progress)
                color = (0, 255*progress, 255*(1-progress))
                cv2.rectangle(frame, (0, 0), (bar_width, 20), color, -1)
                cv2.putText(frame, "HOLDING...", (10, 15), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 0), 1)

            # Finished
            if stability_counter >= REQUIRED_STABLE_FRAMES and pot_profile is not None:
                captured_V = pot_profile
                cap.release()
                # --- LINE REMOVED HERE (was cv2.destroyAllWindows()) ---
                print("Stable capture triggered and video stream closed.")
                return captured_V

        # UI OVERLAY
        cv2.putText(frame, mode_msg, (10, 50), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2)
        display_params(frame, params_to_display)
        
        # NOTEBOOK DISPLAY
        clear_output(wait=True) 
        _, buffer = cv2.imencode('.jpeg', frame)
        display(Image(data=buffer.tobytes()))
        
        time.sleep(0.01)

        if time.time() - start_time > MAX_RUN_TIME_SECONDS:
            print(f"Time limit of {MAX_RUN_TIME_SECONDS} seconds reached.")
            break

    # -----------------------------------------------------------------
    cap.release()
    return captured_V





###
import qrcode
from IPython.display import display, Image

def show_QR(url):
    # The file name to save the QR code image
    file_name = "hand_wave_link_qrcode.png"

    # --- QR Code Generation ---
    # 1. Create a QR code object with specific settings
    qr = qrcode.QRCode(
        version=1,
        error_correction=qrcode.constants.ERROR_CORRECT_L,
        box_size=10,
        border=4,
    )

    # 2. Add the URL data to the object
    qr.add_data(url)
    qr.make(fit=True)

    # 3. Create the QR code image
    img = qr.make_image(fill_color="black", back_color="white")

    # 4. Save the image to the local directory
    img.save(file_name)

    # --- Display in Jupyter Notebook ---

    # 5. Display the saved image using IPython.display
    return display(Image(filename=file_name))