Coordinate System

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

Version 13.2.0 improves the public API documentation, ships runnable examples, and adds a dependency-light four-dimensional Coord4 object for Lorentz-frame algebra 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

import numpy as np
from coordinate_system import Coord4

frame = Coord4.boost_x(0.8)
local_velocity = np.array([1.0, 0.0, 0.0, 0.0])
local_derivative = np.zeros(4)
acceleration = frame.four_acceleration_from_local(
    local_velocity,
    local_derivative,
)
print(acceleration)

Coord4 stores an event origin and a contravariant tetrad whose columns are e_I^mu. It provides affine composition, relative transforms, local/world conversion, Lorentz-algebra projection, and analytic Minkowski/Rindler/boost constructors. It is a computational tetrad object layer, not a new gravity theory.

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 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
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 13.2.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 13.2.0
File	Size	Uploaded
coordinate_system-13.2.0.tar.gz	453.9 kB	Sep 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for coordinate-system 13.2.0
File	Interpreter	ABI	Platform	Reset
coordinate_system-13.2.0-cp313-cp313-win_amd64.whl 238.1 kB Sep 28, 2026	CPython 3.13	CPython 3.13	Windows x86-64	Details

Total release size: 692.0 kB

Release files / coordinate_system-13.2.0.tar.gz

Download URL	coordinate_system-13.2.0.tar.gz
Size	453.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`d01a7ef5ed718ad4722fa8d530de48fdda382c610a73a680b73940bab41f3a59`
BLAKE2b-256 checksum How to use checksums	`9f5e493dc885e94e93bc8aca42e4e34c690534d275040d807f24637026f0a433`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`

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

Download URL	coordinate_system-13.2.0-cp313-cp313-win_amd64.whl
Size	238.1 kB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`1d3be77ae3d112a5554145cbdc472f7d7afd0cbb562a6ef70c533afc4085fb38`
BLAKE2b-256 checksum How to use checksums	`1ea85d58ecbea482a34bc836b8f26698635b7c720904fe32f8f493d1e97269ed`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`