Metadata-Version: 2.1
Name: coordinate_system
Version: 8.2.0
Summary: High-performance 3D coordinate system library with unified differential geometry, frame algebra, and topological-physics application APIs (friction, velocity-decay, non-Newtonian viscosity, sunspot cycle, geomagnetic reversal)
Home-page: https://github.com/panguojun/Coordinate-System
Author: Pan Guojun
Author-email: Pan Guojun <18858146@qq.com>
License: MIT
Project-URL: Homepage, https://github.com/panguojun/Coordinate-System
Project-URL: Documentation, https://github.com/panguojun/Coordinate-System/blob/main/README.md
Project-URL: Repository, https://github.com/panguojun/Coordinate-System
Project-URL: Bug Reports, https://github.com/panguojun/Coordinate-System/issues
Project-URL: DOI, https://doi.org/10.5281/zenodo.14435613
Keywords: 3d,math,vector,quaternion,coordinate-system,geometry,differential-geometry,curvature,spectral-analysis,topological-physics,cfut,unified-field-theory,complex-frame
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 :: Scientific/Engineering :: Physics
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/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Authors: Pan Guojun  
Version: 8.1.0  
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.


### Topological Physics APIs

```python
from coordinate_system import (
    predict_dynamic_stall,
    estimate_non_newtonian,
    mass_from_winding,
    infer_winding_from_mass,
    nearest_dm_shell,
)

stall = predict_dynamic_stall(cl_max_static=1.35, delta_alpha_deg=15.0)
rheo = estimate_non_newtonian(mu_reference_pa_s=0.0035, mu_observed_pa_s=0.0052)
proton = mass_from_winding(53861)
n_e = infer_winding_from_mass(0.51099895e6)
dm = nearest_dm_shell(6.2e3)

print(stall, rheo, proton.mass_MeV, n_e, dm)
```

Notes:
- `topological_physics` now focuses on application-oriented interfaces.
- Low-level field-equation internals and raw coupling parameters are not part of the public API.

---

## 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)
  topological_physics.py         # Application-level topological physics APIs
  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
  topological_physics.py         # Public-safe topological physics formulas
```

---

## 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

### v8.1.0 (2026-03-04)
- Unified public physics interfaces into `topological_physics.py`.
- Switched to application-level APIs for dynamic-stall, non-Newtonian flow, particle mass, and DM shell scans.
- Removed low-level field-equation and raw coupling symbols from top-level public exports.

### v8.0.0 (2026-03-04)
- Added `topological_physics` module with public-safe CFUT formula interfaces.
- Added shared-parameter mass/winding APIs (`mass_from_winding_eV`, `winding_from_mass`).
- Added dynamic-stall and TME helper interfaces (`nmax_dynamic_stall`, `tme_conductance`).
- Restricted top-level export surface to avoid exposing secret field-equation entry points.

### 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
