Metadata-Version: 2.1
Name: coordinate_system
Version: 6.0.1
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.1
**License:** MIT

---

## 🆕 What's New in v6.0.1 (2025-12-04)

### Classical Spectral Geometry Implementation

**ComplexFrame-Based Spectral Geometry** - Complete implementation of **classical geometric spectral analysis** using ComplexFrame as the mathematical foundation

> **Important Design Philosophy**:
>
> This library follows the progression: **Coordinate System (Geometric Frame) → Curvature Computation → ComplexFrame → 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 → ComplexFrame**: More descriptive name avoiding confusion with generic "Frame"
- **QFrameSpectrum → ComplexFrameSpectrum**: Consistent naming convention
- **Backward Compatibility**: All old names (QFrame, QFrameSpectrum) retained as aliases

#### 🌟 **ComplexFrame as Mathematical Foundation**

**ComplexFrame represents the mathematical language for all spectral geometry formulas:**

**1. ComplexFrame Algebra (复标架代数)**
```python
# Core transformations
ComplexFrame * e^{iθ}  # Fourier transform (phase rotation)
ComplexFrame * λ       # Conformal transform (scaling)
e^{tΔ} ComplexFrame    # Diffusion evolution (heat equation solution)
```
- Complex extension of coordinate frames: ComplexFrame = coord3 ⊗ ℂ
- Mathematical tool for spectral analysis (not quantum states)
- Laplacian operator: Δ log ComplexFrame

**2. IntrinsicGradient (内禀梯度算子)**
```python
G_μ = d/dx^μ log ComplexFrame(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² + ...]
```
- **ComplexFrame evolution**: ComplexFrame(x,t) = e^{tΔ} ComplexFrame(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)
ComplexFrame(x) = Σ_n c_n φ_n(x) ComplexFrame_n
```
- **ComplexFrame 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 ComplexFrame 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 ComplexFrame 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**
```
ComplexFrame = coord3 ⊗ ℂ                          [Mathematical Foundation]
G_μ = d/dx^μ log ComplexFrame(x)                   [Intrinsic Gradient]
R_{μν} = [G_μ, G_ν]                                [Curvature]
Δ log ComplexFrame = ∂²/∂x² + ∂²/∂y²             [Laplacian]
e^{tΔ} ComplexFrame = Heat diffusion evolution     [Heat Kernel]
Δφ_n = -λ_n φ_n                                   [Spectral Decomposition]
ComplexFrame = Σ_n c_n φ_n ComplexFrame_n          [Eigenbasis Expansion]
γ = ∮ G_μ dx^μ                                    [Geometric Phase]
c₁ = (1/2π) ∬ R_{μν} dS                           [Chern Number]
```

### Breaking Changes

- `QFrame` → `ComplexFrame` (old name works as alias)
- `QFrameSpectrum` → `ComplexFrameSpectrum` (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 ComplexFrame, ComplexFrameSpectrum

# Full classical spectral geometry toolkit:
from coordinate_system import (
    ComplexFrame, ComplexFrameSpectrum,
    IntrinsicGradient, CurvatureFromFrame,
    BerryPhase, ChernNumber,
    SpectralDecomposition, HeatKernel,
    FrequencyProjection, FrequencyBandState,
)
```

**Example: Heat Kernel Diffusion**
```python
from coordinate_system import ComplexFrame, HeatKernel

# Create a ComplexFrame field
frame_field = [[ComplexFrame(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 (
    ComplexFrame, IntrinsicGradient,
    CurvatureFromFrame, BerryPhase
)

# Create frame field
frame_field = [[ComplexFrame(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 ComplexFrame

# 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
    ComplexFrame, QuantumState, PathIntegral, ComplexFrameSpectrum,

    # 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 = ComplexFrame(base_coord=coord3(), q_factor=1.0+0.5j)

# Fourier transform (phase rotation)
cf_ft = cf.fourier_transform(theta=np.pi/2)  # ComplexFrame * e^{iθ}

# Conformal transform (scaling)
cf_conf = cf.conformal_transform(2.0)  # ComplexFrame * λ

# Intrinsic gradient operator
frame_field = [[ComplexFrame(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 ComplexFrame
G_y = grad_op.compute_at((8, 8), 1)  # G_y = ∂_y log ComplexFrame

# 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 ComplexFrameSpectrum 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 (
    ComplexFrame, 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(ComplexFrame(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.1 (2025-12-04)
- 🎯 **COMPLETE SPECTRAL GEOMETRY**: Full implementation of quantum spectral geometry framework
- ✨ **ComplexFrame Renaming**: QFrame → ComplexFrame (clearer naming)
- 🌟 **IntrinsicGradient**: G_μ = d/dx^μ log ComplexFrame(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).
