coordinate-system 8.1.1

High-performance 3D coordinate system library with unified differential geometry, frame algebra, and topological-physics application APIs

Coordinate System Library

High-performance 3D coordinate system and differential geometry library for Python.

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

pip install coordinate-system

---

Quick Start

Vectors and Frames

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)

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

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: [e-mail]