Coordinate System Library

High-performance 3D geometry, complex frame, and topological physics toolkit for Python.

Authors: Pan Guojun
Version: 12.1.0
License: MIT
DOI: https://doi.org/10.5281/zenodo.14435613

Overview

This library can be used in two ways:

As a mathematical toolkit It provides standalone mathematical objects such as coordinate systems, curvature operators, spectral objects, and complex frames.
As a topological-physics toolkit It organizes those mathematical objects into the physical framework:

CCS -> CFUT -> Lambda -> Topological Physics

The existing mathematical usage remains available. In particular, CCS-style geometry usage is preserved.

Structure

Mathematical Object Layer

coordinate_system Core 3D objects such as vec3, quat, and coord3.
differential_geometry Surface geometry, curvature, metric, shape operator, and curvature packages.
spectral_geometry Spectral objects such as FourierFrame, Berry phase, Chern number, and related tools.
complex_frame Complex frame objects and gauge-side mathematical structures such as ComplexFrame, GaugeConnection, and FieldStrength.

Physical Framework Layer

CCS Geometry-facing physical wrapper over the CCS curvature and geometry pipeline.
CFUT Complexified framework wrapper. This layer organizes complex frame fields, two-sector packaging, Chern-Simons flow, and validation helpers.
Lambda Parameterization and constraint layer. This layer packages lambda benchmark, effective running, and constraint-oriented lambda state construction.
topological_physics Application layer for dynamic stall, friction, non-Newtonian flow, mass shell, dark-matter shell probes, sunspot-cycle compatibility, and geomagnetic reversal.

Installation

pip install coordinate-system

Or from source:

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

Requirements: Python 3.7+, numpy, matplotlib, pybind11 for source builds.

Basic Usage

Mathematical Usage

The original mathematical-object usage is still supported.

from coordinate_system import Sphere, compute_gaussian_curvature
import math

sphere = Sphere(radius=2.0)
K = compute_gaussian_curvature(sphere, u=math.pi / 4, v=math.pi / 3)
print(K)

Surface Constraint Modeling

The library also provides coord-centered surface modeling helpers. Geometry is solved from analytic surface constraints first; visualization or PHG export can then consume the solved coord frames.

import math
from coordinate_system import (
    AnalyticCylinder,
    AnalyticSphere,
    solve_feature_coord,
    interpolate_surface_coords,
    trace_surface_intersection,
    vec3,
)

# 1. Solve a full coord pose for a feature point on a host surface.
sphere = AnalyticSphere(radius=1.0)
feature = solve_feature_coord(sphere, math.pi / 3.0, math.pi / 5.0)
print(feature.frame.o, feature.frame.ux, feature.frame.uz)

# 2. Transport/interpolate coord poses along a host-surface path.
surface_curve = interpolate_surface_coords(
    sphere,
    [(math.pi / 3.0, 0.0), (math.pi / 3.0, math.pi / 2.0)],
    samples=32,
)
points = [c.frame.o for c in surface_curve]

# 3. Trace an analytic surface intersection as a Boolean-ready boundary loop.
host = AnalyticCylinder(
    radius=0.62,
    origin=vec3(0.0, 0.0, -0.80),
    axis=vec3(0.0, 0.0, 1.0),
)
tool = AnalyticCylinder(
    radius=0.20,
    origin=vec3(0.62, 0.20, -0.35),
    axis=vec3(0.70710678, 0.0, 0.70710678),
    ref=vec3(0.0, 1.0, 0.0),
)
loop = trace_surface_intersection(
    host,
    tool,
    seed_a_uv=(0.0, 0.45),
    seed_b_uv=(math.pi, 0.0),
    samples=128,
    step=0.018,
)
print(loop.audit())

CCS Wrapper Usage

from coordinate_system import CCS, Sphere
import math

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

pkg = ccs.geometry_package(sphere, math.pi / 4, math.pi / 3)
print(pkg.K, pkg.H)

CFUT Wrapper Usage

import numpy as np

from coordinate_system import CFUT, ComplexFrame, ComplexFrameField, GaugeConnection

def frame_sampler(x):
    x = np.asarray(x, dtype=float)
    return ComplexFrame(
        np.array([1.0 + 0.02j * x[0], 0.01 * x[1], 0.0], dtype=complex),
        np.array([0.0, 1.0 + 0.03j * x[1], 0.02 * x[2]], dtype=complex),
        np.array([0.01 * x[0], 0.0, 1.0 + 0.01j * x[2]], dtype=complex),
        ensure_unitary=True,
    )

def gauge_sampler(x):
    x = np.asarray(x, dtype=float)
    return [
        GaugeConnection(su3_component=np.full(8, 0.01 * (1.0 + x[0]))),
        GaugeConnection(su2_component=np.array([0.02, 0.01 * (1.0 + x[1]), 0.0])),
        GaugeConnection(u1_component=0.03j * (1.0 + x[2])),
    ]

field = ComplexFrameField(frame_sampler=frame_sampler, gauge_sampler=gauge_sampler)
cfut = CFUT(topo_lambda=0.5, energy_ev=0.026)

state = cfut.state(field, np.array([0.1, -0.2, 0.3]))
cs_term = cfut.cs_term(field, np.array([0.1, -0.2, 0.3]))

print(state.summary())
print(cs_term)

Lambda Wrapper Usage

from coordinate_system import Lambda

lam = Lambda(theta=1.0, energy_ev=0.026, running_beta=0.176)

print(lam.benchmark().lambda_0)
print(lam.low_energy().lambda_value)
print(lam.package().low_energy.lambda_value)

Application Usage

from coordinate_system import dynamic_stall_F, nearest_dm_shell

stall = dynamic_stall_F(k=0.05, delta_alpha_deg=15.0)
dm = nearest_dm_shell(6200.0)

print(stall.F_enhancement)
print(dm.shell_mass_GeV, dm.rel_error_pct)

Numerical Validation

The repository includes numerical tests and report-generation scripts.

Examples:

python -m unittest test_ccs_frame_core.py
python -m unittest test_unified_topological_physics.py
python test_topological_physics.py

External validation runners can be used to generate professional table-form reports without mixing validation scripts into the package code itself.

Notes

Mathematical object APIs remain directly usable.
CCS usage is preserved.
Physical wrappers are intended to organize workflows, constants, constraints, and application-facing computation without replacing the underlying mathematical objects.

Version 12.2.0: Frame Curve Intersection

This release adds coordinate_system.curve_intersection, a solver-facing feature intersection module for frame/coord modeling workflows.

New public APIs:

from coordinate_system import (
    CurveIntersectionPoint,
    CurveIntersectionResult,
    closest_points_on_segments,
    frame_at_curve_hit,
    intersect_polyline_curves,
    intersect_parametric_curves,
    intersect_curve_with_implicit_surface,
)

The module is designed for the modeling chain:

solved coord poses
  -> transported/interpolated curves
  -> curve feature intersections
  -> coord feature frames
  -> PHG / PMEngine Boolean boundary loops

It reports feature points, curve parameters, residuals, coord frames, and audit metrics so downstream PHG/PMEngine code can use the solved geometry directly instead of treating rendered curves as the source of truth.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

coordinate_system-12.2.0.tar.gz (130.3 kB view details)

Uploaded Jul 9, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

coordinate_system-12.2.0-cp313-cp313-win_amd64.whl (278.2 kB view details)

Uploaded Jul 9, 2026 CPython 3.13Windows x86-64

File details

Details for the file coordinate_system-12.2.0.tar.gz.

File metadata

Download URL: coordinate_system-12.2.0.tar.gz
Upload date: Jul 9, 2026
Size: 130.3 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.12

File hashes

Hashes for coordinate_system-12.2.0.tar.gz
Algorithm	Hash digest
SHA256	`6a7d0e057a5e1fdc01270c679dcabc0b46de86c8d1813da44d54a72c6ac1a510`
MD5	`df4ae44d10123042c2ae0e21c0077903`
BLAKE2b-256	`fff30c6fc717c43a126343be079690b48f430cc73fc874cb96a1b4581f0ed706`

See more details on using hashes here.

File details

Details for the file coordinate_system-12.2.0-cp313-cp313-win_amd64.whl.

File metadata

Download URL: coordinate_system-12.2.0-cp313-cp313-win_amd64.whl
Upload date: Jul 9, 2026
Size: 278.2 kB
Tags: CPython 3.13, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.12

File hashes

Hashes for coordinate_system-12.2.0-cp313-cp313-win_amd64.whl
Algorithm	Hash digest
SHA256	`30814e1be9516224b1eb84d0dc42b4bba61284648b021824e929bcd82109a0b3`
MD5	`f9d5ad64127c61004074b967f7ae162b`
BLAKE2b-256	`ecd1aa18fac890494596cb27842ce498bbf5401b4d30e224165c9fb75bf3c4c5`