coordinate-system 6.0.0__tar.gz → 6.0.3__tar.gz

coordinate_system-6.0.3/PKG-INFO

@@ -0,0 +1,1001 @@
+Metadata-Version: 2.1
+Name: coordinate_system
+Version: 6.0.3
+Summary: High-performance 3D coordinate system library with unified differential geometry, quantum frame algebra, spectral transforms, and professional curvature visualization
+Home-page: https://github.com/panguojun/Coordinate-System
+Author: PanGuoJun
+Author-email: 18858146@qq.com
+License: MIT
+Project-URL: Bug Reports, https://github.com/panguojun/Coordinate-System/issues
+Project-URL: Source, https://github.com/panguojun/Coordinate-System
+Project-URL: Documentation, https://github.com/panguojun/Coordinate-System/blob/main/README.md
+Keywords: 3d math vector quaternion coordinate-system geometry graphics spatial-computing differential-geometry curvature curve-interpolation c2-continuity frenet-frames fourier-transform operator-overloading quantum-coordinates heisenberg-uncertainty visualization rgb-frames catmull-rom squad intrinsic-gradient spectral-analysis surface-visualization
+Platform: Windows
+Platform: Linux
+Platform: macOS
+Platform: Android
+Platform: iOS
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: C++
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: matplotlib>=3.3.0
+
+# Coordinate System Library
+
+**High-performance 3D coordinate system and differential geometry library for Python**
+
+[![PyPI version](https://badge.fury.io/py/coordinate-system.svg)](https://pypi.org/project/coordinate-system/)
+[![Python](https://img.shields.io/pypi/pyversions/coordinate-system.svg)](https://pypi.org/project/coordinate-system/)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-blue.svg)](https://pypi.org/project/coordinate-system/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**Author:** PanGuoJun
+**Version:** 6.0.3
+**License:** MIT
+
+---
+
+## 🆕 What's New in v6.0.3 (2025-12-04)
+
+### U(3) Gauge Theory Framework - Unified Complex Frame & Gauge Fields
+
+**Complete implementation of gauge field theory based on U(3) unitary group** - A groundbreaking framework unifying geometry, topology, and gauge field theory through complex frames.
+
+> **Theoretical Foundation**:
+>
+> Based on the paper "*Geometric-Topological Duality: Complex Frame as Unified Structure of Spacetime and Gauge Fields*", this implementation realizes:
+> - **U(3) Complex Frame**: Full 3×3 unitary matrix representation
+> - **Symmetry Breaking Chain**: SU(4) → SU(3) × SU(2) × U(1)
+> - **Color-Space Duality**: RGB color phases ↔ Spatial axes
+> - **Imaginary Time Embedding**: ℝ³ × iℝ → Internal rotation degrees of freedom
+
+#### 🎯 **New U(3) Frame Module**
+
+**U3Frame Class** - Complete U(3) unitary frame:
+
+```python
+from coordinate_system import U3Frame
+import numpy as np
+
+# Create U(3) frame with color phases
+theta_R, theta_G, theta_B = 0.1, 0.3, -0.4  # RGB phases
+e1 = np.array([np.exp(1j * theta_R), 0, 0])
+e2 = np.array([0, np.exp(1j * theta_G), 0])
+e3 = np.array([0, 0, np.exp(1j * theta_B)])
+
+frame = U3Frame(e1, e2, e3)
+
+# Symmetry decomposition
+su3_comp, u1_phase = frame.to_su3_u1()  # U(3) = SU(3) × U(1)
+
+# Color phases (Red, Green, Blue)
+phases = frame.color_phases()  # (θ_R, θ_G, θ_B)
+
+# Quaternion representation (SU(2) subgroup)
+q = frame.to_quaternion_representation()
+```
+
+#### 🌟 **Gauge Field Theory**
+
+**GaugeConnection Class** - Unified gauge field representation:
+
+```python
+from coordinate_system import GaugeConnection, FieldStrength
+
+# Create gauge connection A_μ = A^{SU(3)} + A^{SU(2)} + A^{U(1)}
+connection = GaugeConnection(
+    su3_component=np.random.randn(8) * 0.1,  # 8 gluons (QCD)
+    su2_component=np.random.randn(3) * 0.1,  # 3 W/Z bosons (weak)
+    u1_component=0.05+0.02j                  # 1 photon (EM)
+)
+
+# Field strength tensor F_μν = [A_μ, A_ν]
+F = connection_x.field_strength(connection_y)
+
+# Yang-Mills action
+S_YM = F.yang_mills_action()
+
+# Topological charge (Instanton number)
+Q = F.topological_charge()
+```
+
+#### 🔬 **Core Features**
+
+**1. Complete U(3) Unitary Frame**
+```python
+U(x) = [𝐞₁, 𝐞₂, 𝐞₃] ∈ U(3)
+Each column: 𝐞ₖ = 𝐚ₖ + i𝐛ₖ ∈ ℂ³
+```
+- Full 3×3 complex matrix representation
+- Gram-Schmidt orthonormalization
+- Unitary property: U† U = I
+
+**2. Symmetry Decomposition**
+```python
+U(3) = SU(3) × U(1)
+SU(3) ⊃ SU(2) × U(1)
+```
+- SU(3): 8 generators (Gell-Mann matrices)
+- SU(2): 3 generators (Pauli matrices)
+- U(1): Global phase
+
+**3. Color-Space Duality**
+```
+Spatial Axis ↔ Color Charge
+─────────────────────────────
+x-axis (e₁)  ↔  Red (θ₁)
+y-axis (e₂)  ↔  Green (θ₂)
+z-axis (e₃)  ↔  Blue (θ₃)
+
+Constraint: θ₁ + θ₂ + θ₃ = φ (color singlet)
+```
+
+**4. Gauge Transformations**
+```python
+# U(1) gauge transform
+frame_u1 = frame.gauge_transform_u1(phi)
+
+# SU(2) gauge transform (weak interaction)
+frame_su2 = frame.gauge_transform_su2((θx, θy, θz))
+
+# SU(3) gauge transform (strong interaction)
+frame_su3 = frame.gauge_transform_su3(gell_mann_params)
+```
+
+**5. Imaginary Time Evolution**
+```python
+# Imaginary time evolution U(τ) = exp(-τĤ) U(0)
+frame_tau = frame.imaginary_time_evolution(tau=0.5, hamiltonian=H)
+
+# Wick rotation: t → -iτ
+frame_wick = frame.wick_rotation(real_time=1.0)
+```
+
+**6. Symmetry Breaking Potential**
+```python
+from coordinate_system import SymmetryBreakingPotential
+
+# Higgs-type potential
+potential = SymmetryBreakingPotential(
+    mu_squared=-1.0,      # Negative triggers breaking
+    lambda_coupling=0.5,
+    gamma_coupling=0.1
+)
+
+# Find vacuum state
+frame_vacuum = potential.find_vacuum()
+```
+
+#### 📐 **Physical Interpretation**
+
+**Unified Framework:**
+```
+           U(3) Complex Frame
+          /        |        \
+         /         |         \
+   Geometry    Gauge Field   Imaginary Time
+   (Real Part)  (Connection)  (Imag Part)
+      |            |             |
+      V            V             V
+   Metric      Interactions   Evolution
+```
+
+**Standard Model Gauge Group:**
+| Layer | Gauge Group | Physical Field | Implementation |
+|-------|-------------|----------------|----------------|
+| **Strong** | SU(3) | 8 Gluons | `su3_component` |
+| **Weak** | SU(2) | W⁺, W⁻, Z⁰ | `su2_component` |
+| **EM** | U(1) | Photon (γ) | `u1_component` |
+| **Unified** | U(3) | **Complex Frame** | `U3Frame` |
+
+#### 🚀 **New Classes & Functions**
+
+```python
+from coordinate_system import (
+    # Core U(3) classes
+    U3Frame,                    # Complete U(3) unitary frame
+    SU3Component,               # SU(3) decomposition
+
+    # Gauge field classes
+    GaugeConnection,            # Gauge potential A_μ
+    FieldStrength,              # Field strength F_μν
+
+    # Symmetry breaking
+    SymmetryBreakingPotential,  # Higgs-type potential
+
+    # Constants
+    C_SPEED,                    # Speed of light
+)
+```
+
+#### 📚 **Documentation**
+
+- **Theory Guide**: `.doc/U3_FRAME_THEORY.md` - Complete mathematical framework
+- **Upgrade Summary**: `UPGRADE_SUMMARY.md` - Detailed comparison with v6.0.1
+- **Demo Program**: `examples/u3_gauge_theory_demo.py` - 9 comprehensive demonstrations
+- **Original Paper**: `复标架与规范场.md` - Theoretical foundation
+
+#### 🎓 **Example: Complete Gauge Theory Workflow**
+
+```python
+from coordinate_system import U3Frame, GaugeConnection, SymmetryBreakingPotential
+import numpy as np
+
+# 1. Create U(3) frame with color phases
+theta_R, theta_G, theta_B = 0.1, 0.2, -0.3
+e1 = np.array([np.exp(1j * theta_R), 0, 0])
+e2 = np.array([0, np.exp(1j * theta_G), 0])
+e3 = np.array([0, 0, np.exp(1j * theta_B)])
+frame = U3Frame(e1, e2, e3)
+
+# 2. Decompose to SU(3) × U(1)
+su3_comp, u1_phase = frame.to_su3_u1()
+print(f"SU(3) det: {np.linalg.det(su3_comp.matrix):.6f}")  # Should be 1
+
+# 3. Create gauge connections
+connection_x = GaugeConnection(
+    su3_component=np.random.randn(8) * 0.1,  # Gluons
+    su2_component=np.random.randn(3) * 0.1,  # W/Z bosons
+    u1_component=0.05+0.02j                  # Photon
+)
+connection_y = GaugeConnection(...)
+
+# 4. Calculate field strength
+F_xy = connection_x.field_strength(connection_y)
+S_YM = F_xy.yang_mills_action()
+Q = F_xy.topological_charge()
+print(f"Yang-Mills action: {S_YM:.6f}")
+print(f"Topological charge: {Q:.6f}")
+
+# 5. Symmetry breaking
+potential = SymmetryBreakingPotential(mu_squared=-1.0)
+frame_vacuum = potential.find_vacuum()
+V_vac = potential.potential(frame_vacuum)
+print(f"Vacuum energy: {V_vac:.6f}")
+
+# 6. Gauge transformations
+frame_u1 = frame.gauge_transform_u1(np.pi/4)
+frame_su2 = frame.gauge_transform_su2((0.1, 0.2, 0.3))
+frame_su3 = frame.gauge_transform_su3(np.random.randn(8) * 0.1)
+
+# 7. Imaginary time evolution
+H = np.diag([1.0, 2.0, 3.0])
+frame_evolved = frame.imaginary_time_evolution(tau=0.5, hamiltonian=H)
+```
+
+#### 🔑 **Key Formulas Implemented**
+
+```
+U(x) = [e₁, e₂, e₃] ∈ U(3)                    [U(3) Frame]
+U(3) = SU(3) × U(1)                           [Decomposition]
+A_μ = A_μ^{SU(3)} + A_μ^{SU(2)} + A_μ^{U(1)}  [Gauge Connection]
+F_μν = ∂_μ A_ν - ∂_ν A_μ + [A_μ, A_ν]         [Field Strength]
+S_YM = -1/(4g²) Tr(F_μν F^μν)                 [Yang-Mills Action]
+U(τ) = exp(-τĤ) U(0)                          [Imaginary Time]
+V(U) = -μ² Tr(U†U) + λ[Tr(U†U)]² + ...       [Symmetry Breaking]
+```
+
+### New Features Summary
+
+- ✅ **Complete U(3) unitary matrix representation**
+- ✅ **Symmetry decomposition: U(3) → SU(3) × SU(2) × U(1)**
+- ✅ **Color phase extraction (Red, Green, Blue)**
+- ✅ **Quaternion ↔ SU(2) correspondence**
+- ✅ **Three gauge transformations (U(1), SU(2), SU(3))**
+- ✅ **Gell-Mann & Pauli matrix implementations**
+- ✅ **Gauge connection A_μ ∈ 𝔲(3)**
+- ✅ **Field strength tensor F_μν**
+- ✅ **Yang-Mills action & topological charge**
+- ✅ **Imaginary time evolution & Wick rotation**
+- ✅ **Symmetry breaking potential & vacuum finder**
+- ✅ **Complete documentation & demos**
+
+### Philosophical Vision
+
+> *"The real part describes the space we inhabit,*
+> *The imaginary part describes the time we traverse,*
+> *The complex frame describes the existence we are."*
+>
+> — From the unified gauge theory framework
+
+---
+
+## 🆕 What's New in v6.0.1 (2025-12-04)
+
+### Classical Spectral Geometry Implementation
+
+**FourierFrame-Based Spectral Geometry** - Complete implementation of **classical geometric spectral analysis** using FourierFrame as the mathematical foundation
+
+> **Important Design Philosophy**:
+>
+> This library follows the progression: **Coordinate System (Geometric Frame) → Curvature Computation → FourierFrame → Spectral Geometry**
+>
+> All implementations are **classical geometric tools** suitable for numerical computation on standard computers. While the mathematical formalism resembles quantum theory, this is purely **classical differential geometry** without quantum physical interpretation.
+
+#### 🎯 **Core Class Renaming (Breaking Change)**
+- **QFrame → FourierFrame**: More descriptive name avoiding confusion with generic "Frame"
+- **QFrameSpectrum → FourierFrameSpectrum**: Consistent naming convention
+- **Backward Compatibility**: All old names (QFrame, QFrameSpectrum) retained as aliases
+
+#### 🌟 **FourierFrame as Mathematical Foundation**
+
+**FourierFrame represents the mathematical language for all spectral geometry formulas:**
+
+**1. FourierFrame Algebra (复标架代数)**
+```python
+# Core transformations
+FourierFrame * e^{iθ}  # Fourier transform (phase rotation)
+FourierFrame * λ       # Conformal transform (scaling)
+e^{tΔ} FourierFrame    # Diffusion evolution (heat equation solution)
+```
+- Complex extension of coordinate frames: FourierFrame = coord3 ⊗ ℂ
+- Mathematical tool for spectral analysis (not quantum states)
+- Laplacian operator: Δ log FourierFrame
+
+**2. IntrinsicGradient (内禀梯度算子)**
+```python
+G_μ = d/dx^μ log FourierFrame(x)
+```
+- **Geometric meaning**: Local frame rotation rate (covariant derivative)
+- Corresponds to connection 1-form in Riemannian geometry
+- Computes curvature via Lie bracket: R_{μν} = [G_μ, G_ν]
+- **Classical object**: No quantum interpretation needed
+
+**3. HeatKernel (热核 - Heat Equation Solution)**
+```python
+∂u/∂t = Δu  (Classical heat equation)
+Tr(e^{tΔ}) ~ (4πt)^{-d/2} [a₀ + a₁t + a₂t² + ...]
+```
+- **FourierFrame evolution**: FourierFrame(x,t) = e^{tΔ} FourierFrame(x,0)
+- **Classical diffusion process** (NOT quantum imaginary time)
+- Heat kernel coefficients encode geometric invariants:
+  - a₀ = Volume of manifold
+  - a₁ ∝ ∫ Scalar curvature
+  - a₂ ∝ ∫ (R² + higher curvature terms)
+- **Application**: ShapeDNA, spectral distances, multi-scale analysis
+
+**4. SpectralDecomposition (谱分解)**
+```python
+Δφ_n = -λ_n φ_n  (Laplacian eigenvalue problem)
+FourierFrame(x) = Σ_n c_n φ_n(x) FourierFrame_n
+```
+- **FourierFrame as eigenstates**: Expansion in Laplacian eigenbasis
+- **Shape DNA**: Eigenvalue spectrum {λ_n} characterizes manifold geometry
+- Weyl asymptotic law: N(λ) ~ (1/4π) Area(M) λ (2D case)
+- **Classical spectral theory**: "Can one hear the shape of a drum?" (Kac, 1966)
+
+**5. BerryPhase (几何相位)**
+```python
+γ = ∮_C G_μ dx^μ
+```
+- **Classical geometric phase**: Parallel transport in frame bundle
+- **NOT quantum Berry phase** (though mathematically analogous)
+- Path-independent topological quantity
+- Related to Chern number via Stokes theorem
+
+**6. ChernNumber (陈数)**
+```python
+c₁ = (1/2π) ∬_M R_{μν} dS
+```
+- **Topological invariant** of fiber bundle
+- Integer-valued geometric index
+- Characterizes global geometry of FourierFrame field
+- **Classical topology**: No quantum Hall effect interpretation here
+
+**7. CurvatureFromFrame (曲率计算)**
+```python
+R_{μν} = [G_μ, G_ν]
+K = -Im(R_{xy})  (Gaussian curvature, for complex frames)
+```
+- Curvature computed from FourierFrame field
+- Intrinsic gradient formulation
+- **Classical differential geometry**
+
+#### 📐 **Mathematical Framework (Classical)**
+
+**Based on:**
+- Differential geometry (Riemannian manifolds, curvature)
+- Spectral theory (Laplacian eigenvalue problems)
+- Fiber bundle theory (frame bundles, connections)
+- Lie algebra (commutators, curvature 2-forms)
+
+**Theoretical Limitations:**
+- ⚠️ **Classical only**: No quantum superposition, entanglement, or measurement
+- ⚠️ **Computational**: Requires discretization (finite difference, spectral methods)
+- ⚠️ **Not quantum computing**: All operations run on classical computers
+- ⚠️ Forms **resemble** quantum theory but physical interpretation is purely geometric
+
+#### 🔬 **Core Formulas Summary**
+```
+FourierFrame = coord3 ⊗ ℂ                          [Mathematical Foundation]
+G_μ = d/dx^μ log FourierFrame(x)                   [Intrinsic Gradient]
+R_{μν} = [G_μ, G_ν]                                [Curvature]
+Δ log FourierFrame = ∂²/∂x² + ∂²/∂y²             [Laplacian]
+e^{tΔ} FourierFrame = Heat diffusion evolution     [Heat Kernel]
+Δφ_n = -λ_n φ_n                                   [Spectral Decomposition]
+FourierFrame = Σ_n c_n φ_n FourierFrame_n          [Eigenbasis Expansion]
+γ = ∮ G_μ dx^μ                                    [Geometric Phase]
+c₁ = (1/2π) ∬ R_{μν} dS                           [Chern Number]
+```
+
+### Breaking Changes
+
+- `QFrame` → `FourierFrame` (old name works as alias)
+- `QFrameSpectrum` → `FourierFrameSpectrum` (old name works as alias)
+- `qframes.py` deleted (functionality moved to `frames.py`)
+- Quantum-related classes removed (QuantumState, PathIntegral, Dirac notation)
+
+### Migration Guide
+
+```python
+# Old code (still works with aliases):
+from coordinate_system import QFrame, QFrameSpectrum
+
+# New code (recommended):
+from coordinate_system import FourierFrame, FourierFrameSpectrum
+
+# Full classical spectral geometry toolkit:
+from coordinate_system import (
+    FourierFrame, FourierFrameSpectrum,
+    IntrinsicGradient, CurvatureFromFrame,
+    BerryPhase, ChernNumber,
+    SpectralDecomposition, HeatKernel,
+    FrequencyProjection, FrequencyBandState,
+)
+```
+
+**Example: Heat Kernel Diffusion**
+```python
+from coordinate_system import FourierFrame, HeatKernel
+
+# Create a FourierFrame field
+frame_field = [[FourierFrame(q_factor=1.0 + 0.1j*(i+j))
+                for j in range(10)] for i in range(10)]
+
+# Initialize heat kernel
+heat = HeatKernel(frame_field)
+
+# Evolve using classical diffusion (NOT quantum evolution)
+t = 0.1  # Diffusion time
+evolved_field = heat.evolution_operator(t, kappa=1.0)
+
+# Compute heat kernel trace (geometric invariant)
+trace = heat.trace(t)
+
+# Asymptotic expansion (extracts curvature information)
+asymptotic = heat.asymptotic_expansion(t, order=2)
+```
+
+---
+
+## 🆕 What's New in v6.0.0 (2025-12-03)
+
+### Major Architecture Refactoring
+
+**Unified Differential Geometry Module** - Complete integration of curvature computation methods
+
+- **Merged Module**: `differential_geometry.py` now contains both classical and intrinsic gradient methods
+- **Dual Method Support**:
+  - Intrinsic gradient method (default): `compute_gaussian_curvature()`, `compute_mean_curvature()`
+  - Classical method: `gaussian_curvature_classical()`, `mean_curvature_classical()`
+- **Backward Compatibility**: Old function names still work as aliases
+- **High-Order Finite Differences**: 5-point formulas with O(h⁴) accuracy
+- **All English Documentation**: Complete internationalization for global distribution
+
+**Enhanced Visualization Module** - Professional surface and curvature rendering
+
+- **New Class**: `SurfaceVisualizer` with curvature coloring support
+- **Curvature Visualization**: Diverging colormap (blue-white-red) for Gaussian/Mean curvature
+- **Surface Frame Fields**: RGB-coded tangent frames (red=u direction, green=v direction, blue=normal)
+- **Enhanced Curve Rendering**: Binormal support, improved styling
+- **Integration**: Direct support for differential_geometry surfaces
+- **Convenience Functions**: `visualize_surface()` for quick visualization
+
+**Runtime Handedness Switching** - Flexible coordinate system control
+
+- **Global Control**: Switch between left-handed and right-handed systems at runtime
+- **API Functions**: `set_handedness('left'/'right')`, `get_handedness()`, `is_left_handed()`
+- **Automatic Adaptation**: All vector operations, quaternions, and Frenet frames adjust automatically
+- **Cross-Platform Compatibility**: Seamlessly work with DirectX (left-handed) and OpenGL (right-handed) conventions
+
+---
+
+## Features
+
+### Core Components
+
+**C++ Performance Layer:**
+- **vec3** - 3D vector with comprehensive operations
+- **vec2** - 2D vector for parametric coordinates
+- **quat** - Quaternion for 3D rotations
+- **coord3** - Complete 3D coordinate system (position, rotation, scale)
+
+**Advanced Mathematics Modules:**
+- **differential_geometry** - Surface analysis with dual curvature methods
+- **frames** - Complex frame algebra with spectral geometry
+- **visualization** - Professional 3D rendering for geometry and curvature
+- **curve_interpolation** - C2-continuous curve and frame interpolation
+
+### Operations
+
+- Vector arithmetic (+, -, *, /)
+- Dot product, cross product (runtime switchable handedness)
+- Vector projection, reflection
+- Linear interpolation (lerp)
+- Spherical linear interpolation (slerp)
+- Coordinate system transformations
+- Euler angle conversion
+- Gaussian and mean curvature computation
+- Spectral analysis and Fourier transforms
+- **Runtime handedness control** (left/right-handed systems)
+- **Spectral geometry analysis** (Berry phase, Chern number, heat kernel)
+
+### Performance
+
+- Written in optimized C++17
+- Python bindings via pybind11
+- Over 1,000,000 operations per second
+- GPU acceleration for spectral transforms (optional)
+
+### Platform Support
+
+- ✅ Windows (7, 10, 11)
+- ✅ Linux (Ubuntu, Debian, CentOS, etc.)
+- ✅ macOS (10.14+)
+
+---
+
+## 📚 Documentation
+
+### Mathematical Foundation
+
+For a comprehensive understanding of the mathematical principles behind coordinate systems, vectors, quaternions, and differential geometry, see our detailed guide:
+
+**[📖 Mathematical Foundation of Coordinate Systems](https://github.com/panguojun/Coordinate-System)**
+
+### Module Documentation
+
+- [Curve Interpolation Guide](CURVE_INTERPOLATION_README.md)
+- [C2 Interpolation Guide](C2_INTERPOLATION_GUIDE.md)
+
+---
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install coordinate-system
+```
+
+### From Source
+
+```bash
+git clone https://github.com/panguojun/Coordinate-System.git
+cd Coordinate-System
+pip install .
+```
+
+---
+
+## Quick Start
+
+```python
+from coordinate_system import vec3, quat, coord3
+
+# Create vectors
+v1 = vec3(1, 2, 3)
+v2 = vec3(4, 5, 6)
+
+# Vector operations
+v3 = v1 + v2              # Addition: vec3(5, 7, 9)
+dot = v1.dot(v2)          # Dot product: 32.0
+cross = v1.cross(v2)      # Cross product (left-handed)
+length = v1.length()      # Length: 3.742
+normalized = v1.normcopy() # Unit vector
+
+# Quaternion rotation
+axis = vec3(0, 0, 1)      # Z axis
+q = quat(1.5708, axis)    # 90 degrees rotation
+rotated = q * v1          # Rotate v1
+
+# Coordinate systems
+frame = coord3.from_angle(1.57, vec3(0, 0, 1))  # Frame rotated 90°
+world_pos = v1 * frame    # Transform to world space
+local_pos = world_pos / frame  # Transform back to local
+
+# Differential geometry
+from coordinate_system import Sphere, compute_gaussian_curvature
+
+sphere = Sphere(radius=1.0)
+K = compute_gaussian_curvature(sphere, u=0.5, v=0.5)  # K = 1.0 for unit sphere
+
+# Visualization
+from coordinate_system import visualize_surface
+
+visualize_surface(sphere, curvature_type='gaussian', show_colorbar=True)
+
+# Spectral geometry (NEW in 6.0.1)
+from coordinate_system import (
+    FourierFrame, IntrinsicGradient,
+    CurvatureFromFrame, BerryPhase
+)
+
+# Create frame field
+frame_field = [[FourierFrame(q_factor=1.0 + 0.1j*(i+j))
+                for j in range(10)] for i in range(10)]
+
+# Compute intrinsic gradient
+grad_op = IntrinsicGradient(frame_field)
+G_x = grad_op.compute_at((5, 5), 0)  # ∂_x log FourierFrame
+
+# Compute curvature
+curv_calc = CurvatureFromFrame(frame_field)
+K = curv_calc.gaussian_curvature(5, 5)
+
+# Compute Berry phase
+berry = BerryPhase(grad_op)
+path = [(1, 1), (1, 8), (8, 8), (8, 1), (1, 1)]
+gamma = berry.compute_along_path(path)  # γ = ∮ G_μ dx^μ
+```
+
+---
+
+## Module Guide
+
+### Complex Frame Module (NEW in 6.0.1)
+
+```python
+from coordinate_system import (
+    # Core classes
+    FourierFrame, QuantumState, PathIntegral, FourierFrameSpectrum,
+
+    # Spectral geometry core
+    IntrinsicGradient, CurvatureFromFrame,
+    BerryPhase, ChernNumber,
+    SpectralDecomposition, HeatKernel,
+    FrequencyProjection, FrequencyBandState,
+
+    # Dirac notation (optional export)
+    DiracBra, DiracKet, bra, ket,
+
+    # Spectral transforms
+    spectral_transform, inverse_spectral_transform,
+
+    # Constants
+    HBAR, GPU_AVAILABLE,
+)
+
+# Create complex frame
+cf = FourierFrame(base_coord=coord3(), q_factor=1.0+0.5j)
+
+# Fourier transform (phase rotation)
+cf_ft = cf.fourier_transform(theta=np.pi/2)  # FourierFrame * e^{iθ}
+
+# Conformal transform (scaling)
+cf_conf = cf.conformal_transform(2.0)  # FourierFrame * λ
+
+# Intrinsic gradient operator
+frame_field = [[FourierFrame(q_factor=1.0 + 0.1j*(i+j))
+                for j in range(16)] for i in range(16)]
+grad_op = IntrinsicGradient(frame_field)
+G_x = grad_op.compute_at((8, 8), 0)  # G_x = ∂_x log FourierFrame
+G_y = grad_op.compute_at((8, 8), 1)  # G_y = ∂_y log FourierFrame
+
+# Curvature from frame field
+curv_calc = CurvatureFromFrame(frame_field)
+K = curv_calc.gaussian_curvature(8, 8)  # Gaussian curvature
+H = curv_calc.mean_curvature(8, 8)      # Mean curvature
+
+# Berry phase
+berry = BerryPhase(grad_op)
+path = [(4, 4), (4, 12), (12, 12), (12, 4), (4, 4)]
+gamma = berry.compute_along_path(path, closed=True)  # γ = ∮ G_μ dx^μ
+
+# Chern number (topological invariant)
+chern = ChernNumber(curv_calc)
+c1 = chern.compute()  # c₁ = (1/2π) ∬ R_{μν} dS
+
+# Spectral decomposition
+# First create a FourierFrameSpectrum from coordinate field
+import numpy as np
+coord_field = [[coord3(vec3(i, j, 0)) for j in range(16)] for i in range(16)]
+spectrum = spectral_transform(coord_field)
+
+decomp = SpectralDecomposition(spectrum)
+eigenvalues, _ = decomp.compute_eigenspectrum()
+shape_dna = decomp.shape_dna(n_modes=50)  # First 50 eigenvalues
+
+# Heat kernel
+heat = HeatKernel(decomp)
+trace_t = heat.trace(t=0.1)  # Tr(e^{-tK̂})
+asymp = heat.asymptotic_expansion(t=0.1, order=3)
+
+# Frequency projection
+freq_proj = FrequencyProjection(decomp)
+frequencies = freq_proj.compute_frequencies()  # ω_n = √|κ_n| · sign(κ_n)
+band_state = freq_proj.project_to_band(omega_min=0.5, omega_max=2.0)
+```
+
+### Differential Geometry Module
+
+```python
+from coordinate_system import (
+    # Surface classes
+    Surface, Sphere, Torus,
+
+    # Intrinsic gradient method (default, more accurate)
+    compute_gaussian_curvature,
+    compute_mean_curvature,
+    compute_riemann_curvature,
+    compute_all_curvatures,
+
+    # Classical method (high-order finite differences)
+    gaussian_curvature_classical,
+    mean_curvature_classical,
+    principal_curvatures_classical,
+
+    # Method comparison
+    compare_methods,
+)
+
+# Create a surface
+sphere = Sphere(radius=2.0)
+torus = Torus(major_radius=3.0, minor_radius=1.0)
+
+# Compute curvature (intrinsic gradient method)
+K = compute_gaussian_curvature(sphere, u=0.5, v=0.5)
+H = compute_mean_curvature(sphere, u=0.5, v=0.5)
+
+# Use classical method
+K_classical = gaussian_curvature_classical(sphere, u=0.5, v=0.5)
+
+# Compare methods
+results = compare_methods(sphere, u=0.5, v=0.5)
+print(f"Intrinsic: K={results['intrinsic']['K']:.6f}")
+print(f"Classical: K={results['classical']['K']:.6f}")
+```
+
+### Visualization Module
+
+```python
+from coordinate_system import (
+    CoordinateSystemVisualizer,
+    CurveVisualizer,
+    SurfaceVisualizer,
+    visualize_coord_system,
+    visualize_curve,
+    visualize_surface,
+)
+
+# Quick surface visualization with curvature
+from coordinate_system import Sphere
+
+sphere = Sphere(radius=1.0)
+visualize_surface(
+    sphere,
+    curvature_type='gaussian',  # or 'mean'
+    show_colorbar=True,
+    show_normals=False,
+    show_frames=True,
+    title='Sphere with Gaussian Curvature'
+)
+```
+
+---
+
+## Advanced Examples
+
+### Spectral Geometry Analysis (NEW)
+
+```python
+from coordinate_system import (
+    FourierFrame, IntrinsicGradient,
+    CurvatureFromFrame, BerryPhase, ChernNumber,
+    SpectralDecomposition, spectral_transform
+)
+import numpy as np
+
+# Create a complex frame field (wave-like pattern)
+nx, ny = 32, 32
+frame_field = []
+for i in range(ny):
+    row = []
+    for j in range(nx):
+        phase = 2*np.pi*(i/ny + j/nx)
+        amplitude = 1.0 + 0.3*np.sin(2*np.pi*i/ny)*np.cos(2*np.pi*j/nx)
+        q = amplitude * np.exp(1j * phase)
+        row.append(FourierFrame(q_factor=q))
+    frame_field.append(row)
+
+# 1. Intrinsic gradient
+grad_op = IntrinsicGradient(frame_field)
+print("=== Intrinsic Gradient ===")
+for i in range(5, 28, 8):
+    for j in range(5, 28, 8):
+        G_x = grad_op.compute_at((i, j), 0)
+        G_y = grad_op.compute_at((i, j), 1)
+        print(f"  ({i},{j}): G_x={G_x:.4f}, G_y={G_y:.4f}")
+
+# 2. Curvature
+curv_calc = CurvatureFromFrame(frame_field)
+print("\n=== Curvature ===")
+K_values = []
+for i in range(5, 28, 4):
+    for j in range(5, 28, 4):
+        K = curv_calc.gaussian_curvature(i, j)
+        K_values.append(K)
+        if abs(K) > 0.01:
+            print(f"  ({i},{j}): K={K:.6f}")
+print(f"  Average |K|: {np.mean(np.abs(K_values)):.6f}")
+
+# 3. Berry phase
+berry = BerryPhase(grad_op)
+print("\n=== Berry Phase ===")
+# Square path
+path_square = [(8, 8), (8, 24), (24, 24), (24, 8), (8, 8)]
+gamma_square = berry.compute_along_path(path_square, closed=True)
+print(f"  Square path: γ = {gamma_square:.6f}")
+
+# Circular path
+path_circle = []
+for theta in np.linspace(0, 2*np.pi, 32):
+    i = int(16 + 8*np.cos(theta))
+    j = int(16 + 8*np.sin(theta))
+    path_circle.append((i, j))
+gamma_circle = berry.compute_along_path(path_circle, closed=True)
+print(f"  Circular path: γ = {gamma_circle:.6f}")
+
+# 4. Chern number
+chern = ChernNumber(curv_calc)
+c1 = chern.compute()
+print(f"\n=== Topological Invariant ===")
+print(f"  First Chern number: c₁ = {c1}")
+
+# 5. Spectral decomposition
+coord_field = [[coord3(vec3(j, i, np.sin(2*np.pi*j/nx)*np.cos(2*np.pi*i/ny)))
+                for j in range(nx)] for i in range(ny)]
+spectrum = spectral_transform(coord_field)
+decomp = SpectralDecomposition(spectrum)
+eigenvalues, _ = decomp.compute_eigenspectrum()
+
+print(f"\n=== Spectral Decomposition ===")
+print(f"  Total modes: {len(eigenvalues)}")
+print(f"  Top 10 eigenvalues:")
+for i, ev in enumerate(eigenvalues[:10]):
+    print(f"    λ_{i} = {ev:.6f}")
+
+# Shape DNA
+shape_dna = decomp.shape_dna(n_modes=50)
+print(f"  Shape DNA (first 5): {shape_dna[:5]}")
+
+# Weyl counting
+n_below_1 = decomp.weyl_counting(kappa=1.0)
+print(f"  Eigenvalues < 1.0: {n_below_1}")
+
+print("\n" + "="*60)
+print("Spectral Geometry Analysis Complete!")
+print("="*60)
+```
+
+---
+
+## Performance
+
+Benchmark on Intel i7-10700K @ 3.8GHz:
+
+| Operation | Ops/second | Notes |
+|-----------|-----------|-------|
+| Vector addition | 5,200,000 | C++ optimized |
+| Dot product | 4,800,000 | C++ optimized |
+| Cross product | 3,500,000 | C++ optimized |
+| Normalize | 2,100,000 | C++ optimized |
+| Quaternion rotation | 1,800,000 | C++ optimized |
+| Gaussian curvature | 85,000 | Python + NumPy |
+| Spectral transform (CPU) | 1,200/sec | 64×64 field |
+| Spectral transform (GPU) | 12,000/sec | 64×64 field, CuPy |
+| Intrinsic gradient | 180,000 | Python + NumPy |
+| Berry phase (path) | 25,000 | Python |
+
+---
+
+## Changelog
+
+### Version 6.0.3 (2025-12-04)
+- 🚀 **U(3) GAUGE THEORY FRAMEWORK**: Complete implementation of unified gauge field theory
+- ✨ **U3Frame Class**: Full 3×3 unitary matrix representation (U(3) group)
+- ✨ **Symmetry Decomposition**: U(3) → SU(3) × SU(2) × U(1) breaking chain
+- 🎨 **Color-Space Duality**: RGB color phases ↔ Spatial axes correspondence
+- 🌟 **GaugeConnection**: Unified gauge potential A_μ = A^{SU(3)} + A^{SU(2)} + A^{U(1)}
+- 🌟 **FieldStrength**: Yang-Mills field tensor F_μν with action & topological charge
+- 🔬 **Gell-Mann Matrices**: Complete SU(3) generators (8 matrices)
+- 🔬 **Pauli Matrices**: SU(2) generators (3 matrices)
+- 🎯 **Quaternion ↔ SU(2)**: Direct correspondence interface
+- ⚛️ **Imaginary Time Evolution**: U(τ) = exp(-τĤ) U(0) with Wick rotation
+- 🔮 **Symmetry Breaking**: Higgs-type potential with vacuum state finder
+- 📚 **Complete Documentation**: Theory guide, upgrade summary, demo programs
+- 🗑️ **Cleanup**: Removed obsolete build files and created .gitignore
+
+### Version 6.0.1 (2025-12-04)
+- 🎯 **COMPLETE SPECTRAL GEOMETRY**: Full implementation of quantum spectral geometry framework
+- ✨ **FourierFrame Renaming**: QFrame → FourierFrame (clearer naming)
+- 🌟 **IntrinsicGradient**: G_μ = d/dx^μ log FourierFrame(x)
+- 🌟 **CurvatureFromFrame**: R_{μν} = [G_μ, G_ν]
+- 🌟 **BerryPhase**: γ = ∮ G_μ dx^μ (geometric phase)
+- 🌟 **ChernNumber**: c₁ = (1/2π) ∬ R_{μν} dS (topological invariant)
+- 🌟 **SpectralDecomposition**: Eigenvalue decomposition, Shape DNA
+- 🌟 **HeatKernel**: Tr(e^{-tK̂}) with asymptotic expansion
+- 🌟 **FrequencyProjection**: Geometric frequency space and band projection
+- 📐 **Mathematical Rigor**: Fiber bundle, Lie algebra, spectral geometry
+- 🔬 **Complete Theory**: Based on unified quantum spectral geometry document
+- 🗑️ **Cleanup**: Removed obsolete qframes.py file
+
+### Version 6.0.0 (2025-12-03)
+- 🔄 **MAJOR REFACTORING**: Unified module architecture
+- ✨ **Merged differential_geometry**: Combined curvature.py functionality with dual-method support
+- ✨ **Merged frames**: Integrated quantum frame modules into unified framework
+- ✨ **Enhanced visualization**: Added SurfaceVisualizer with curvature coloring
+- 🔀 **Runtime handedness control**: Switch between left/right-handed systems on the fly
+- 📚 **Full English documentation**: Complete internationalization
+- ⚡ **Improved API**: Cleaner imports and more intuitive method names
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+Copyright (c) 2024-2025 PanGuoJun
+
+---
+
+## Author
+
+**PanGuoJun** (romeosoft)
+
+- Email: 18858146@qq.com
+- GitHub: [panguojun/Coordinate-System](https://github.com/panguojun/Coordinate-System)
+
+---
+
+## Links
+
+- **PyPI**: https://pypi.org/project/coordinate-system/
+- **GitHub**: https://github.com/panguojun/Coordinate-System
+- **Mathematical Foundation**: [MATHEMATICAL_FOUNDATION.md](https://github.com/panguojun/Coordinate-System/blob/main/MATHEMATICAL_FOUNDATION.md)
+- **Issues**: https://github.com/panguojun/Coordinate-System/issues
+
+---
+
+## Acknowledgments
+
+Built with ❤️ using:
+- **C++17** - High-performance core
+- **pybind11** - Python-C++ bindings
+- **NumPy** - Numerical computations
+- **Matplotlib** - Visualization
+- **CuPy** - Optional GPU acceleration
+
+---
+
+**Note**: For the latest updates and documentation, visit the [GitHub repository](https://github.com/panguojun/Coordinate-System).