coordinate-system 11.0.0

High-performance 3D coordinate system, differential geometry, and CFUT topological physics library with universal validation framework

Coordinate System Library

High-performance 3D coordinate system, differential geometry, and CFUT topological physics library for Python.

Authors: Pan Guojun Version: 11.0.0 License: MIT DOI: https://doi.org/10.5281/zenodo.14435613

---

What's New in v11.0.0

CFUT Universal Validation Framework — a methodology-embedded computation and validation pipeline for topological physics research.

• CFUTConstants: all first-principles constants ($\lambda_0 = 4\pi\alpha$, $k_c = \pi\alpha$)
• DomainValidator: base class for zero-parameter validation in any new domain
• DynamicStallValidator: reference implementation (Level 3 evidence)
• dynamic_stall_ratio_test(): the strongest single validation ($+0.13%$ error)
• boundary_check(): five-dimensional framework boundary gate check
• EvidenceLevel: automatic five-level evidence grading (Level 0-5)
• Full dynamic stall formulas: dynamic_stall_F(), dynamic_stall_N_max()
• WINDING_NUMBER_REGISTRY: cross-domain N definition tracking

---

Architecture

coordinate_system/
    coord3, vec3, quat          C++ core (Sim(3) group algebra)
    differential_geometry       Intrinsic gradient, Lie bracket curvature
    spectral_geometry           FourierFrame (GL(1,C)), heat kernel, Chern number
    complex_frame               Internal U(3) complex frame, gauge fields
    complex_frame_theory        ComplexFrameField, CS current, Einstein tensor
    topological_physics         Application formulas (stall, friction, particles)
    cfut_validation             Universal validation framework (NEW in v11)
    visualization               3D coordinate system visualization
    curve_interpolation         SE(3) interpolation, C2 splines

Three-Layer Design

Layer	Module	Group	Purpose
Geometry	coord3	Sim(3)	Computable coordinate systems
Spectral	FourierFrame	GL(1,C)	Fourier/conformal transforms
Internal	ComplexFrame	U(3)	Gauge structure, symmetry breaking

CFUT Research Pipeline

CFUTConstants           First-principles constants (alpha -> lambda0 -> k_c)
    |
boundary_check()        Five-dimensional gate check (B1-B5)
    |
DomainValidator         Base class for new domain validation
    |
validate()              Zero-parameter comparison: CFUT vs classical
    |
EvidenceLevel           Automatic grading (Level 0-5)
    |
ValidationResult        Full report with point-by-point comparison

---

Installation

pip install coordinate-system

Or from source:

git clone https://github.com/panguojun/Coordinate-System.git
cd Coordinate-System
pip install -e .

Requirements: Python 3.7+, numpy, matplotlib, pybind11 (build)

---

Quick Start

Curvature Computation

from coordinate_system import Sphere, compute_gaussian_curvature
import math

sphere = Sphere(radius=2.0)
K = compute_gaussian_curvature(sphere, u=math.pi/4, v=math.pi/3)
print(f"K = {K:.9f}  (theory = 0.25)")
# K = 0.249999999  (error ~ 10^-9)

CFUT Dynamic Stall Prediction

from coordinate_system import dynamic_stall_F, CFUTConstants

# CENER NACA64418, A15, k=0.050
result = dynamic_stall_F(k=0.050, delta_alpha_deg=15.0)
print(f"N_max = {result.N_max:.2f}")          # 9.00 (first-principles)
print(f"k_c = {result.k_c:.5f}")              # 0.02293 (= pi*alpha)
print(f"F(k) = {result.F_enhancement:.4f}")    # enhancement factor

Ratio Test (Strongest Validation)

from coordinate_system import dynamic_stall_ratio_test

# CENER P_A15: k = 0.010, 0.050, 0.100
result = dynamic_stall_ratio_test(
    k1=0.010, k2=0.050, k3=0.100,
    N_obs_k1=2.85, N_obs_k2=7.62, N_obs_k3=8.40,
)
print(f"R_obs  = {result.R_observed:.6f}")
print(f"R_pred = {result.R_predicted:.6f}")
print(f"Error  = {result.error_pct:+.2f}%")    # +0.13%
print(f"k_c best fit = {result.k_c_best_fit:.6f}")
print(f"k_c = pi*alpha deviation = {result.k_c_deviation_pct:+.2f}%")

Validate a New Domain

from coordinate_system import (
    DomainValidator, CFUTConstants,
    boundary_check, BoundaryStatus,
)

# Step 1: Boundary check
bc = boundary_check(
    b1_smoothness=BoundaryStatus.PASS, b1_note="Continuum system",
    b2_topology=BoundaryStatus.PASS, b2_note="N = integer winding number",
)
print(bc.summary())

# Step 2: Implement validator
class MyDomainValidator(DomainValidator):
    def cfut_predict(self, *, my_param, **kw):
        N = my_param / (4 * CFUTConstants.ALPHA)  # define N
        return 1.0 + CFUTConstants.lambda_eff() * N  # CFUT formula

    def classical_predict(self, *, my_param, **kw):
        return 1.0  # traditional formula (no correction)

# Step 3: Add data and validate
v = MyDomainValidator("My Domain", "1+lambda*N", "1.0",
                      "My Paper (2026)", data_grade=2, boundary=bc)
v.add_point("point1", observed=1.05, my_param=0.1)
v.add_point("point2", observed=1.12, my_param=0.2)
# ... add more points

result = v.validate()
print(result.report())
print(f"Evidence Level: {result.evidence_level.name}")

---

CFUT Fundamental Constants

All derived from the fine structure constant $\alpha = 1/137.036$:

Constant	Expression	Value	Status
$\lambda_0$	$4\pi\alpha$	0.09170	Irreducible (proved)
$k_c$	$\pi\alpha$	0.02293	Verified to 0.13%
$\lambda_{\text{eff}}(300\text{K})$	$\lambda_0 e^{-k_BT/E_{\text{ref}}}$	0.08596	Phenomenological

Lambda Irreducibility Theorem: $\lambda$ cannot be derived from first principles within the theory. It is an irreducible free parameter, with its determination linked to the Yang-Mills Millennium Problem.

---

Evidence Grading System

Level	Name	Criteria
0	Internal Consistency	Correct derivation, classical limit OK
1	Directional	Correct sign/order, n >= 5
2	Strong Compatibility	Comparable to classical, zero-param, n >= 10
3	Exclusionary Advantage	MAPE ratio < 0.5 OR classical qualitative failure
4	Independent Replication	Level 3 from independent source
5	Cross-Domain Unification	Level 3+ in 2+ independent domains

Current strongest: Dynamic stall Level 3 (CENER NACA64418, $k_c$ ratio test $+0.13%$).

---

Framework Boundaries

Five-dimensional gate check for domain admission:

Boundary	Question	Hard/Soft
B1 Smoothness	Smooth manifold?	Hard
B2 Topology	Can N be defined as integer?	Hardest
B3 EFT	Lowest-order truncation valid?	Hard
B4 Lambda	Prediction needs lambda absolute value?	Soft (caps level)
B5 Observer	Observer external to system?	Hard

B2 is the hard gate: if the topology is too complex for a simple winding number (e.g., 3D network structures, knot invariants), the domain is outside CFUT's effective region.

---

Module Reference

Core Types (C++)

vec3, vec2, quat, coord3, cross, lerp

Differential Geometry

Surface, Sphere, Torus, compute_gaussian_curvature, compute_mean_curvature, compute_riemann_curvature, IntrinsicGradientOperator, CurvatureCalculator

Spectral Geometry

FourierFrame, BerryPhase, ChernNumber, SpectralDecomposition, HeatKernel

Complex Frame

ComplexFrame, ComplexFrameField, GaugeConnection, FieldStrength, SymmetryBreakingPotential

Topological Physics

dynamic_stall_F, dynamic_stall_N_max, predict_dynamic_stall, predict_friction_force, mass_from_winding, nearest_dm_shell, lambda_reference_benchmark

CFUT Validation (NEW)

CFUTConstants, boundary_check, EvidenceLevel, DomainValidator, DynamicStallValidator, dynamic_stall_ratio_test, ValidationResult, WINDING_NUMBER_REGISTRY

---

References

1. Pan Guojun, On Computable Coordinate Systems, DOI: 10.5281/zenodo.14435613
2. Pan Guojun, Complex Frame Field Algebra, DOI: 10.5281/zenodo.14435613
3. Pan Guojun, A Two-Sector Curvature Formalism, March 2026
4. Pan Guojun, The Irreducibility of the Topological Coupling Parameter, March 2026
5. Pan Guojun, CFUT Research Methodology, March 2026

---

MIT License. Copyright (c) 2024-2026 Pan Guojun.