coordinate-system 12.1.0

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

Coordinate System Library

High-performance 3D geometry, complex frame, and topological physics toolkit for Python.

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

---

Overview

This library can be used in two ways:

1. As a mathematical toolkit It provides standalone mathematical objects such as coordinate systems, curvature operators, spectral objects, and complex frames.

2. As a topological-physics toolkit It organizes those mathematical objects into the physical framework:

   CCS -> CFUT -> Lambda -> Topological Physics

The existing mathematical usage remains available. In particular, CCS-style geometry usage is preserved.

---

Structure

Mathematical Object Layer

• coordinate_system Core 3D objects such as vec3, quat, and coord3.

• differential_geometry Surface geometry, curvature, metric, shape operator, and curvature packages.

• spectral_geometry Spectral objects such as FourierFrame, Berry phase, Chern number, and related tools.

• complex_frame Complex frame objects and gauge-side mathematical structures such as ComplexFrame, GaugeConnection, and FieldStrength.

Physical Framework Layer

• CCS Geometry-facing physical wrapper over the CCS curvature and geometry pipeline.

• CFUT Complexified framework wrapper. This layer organizes complex frame fields, two-sector packaging, Chern-Simons flow, and validation helpers.

• Lambda Parameterization and constraint layer. This layer packages lambda benchmark, effective running, and constraint-oriented lambda state construction.

• topological_physics Application layer for dynamic stall, friction, non-Newtonian flow, mass shell, dark-matter shell probes, sunspot-cycle compatibility, and geomagnetic reversal.

---

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 for source builds.

---

Basic Usage

Mathematical Usage

The original mathematical-object usage is still supported.

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(K)

CCS Wrapper Usage

from coordinate_system import CCS, Sphere
import math

ccs = CCS(step_size=1e-4)
sphere = Sphere(radius=2.0)

pkg = ccs.geometry_package(sphere, math.pi / 4, math.pi / 3)
print(pkg.K, pkg.H)

CFUT Wrapper Usage

import numpy as np

from coordinate_system import CFUT, ComplexFrame, ComplexFrameField, GaugeConnection

def frame_sampler(x):
    x = np.asarray(x, dtype=float)
    return ComplexFrame(
        np.array([1.0 + 0.02j * x[0], 0.01 * x[1], 0.0], dtype=complex),
        np.array([0.0, 1.0 + 0.03j * x[1], 0.02 * x[2]], dtype=complex),
        np.array([0.01 * x[0], 0.0, 1.0 + 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.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)
cfut = CFUT(topo_lambda=0.5, energy_ev=0.026)

state = cfut.state(field, np.array([0.1, -0.2, 0.3]))
cs_term = cfut.cs_term(field, np.array([0.1, -0.2, 0.3]))

print(state.summary())
print(cs_term)

Lambda Wrapper Usage

from coordinate_system import Lambda

lam = Lambda(theta=1.0, energy_ev=0.026, running_beta=0.176)

print(lam.benchmark().lambda_0)
print(lam.low_energy().lambda_value)
print(lam.package().low_energy.lambda_value)

Application Usage

from coordinate_system import dynamic_stall_F, nearest_dm_shell

stall = dynamic_stall_F(k=0.05, delta_alpha_deg=15.0)
dm = nearest_dm_shell(6200.0)

print(stall.F_enhancement)
print(dm.shell_mass_GeV, dm.rel_error_pct)

---

Numerical Validation

The repository includes numerical tests and report-generation scripts.

Examples:

python -m unittest test_ccs_frame_core.py
python -m unittest test_unified_topological_physics.py
python test_topological_physics.py

External validation runners can be used to generate professional table-form reports without mixing validation scripts into the package code itself.

---

Notes

• Mathematical object APIs remain directly usable.
• CCS usage is preserved.
• Physical wrappers are intended to organize workflows, constants, constraints, and application-facing computation without replacing the underlying mathematical objects.

---

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