Metadata-Version: 2.1
Name: coordinate_system
Version: 11.2.0
Summary: High-performance 3D coordinate system, differential geometry, and CFUT topological physics library with universal validation framework
Home-page: https://github.com/panguojun/Coordinate-System
Author: Pan Guojun
Author-email: Pan Guojun <18858146@qq.com>
License: MIT
Project-URL: Homepage, https://github.com/panguojun/Coordinate-System
Project-URL: Documentation, https://github.com/panguojun/Coordinate-System/blob/main/README.md
Project-URL: Repository, https://github.com/panguojun/Coordinate-System
Project-URL: Bug Reports, https://github.com/panguojun/Coordinate-System/issues
Project-URL: DOI, https://doi.org/10.5281/zenodo.14435613
Keywords: 3d,math,vector,quaternion,coordinate-system,geometry,differential-geometry,curvature,spectral-analysis,topological-physics,cfut,unified-field-theory,complex-frame
Platform: Windows
Platform: Linux
Platform: macOS
Platform: Android
Platform: iOS
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Requires-Dist: matplotlib>=3.3.0

# Coordinate System Library

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

[![PyPI version](https://badge.fury.io/py/coordinate-system.svg)](https://pypi.org/project/coordinate-system/)
[![Python](https://img.shields.io/pypi/pyversions/coordinate-system.svg)](https://pypi.org/project/coordinate-system/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

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

```bash
pip install coordinate-system
```

Or from source:

```bash
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

```python
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

```python
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)

```python
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

```python
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

```python
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

```python
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.
