coordinate-system 2.5.0__cp313-cp313-win_amd64.whl → 2.5.3__cp313-cp313-win_amd64.whl

coordinate_system/__init__.py

@@ -4,26 +4,21 @@ from .coordinate_system import vec3, vec2
 from .coordinate_system import quat
 from .coordinate_system import coord3
 
-# Differential geometry module (v2.2.0+)
+# Differential geometry module (v3.0.0+)
 from .differential_geometry import (
     # Classes
     Surface,
     Sphere,
     Torus,
     MetricTensor,
-    ConnectionOperator,
+    IntrinsicGradientOperator,
+    IntrinsicGradientCurvatureCalculator,
 
     # Main functions
-    compute_metric,
-    compute_connection,
-    compute_curvature_tensor,
-    compute_gaussian_curvature,
-
-    # Aliases
-    compute_frame_derivative,
     compute_intrinsic_gradient,
-    compute_geometric_gradient,
-    compute_metric_tensor,
+    compute_gaussian_curvature,
+    compute_curvature_tensor,
+    compute_all_curvatures,
 )
 
 # High-precision curvature computation module (v2.3.0+)
@@ -47,9 +42,8 @@ from .curvature import (
 )
 
 # Intrinsic Gradient Operator method (v2.4.0+)
-from .intrinsic_gradient_curvature import (
-    IntrinsicGradientOperator,
-    IntrinsicGradientCurvatureCalculator,
+# Now imported from curvature module for backward compatibility
+from .curvature import (
     intrinsic_gradient_gaussian_curvature,
     intrinsic_gradient_mean_curvature,
     intrinsic_gradient_principal_curvatures,
@@ -57,20 +51,21 @@ from .intrinsic_gradient_curvature import (
 )
 
 __all__ = [
+    # Constants
+    'ZERO3','UNITX','UNITY','UNITZ','ONE3','ONE4','ONEC',
+    
     # Core types
     'vec3', 'vec2', 'quat', 'coord3', 'lerp',
 
-    # Differential geometry classes (v2.2.0+)
+    # Differential geometry classes (v3.0.0+)
     'Surface', 'Sphere', 'Torus',
-    'MetricTensor', 'ConnectionOperator',
-
-    # Differential geometry functions (v2.2.0+)
-    'compute_metric', 'compute_connection',
-    'compute_curvature_tensor', 'compute_gaussian_curvature',
+    'MetricTensor', 'IntrinsicGradientOperator', 'IntrinsicGradientCurvatureCalculator',
 
-    # Aliases
-    'compute_frame_derivative', 'compute_intrinsic_gradient',
-    'compute_geometric_gradient', 'compute_metric_tensor',
+    # Differential geometry functions (v3.0.0+)
+    'compute_intrinsic_gradient',
+    'compute_gaussian_curvature',
+    'compute_curvature_tensor',
+    'compute_all_curvatures',
 
     # High-precision curvature module - Classical method (v2.3.0+)
     'CurvatureCalculator',
@@ -82,9 +77,7 @@ __all__ = [
     'gaussian_curvature_lie',
     'compare_methods',
 
-    # Intrinsic Gradient Operator method (v2.4.0+)
-    'IntrinsicGradientOperator',
-    'IntrinsicGradientCurvatureCalculator',
+    # Intrinsic Gradient Operator method (v2.4.0+, merged into other modules)
     'intrinsic_gradient_gaussian_curvature',
     'intrinsic_gradient_mean_curvature',
     'intrinsic_gradient_principal_curvatures',

coordinate_system/coord3_wrapper.py

@@ -0,0 +1,300 @@
+"""
+Coord3 Wrapper for Intrinsic Gradient Operator
+===============================================
+
+This module provides a Python wrapper for coord3 that correctly implements
+the mathematical operations needed for the intrinsic gradient operator.
+
+Key insight: Use coord3's normalize() to separate rotation and scaling,
+which is a core advantage of our coordinate system design over matrices.
+
+Solution: Implement subtraction that properly handles the rotation-scale separation.
+"""
+
+import numpy as np
+from .coordinate_system import coord3 as _coord3, vec3
+import math
+
+
+class Coord3Wrapper:
+    """
+    Wrapper for coord3 that implements correct arithmetic for gradient operators
+
+    The intrinsic gradient operator requires:
+    G_μ = (c(u+h) - c(u)) / h
+
+    This implementation leverages coord3's ability to separate rotation and scaling.
+    """
+
+    def __init__(self, coord3_obj=None):
+        """
+        Initialize from a coord3 object or create new
+
+        Args:
+            coord3_obj: Original coord3 object from C++ binding
+        """
+        if coord3_obj is None:
+            self._c3 = _coord3()
+        else:
+            self._c3 = coord3_obj
+            # Ensure normalization to separate rotation and scale
+            self.normalize_axes()
+
+    def normalize_axes(self):
+        """
+        Normalize axes and extract scale factors
+
+        This is the key operation that separates rotation from scaling,
+        which is the core advantage of coord3 over matrix representations.
+        """
+        # Extract scale factors from current axes
+        sx = math.sqrt(self._c3.ux.dot(self._c3.ux))
+        sy = math.sqrt(self._c3.uy.dot(self._c3.uy))
+        sz = math.sqrt(self._c3.uz.dot(self._c3.uz))
+
+        # Normalize axes (pure rotation)
+        if sx > 1e-10:
+            self._c3.ux = self._c3.ux / sx
+        if sy > 1e-10:
+            self._c3.uy = self._c3.uy / sy
+        if sz > 1e-10:
+            self._c3.uz = self._c3.uz / sz
+
+        # Store scale factors separately
+        self._c3.s = vec3(sx, sy, sz)
+
+    @property
+    def o(self):
+        """Origin/position"""
+        return self._c3.o
+
+    @property
+    def ux(self):
+        """X axis direction (unit vector)"""
+        return self._c3.ux
+
+    @property
+    def uy(self):
+        """Y axis direction (unit vector)"""
+        return self._c3.uy
+
+    @property
+    def uz(self):
+        """Z axis direction (unit vector)"""
+        return self._c3.uz
+
+    @property
+    def s(self):
+        """Scale factors"""
+        return self._c3.s
+
+    def VX(self):
+        """Scaled X axis = ux * s.x"""
+        return vec3(
+            self.ux.x * self.s.x,
+            self.ux.y * self.s.x,
+            self.ux.z * self.s.x
+        )
+
+    def VY(self):
+        """Scaled Y axis = uy * s.y"""
+        return vec3(
+            self.uy.x * self.s.y,
+            self.uy.y * self.s.y,
+            self.uy.z * self.s.y
+        )
+
+    def VZ(self):
+        """Scaled Z axis = uz * s.z"""
+        return vec3(
+            self.uz.x * self.s.z,
+            self.uz.y * self.s.z,
+            self.uz.z * self.s.z
+        )
+
+    def __sub__(self, other):
+        """
+        Subtraction for gradient operator with proper rotation-scale separation
+
+        This leverages coord3's design advantage:
+        1. Both frames are normalized (rotation and scale separated)
+        2. Compute differences in rotation (unit vectors)
+        3. Compute differences in scale (scale factors)
+        4. Keep them separated for proper gradient computation
+        """
+        result = Coord3Wrapper()
+
+        # Ensure both frames are normalized
+        self.normalize_axes()
+        if isinstance(other, Coord3Wrapper):
+            other.normalize_axes()
+
+        # Origin difference
+        result._c3.o = self.o - other.o
+
+        # Rotation differences (unit vectors)
+        result._c3.ux = self.ux - other.ux
+        result._c3.uy = self.uy - other.uy
+        result._c3.uz = self.uz - other.uz
+
+        # Scale differences (kept separate)
+        result._c3.s = self.s - other.s
+
+        return result
+
+    def __truediv__(self, scalar):
+        """
+        Division by scalar for gradient operator
+
+        Used in G_μ = (c(u+h) - c(u)) / h
+        """
+        if isinstance(scalar, (int, float)):
+            result = Coord3Wrapper()
+
+            # Divide all components by scalar
+            result._c3.o = self.o / scalar
+            result._c3.ux = self.ux / scalar
+            result._c3.uy = self.uy / scalar
+            result._c3.uz = self.uz / scalar
+            result._c3.s = self.s / scalar
+
+            return result
+        else:
+            raise TypeError(f"Division only supported by scalar, got {type(scalar)}")
+
+    def compute_metric_det(self):
+        """
+        Compute determinant of metric tensor for 2D surface
+
+        For a surface parametrized by (u,v):
+        g = [[E, F], [F, G]]
+        where E = |∂r/∂u|², F = ∂r/∂u · ∂r/∂v, G = |∂r/∂v|²
+
+        Returns:
+            det(g) = E*G - F²
+        """
+        # Get scaled tangent vectors
+        vx = self.VX()  # ∂r/∂u direction
+        vy = self.VY()  # ∂r/∂v direction
+
+        # First fundamental form coefficients
+        E = vx.dot(vx)  # g_uu
+        F = vx.dot(vy)  # g_uv
+        G = vy.dot(vy)  # g_vv
+
+        # Determinant
+        return E * G - F * F
+
+    def to_coord3(self):
+        """Convert back to original coord3"""
+        return self._c3
+
+    @classmethod
+    def from_surface_frame(cls, surface, u, v, compute_frame_func):
+        """
+        Create from surface using frame computation function
+
+        Args:
+            surface: Surface object
+            u, v: Parameters
+            compute_frame_func: Function to compute embedding frame
+
+        Returns:
+            Coord3Wrapper with proper metric information
+        """
+        frame = compute_frame_func(surface, u, v)
+        return cls(frame)
+
+
+def create_embedding_frame_with_normalize(surface, u, v):
+    """
+    Create embedding frame for surface at point (u,v) using coord3's normalize
+
+    This implementation leverages coord3's design advantage:
+    1. Compute tangent vectors r_u, r_v
+    2. Build initial frame with scaled axes
+    3. Use normalize() to separate rotation and scaling
+    4. Apply Gram-Schmidt in the normalized space
+    5. Preserve metric information in scale factors
+
+    Returns:
+        coord3 with proper embedding frame (rotation and scale separated)
+    """
+    # Get position
+    pos = surface.position(u, v)
+
+    # Compute tangent vectors using finite differences
+    h = 1e-6
+    pos_u_plus = surface.position(u + h, v)
+    pos_u_minus = surface.position(u - h, v)
+    r_u = (pos_u_plus - pos_u_minus) / (2 * h)
+
+    pos_v_plus = surface.position(u, v + h)
+    pos_v_minus = surface.position(u, v - h)
+    r_v = (pos_v_plus - pos_v_minus) / (2 * h)
+
+    # Create initial frame with tangent vectors (not normalized)
+    c = _coord3()
+    c.o = pos
+    c.ux = r_u  # Will be normalized later
+    c.uy = r_v  # Will be normalized later
+
+    # Compute initial normal (may not be unit)
+    n = r_u.cross(r_v)
+    c.uz = n
+
+    # Use coord3's normalize to separate rotation and scale
+    # This automatically extracts scale factors and normalizes axes
+    c.normalize()  # This is the key operation!
+
+    # Now apply Gram-Schmidt to ensure orthogonality
+    # (while preserving the extracted scale factors)
+
+    # Get current scale factors (preserved from normalize)
+    s1 = c.s.x
+    s2 = c.s.y
+    s3 = c.s.z
+
+    # Gram-Schmidt on normalized axes
+    e1 = c.ux  # Already normalized
+
+    # Orthogonalize e2 against e1
+    e2_temp = c.uy - e1 * c.uy.dot(e1)
+    e2_len = math.sqrt(e2_temp.dot(e2_temp))
+    if e2_len > 1e-10:
+        e2 = e2_temp / e2_len
+    else:
+        # Degenerate case: create orthogonal vector
+        if abs(e1.x) < 0.9:
+            e2 = vec3(1, 0, 0) - e1 * e1.x
+        else:
+            e2 = vec3(0, 1, 0) - e1 * e1.y
+        e2 = e2.normalized()
+
+    # Compute orthogonal normal
+    e3 = e1.cross(e2)
+    e3_len = math.sqrt(e3.dot(e3))
+    if e3_len > 1e-10:
+        e3 = e3 / e3_len
+    else:
+        e3 = vec3(0, 0, 1)
+
+    # Update frame with orthonormal axes
+    c.ux = e1
+    c.uy = e2
+    c.uz = e3
+
+    # Preserve the original scale factors (metric information)
+    # This is crucial for curvature computation
+    c.s = vec3(s1, s2, 1.0)
+
+    return c
+
+
+def create_embedding_frame(surface, u, v):
+    """
+    Create embedding frame for surface - backward compatibility wrapper
+
+    Calls the new implementation that uses normalize().
+    """
+    return create_embedding_frame_with_normalize(surface, u, v)

coordinate_system/curvature.py

@@ -33,9 +33,10 @@ from .differential_geometry import Surface
 from .coordinate_system import coord3, vec3
 from .differential_geometry import (
     MetricTensor,
-    ConnectionOperator,
+    IntrinsicGradientOperator,
+    IntrinsicGradientCurvatureCalculator,
     compute_curvature_tensor as compute_curvature_tensor_lie,
-    compute_metric
+    compute_all_curvatures as compute_all_curvatures_intrinsic
 )
 
 
@@ -594,7 +595,7 @@ class LieGroupCurvatureCalculator:
             )
 
             # Compute metric tensor
-            g = compute_metric(self.surface, u, v)
+            g = MetricTensor.from_surface(self.surface, u, v)
 
             # Extract Gaussian curvature using antisymmetric part
             # K = R_{12}^{antisym} / det(g) = (R_01 - R_10)/2 / det(g)
@@ -650,14 +651,12 @@ class LieGroupCurvatureCalculator:
         self.surface.h = self.h
 
         try:
-            # Compute connection operators
-            conn = ConnectionOperator(
+            # Compute intrinsic gradient operators
+            intrinsic_op = IntrinsicGradientOperator(
                 self.surface,
-                self.scale_factor,
-                self.use_metric_correction,
                 self.h
             )
-            G_u, G_v = conn.compute_both(u, v)
+            G_u, G_v = intrinsic_op.compute_both(u, v)
 
             # Compute curvature tensor
             R_uv = compute_curvature_tensor_lie(
@@ -668,7 +667,7 @@ class LieGroupCurvatureCalculator:
             )
 
             # Compute metric
-            g = compute_metric(self.surface, u, v)
+            g = MetricTensor.from_surface(self.surface, u, v)
 
             # Extract Gaussian curvature using antisymmetric part
             # K = (R_01 - R_10)/2 / det(g)
@@ -785,16 +784,30 @@ def gaussian_curvature_lie(
 
 
 # ========== Intrinsic Gradient Operator Method ==========
-# Import from the new module
-from .intrinsic_gradient_curvature import (
+# Now imported from differential_geometry module
+from .differential_geometry import (
     IntrinsicGradientOperator,
     IntrinsicGradientCurvatureCalculator,
-    intrinsic_gradient_gaussian_curvature,
-    intrinsic_gradient_mean_curvature,
-    intrinsic_gradient_principal_curvatures,
-    intrinsic_gradient_all_curvatures,
 )
 
+# Define convenience functions for backward compatibility
+def intrinsic_gradient_gaussian_curvature(surface, u, v, step_size=1e-3):
+    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
+    return calc.compute_gaussian_curvature(u, v)
+
+def intrinsic_gradient_mean_curvature(surface, u, v, step_size=1e-3):
+    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
+    return calc.compute_mean_curvature(u, v)
+
+def intrinsic_gradient_principal_curvatures(surface, u, v, step_size=1e-3):
+    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
+    result = calc.compute_all_curvatures(u, v)
+    return result['principal_curvatures']
+
+def intrinsic_gradient_all_curvatures(surface, u, v, step_size=1e-3):
+    calc = IntrinsicGradientCurvatureCalculator(surface, step_size)
+    return calc.compute_all_curvatures(u, v)
+
 # ========== Export ==========
 
 __all__ = [