Metadata-Version: 2.4
Name: coordinate_system
Version: 13.0.0
Summary: Computable coordinate systems for object-level spatial calculus, frame fields, and differential geometry
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,computable-coordinate-system,frame-field,differential-geometry,curvature,surface-geometry,spectral-geometry,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: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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++
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Provides-Extra: plot
Requires-Dist: matplotlib>=3.5.0; extra == "plot"
Provides-Extra: scipy
Requires-Dist: scipy>=1.8.0; extra == "scipy"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: matplotlib>=3.5.0; extra == "dev"
Requires-Dist: scipy>=1.8.0; extra == "dev"
Dynamic: license-file

﻿# Coordinate System

`coordinate_system` is a mathematical library for computable coordinate systems,
quaternionic frames, and object-level spatial calculus in Python.

Version 13.0.0 is a major cleanup release.  The package root is now deliberately
pure: it exposes coordinate objects, frame-field calculus, curvature operators,
spectral geometry, complex-frame algebra, and curve/surface construction tools.
Application-oriented physical wrappers and report generators have been removed
from the public package surface.

## Core Idea

A computable coordinate system is a local spatial measuring object:

```text
C = (o, q, s)  or  C = (o, R, D), with E = R D.
```

- `o` is the affine origin.
- `q` or `R` is the local orientation.
- `s` or `D` is the local scale/ruler structure.

The differential datum of a frame field is the logarithmic or relative local
variation of neighboring coordinate objects.  The integral operation is the
ordered composition that reconstructs global geometry from those local changes.

## Installation

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

From source:

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

Source builds require a C++17 compiler and `pybind11`.  Runtime dependency is
kept minimal: `numpy` is required; plotting and SciPy features are optional.

## Public Mathematical Layers

### Core Coordinate Objects

```python
from coordinate_system import vec3, quat, coord3, ONEC

p = vec3(1.0, 2.0, 3.0)
q = quat(1.0, 0.0, 0.0, 0.0)
scale = vec3(1.0, 1.0, 1.0)
C = coord3(p, q, scale)
```

### CCS Surface Geometry

```python
import math
from coordinate_system import Sphere, compute_ccs_geometry_package

sphere = Sphere(radius=2.0)
pkg = compute_ccs_geometry_package(sphere, math.pi / 4.0, math.pi / 3.0)

print(pkg.K)       # Gaussian curvature
print(pkg.H)       # Mean curvature
print(pkg.g)       # First fundamental form
print(pkg.h)       # Second fundamental form
print(pkg.center_frame)
```

The package keeps the theorem chain explicit:

```text
coord frame -> finite relative variation -> metric/shape data -> curvature invariants
```

### Convenience CCS Wrapper

```python
import math
from coordinate_system import CCS, Sphere

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

print(ccs.gaussian(sphere, math.pi / 4.0, math.pi / 3.0))
print(ccs.mean(sphere, math.pi / 4.0, math.pi / 3.0))
```

### Curve and Surface Construction

```python
import math
from coordinate_system import AnalyticSphere, interpolate_surface_coords

surface = AnalyticSphere(radius=1.0)
frames = interpolate_surface_coords(
    surface,
    [(math.pi / 3.0, 0.0), (math.pi / 3.0, math.pi / 2.0)],
    samples=16,
)

points = [item.frame.o for item in frames]
```

These APIs are mathematical construction tools.  Downstream CAD, rendering, or
simulation systems can consume the resulting coord frames, but those application
layers are not part of the package root.

### Spectral and Complex Frames

```python
from coordinate_system import ComplexFrame, GaugeConnection, FourierFrame

U = ComplexFrame()
A = GaugeConnection()
```

The complex-frame layer is kept as a mathematical utility for unitary frames,
connections, field-strength-like algebra, and spectral constructions.  It should
not be read as a validated physical model by itself.

## API Boundary in 13.0.0

Removed from the public package root:

- CFUT wrapper APIs
- Lambda wrapper APIs
- topological physics application functions
- research registry helpers
- report-generation scripts
- dark-matter, dynamic-stall, and validation application examples

Kept in the mathematical package root:

- `vec3`, `vec2`, `quat`, `coord3`
- `CCS`, `Surface`, `Sphere`, `Torus`
- metric, intrinsic-gradient, curvature, and CCS geometry package APIs
- spectral geometry utilities
- complex-frame algebra utilities
- curve interpolation, curve intersection, and analytic surface coord tools

## Development Smoke Test

```bash
python -c "import coordinate_system as cs; print(cs.__version__, cs.Sphere(2).theoretical_gaussian_curvature)"
python -m unittest discover -s test
```

## License

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

DOI: https://doi.org/10.5281/zenodo.14435613
