coordinate-system 9.0.0

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)

Coordinate System Library

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

Authors: Pan Guojun
Version: 9.0.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
• Numerical ComplexFrame observables: conformal Einstein tensor, CS current, CS-gradient tensor
• Clear CFUT layering: coord3 for geometry, ComplexFrame for the internal complex layer

---

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.

ComplexFrame Numerical Interfaces

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)
K = field.chern_simons_current(x0)
grad_K = field.cs_gradient_tensor(x0)
lhs = field.christmas_equation_lhs(x0, planck_mass=2.0, topo_lambda=0.5)

Notes:

• ComplexFrame is the internal complex-frame layer, not the full CFUT closure by itself.
• ComplexFrameField provides numerically computable proxies for Einstein/CS observables useful in regression tests and local experiments.

---

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
  complex_frame.py               # ComplexFrame, internal gauge utilities
  complex_frame_physics.py       # Computable Einstein/CS observables for ComplexFrame
  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
  • Christmas-equation left-side proxy
• Updated examples and API tests to validate the new ComplexFrame interface.

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]