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).
