coordinate-system 10.2.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: 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

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

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

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