coordinate-system 7.1.0__tar.gz → 7.1.1__tar.gz

{coordinate_system-7.1.0/coordinate_system.egg-info → coordinate_system-7.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: coordinate_system
-Version: 7.1.0
+Version: 7.1.1
 Summary: High-performance 3D coordinate system library with unified differential geometry, quantum frame algebra, and Christmas Equation (CFUT)
 Home-page: https://github.com/panguojun/Coordinate-System
 Author: Pan Guojun
@@ -51,12 +51,19 @@ Requires-Dist: matplotlib>=3.3.0
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 **Authors:** Pan Guojun
-**Version:** 7.1.0
+**Version:** 7.1.1
 **License:** MIT
 **DOI:** https://doi.org/10.5281/zenodo.14435613
 
 ---
 
+## What's New in v7.1.1 (2026-02-05)
+
+- **Curvature Fast Path**: Analytical curvature for Sphere/Torus and any surface providing `derivs` or `analytic_KH` (toggle via `USE_ANALYTIC_DERIVS`)
+- **Caching**: Reuse curvature calculators and last-call results to reduce per-sample overhead
+- **Math Core**: Branchless handedness selection for cross product; optional SIMD alignment via `PMSYS_SIMD_ALIGN`
+- **Build Flags**: AVX2 / fast-math enabled by default in build config for faster native builds
+
 ## What's New in v7.1.0 (2026-01-16)
 
 - **Physical Constants**: Added SI unit constants for precision calculations (ALPHA_FS, LAMBDA_C, ALPHA_PROJECTION)
@@ -236,6 +243,12 @@ S_YM = F_xy.yang_mills_action()
 
 ## Changelog
 
+### v7.1.1 (2026-02-05)
+- **Curvature Fast Path**: Analytical curvature for analytic surfaces with optional toggle
+- **Caching**: Curvature calculator reuse and last-call caching for repeated samples
+- **Math Core**: Branchless cross product handedness selection
+- **Build**: AVX2 / fast-math flags enabled by default for native builds
+
 ### v7.1.0 (2026-01-16)
 - **Physical Constants**: Added SI unit constants (ALPHA_FS, LAMBDA_C, ALPHA_PROJECTION)
 - **Projection Factor**: Implemented α = α_fs × λ_c ≈ 1.77×10⁻¹⁴ m for geometry-gauge coupling

{coordinate_system-7.1.0 → coordinate_system-7.1.1}/README.md

@@ -7,12 +7,19 @@
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 **Authors:** Pan Guojun
-**Version:** 7.1.0
+**Version:** 7.1.1
 **License:** MIT
 **DOI:** https://doi.org/10.5281/zenodo.14435613
 
 ---
 
+## What's New in v7.1.1 (2026-02-05)
+
+- **Curvature Fast Path**: Analytical curvature for Sphere/Torus and any surface providing `derivs` or `analytic_KH` (toggle via `USE_ANALYTIC_DERIVS`)
+- **Caching**: Reuse curvature calculators and last-call results to reduce per-sample overhead
+- **Math Core**: Branchless handedness selection for cross product; optional SIMD alignment via `PMSYS_SIMD_ALIGN`
+- **Build Flags**: AVX2 / fast-math enabled by default in build config for faster native builds
+
 ## What's New in v7.1.0 (2026-01-16)
 
 - **Physical Constants**: Added SI unit constants for precision calculations (ALPHA_FS, LAMBDA_C, ALPHA_PROJECTION)
@@ -190,8 +197,14 @@ S_YM = F_xy.yang_mills_action()
 
 ---
 
-## Changelog
-
+## Changelog
+
+### v7.1.1 (2026-02-05)
+- **Curvature Fast Path**: Analytical curvature for analytic surfaces with optional toggle
+- **Caching**: Curvature calculator reuse and last-call caching for repeated samples
+- **Math Core**: Branchless cross product handedness selection
+- **Build**: AVX2 / fast-math flags enabled by default for native builds
+
 ### v7.1.0 (2026-01-16)
 - **Physical Constants**: Added SI unit constants (ALPHA_FS, LAMBDA_C, ALPHA_PROJECTION)
 - **Projection Factor**: Implemented α = α_fs × λ_c ≈ 1.77×10⁻¹⁴ m for geometry-gauge coupling

{coordinate_system-7.1.0 → coordinate_system-7.1.1}/coordinate_system/__init__.py

@@ -24,11 +24,11 @@ Group Correspondence:
 - U3Frame ∈ U(3) = SU(3) × U(1)
 
 **Authors:** Pan Guojun
-Version: 7.1.0
+Version: 7.1.1
 **DOI:** https://doi.org/10.5281/zenodo.14435613
 """
 
-__version__ = '7.1.0'
+__version__ = '7.1.1'
 
 from .coordinate_system import (
     vec3,

{coordinate_system-7.1.0 → coordinate_system-7.1.1}/coordinate_system/complex_geometric_physics.py

@@ -26,11 +26,11 @@ Physical Interpretation:
 
 **Authors:** Pan Guojun
 Date: 2025-01-14
-Version: 7.1.0
+Version: 7.1.1
 **DOI:** https://doi.org/10.5281/zenodo.14435613
 """
 
-__version__ = '7.1.0'
+__version__ = '7.1.1'
 
 import numpy as np
 from typing import Tuple, Optional, Callable, Dict, Any

{coordinate_system-7.1.0 → coordinate_system-7.1.1}/coordinate_system/differential_geometry.py

@@ -18,6 +18,7 @@ Date: 2025-12-03
 """
 
 import math
+import weakref
 import numpy as np
 from typing import Tuple, Optional, Callable, Union, Dict, List
 from .coordinate_system import coord3, vec3
@@ -38,6 +39,7 @@ def _safe_normal_from_tangents(r_u: vec3, r_v: vec3) -> vec3:
         return n * (1.0 / length)
     return vec3(0.0, 0.0, 1.0)
 
+
 def derivative_5pt(f: Callable[[float], np.ndarray], x: float, h: float) -> np.ndarray:
     """
     5-point finite difference formula for first derivative.
@@ -328,7 +330,6 @@ class IntrinsicGradientOperator:
             n = _safe_normal_from_tangents(r_theta, r_phi)
             e1 = r_theta.normalized()
             e2 = r_phi.normalized()
-
         elif isinstance(self.surface, Torus):
             R = self.surface.R
             r = self.surface.r
@@ -351,7 +352,6 @@ class IntrinsicGradientOperator:
             n = _safe_normal_from_tangents(r_u, r_v)
             e1 = r_u.normalized()
             e2 = r_v.normalized()
-
         else:
             # Numerical method for general surfaces
             pos = self.surface.position(u, v)
@@ -361,14 +361,12 @@ class IntrinsicGradientOperator:
             n = _safe_normal_from_tangents(r_u, r_v)
             e1 = r_u.normalized()
             e2 = r_v.normalized()
-
         # Create intrinsic frame
         frame = coord3()
         frame.o = pos
         frame.ux = e1
         frame.uy = e2
         frame.uz = n
-
         return frame
 
     def compute_both(self, u: float, v: float) -> Tuple[GradientResult, GradientResult, coord3]:
@@ -426,6 +424,9 @@ class IntrinsicGradientCurvatureCalculator:
         self.surface = surface
         self.h = step_size
         self.grad_op = IntrinsicGradientOperator(surface, step_size)
+        self._cache_u: Optional[float] = None
+        self._cache_v: Optional[float] = None
+        self._cache_terms: Optional[Tuple[float, float, float, float, float, float, float, float]] = None
 
     def _get_tangent_vectors(self, u: float, v: float) -> Tuple[vec3, vec3]:
         """Get tangent vectors (analytical for known surfaces, numerical otherwise)."""
@@ -461,9 +462,12 @@ class IntrinsicGradientCurvatureCalculator:
 
         return r_u, r_v
 
-    def compute_gaussian_curvature(self, u: float, v: float) -> float:
+    def _compute_shape_terms(self, u: float, v: float) -> Tuple[float, float, float, float, float, float, float, float]:
         """
-        Compute Gaussian curvature K = det(II) / det(I).
+        Compute shared shape-operator terms used by multiple curvature routines.
+
+        Returns:
+            (E, F, G, metric_det, L, M, N, M_uv)
         """
         G_u, G_v, _ = self.grad_op.compute_both(u, v)
         r_u, r_v = self._get_tangent_vectors(u, v)
@@ -477,45 +481,39 @@ class IntrinsicGradientCurvatureCalculator:
         G = r_v.dot(r_v)
         metric_det = E * G - F * F
 
-        # Second fundamental form
+        # Second fundamental form components
         L = -dn_du.dot(r_u)
-        M1 = -dn_du.dot(r_v)
-        M2 = -dn_dv.dot(r_u)
+        M_uv = -dn_du.dot(r_v)
+        M_vu = -dn_dv.dot(r_u)
         N = -dn_dv.dot(r_v)
-        M = (M1 + M2) / 2.0
-
-        # Gaussian curvature
-        if abs(metric_det) > 1e-14:
-            K = (L * N - M * M) / metric_det
-        else:
-            K = 0.0
-
-        return K
-
-    def compute_mean_curvature(self, u: float, v: float) -> float:
+        M = (M_uv + M_vu) / 2.0
+
+        return E, F, G, metric_det, L, M, N, M_uv
+
+    def _get_terms_cached(self, u: float, v: float) -> Tuple[float, float, float, float, float, float, float, float]:
+        if self._cache_terms is not None and u == self._cache_u and v == self._cache_v:
+            return self._cache_terms
+        terms = self._compute_shape_terms(u, v)
+        self._cache_u = u
+        self._cache_v = v
+        self._cache_terms = terms
+        return terms
+
+    def _compute_curvatures_from_terms(
+        self,
+        u: float,
+        terms: Tuple[float, float, float, float, float, float, float, float]
+    ) -> Tuple[float, float]:
         """
-        Compute mean curvature H = (EN - 2FM + GL) / (2*det(I)).
+        Compute Gaussian and mean curvature from shared terms.
         """
-        G_u, G_v, _ = self.grad_op.compute_both(u, v)
-        r_u, r_v = self._get_tangent_vectors(u, v)
-
-        dn_du = G_u.dn
-        dn_dv = G_v.dn
-
-        E = r_u.dot(r_u)
-        F = r_u.dot(r_v)
-        G = r_v.dot(r_v)
-        metric_det = E * G - F * F
-
-        L = -dn_du.dot(r_u)
-        M1 = -dn_du.dot(r_v)
-        M2 = -dn_dv.dot(r_u)
-        N = -dn_dv.dot(r_v)
-        M = (M1 + M2) / 2.0
+        E, F, G, metric_det, L, M, N, _ = terms
 
         if abs(metric_det) > 1e-14:
+            K = (L * N - M * M) / metric_det
             H = (G * L - 2 * F * M + E * N) / (2 * metric_det)
         else:
+            K = 0.0
             H = 0.0
 
         if isinstance(self.surface, Sphere):
@@ -527,6 +525,22 @@ class IntrinsicGradientCurvatureCalculator:
             if theory != 0.0:
                 H = math.copysign(abs(H), theory)
 
+        return K, H
+
+    def compute_gaussian_curvature(self, u: float, v: float) -> float:
+        """
+        Compute Gaussian curvature K = det(II) / det(I).
+        """
+        terms = self._get_terms_cached(u, v)
+        K, _ = self._compute_curvatures_from_terms(u, terms)
+        return K
+
+    def compute_mean_curvature(self, u: float, v: float) -> float:
+        """
+        Compute mean curvature H = (EN - 2FM + GL) / (2*det(I)).
+        """
+        terms = self._get_terms_cached(u, v)
+        _, H = self._compute_curvatures_from_terms(u, terms)
         return H
 
     def compute_riemann_curvature(self, u: float, v: float) -> float:
@@ -535,17 +549,9 @@ class IntrinsicGradientCurvatureCalculator:
 
         For 2D surfaces: R^1_212 = K * det(g) = LN - M^2
         """
-        G_u, G_v, _ = self.grad_op.compute_both(u, v)
-        r_u, r_v = self._get_tangent_vectors(u, v)
-
-        dn_du = G_u.dn
-        dn_dv = G_v.dn
-
-        L = -dn_du.dot(r_u)
-        M = -dn_du.dot(r_v)
-        N = -dn_dv.dot(r_v)
-
-        R_1212 = L * N - M * M
+        terms = self._get_terms_cached(u, v)
+        _, _, _, _, L, _, N, M_uv = terms
+        R_1212 = L * N - M_uv * M_uv
         return R_1212
 
     def compute_principal_curvatures(self, u: float, v: float) -> Tuple[float, float]:
@@ -554,8 +560,8 @@ class IntrinsicGradientCurvatureCalculator:
 
         Uses: k1,k2 = H +/- sqrt(H^2 - K)
         """
-        K = self.compute_gaussian_curvature(u, v)
-        H = self.compute_mean_curvature(u, v)
+        terms = self._get_terms_cached(u, v)
+        K, H = self._compute_curvatures_from_terms(u, terms)
 
         discriminant = max(0, H * H - K)
         sqrt_disc = discriminant ** 0.5
@@ -569,8 +575,8 @@ class IntrinsicGradientCurvatureCalculator:
         """
         Compute all curvature quantities at once.
         """
-        K = self.compute_gaussian_curvature(u, v)
-        H = self.compute_mean_curvature(u, v)
+        terms = self._get_terms_cached(u, v)
+        K, H = self._compute_curvatures_from_terms(u, terms)
 
         discriminant = max(0, H * H - K)
         sqrt_disc = discriminant ** 0.5
@@ -599,6 +605,28 @@ class CurvatureCalculator:
     def __init__(self, surface: Surface, step_size: float = 1e-3):
         self.surface = surface
         self.h = step_size
+        self._cache_u: Optional[float] = None
+        self._cache_v: Optional[float] = None
+        self._cache_derivs: Optional[Dict[str, np.ndarray]] = None
+        self._cache_forms: Optional[Tuple[np.ndarray, np.ndarray, np.ndarray]] = None
+
+    def _get_derivs_cached(self, u: float, v: float) -> Dict[str, np.ndarray]:
+        if self._cache_derivs is not None and u == self._cache_u and v == self._cache_v:
+            return self._cache_derivs
+        derivs = self._compute_derivatives(u, v)
+        self._cache_u = u
+        self._cache_v = v
+        self._cache_derivs = derivs
+        self._cache_forms = None
+        return derivs
+
+    def _get_forms_cached(self, u: float, v: float) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        if self._cache_forms is not None and u == self._cache_u and v == self._cache_v:
+            return self._cache_forms
+        derivs = self._get_derivs_cached(u, v)
+        forms = self.compute_fundamental_forms(u, v, derivs)
+        self._cache_forms = forms
+        return forms
 
     def _position_array(self, u: float, v: float) -> np.ndarray:
         """Convert vec3 position to numpy array."""
@@ -608,31 +636,62 @@ class CurvatureCalculator:
     def _compute_derivatives(self, u: float, v: float) -> Dict[str, np.ndarray]:
         """Compute surface derivatives using high-order finite differences."""
         effective_h = max(self.h, 1e-6)
-
-        r_u = derivative_5pt(lambda uu: self._position_array(uu, v), u, effective_h)
-        r_v = derivative_5pt(lambda vv: self._position_array(u, vv), v, effective_h)
-
-        r_uu = derivative_2nd_5pt(lambda uu: self._position_array(uu, v), u, effective_h)
-        r_vv = derivative_2nd_5pt(lambda vv: self._position_array(u, vv), v, effective_h)
-        r_uv = derivative_5pt(
-            lambda vv: derivative_5pt(
-                lambda uu: self._position_array(uu, vv), u, effective_h
-            ), v, effective_h
-        )
+        h = effective_h
+
+        offsets = (-2, -1, 0, 1, 2)
+        pos = {}
+        for du in offsets:
+            u_offset = u + du * h
+            for dv in offsets:
+                pos[(du, dv)] = self._position_array(u_offset, v + dv * h)
+
+        # 5-point first-derivative coefficients
+        c1 = { -2: 1.0, -1: -8.0, 1: 8.0, 2: -1.0 }
+
+        # First derivatives
+        r_u = (
+            pos[(-2, 0)] - 8.0 * pos[(-1, 0)] + 8.0 * pos[(1, 0)] - pos[(2, 0)]
+        ) / (12.0 * h)
+        r_v = (
+            pos[(0, -2)] - 8.0 * pos[(0, -1)] + 8.0 * pos[(0, 1)] - pos[(0, 2)]
+        ) / (12.0 * h)
+
+        # 5-point second derivatives
+        r_uu = (
+            -pos[(2, 0)] + 16.0 * pos[(1, 0)] - 30.0 * pos[(0, 0)] +
+            16.0 * pos[(-1, 0)] - pos[(-2, 0)]
+        ) / (12.0 * h * h)
+        r_vv = (
+            -pos[(0, 2)] + 16.0 * pos[(0, 1)] - 30.0 * pos[(0, 0)] +
+            16.0 * pos[(0, -1)] - pos[(0, -2)]
+        ) / (12.0 * h * h)
+
+        # Mixed derivative via separable 5-point stencil
+        r_uv = np.zeros(3, dtype=np.float64)
+        for du, cu in c1.items():
+            for dv, cv in c1.items():
+                r_uv += (cu * cv) * pos[(du, dv)]
+        r_uv /= (144.0 * h * h)
 
         return {
             'r_u': r_u, 'r_v': r_v,
             'r_uu': r_uu, 'r_vv': r_vv, 'r_uv': r_uv
         }
 
-    def compute_fundamental_forms(self, u: float, v: float) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    def compute_fundamental_forms(
+        self,
+        u: float,
+        v: float,
+        derivs: Optional[Dict[str, np.ndarray]] = None
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
         """
         Compute first and second fundamental forms.
 
         Returns:
             (g, h, n): First form, second form, normal vector
         """
-        derivs = self._compute_derivatives(u, v)
+        if derivs is None:
+            derivs = self._compute_derivatives(u, v)
         r_u = derivs['r_u']
         r_v = derivs['r_v']
         r_uu = derivs['r_uu']
@@ -661,40 +720,31 @@ class CurvatureCalculator:
 
         return g, h, n
 
-    def compute_gaussian_curvature(self, u: float, v: float) -> float:
-        """Compute Gaussian curvature K = det(II) / det(I)."""
-        g, h, _ = self.compute_fundamental_forms(u, v)
-
+    def _compute_curvatures_from_forms(
+        self,
+        g: np.ndarray,
+        h: np.ndarray
+    ) -> Tuple[float, float]:
+        """Compute Gaussian and mean curvature from fundamental forms."""
         det_g = np.linalg.det(g)
-        det_h = np.linalg.det(h)
-
         if abs(det_g) < 1e-14:
-            return 0.0
-
-        return det_h / det_g
+            return 0.0, 0.0
 
-    def compute_mean_curvature(self, u: float, v: float) -> float:
-        """Compute mean curvature H."""
-        g, h, _ = self.compute_fundamental_forms(u, v)
-
-        det_g = np.linalg.det(g)
-        if abs(det_g) < 1e-14:
-            return 0.0
+        det_h = np.linalg.det(h)
+        K = det_h / det_g
 
         trace_term = g[1, 1] * h[0, 0] - 2 * g[0, 1] * h[0, 1] + g[0, 0] * h[1, 1]
         H = trace_term / (2 * det_g)
 
-        return abs(H)
+        return K, abs(H)
 
-    def compute_principal_curvatures(self, u: float, v: float) -> Tuple[float, float, np.ndarray, np.ndarray]:
-        """
-        Compute principal curvatures and principal directions.
-
-        Returns:
-            (k1, k2, dir1, dir2): Principal curvatures and directions
-        """
-        g, h, _ = self.compute_fundamental_forms(u, v)
-        derivs = self._compute_derivatives(u, v)
+    def _compute_principal_from_forms(
+        self,
+        derivs: Dict[str, np.ndarray],
+        g: np.ndarray,
+        h: np.ndarray
+    ) -> Tuple[float, float, np.ndarray, np.ndarray]:
+        """Compute principal curvatures and directions from forms."""
         r_u = derivs['r_u']
         r_v = derivs['r_v']
 
@@ -702,20 +752,16 @@ class CurvatureCalculator:
         if abs(det_g) < 1e-14:
             return 0.0, 0.0, np.array([1., 0., 0.]), np.array([0., 1., 0.])
 
-        # Shape operator S = g^{-1} h
         g_inv = np.linalg.inv(g)
         S = g_inv @ h
 
-        # Eigenvalue decomposition
         eigenvalues, eigenvectors = np.linalg.eig(S)
         k1, k2 = eigenvalues.real
 
-        # Ensure k1 >= k2 by absolute value
         if abs(k1) < abs(k2):
             k1, k2 = k2, k1
             eigenvectors = eigenvectors[:, [1, 0]]
 
-        # Convert to 3D directions
         dir1_2d = eigenvectors[:, 0]
         dir2_2d = eigenvectors[:, 1]
 
@@ -727,12 +773,35 @@ class CurvatureCalculator:
 
         return k1, k2, dir1_3d, dir2_3d
 
+    def compute_gaussian_curvature(self, u: float, v: float) -> float:
+        """Compute Gaussian curvature K = det(II) / det(I)."""
+        g, h, _ = self._get_forms_cached(u, v)
+        K, _ = self._compute_curvatures_from_forms(g, h)
+        return K
+
+    def compute_mean_curvature(self, u: float, v: float) -> float:
+        """Compute mean curvature H."""
+        g, h, _ = self._get_forms_cached(u, v)
+        _, H = self._compute_curvatures_from_forms(g, h)
+        return H
+
+    def compute_principal_curvatures(self, u: float, v: float) -> Tuple[float, float, np.ndarray, np.ndarray]:
+        """
+        Compute principal curvatures and principal directions.
+
+        Returns:
+            (k1, k2, dir1, dir2): Principal curvatures and directions
+        """
+        derivs = self._get_derivs_cached(u, v)
+        g, h, _ = self._get_forms_cached(u, v)
+        return self._compute_principal_from_forms(derivs, g, h)
+
     def compute_all_curvatures(self, u: float, v: float) -> Dict[str, Union[float, np.ndarray]]:
         """Compute all curvature quantities at once."""
-        g, h, n = self.compute_fundamental_forms(u, v)
-        K = self.compute_gaussian_curvature(u, v)
-        H = self.compute_mean_curvature(u, v)
-        k1, k2, dir1, dir2 = self.compute_principal_curvatures(u, v)
+        derivs = self._get_derivs_cached(u, v)
+        g, h, n = self._get_forms_cached(u, v)
+        K, H = self._compute_curvatures_from_forms(g, h)
+        k1, k2, dir1, dir2 = self._compute_principal_from_forms(derivs, g, h)
 
         return {
             'K': K,
@@ -751,6 +820,102 @@ class CurvatureCalculator:
 # Convenience Functions - Intrinsic Gradient Method (Default)
 # ============================================================
 
+_intrinsic_calc_cache: "weakref.WeakKeyDictionary[Surface, Dict[float, IntrinsicGradientCurvatureCalculator]]" = weakref.WeakKeyDictionary()
+_classical_calc_cache: "weakref.WeakKeyDictionary[Surface, Dict[float, CurvatureCalculator]]" = weakref.WeakKeyDictionary()
+_intrinsic_grad_cache: "weakref.WeakKeyDictionary[Surface, Dict[float, IntrinsicGradientOperator]]" = weakref.WeakKeyDictionary()
+
+
+def _get_cached_calc(cache, surface: Surface, step_size: float, ctor, attr_name: str):
+    try:
+        surf_dict = surface.__dict__
+    except Exception:
+        surf_dict = None
+
+    if surf_dict is not None:
+        step_map = surf_dict.get(attr_name)
+        if step_map is None:
+            step_map = {}
+            surf_dict[attr_name] = step_map
+        calc = step_map.get(step_size)
+        if calc is None:
+            calc = ctor(surface, step_size)
+            step_map[step_size] = calc
+        return calc
+
+    step_map = cache.get(surface)
+    if step_map is None:
+        step_map = {}
+        cache[surface] = step_map
+    calc = step_map.get(step_size)
+    if calc is None:
+        calc = ctor(surface, step_size)
+        step_map[step_size] = calc
+    return calc
+
+
+def _curvatures_from_derivs(
+    r_u: vec3,
+    r_v: vec3,
+    r_uu: vec3,
+    r_uv: vec3,
+    r_vv: vec3
+) -> Tuple[float, float]:
+    E = r_u.dot(r_u)
+    F = r_u.dot(r_v)
+    G = r_v.dot(r_v)
+    denom = E * G - F * F
+    if abs(denom) < 1e-14:
+        return 0.0, 0.0
+    n = _safe_normal_from_tangents(r_u, r_v)
+    L = r_uu.dot(n)
+    M = r_uv.dot(n)
+    N = r_vv.dot(n)
+    K = (L * N - M * M) / denom
+    H = (E * N - 2.0 * F * M + G * L) / (2.0 * denom)
+    return K, H
+
+
+def _analytic_curvatures(surface: Surface, u: float, v: float) -> Optional[Tuple[float, float]]:
+    if not USE_ANALYTIC_DERIVS:
+        return None
+    if isinstance(surface, Sphere):
+        return surface.theoretical_gaussian_curvature, surface.theoretical_mean_curvature
+    if isinstance(surface, Torus):
+        return surface.theoretical_gaussian_curvature(u), surface.theoretical_mean_curvature(u)
+    if hasattr(surface, "analytic_KH"):
+        try:
+            return surface.analytic_KH(u, v)
+        except Exception:
+            pass
+    if hasattr(surface, "derivs"):
+        try:
+            r_u, r_v, r_uu, r_uv, r_vv = surface.derivs(u, v)
+            return _curvatures_from_derivs(r_u, r_v, r_uu, r_uv, r_vv)
+        except Exception:
+            pass
+    return None
+
+
+_last_intrinsic: Dict[str, Union[Surface, float, Tuple[float, float], None]] = {
+    "surface": None,
+    "u": None,
+    "v": None,
+    "step": None,
+    "kh": None,
+}
+
+_last_classical: Dict[str, Union[Surface, float, Tuple[float, float], None]] = {
+    "surface": None,
+    "u": None,
+    "v": None,
+    "step": None,
+    "kh": None,
+}
+
+# Toggle analytic fast path (derivs/analytic_KH/theoretical formulas)
+USE_ANALYTIC_DERIVS = True
+
+
 def compute_gaussian_curvature(
     surface: Surface,
     u: float,
@@ -760,8 +925,24 @@ def compute_gaussian_curvature(
     """
     Compute Gaussian curvature using intrinsic gradient method.
     """
-    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
-    return calc.compute_gaussian_curvature(u, v)
+    if (
+        _last_intrinsic["surface"] is surface and
+        _last_intrinsic["u"] == u and
+        _last_intrinsic["v"] == v and
+        _last_intrinsic["step"] == step_size and
+        _last_intrinsic["kh"] is not None
+    ):
+        return _last_intrinsic["kh"][0]
+
+    analytic = _analytic_curvatures(surface, u, v)
+    if analytic is not None:
+        _last_intrinsic.update({"surface": surface, "u": u, "v": v, "step": step_size, "kh": analytic})
+        return analytic[0]
+
+    calc = _get_cached_calc(_intrinsic_calc_cache, surface, step_size, IntrinsicGradientCurvatureCalculator, "_cs_intrinsic_calc")
+    K = calc.compute_gaussian_curvature(u, v)
+    _last_intrinsic.update({"surface": surface, "u": u, "v": v, "step": step_size, "kh": (K, None)})
+    return K
 
 
 def compute_mean_curvature(
@@ -773,8 +954,25 @@ def compute_mean_curvature(
     """
     Compute mean curvature using intrinsic gradient method.
     """
-    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
-    return calc.compute_mean_curvature(u, v)
+    if (
+        _last_intrinsic["surface"] is surface and
+        _last_intrinsic["u"] == u and
+        _last_intrinsic["v"] == v and
+        _last_intrinsic["step"] == step_size and
+        _last_intrinsic["kh"] is not None and
+        _last_intrinsic["kh"][1] is not None
+    ):
+        return _last_intrinsic["kh"][1]
+
+    analytic = _analytic_curvatures(surface, u, v)
+    if analytic is not None:
+        _last_intrinsic.update({"surface": surface, "u": u, "v": v, "step": step_size, "kh": analytic})
+        return analytic[1]
+
+    calc = _get_cached_calc(_intrinsic_calc_cache, surface, step_size, IntrinsicGradientCurvatureCalculator, "_cs_intrinsic_calc")
+    H = calc.compute_mean_curvature(u, v)
+    _last_intrinsic.update({"surface": surface, "u": u, "v": v, "step": step_size, "kh": (None, H)})
+    return H
 
 
 def compute_riemann_curvature(
@@ -786,7 +984,7 @@ def compute_riemann_curvature(
     """
     Compute Riemann curvature tensor component R^1_212.
     """
-    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
+    calc = _get_cached_calc(_intrinsic_calc_cache, surface, step_size, IntrinsicGradientCurvatureCalculator, "_cs_intrinsic_calc")
     return calc.compute_riemann_curvature(u, v)
 
 
@@ -799,7 +997,20 @@ def compute_all_curvatures(
     """
     Compute all curvature quantities using intrinsic gradient method.
     """
-    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
+    analytic = _analytic_curvatures(surface, u, v)
+    if analytic is not None:
+        K, H = analytic
+        discriminant = max(0, H * H - K)
+        sqrt_disc = discriminant ** 0.5
+        k1 = H + sqrt_disc
+        k2 = H - sqrt_disc
+        return {
+            'gaussian_curvature': K,
+            'mean_curvature': H,
+            'principal_curvatures': (k1, k2)
+        }
+
+    calc = _get_cached_calc(_intrinsic_calc_cache, surface, step_size, IntrinsicGradientCurvatureCalculator, "_cs_intrinsic_calc")
     return calc.compute_all_curvatures(u, v)
 
 
@@ -822,7 +1033,7 @@ def compute_intrinsic_gradient(
     Returns:
         GradientResult object
     """
-    grad_op = IntrinsicGradientOperator(surface, step_size)
+    grad_op = _get_cached_calc(_intrinsic_grad_cache, surface, step_size, IntrinsicGradientOperator, "_cs_intrinsic_grad")
 
     if direction == 'u':
         return grad_op.compute_u(u, v)
@@ -843,8 +1054,24 @@ def gaussian_curvature_classical(
     step_size: float = 1e-3
 ) -> float:
     """Compute Gaussian curvature using classical method."""
-    calc = CurvatureCalculator(surface, step_size)
-    return calc.compute_gaussian_curvature(u, v)
+    if (
+        _last_classical["surface"] is surface and
+        _last_classical["u"] == u and
+        _last_classical["v"] == v and
+        _last_classical["step"] == step_size and
+        _last_classical["kh"] is not None
+    ):
+        return _last_classical["kh"][0]
+
+    analytic = _analytic_curvatures(surface, u, v)
+    if analytic is not None:
+        _last_classical.update({"surface": surface, "u": u, "v": v, "step": step_size, "kh": (analytic[0], abs(analytic[1]))})
+        return analytic[0]
+
+    calc = _get_cached_calc(_classical_calc_cache, surface, step_size, CurvatureCalculator, "_cs_classical_calc")
+    K = calc.compute_gaussian_curvature(u, v)
+    _last_classical.update({"surface": surface, "u": u, "v": v, "step": step_size, "kh": (K, None)})
+    return K
 
 
 def mean_curvature_classical(
@@ -854,8 +1081,25 @@ def mean_curvature_classical(
     step_size: float = 1e-3
 ) -> float:
     """Compute mean curvature using classical method."""
-    calc = CurvatureCalculator(surface, step_size)
-    return calc.compute_mean_curvature(u, v)
+    if (
+        _last_classical["surface"] is surface and
+        _last_classical["u"] == u and
+        _last_classical["v"] == v and
+        _last_classical["step"] == step_size and
+        _last_classical["kh"] is not None and
+        _last_classical["kh"][1] is not None
+    ):
+        return _last_classical["kh"][1]
+
+    analytic = _analytic_curvatures(surface, u, v)
+    if analytic is not None:
+        _last_classical.update({"surface": surface, "u": u, "v": v, "step": step_size, "kh": (analytic[0], abs(analytic[1]))})
+        return abs(analytic[1])
+
+    calc = _get_cached_calc(_classical_calc_cache, surface, step_size, CurvatureCalculator, "_cs_classical_calc")
+    H = calc.compute_mean_curvature(u, v)
+    _last_classical.update({"surface": surface, "u": u, "v": v, "step": step_size, "kh": (None, H)})
+    return H
 
 
 def principal_curvatures_classical(
@@ -865,7 +1109,7 @@ def principal_curvatures_classical(
     step_size: float = 1e-3
 ) -> Tuple[float, float]:
     """Compute principal curvatures using classical method."""
-    calc = CurvatureCalculator(surface, step_size)
+    calc = _get_cached_calc(_classical_calc_cache, surface, step_size, CurvatureCalculator, "_cs_classical_calc")
     k1, k2, _, _ = calc.compute_principal_curvatures(u, v)
     return k1, k2
 
@@ -877,7 +1121,7 @@ def all_curvatures_classical(
     step_size: float = 1e-3
 ) -> Dict[str, Union[float, np.ndarray]]:
     """Compute all curvature quantities using classical method."""
-    calc = CurvatureCalculator(surface, step_size)
+    calc = _get_cached_calc(_classical_calc_cache, surface, step_size, CurvatureCalculator, "_cs_classical_calc")
     return calc.compute_all_curvatures(u, v)
 
 

{coordinate_system-7.1.0 → coordinate_system-7.1.1/coordinate_system.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: coordinate_system
-Version: 7.1.0
+Version: 7.1.1
 Summary: High-performance 3D coordinate system library with unified differential geometry, quantum frame algebra, and Christmas Equation (CFUT)
 Home-page: https://github.com/panguojun/Coordinate-System
 Author: Pan Guojun
@@ -51,12 +51,19 @@ Requires-Dist: matplotlib>=3.3.0
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 **Authors:** Pan Guojun
-**Version:** 7.1.0
+**Version:** 7.1.1
 **License:** MIT
 **DOI:** https://doi.org/10.5281/zenodo.14435613
 
 ---
 
+## What's New in v7.1.1 (2026-02-05)
+
+- **Curvature Fast Path**: Analytical curvature for Sphere/Torus and any surface providing `derivs` or `analytic_KH` (toggle via `USE_ANALYTIC_DERIVS`)
+- **Caching**: Reuse curvature calculators and last-call results to reduce per-sample overhead
+- **Math Core**: Branchless handedness selection for cross product; optional SIMD alignment via `PMSYS_SIMD_ALIGN`
+- **Build Flags**: AVX2 / fast-math enabled by default in build config for faster native builds
+
 ## What's New in v7.1.0 (2026-01-16)
 
 - **Physical Constants**: Added SI unit constants for precision calculations (ALPHA_FS, LAMBDA_C, ALPHA_PROJECTION)
@@ -236,6 +243,12 @@ S_YM = F_xy.yang_mills_action()
 
 ## Changelog
 
+### v7.1.1 (2026-02-05)
+- **Curvature Fast Path**: Analytical curvature for analytic surfaces with optional toggle
+- **Caching**: Curvature calculator reuse and last-call caching for repeated samples
+- **Math Core**: Branchless cross product handedness selection
+- **Build**: AVX2 / fast-math flags enabled by default for native builds
+
 ### v7.1.0 (2026-01-16)
 - **Physical Constants**: Added SI unit constants (ALPHA_FS, LAMBDA_C, ALPHA_PROJECTION)
 - **Projection Factor**: Implemented α = α_fs × λ_c ≈ 1.77×10⁻¹⁴ m for geometry-gauge coupling

{coordinate_system-7.1.0 → coordinate_system-7.1.1}/pmsys_minimal.hpp

@@ -61,13 +61,32 @@
 #pragma warning(disable:4018)
 #pragma warning(disable:4005)
 
-// ==============================================================================
-// Type definitions
-// ==============================================================================
-#define real                double
-#define EPSILON             1e-5
-#define DEVICE_CALLABLE
-#define EXPORT_API
+// ==============================================================================
+// Type definitions
+// ==============================================================================
+#define real                double
+#define EPSILON             1e-5
+
+// Force inline for hot math paths
+#if defined(_MSC_VER)
+    #define PMSYS_FORCE_INLINE __forceinline
+#elif defined(__GNUC__) || defined(__clang__)
+    #define PMSYS_FORCE_INLINE inline __attribute__((always_inline))
+#else
+    #define PMSYS_FORCE_INLINE inline
+#endif
+
+// Alignment helpers for SIMD-friendly layouts (opt-in)
+#if defined(PMSYS_SIMD_ALIGN)
+    #define PMSYS_ALIGN16   alignas(16)
+    #define PMSYS_ALIGN32   alignas(32)
+#else
+    #define PMSYS_ALIGN16
+    #define PMSYS_ALIGN32
+#endif
+
+#define DEVICE_CALLABLE     PMSYS_FORCE_INLINE
+#define EXPORT_API
 
 // Aliases
 #define anyptr              void*
@@ -152,15 +171,18 @@ inline real lerp(real h1, real h2, real alpha) {
 // ==============================================================================
 // Coordinate System Handedness (Left/Right)
 // ==============================================================================
-namespace {
-    // Global handedness setting: true = left-handed (default), false = right-handed
-    bool g_use_left_handed_system = true;
-}
+namespace {
+    // Global handedness setting: true = left-handed (default), false = right-handed
+    bool g_use_left_handed_system = true;
+    // Cross product sign to avoid per-call branching
+    real g_cross_sign = -1.0;
+}
 
 // Set coordinate system handedness
-inline void set_coordinate_handedness(bool use_left_handed) {
-    g_use_left_handed_system = use_left_handed;
-}
+inline void set_coordinate_handedness(bool use_left_handed) {
+    g_use_left_handed_system = use_left_handed;
+    g_cross_sign = use_left_handed ? -1.0 : 1.0;
+}
 
 // Get current coordinate system handedness
 inline bool get_coordinate_handedness() {
@@ -231,7 +253,7 @@ inline void hash_combine(std::size_t& seed, const real& v) {
 // 2D
 // **********************************************************************
 #pragma once
-struct vector2
+struct PMSYS_ALIGN16 vector2
 {
     static const vector2 ZERO;
     static const vector2 ONE;
@@ -523,7 +545,7 @@ inline real vector2::sEPSILON = EPSILON;
 // **********************************************************************
 // 3D
 // **********************************************************************
-struct vector3
+struct PMSYS_ALIGN32 vector3
 {
     static const vector3 ZERO;
     static const vector3 ONE;
@@ -894,25 +916,15 @@ struct vector3
         const vector3& v = (*this);
         return v - n * v.dot(n);
     }
-    DEVICE_CALLABLE vector3 cross(const vector3& v) const
-    {
-        // Use global handedness setting
-        if (g_use_left_handed_system) {
-            // Left-handed system
-            vector3 n;
-            n.x = -(y * v.z - z * v.y);
-            n.y = -(z * v.x - x * v.z);
-            n.z = -(x * v.y - y * v.x);
-            return n;
-        } else {
-            // Right-handed system
-            vector3 n;
-            n.x = (y * v.z - z * v.y);
-            n.y = (z * v.x - x * v.z);
-            n.z = (x * v.y - y * v.x);
-            return n;
-        }
-    }
+    DEVICE_CALLABLE vector3 cross(const vector3& v) const
+    {
+        // Branchless handedness selection via precomputed sign
+        vector3 n;
+        n.x = (y * v.z - z * v.y) * g_cross_sign;
+        n.y = (z * v.x - x * v.z) * g_cross_sign;
+        n.z = (x * v.y - y * v.x) * g_cross_sign;
+        return n;
+    }
     DEVICE_CALLABLE vector3 cross_left(const vector3& v) const
     {
         vector3 n;
@@ -1025,7 +1037,7 @@ inline real vector3::sEPSILON = EPSILON;
 // **********************************************************************
 // 4D vector
 // **********************************************************************
-struct vector4
+struct PMSYS_ALIGN32 vector4
 {
     static const vector4 ZERO;
     static const vector4 UX;
@@ -1606,7 +1618,7 @@ inline const vectorn vectorn::CENTER = vectorn(0.5);
     and define the unit element ONE.
 
 **************************************************************************/
-struct  quaternion
+struct PMSYS_ALIGN32 quaternion
 {
 	static const quaternion ONE;
 	static const quaternion UX;

{coordinate_system-7.1.0 → coordinate_system-7.1.1}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "coordinate_system"
-version = "7.1.0"
+version = "7.1.1"
 description = "High-performance 3D coordinate system library with unified differential geometry, quantum frame algebra, and Christmas Equation (CFUT)"
 readme = "README.md"
 requires-python = ">=3.7"

{coordinate_system-7.1.0 → coordinate_system-7.1.1}/setup.py

@@ -3,7 +3,7 @@ setup.py - Cross-platform setup for coordinate_system package
 
 **Authors:** Pan Guojun
 **DOI:** https://doi.org/10.5281/zenodo.14435613
-Version: 7.1.0
+Version: 7.1.1
 License: MIT
 """
 
@@ -33,34 +33,42 @@ with open('README.md', 'r', encoding='utf-8') as f:
 extra_compile_args = []
 extra_link_args = []
 
-if system == 'Windows':
-    # MSVC compiler flags
-    extra_compile_args = [
-        '/std:c++17',           # C++17 standard
-        '/O2',                  # Optimization
-        '/W3',                  # Warning level
-        '/EHsc',                # Exception handling
-        '/MD',                  # Runtime library
-    ]
-elif system == 'Linux':
-    # GCC compiler flags
-    extra_compile_args = [
-        '-std=c++17',           # C++17 standard
-        '-O3',                  # Optimization
-        '-Wall',                # Warnings
-        '-fPIC',                # Position independent code
-        '-fvisibility=hidden',  # Hide symbols by default
-    ]
-elif system == 'Darwin':  # macOS
-    # Clang compiler flags
-    extra_compile_args = [
-        '-std=c++17',           # C++17 standard
-        '-O3',                  # Optimization
-        '-Wall',                # Warnings
-        '-fPIC',                # Position independent code
-        '-fvisibility=hidden',  # Hide symbols by default
-        '-mmacosx-version-min=10.14',  # macOS 10.14+
-    ]
+if system == 'Windows':
+    # MSVC compiler flags
+    extra_compile_args = [
+        '/std:c++17',           # C++17 standard
+        '/O2',                  # Optimization
+        '/arch:AVX2',           # Enable AVX2
+        '/fp:fast',             # Fast floating-point (unsafe math optimizations)
+        '/W3',                  # Warning level
+        '/EHsc',                # Exception handling
+        '/MD',                  # Runtime library
+    ]
+elif system == 'Linux':
+    # GCC compiler flags
+    extra_compile_args = [
+        '-std=c++17',           # C++17 standard
+        '-O3',                  # Optimization
+        '-march=native',        # Enable local CPU features (SSE/AVX)
+        '-ffast-math',          # Fast math (unsafe)
+        '-funroll-loops',       # Loop unrolling
+        '-Wall',                # Warnings
+        '-fPIC',                # Position independent code
+        '-fvisibility=hidden',  # Hide symbols by default
+    ]
+elif system == 'Darwin':  # macOS
+    # Clang compiler flags
+    extra_compile_args = [
+        '-std=c++17',           # C++17 standard
+        '-O3',                  # Optimization
+        '-march=native',        # Enable local CPU features
+        '-ffast-math',          # Fast math (unsafe)
+        '-funroll-loops',       # Loop unrolling
+        '-Wall',                # Warnings
+        '-fPIC',                # Position independent code
+        '-fvisibility=hidden',  # Hide symbols by default
+        '-mmacosx-version-min=10.14',  # macOS 10.14+
+    ]
 
 # Define the extension module
 ext_modules = [
@@ -79,7 +87,7 @@ ext_modules = [
 
 setup(
     name='coordinate_system',
-    version='7.1.0',
+    version='7.1.1',
     packages=find_packages(),
     ext_modules=ext_modules,  # Add extension modules