Metadata-Version: 2.4
Name: coordinate_system
Version: 14.0.0
Summary: Computable coordinate systems for object-level spatial calculus, frame fields, and differential geometry
Author-email: Pan Guojun <18858146@qq.com>
License-Expression: 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: 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 14.0.0 adds a dependency-light four-dimensional `Coord4` object for
Lorentz-frame algebra, tetrad conversion, relative frame generators, and
tetrad-based four-acceleration calculations. The package root is deliberately
mathematical: it exposes coordinate objects, frame-field calculus, curvature
operators, spectral geometry, complex-frame algebra, and curve/surface
construction tools.

## 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.

In the CCS frame paper this is the object-level recovery chain:

```text
C = (o, R, D) -> T = [s1 e1, s2 e2] -> g, h, S -> K, H, k1, k2
```

## 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.

## Documentation

- [Full API Reference](https://github.com/panguojun/Coordinate-System/blob/main/coordinate_system_pippy/API.md)
- [Runnable Examples](https://github.com/panguojun/Coordinate-System/tree/main/coordinate_system_pippy/examples)
- [Source Code](https://github.com/panguojun/Coordinate-System/tree/main/coordinate_system_pippy/coordinate_system)
- [CCS frame paper](https://doi.org/10.5281/zenodo.21700304)

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

Important `vec3` methods: `dot`, `cross`, `len`, `length`, `sqrlen`,
`normalized`, `project`, `reflect`, `distance`, `vec3.lerp`, and `vec3.angle`.

Important `quat` methods: composition with `*`, vector rotation with `q * v` or
`q.rotate(v)`, `normalized`, `inverse`, `to_eulers`, `to_angle_axis`,
`quat.slerp`, `quat.nlerp`, `quat.from_euler`, and `quat.from_axis_angle`.

Important `coord3` fields and methods: `o`/`p`, `ux`, `uy`, `uz`, `s`,
composition `A * B`, relative frame `A / B`, `to_world`, `to_local`, `inverse`,
`Q`, `R`, `VX`, `VY`, `VZ`, `coord3.look_at`, `coord3.from_forward`,
`coord3.lerp`, and `coord3.slerp`.

### Four-Dimensional CCS (`Coord4`)

`Coord4` is the four-dimensional CCS object for a contravariant Lorentz frame.
It is a computational tetrad object layer, not a new gravity theory.

The package uses the following convention:

```text
frame[mu, I] = e_I^mu
origin[mu]   = x^mu
ETA          = diag(-1, 1, 1, 1)
```

The four columns of `frame` are the local tetrad vectors. For a coordinate
inverse metric `g^mu nu`, the tetrad relation is:

```text
g^mu nu = frame @ ETA @ frame.T
```

#### Public imports

```python
import numpy as np

from coordinate_system import (
    Coord4,
    ETA,
    four_acceleration_from_tetrad,
    lorentz_algebra_residual,
    project_lorentz_algebra,
)
```

#### Constructing four-dimensional frames

```python
from coordinate_system import Coord4

# Identity/Minkowski frame. The default origin is [0, 0, 0, 0].
identity = Coord4.identity()
minkowski = Coord4.minkowski()

# Set an event origin explicitly.
event = Coord4.minkowski(origin=[10.0, 2.0, 0.0, -1.0])

# Lorentz boost along the x direction, parameterized by rapidity.
boosted = Coord4.boost_x(rapidity=0.8)

# Orthonormal tetrad for Rindler coordinates in c = 1 units.
rindler = Coord4.rindler(rho=4.0)
```

`Coord4.rindler(rho)` uses coordinates ordered as `(eta, xi, y, z)` and
requires `rho > 0`. Its coordinate metric is:

```text
g_mu nu = diag(-rho^2, 1, 1, 1)
```

#### Creating a custom tetrad

```python
import numpy as np
from coordinate_system import Coord4

origin = np.array([0.0, 0.0, 0.0, 0.0])
frame = np.eye(4)
custom = Coord4(origin=origin, frame=frame)
```

The constructor requires finite arrays with shapes `(4,)` and `(4, 4)`.
It does not silently repair a malformed tetrad.

#### Frame and metric properties

```python
frame = Coord4.boost_x(0.5)

inverse_frame = frame.inverse_frame
metric_inverse = frame.metric_inverse
metric = frame.metric

# In a Minkowski chart this should be close to zero.
residual = frame.lorentz_residual()

# For a general coordinate tetrad, pass the expected coordinate inverse metric.
coordinate_residual = frame.lorentz_residual(metric_inverse)
```

`lorentz_residual()` without an argument checks whether the frame itself is a
Lorentz transformation relative to `ETA`. For a general non-Minkowski tetrad,
pass the expected coordinate inverse metric explicitly.

#### Local and coordinate vector conversion

```python
local_vector = np.array([1.0, 0.2, 0.0, 0.0])
world_vector = frame.to_world(local_vector)
round_trip = frame.to_local(world_vector)

assert np.allclose(round_trip, local_vector)
```

The operations are:

```text
world_vector = frame @ local_vector
local_vector = inverse(frame) @ world_vector
```

#### Object composition and relative transforms

```python
first = Coord4(origin=[1.0, 0.0, 0.0, 0.0], frame=Coord4.boost_x(0.2).frame)
second = Coord4(origin=[0.0, 2.0, 0.0, 0.0], frame=Coord4.boost_x(-0.4).frame)

composed = first.compose(second)
relative = composed.relative_to(first)

np.testing.assert_allclose(relative.origin, second.origin)
np.testing.assert_allclose(relative.frame, second.frame)
```

Available object-level operations:

```python
homogeneous = frame.homogeneous()
relative_homogeneous = frame.relative_homogeneous(first)
log_relative = frame.log_relative(first)
generator = frame.generator_to(first, step=1.0e-4)
```

The homogeneous object is a 5x5 affine matrix:

```text
| frame  origin |
|   0      1    |
```

`generator_to()` computes the finite relative object change, maps it to a
matrix logarithm, divides by the supplied step, and projects the linear block
to the Lorentz Lie algebra.

#### Lorentz-algebra projection

```python
candidate = np.array([
    [0.0, 0.5, 0.0, 0.0],
    [0.5, 0.0, 0.1, 0.0],
    [0.0, -0.1, 0.0, 0.2],
    [0.0, 0.0, -0.2, 0.0],
])

projected = project_lorentz_algebra(candidate)
residual = lorentz_algebra_residual(projected)

assert residual < 1.0e-12
```

The projected matrix satisfies:

```text
projected.T @ ETA + ETA @ projected = 0
```

This is the numerical object-layer projection. A physical Levi-Civita spin
connection still requires the tetrad postulate and the torsion-free condition.

#### Four-acceleration from local tetrad components

For local tetrad components, use:

```text
a^I = d(u^I)/d(tau) + omega^I_J(tau) u^J
a^mu = e_I^mu a^I
```

In code:

```python
frame = Coord4.minkowski()
local_velocity = np.array([1.0, 0.0, 0.0, 0.0])
local_derivative = np.array([0.0, 0.0, 0.0, 0.0])
connection_along_worldline = np.zeros((4, 4))

acceleration = frame.four_acceleration_from_local(
    local_velocity=local_velocity,
    local_derivative=local_derivative,
    connection_along_worldline=connection_along_worldline,
)
```

The connection argument is optional. If omitted, the method maps the local
derivative directly back to coordinate components.

The same operation is available as a functional API:

```python
acceleration = four_acceleration_from_tetrad(
    frame=frame.frame,
    local_velocity=local_velocity,
    local_derivative=local_derivative,
    connection_along_worldline=connection_along_worldline,
)
```

#### Four-acceleration from coordinate components

For coordinate components and an optional Christoffel array:

```python
velocity = np.array([1.0, 0.0, 0.0, 0.0])
derivative = np.zeros(4)
christoffel = np.zeros((4, 4, 4))

acceleration = frame.four_acceleration_from_coordinate(
    velocity=velocity,
    derivative=derivative,
    christoffel=christoffel,
)
```

The coordinate expression is:

```text
a^mu = d(u^mu)/d(tau) + Gamma^mu_ab u^a u^b
```

#### Proper acceleration

```python
proper = frame.proper_acceleration(acceleration)
```

The method evaluates:

```text
a_proper = sqrt(g_mu nu a^mu a^nu)
```

and rejects a significantly timelike acceleration vector. For the Rindler
stationary observer with `rho = 4`:

```python
frame = Coord4.rindler(rho=4.0)
acceleration = np.array([0.0, 0.25, 0.0, 0.0])
assert np.isclose(frame.proper_acceleration(acceleration), 0.25)
```

#### Numerical validation

The four-dimensional implementation is covered by analytic and object-algebra
tests in `test/test_coord4.py`. The controlled precision benchmark is:

```bash
python bench/coord4_precision_benchmark.py
```

The benchmark compares raw component-wise frame derivatives with
object-relative finite changes followed by Lorentz-algebra projection. Its
result is written to:

```text
bench/coord4_precision_benchmark.json
```

The reported improvement is specific to the documented perturbation model and
is not a claim of universal superiority for every numerical-relativity
discretization.

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

`compute_ccs_geometry_package` returns a `CCSGeometryPackage` with:

- `center_frame`: surface-adapted `coord3`
- `G_u`, `G_v`: finite relative CCS variation objects
- `g`: first fundamental form
- `h`: second fundamental form
- `S`: shape operator
- `K`, `H`, `k1`, `k2`: curvature invariants
- `normal`: unit normal as a NumPy array
- `riemann_1212`: Riemann component
- `as_dict()`: dictionary view

Related curvature functions:

```python
from coordinate_system import (
    compute_gaussian_curvature,
    compute_mean_curvature,
    compute_riemann_curvature,
    compute_all_curvatures,
    compute_intrinsic_gradient,
    compute_connection_matrices,
)
```

For custom surfaces, subclass `Surface` and implement `position(u, v)`. For
better speed and accuracy, optionally add `derivs(u, v)` returning
`(r_u, r_v, r_uu, r_uv, r_vv)`.

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

The wrapper methods are `geometry_package`, `gaussian`, `mean`, `riemann`,
`connection_matrices`, and `curvature_tensor`.

### Custom Surface Example

```python
from coordinate_system import Surface, compute_ccs_geometry_package, vec3

class Paraboloid(Surface):
    def position(self, u, v):
        return vec3(u, v, 0.25 * (u*u + v*v))

    def derivs(self, u, v):
        return (
            vec3(1, 0, 0.5*u),
            vec3(0, 1, 0.5*v),
            vec3(0, 0, 0.5),
            vec3(0, 0, 0),
            vec3(0, 0, 0.5),
        )

pkg = compute_ccs_geometry_package(Paraboloid(), 0.4, -0.2)
print(pkg.K, pkg.H)
```



### Helicity-Phase Utilities

The package now includes a small mathematical module for CFLH-style validation:

```python
from coordinate_system.helicity_phase import (
    cumulative_pose_exposure,
    integrate_helicity_phase,
    integrate_compact_branch,
)
```

These helpers are generic. They turn a monotone CCS frame exposure into a
phase trajectory, branch labels, and compact finite-capacity closure diagnostics.

### 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]
```

NURBS entry points include `NURBSCurve`, `NURBSCurve2D`, `NURBSSurface`,
`make_nurbs_curve`, `make_nurbs_surface`, `sample_nurbs_frame_curve`,
`nurbs_arc_length`, `nurbs_curvature_profile`, and NURBS intersection helpers.

CoordScript entry points include `parse_coordscript`, `eval_coordscript`, and
`eval_coordscript_file`.

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 14.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
- NURBS and CoordScript helpers

## 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
