coordinate-system 11.2.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.2.0 License: MIT DOI: https://doi.org/10.5281/zenodo.14435613

---

What's New in v11.2.0

Structured topological-physics release: the library is now organized around the research stack CCS -> complexified frame -> dual sector + CS -> lambda -> applications.

• ccs.py: stable geometry-facing layer for CCS and curvature workflows
• complexified_frame.py: grouped entry for ComplexFrame, gauge utilities, and sampled frame fields
• dual_sector.py: grouped entry for two-sector packaging, CS flow, lambda sector, dark-matter sector, and unified state construction
• unified_topological_physics.py: system-level chain packaging from geometry to applications
• generate_topological_physics_report.py: consolidated numerical report and raw-log generator
• generate_lambda_scale_table.py: lambda scale-running tables in CSV and Markdown
• generate_dark_matter_comparison_table.py: dark-matter shell comparison tables with target-vs-prediction errors

What's New in v11.1.0

CCS frame alignment release: theorem-chain-oriented CCS geometry packaging and numerical verification support.

• compute_ccs_geometry_package(): structured API exposing CCS object, local variation, recovered geometry, and curvature invariants together
• CCSGeometryPackage: dataclass wrapper for theorem-chain-aligned outputs
• orthonormalized adapted tangent-frame construction for general parametric surfaces
• test_ccs_frame_core.py: focused numerical verification of the core CCS frame theory
• research_registry.py: curated registry for numerically packaged studies with evidence level, source grade, reliability flag, and source-path provenance
• get_reliable_research_entries(): foreground important and reliable studies already encoded in the package
• unified_topological_physics.py: system-level packaging from CCS geometry to complex-frame two-sector tensors, CS flow, lambda, dark-matter shell probes, and loop observables

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)
    unified_topological_physics System-level theory chain packaging
    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}%")

Research Registry With Evidence Levels

from coordinate_system import get_reliable_research_entries, summarize_research_registry

for entry in get_reliable_research_entries():
    print(entry.slug, entry.evidence_label, entry.claim_status.value)

print()
print(summarize_research_registry(reliable_only=True))

System-Level Unified Chain

import numpy as np

from coordinate_system import (
    ComplexFrame,
    ComplexFrameField,
    GaugeConnection,
    Sphere,
    build_unified_topological_state,
)

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

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

field = ComplexFrameField(frame_sampler=frame_sampler, gauge_sampler=gauge_sampler)
state = build_unified_topological_state(
    field,
    np.array([0.1, -0.2, 0.3]),
    surface=Sphere(radius=2.0),
    surface_u=0.5,
    surface_v=0.7,
    topo_lambda=0.5,
    running_beta=0.2,
    dark_matter_targets_GeV=[100.0, 6200.0],
)

print(state.summary())
print(state.loop_observables.large_loop_phase)
print(state.lambda_sector.low_energy.lambda_value)

See also: SYSTEM_TOPOLOGICAL_PHYSICS.md

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.