coordinate-system 4.0.3__cp313-cp313-win_amd64.whl → 5.2.0__cp313-cp313-win_amd64.whl

coordinate_system/fourier_frames.py

@@ -0,0 +1,530 @@
+"""
+Fourier Frame System - Quantum Coordinate Transformations
+=========================================================
+
+Implements Fourier coordinate frames for quantum state transformations
+between position and momentum representations.
+
+Features:
+- FourierFrame: Coordinate frames for Fourier transformations
+- QuantumState: Quantum states in specific basis
+- StateVector: Complete state representations
+- **Operator Overloading**: Use @ and * for transformations
+- Position ↔ Momentum transformations
+- Gaussian wave packet creation
+- Uncertainty principle demonstrations
+
+Operator Overloading:
+--------------------
+- `frame @ state`  : Transform state to this frame
+- `frame * state`  : Same as @ (alternative)
+- `~frame`         : Get dual frame (position ↔ momentum)
+- `state | frame`  : Transform state to frame (bra-ket notation)
+
+Author: PanGuoJun
+Date: 2025-12-01
+"""
+
+import numpy as np
+from typing import List, Tuple, Union, Optional
+
+try:
+    from .coordinate_system import vec3, quat, coord3
+except ImportError:
+    import coordinate_system
+    vec3 = coordinate_system.vec3
+    quat = coordinate_system.quat
+    coord3 = coordinate_system.coord3
+
+
+class QuantumState:
+    """
+    Quantum state |ψ⟩ - Representation in a specific basis
+
+    Represents a quantum state with:
+    - basis_vector: Position or momentum value
+    - amplitude: Complex amplitude in this basis
+    - basis: Type of basis ('position' or 'momentum')
+
+    Operator Overloading:
+    --------------------
+    - `state | frame` : Transform to frame (bra-ket notation)
+    """
+
+    def __init__(self, basis_vector: vec3, amplitude: complex = 1.0, basis: str = 'position'):
+        """
+        Initialize quantum state
+
+        Args:
+            basis_vector: Basis vector (position or momentum value)
+            amplitude: Complex amplitude in this basis
+            basis: Basis type ('position' or 'momentum')
+        """
+        self.basis_vector = basis_vector
+        self.amplitude = amplitude
+        self.basis = basis
+
+    def transform(self, frame: 'FourierFrame') -> 'StateVector':
+        """
+        Transform to another coordinate frame
+
+        Args:
+            frame: Target Fourier frame
+
+        Returns:
+            Transformed state vector
+        """
+        return frame.transform(self)
+
+    def __or__(self, other: 'FourierFrame') -> 'StateVector':
+        """
+        Bra-ket notation: state | frame
+
+        Transforms the state to the given frame
+
+        Args:
+            other: Target Fourier frame
+
+        Returns:
+            Transformed state vector
+        """
+        if isinstance(other, FourierFrame):
+            return other.transform(self)
+        return NotImplemented
+
+    def __repr__(self) -> str:
+        basis_symbol = 'x' if self.basis == 'position' else 'p'
+        return f"{self.amplitude:.3f}|{basis_symbol}={self.basis_vector.x:.1f}⟩"
+
+
+class StateVector:
+    """
+    State vector - Complete representation in a coordinate system
+
+    Represents a quantum state as a superposition:
+    |ψ⟩ = Σᵢ cᵢ|bᵢ⟩
+
+    where cᵢ are complex amplitudes and |bᵢ⟩ are basis states.
+
+    Operator Overloading:
+    --------------------
+    - `state | frame` : Transform to frame (bra-ket notation)
+    """
+
+    def __init__(self, states: Union[List[QuantumState], List[Tuple[vec3, complex]]],
+                 basis: str = 'position'):
+        """
+        Initialize state vector
+
+        Args:
+            states: List of QuantumState objects or (vector, amplitude) tuples
+            basis: Basis type ('position' or 'momentum')
+        """
+        if isinstance(states, list) and states and isinstance(states[0], QuantumState):
+            self.components = [(s.basis_vector, s.amplitude) for s in states]
+        else:
+            self.components = states  # Direct (vector, amplitude) list
+        self.basis = basis
+        self._normalize()
+
+    def _normalize(self):
+        """Normalize the state vector to unit probability"""
+        total_prob = sum(abs(amp)**2 for _, amp in self.components)
+        if total_prob > 0:
+            norm = 1.0 / np.sqrt(total_prob)
+            self.components = [(vec, amp * norm) for vec, amp in self.components]
+
+    def transform(self, frame: 'FourierFrame') -> 'StateVector':
+        """
+        Transform to another coordinate frame
+
+        Args:
+            frame: Target Fourier frame
+
+        Returns:
+            Transformed state vector
+        """
+        return frame.transform(self)
+
+    def __or__(self, other: 'FourierFrame') -> 'StateVector':
+        """
+        Bra-ket notation: state | frame
+
+        Transforms the state to the given frame
+
+        Args:
+            other: Target Fourier frame
+
+        Returns:
+            Transformed state vector
+        """
+        if isinstance(other, FourierFrame):
+            return other.transform(self)
+        return NotImplemented
+
+    def probability_density(self) -> List[Tuple[vec3, float]]:
+        """
+        Compute probability density distribution |ψ(x)|²
+
+        Returns:
+            List of (position/momentum, probability) tuples
+        """
+        return [(vec, abs(amp)**2) for vec, amp in self.components]
+
+    def expectation_value(self) -> float:
+        """
+        Compute expectation value ⟨x⟩ or ⟨p⟩
+
+        Returns:
+            Expectation value in current basis
+        """
+        return sum(vec.x * abs(amp)**2 for vec, amp in self.components)
+
+    def variance(self) -> float:
+        """
+        Compute variance σ² = ⟨x²⟩ - ⟨x⟩²
+
+        Returns:
+            Variance in current basis
+        """
+        mean = self.expectation_value()
+        mean_square = sum((vec.x ** 2) * abs(amp)**2 for vec, amp in self.components)
+        return mean_square - mean ** 2
+
+    def standard_deviation(self) -> float:
+        """
+        Compute standard deviation σ = √(⟨x²⟩ - ⟨x⟩²)
+
+        Returns:
+            Standard deviation in current basis
+        """
+        return np.sqrt(self.variance())
+
+    def __repr__(self) -> str:
+        main_components = []
+        for vec, amp in self.components:
+            if abs(amp) > 0.05:  # Only show significant components
+                basis_symbol = 'x' if self.basis == 'position' else 'p'
+                main_components.append(f"{amp:.3f}|{basis_symbol}={vec.x:.1f}⟩")
+
+        if len(main_components) > 3:
+            return " + ".join(main_components[:3]) + " + ..."
+        return " + ".join(main_components) if main_components else "0"
+
+
+class FourierFrame:
+    """
+    Fourier coordinate frame - Basis vectors for Fourier transformations
+
+    Implements position ↔ momentum transformations via Fourier transform:
+
+    Position → Momentum: ψ̃(p) = (1/√2π) ∫ ψ(x) e^(-ipx) dx
+    Momentum → Position: ψ(x) = (1/√2π) ∫ ψ̃(p) e^(ipx) dp
+
+    Operator Overloading:
+    --------------------
+    - `frame @ state` : Transform state to this frame (matrix multiplication)
+    - `frame * state` : Same as @ (alternative syntax)
+    - `~frame` : Get dual frame (position ↔ momentum)
+
+    Examples:
+    ---------
+    >>> position_frame = FourierFrame(domain='position')
+    >>> momentum_frame = FourierFrame(domain='momentum')
+    >>> psi_x = QuantumState(vec3(0,0,0), 1.0, 'position')
+    >>>
+    >>> # Method 1: Using @ operator
+    >>> psi_p = momentum_frame @ psi_x
+    >>>
+    >>> # Method 2: Using * operator
+    >>> psi_p = momentum_frame * psi_x
+    >>>
+    >>> # Method 3: Using bra-ket notation |
+    >>> psi_p = psi_x | momentum_frame
+    >>>
+    >>> # Method 4: Get dual and transform
+    >>> psi_p = (~position_frame) @ psi_x
+    """
+
+    def __init__(self, dimension: int = 1, domain: str = 'position',
+                 sample_points: int = 64, x_range: Tuple[float, float] = (-5, 5)):
+        """
+        Initialize Fourier frame
+
+        Args:
+            dimension: Spatial dimension (currently only 1D supported)
+            domain: Domain type ('position' or 'momentum')
+            sample_points: Number of sample points for discrete representation
+            x_range: Range of position/momentum values (min, max)
+        """
+        self.dim = dimension
+        self.domain = domain
+        self.N = sample_points
+        self.range = x_range
+        self._setup_basis()
+
+    def _setup_basis(self):
+        """Setup basis vectors for the coordinate frame"""
+        if self.dim == 1:
+            if self.domain == 'position':
+                # Position basis |x⟩
+                self.basis_vectors = [
+                    vec3(x, 0, 0)
+                    for x in np.linspace(self.range[0], self.range[1], self.N)
+                ]
+            else:
+                # Momentum basis |p⟩
+                self.basis_vectors = [
+                    vec3(p, 0, 0)
+                    for p in np.linspace(self.range[0], self.range[1], self.N)
+                ]
+
+    def transform(self, obj: Union[QuantumState, StateVector, vec3]) -> Union[StateVector, 'StateVector']:
+        """
+        Universal coordinate transformation method
+
+        Args:
+            obj: Object to transform (QuantumState, StateVector, or vec3)
+
+        Returns:
+            Transformed object
+        """
+        if isinstance(obj, QuantumState):
+            return self._transform_single_state(obj)
+        elif isinstance(obj, StateVector):
+            return self._transform_state_vector(obj)
+        elif isinstance(obj, vec3):
+            return self._transform_single_vector(obj)
+        else:
+            raise TypeError(f"Unsupported type: {type(obj)}")
+
+    def inverse_transform(self, obj: Union[QuantumState, StateVector, vec3]) -> Union[StateVector, 'StateVector']:
+        """
+        Inverse coordinate transformation
+
+        Args:
+            obj: Object to inverse transform
+
+        Returns:
+            Inverse transformed object
+        """
+        # Create inverse frame for transformation
+        dual = ~self
+        return dual.transform(obj)
+
+    # ========== Operator Overloading ==========
+
+    def __matmul__(self, other: Union[QuantumState, StateVector, vec3]) -> Union[StateVector, 'StateVector']:
+        """
+        Matrix multiplication operator: frame @ state
+
+        Transforms the state to this frame
+
+        Args:
+            other: State to transform
+
+        Returns:
+            Transformed state
+        """
+        return self.transform(other)
+
+    def __mul__(self, other: Union[QuantumState, StateVector, vec3]) -> Union[StateVector, 'StateVector']:
+        """
+        Multiplication operator: frame * state
+
+        Transforms the state to this frame (alternative to @)
+
+        Args:
+            other: State to transform
+
+        Returns:
+            Transformed state
+        """
+        return self.transform(other)
+
+    def __invert__(self) -> 'FourierFrame':
+        """
+        Inversion operator: ~frame
+
+        Get the dual frame (position ↔ momentum)
+
+        Returns:
+            Dual Fourier frame
+        """
+        if self.domain == 'position':
+            return FourierFrame(self.dim, 'momentum', self.N, self.range)
+        else:
+            return FourierFrame(self.dim, 'position', self.N, self.range)
+
+    # ========== Internal Transform Methods ==========
+
+    def _transform_single_state(self, state: QuantumState) -> StateVector:
+        """Transform a single quantum state"""
+        if state.basis != self.domain:
+            # Transform between different domains
+            return self._fourier_transform_single(state)
+        else:
+            # Same domain, return state vector directly
+            return StateVector([state], self.domain)
+
+    def _transform_state_vector(self, state_vector: StateVector) -> StateVector:
+        """Transform a state vector"""
+        if state_vector.basis != self.domain:
+            # Transform between different domains
+            return self._fourier_transform_vector(state_vector)
+        else:
+            # Same domain, return directly
+            return state_vector
+
+    def _transform_single_vector(self, vector: vec3) -> StateVector:
+        """Transform a single vector"""
+        results = []
+        for basis_vec in self.basis_vectors:
+            if self.dim == 1:
+                # Use Fourier kernel for 1D
+                if self.domain == 'position':
+                    # Momentum → Position
+                    amplitude = (1/np.sqrt(2*np.pi)) * np.exp(1j * vector.x * basis_vec.x)
+                else:
+                    # Position → Momentum
+                    amplitude = (1/np.sqrt(2*np.pi)) * np.exp(-1j * vector.x * basis_vec.x)
+
+                results.append(QuantumState(basis_vec, amplitude, self.domain))
+
+        return StateVector(results, self.domain)
+
+    def _fourier_transform_single(self, state: QuantumState) -> StateVector:
+        """Fourier transform a single quantum state"""
+        results = []
+        for target_basis in self.basis_vectors:
+            if self.dim == 1:
+                if state.basis == 'position' and self.domain == 'momentum':
+                    # ⟨p|x⟩ = (1/√2π) exp(-i p x)
+                    kernel = (1/np.sqrt(2*np.pi)) * np.exp(-1j * target_basis.x * state.basis_vector.x)
+                    amplitude = kernel * state.amplitude
+                else:
+                    # ⟨x|p⟩ = (1/√2π) exp(i p x)
+                    kernel = (1/np.sqrt(2*np.pi)) * np.exp(1j * state.basis_vector.x * target_basis.x)
+                    amplitude = kernel * state.amplitude
+
+                results.append(QuantumState(target_basis, amplitude, self.domain))
+
+        return StateVector(results, self.domain)
+
+    def _fourier_transform_vector(self, state_vector: StateVector) -> StateVector:
+        """Fourier transform a state vector"""
+        results = []
+        for target_basis in self.basis_vectors:
+            total_amplitude = 0 + 0j
+
+            # Transform all components of the original state vector
+            for component, amp in state_vector.components:
+                if self.dim == 1:
+                    if state_vector.basis == 'position' and self.domain == 'momentum':
+                        # ⟨p|x⟩ = (1/√2π) exp(-i p x)
+                        kernel = (1/np.sqrt(2*np.pi)) * np.exp(-1j * target_basis.x * component.x)
+                    else:
+                        # ⟨x|p⟩ = (1/√2π) exp(i p x)
+                        kernel = (1/np.sqrt(2*np.pi)) * np.exp(1j * component.x * target_basis.x)
+
+                    total_amplitude += kernel * amp
+
+            results.append(QuantumState(target_basis, total_amplitude, self.domain))
+
+        return StateVector(results, self.domain)
+
+    def __repr__(self) -> str:
+        return f"FourierFrame(domain='{self.domain}', dim={self.dim}, samples={self.N})"
+
+
+# ========== Utility Functions ==========
+
+def create_gaussian_wavepacket(center: float = 0.0, width: float = 1.0,
+                               momentum: float = 0.0,
+                               frame: Optional[FourierFrame] = None) -> StateVector:
+    """
+    Create Gaussian wave packet
+
+    ψ(x) = (1/(πσ²)^(1/4)) exp(-(x-x₀)²/(2σ²)) exp(ip₀x)
+
+    Args:
+        center: Center position x₀
+        width: Width σ (standard deviation)
+        momentum: Central momentum p₀
+        frame: Fourier frame (creates default if None)
+
+    Returns:
+        StateVector representing the Gaussian wave packet
+    """
+    if frame is None:
+        frame = FourierFrame(dimension=1, domain='position', sample_points=64)
+
+    states = []
+    normalization = (1.0 / (np.pi * width**2))**0.25
+
+    for basis_vec in frame.basis_vectors:
+        x = basis_vec.x
+        # Gaussian envelope × plane wave
+        amplitude = normalization * np.exp(-(x - center)**2 / (2 * width**2)) * np.exp(1j * momentum * x)
+        states.append(QuantumState(basis_vec, amplitude, frame.domain))
+
+    return StateVector(states, frame.domain)
+
+
+def fourier_transform(state_vector: StateVector, sample_points: int = 64) -> StateVector:
+    """
+    Fourier transform function: Position ↔ Momentum
+
+    Args:
+        state_vector: State vector to transform
+        sample_points: Number of sample points for result
+
+    Returns:
+        Transformed state vector
+    """
+    if state_vector.basis == 'position':
+        momentum_frame = FourierFrame(dimension=1, domain='momentum', sample_points=sample_points)
+        return momentum_frame @ state_vector  # Using @ operator
+    else:
+        position_frame = FourierFrame(dimension=1, domain='position', sample_points=sample_points)
+        return position_frame @ state_vector  # Using @ operator
+
+
+def compute_uncertainty_product(state_vector: StateVector) -> Tuple[float, float, float]:
+    """
+    Compute uncertainty product ΔxΔp for a state
+
+    Demonstrates Heisenberg uncertainty principle: ΔxΔp ≥ ℏ/2
+
+    Args:
+        state_vector: State vector in position basis
+
+    Returns:
+        Tuple of (Δx, Δp, ΔxΔp)
+    """
+    # Position uncertainty
+    if state_vector.basis != 'position':
+        raise ValueError("State must be in position basis")
+
+    delta_x = state_vector.standard_deviation()
+
+    # Transform to momentum space using @ operator
+    momentum_state = fourier_transform(state_vector)
+    delta_p = momentum_state.standard_deviation()
+
+    # Uncertainty product
+    product = delta_x * delta_p
+
+    return delta_x, delta_p, product
+
+
+# ========== Export ==========
+
+__all__ = [
+    'FourierFrame',
+    'QuantumState',
+    'StateVector',
+    'create_gaussian_wavepacket',
+    'fourier_transform',
+    'compute_uncertainty_product',
+]