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:

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:

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

Installation

pip install coordinate-system

From source:

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

Public Mathematical Layers

Core Coordinate Objects

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:

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:

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

Public imports

import numpy as np

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

Constructing four-dimensional frames

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:

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

Creating a custom tetrad

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

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

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:

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

Object composition and relative transforms

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:

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:

| 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

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:

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:

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

In code:

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:

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:

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:

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

Proper acceleration

proper = frame.proper_acceleration(acceleration)

The method evaluates:

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:

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:

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:

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

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:

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:

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

Convenience CCS Wrapper

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

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:

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

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

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.

Threefold Gauge Decomposition (v15.0.0)

Explicit separation of complex tetrad gauge freedoms into rotational, scaling, translational sectors:

from coordinate_system import decompose_complex_frame, scaling_gauge_fix

decomp = decompose_complex_frame(frame_matrix)
# decomp.rotation_matrix: pure rotational (gauge field) sector
# decomp.scaling_factor: conformal scale λ (gravity sector)
# decomp.imag_torsion: imaginary translational torsion (CS sector)
fixed_metric = scaling_gauge_fix(decomp).scaling_invariant_metric

Chern-Simons Exterior Calculus (v15.0.0)

CS 3-form, Pontryagin 4-form exterior derivative, topological charge integration, and path-widening observable:

from coordinate_system import compute_cs_3form, compute_path_multiplicity_Lambda

cs_density = compute_cs_3form(e_im, torsion_im)
# Compute Λ*: local sign entropy / topological channel count
lambda_star = compute_path_multiplicity_Lambda(signed_helicity_field)

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

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

License

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

Metadata

Release files for coordinate-system 15.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for coordinate-system 15.0.0
File	Size	Uploaded	Provenance
coordinate_system-15.0.0.tar.gz	463.0 kB	Oct 22, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for coordinate-system 15.0.0
File	Interpreter	ABI	Platform	Reset
coordinate_system-15.0.0-cp313-cp313-win_amd64.whl 243.8 kB Oct 22, 2026 Without provenance	CPython 3.13	CPython 3.13	Windows x86-64	Details

Total release size: 706.9 kB

Release files / coordinate_system-15.0.0.tar.gz

Download URL	coordinate_system-15.0.0.tar.gz
Size	463.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`9ddde3535a1ef2caeca7829d4fedccd697220226cd072dce1b6fdbe5432eb03e`
BLAKE2b-256 checksum How to use checksums	`a7db695c66eb56c2e3cd3b8a64a2fa7621f035f0dac3d3d4f4d8ffcc87019884`
Upload date	Oct 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.15`

Release files / coordinate_system-15.0.0-cp313-cp313-win_amd64.whl

Download URL	coordinate_system-15.0.0-cp313-cp313-win_amd64.whl
Size	243.8 kB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`c4f4e85756286a487864bd5f603d9c6c7593b4df3a514f658223a3170e1e7109`
BLAKE2b-256 checksum How to use checksums	`e307be03cdb2da4d8f10c9f3acb311d86d9915dae0120e9b136a537efc724573`
Upload date	Oct 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.15`

Security for coordinate-system 15.0.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.