Metadata-Version: 2.1
Name: coordinate_system
Version: 10.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: 10.2.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 ComplexFrame internal-gauge utilities
- ComplexFrame theory observables: conformal Einstein tensor, CS current, CS-gradient tensor
- Clear CFUT layering: `coord3` for geometry, `ComplexFrame` for the internal complex layer
- Topological-physics lambda utilities: structural benchmark, low-energy matching, and phenomenological running models

---

## 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,
    lambda_reference_benchmark,
    lambda_power_law_running,
)

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)
lam0 = lambda_reference_benchmark()
lam_run = lambda_power_law_running(energy_ev=1.0, beta=0.176)

print(stall, rheo, proton.mass_MeV, n_e, dm, lam0.lambda_0, lam_run.lambda_value)
```

Notes:
- `topological_physics` now focuses on application-oriented interfaces.
- The new `lambda_*` helpers expose physical-method interfaces for the topological coupling without claiming a geometry-only derivation of its numerical value.
- Low-level field-equation internals remain hidden; public APIs expose structure-level benchmarks and phenomenological running models instead.

### ComplexFrame Numerical Interfaces

```python
from coordinate_system import ComplexFrame, ComplexFrameField, GaugeConnection
import numpy as np

def frame_sampler(x):
    x = np.asarray(x, dtype=float)
    e1 = np.array([1.0 + 0.10j * x[0], 0.02 * x[1], 0.0], dtype=complex)
    e2 = np.array([0.0, 1.0 + 0.08j * x[1], 0.03 * x[2]], dtype=complex)
    e3 = np.array([0.01 * x[0], 0.0, 1.0 + 0.06j * x[2]], dtype=complex)
    return ComplexFrame(e1, e2, e3, ensure_unitary=True)

def gauge_sampler(x):
    x = np.asarray(x, dtype=float)
    return [
        GaugeConnection(su3_component=np.full(8, 0.01 * (1.0 + x[0]))),
        GaugeConnection(su2_component=np.array([0.02, 0.01 * (1.0 + x[1]), 0.0])),
        GaugeConnection(u1_component=0.03j * (1.0 + x[2])),
    ]

field = ComplexFrameField(frame_sampler=frame_sampler, gauge_sampler=gauge_sampler)
x0 = np.array([0.1, -0.2, 0.3])

G_conf = field.einstein_conformal_tensor(x0)
curv = field.complex_curvature_package(x0)
G_cf = field.complex_einstein_tensor(x0)
Q = curv.encoding_tensor
P = field.pontryagin_density(x0)
flow = field.cs_flow_package(x0)
K = flow.cs_current
grad_K = flow.symmetric_gradient
lhs = field.minimal_natural_lhs(x0, planck_mass=2.0, topo_lambda=0.5)
```

Notes:
- `ComplexFrame` is the internal complex-frame theory layer, not the full CFUT closure by itself.
- `ComplexFrameField` now exposes the explicit theory path `ComplexFrame -> complex curvature package -> CS flow -> minimal natural LHS`.
- `complex_curvature_package()` keeps the complexification at the curvature/tensor level instead of asserting a single prepackaged complex connection object.
- In the strict CFUT reading, `complex_einstein_tensor()` uses `real = geometry` and `imaginary = gauge-curvature encoding`.
- `minimal_natural_lhs()` places the topological-current tensor correction in the imaginary channel together with the gauge sector.

### Lambda Physical-Method APIs

```python
from coordinate_system import (
    lambda_reference_benchmark,
    lambda_from_theta,
    lambda_low_energy_effective,
    lambda_power_law_running,
)

bench = lambda_reference_benchmark(theta=1.0)
lam_theta = lambda_from_theta(theta=1.0)
lam_low = lambda_low_energy_effective(energy_ev=0.026)
lam_run = lambda_power_law_running(energy_ev=1.0e3, beta=0.176)

print(bench.lambda_0, lam_theta, lam_low.lambda_value, lam_run.lambda_value)
```

Notes:
- `lambda_reference_benchmark()` implements the conditional low-energy matching
  `lambda_0 = theta e^2 = 4*pi*alpha*theta` in the library normalization.
- `lambda_low_energy_effective()` and `lambda_power_law_running()` are explicitly phenomenological models for experimental comparison and cross-scale studies.
- These APIs upgrade the physical layer of the library without blurring the line between theorem-level CCS geometry and empirical coupling calibration.

---

## 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
                                 # including lambda physical-method utilities
  spectral_geometry.py           # FourierFrame, spectral analysis
  complex_frame.py               # ComplexFrame, internal gauge utilities
  complex_frame_theory.py        # Computable curvature packaging, CS flow, and minimal complex LHS proxies
  examples/complex_frame_gauge_demo.py  # Internal complex-frame demo
  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

### v9.0.0 (2026-03-12)
- Promoted `ComplexFrame` as the public internal complex-frame object and removed `U3Frame` from the active top-level API.
- Clarified that `ComplexFrame` is the internal CFUT layer only, not the complete spacetime-plus-gauge closure by itself.
- Added `ComplexFrameField` for numerically computable observables:
  - metric tensor
  - Einstein tensor / conformal Einstein tensor proxy
  - Chern-Simons current proxy
  - CS-gradient tensor proxy
  - CFUT unified field equation left-side proxy
- Updated examples and API tests to validate the new `ComplexFrame` interface.

### v10.2.0 (2026-03-19)
- Removed `complex_frame_physics.py`; the library now keeps a single canonical theory-layer module name.
- Added explicit ComplexFrame theory-path APIs:
  - `complex_curvature_package()`
  - `pontryagin_density()`
  - `cs_flow_package()`
  - `minimal_natural_lhs()`
- Clarified the library path as curvature-level complex packaging followed by Chern-Simons flow.

### v10.1.0 (2026-03-19)
- Upgraded the physical layer around the topological coupling `lambda`.
- Renamed the primary ComplexFrame structural interface layer to `complex_frame_theory.py`.
- Added public-safe `lambda` APIs:
  - `lambda_reference_benchmark()`
  - `lambda_from_theta()`
  - `lambda_low_energy_effective()`
  - `lambda_power_law_running()`
- Clarified that `lambda` is treated as a physical-method coupling parameter, not a geometry-only constant.
- Updated `ComplexFrameField.unified_field_equation_lhs()` so the topological-current tensor correction enters the imaginary channel in the strict CFUT reading.

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


