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

• Full API Reference
• Runnable Examples
• Source Code
• CCS frame paper

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.

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

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

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