Metadata-Version: 2.1
Name: coordinate_system
Version: 12.1.0
Summary: High-performance 3D coordinate system, differential geometry, and CFUT topological physics library with universal validation framework
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
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 geometry, complex frame, and topological physics toolkit 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: 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

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

---

## Basic Usage

### Mathematical Usage

The original mathematical-object usage is still supported.

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

### CCS Wrapper Usage

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

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

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

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

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