coordinate-system 7.1.2
High-performance 3D coordinate system library with unified differential geometry, quantum frame algebra, and Christmas Equation (CFUT)
License: MIT
Requires Python: >=3.7
Keywords: 3d, math, vector, quaternion, coordinate-system, geometry, differential-geometry, curvature, spectral-analysis, christmas-equation, cfut, unified-field-theory, complex-frame

# 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/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Authors: Pan Guojun  
Version: 7.1.2  
License: MIT  
DOI: https://doi.org/10.5281/zenodo.14435613

---

## Highlights

- C++ math core: vec3, quat, coord3
- Intrinsic gradient curvature (default)
- Classical finite-difference curvature (reference)
- Analytical fast path for Sphere/Torus and surfaces that provide derivatives
- Caching for repeated samples
- Spectral geometry and U(3) frame utilities

---

## Installation

```bash
pip install coordinate-system
```

---

## Quick Start

### Vectors and Frames

```python
from coordinate_system import vec3, quat, coord3

v1 = vec3(1, 2, 3)
v2 = vec3(4, 5, 6)
dot = v1.dot(v2)
cross = v1.cross(v2)

q = quat(1.5708, vec3(0, 0, 1))  # 90 degrees around Z
rotated = q * v1

frame = coord3.from_angle(1.57, vec3(0, 0, 1))
world_pos = v1 * frame
local_pos = world_pos / frame
```

### Curvature (Differential Geometry)

```python
from coordinate_system import Sphere, compute_gaussian_curvature, compute_mean_curvature

sphere = Sphere(radius=1.0)
K = compute_gaussian_curvature(sphere, u=0.5, v=0.5)
H = compute_mean_curvature(sphere, u=0.5, v=0.5)
print(K, H)
```

Notes:
- Intrinsic method returns signed mean curvature.
- Classical method returns absolute mean curvature.

---

## Curvature APIs

Intrinsic (default):
- compute_gaussian_curvature(surface, u, v, step_size=1e-3)
- compute_mean_curvature(surface, u, v, step_size=1e-3)
- compute_riemann_curvature(surface, u, v, step_size=1e-3)
- compute_curvature_tensor(surface, u, v, step_size=1e-3)

Classical (reference):
- gaussian_curvature_classical(surface, u, v, step_size=1e-3)
- mean_curvature_classical(surface, u, v, step_size=1e-3)

---

## Methods

### Intrinsic Gradient (default)
Computes curvature from the intrinsic frame and the gradient of the normal field.
This path is usually faster and stable on smooth surfaces.

### Classical Finite Differences
Uses 5-point stencils to compute first and second derivatives and then builds
the fundamental forms. This is useful as a numerical reference.

---

## Project Layout

```
coordinate_system/
  coordinate_system.pyd/.so      # C++ core (vec3, quat, coord3)
  complex_geometric_physics.py   # Complex geometric physics module
  spectral_geometry.py           # FourierFrame, spectral analysis
  u3_frame.py                    # U3Frame, gauge field theory
  differential_geometry.py       # Surface curvature
  visualization.py               # 3D visualization
  curve_interpolation.py         # C2-continuous interpolation
```

---

## Performance Notes

Performance depends on hardware and step size. For local benchmarks:
- vec3 microbenchmarks: `bench/compare_perf.py`
- curvature examples: `examples/curvature_computation.py`

---

## Changelog

### v7.1.2 (2026-02-09)
- Intrinsic curvature sampling reuse for numeric surfaces (13 position calls per point)
- Documentation updates and benchmark clarity

### v7.1.1 (2026-02-05)
- Analytical curvature fast path (Sphere/Torus and surfaces with derivatives)
- Caching for curvature calculators and last-call results
- AVX2 / fast-math enabled in native build config

---

## License

MIT License - Copyright (c) 2024-2026 Pan Guojun

---

## Links

- PyPI: https://pypi.org/project/coordinate-system/
- GitHub: https://github.com/panguojun/Coordinate-System
- Email: 18858146@qq.com