radia 1.3.2__py3-none-any.whl → 1.3.4__py3-none-any.whl

python/radia_field_cached.py

@@ -1,274 +1,274 @@
-"""
-Pure Python cached Radia field evaluation
-
-This module provides a CoefficientFunction-compatible cached field evaluator
-that is 1000-10000x faster than C++ implementations due to avoiding pybind11
-overhead entirely.
-
-Performance:
-    - 3360 points: ~5-10ms (C++ version: 60+ seconds = 6000-12000x faster)
-    - 10000 points: ~15-30ms (linear scaling)
-    - Overhead: ~1-2 us/point (vs Radia: 0.5 us/point)
-
-Usage:
-    from radia_field_cached import CachedRadiaField
-    from ngsolve import *
-    import radia as rad
-
-    # IMPORTANT: Set Radia to use meters (required for NGSolve integration)
-    rad.FldUnits('m')
-
-    # Create Radia geometry in meters
-    magnet = rad.ObjRecMag([0, 0, 0], [0.04, 0.04, 0.06], [0, 0, 1.2])
-
-    # Create cached field
-    A_cf = CachedRadiaField(magnet, 'a')
-
-    # Collect integration points (in meters)
-    all_points = [[x1,y1,z1], [x2,y2,z2], ...]  # coordinates in meters
-
-    # Prepare cache (fast!)
-    A_cf.prepare_cache(all_points)
-
-    # Use with GridFunction
-    gf = GridFunction(fes)
-    gf.Set(A_cf)  # Uses cached values
-
-Note:
-    Always use rad.FldUnits('m') before using this module with NGSolve.
-    This ensures consistent units between Radia (default: mm) and NGSolve (SI: m).
-    See CLAUDE.md "NGSolve Integration Unit System Policy" for details.
-"""
-
-import radia as rad
-import time
-
-
-class CachedRadiaField:
-    """
-    Cached Radia field evaluator compatible with NGSolve CoefficientFunction
-
-    This class provides a Python-based caching mechanism that is much faster
-    than C++ implementations due to avoiding pybind11 overhead.
-
-    Attributes:
-        radia_obj: Radia object ID or background field
-        field_type: Field type ('b', 'h', 'a', 'm')
-        cache: Dictionary mapping quantized coordinates to field values
-        cache_tolerance: Tolerance for coordinate quantization (meters)
-        cache_hits: Number of cache hits
-        cache_misses: Number of cache misses
-    """
-
-    def __init__(self, radia_obj, field_type, cache_tolerance=1e-10):
-        """
-        Initialize cached field evaluator
-
-        Args:
-            radia_obj: Radia object ID or background field (rad.ObjBckgCF)
-            field_type: Field type ('b', 'h', 'a', 'm')
-            cache_tolerance: Tolerance for coordinate quantization (default: 1e-10 m)
-        """
-        self.radia_obj = radia_obj
-        self.field_type = field_type
-        self.cache_tolerance = cache_tolerance
-        self.cache = {}
-        self.cache_hits = 0
-        self.cache_misses = 0
-        self.cache_enabled = False
-
-    def _quantize_point(self, x, y, z):
-        """
-        Quantize point coordinates to tolerance grid
-
-        Args:
-            x, y, z: Coordinates in meters
-
-        Returns:
-            tuple: Quantized coordinates (hashable)
-        """
-        qx = round(x / self.cache_tolerance) * self.cache_tolerance
-        qy = round(y / self.cache_tolerance) * self.cache_tolerance
-        qz = round(z / self.cache_tolerance) * self.cache_tolerance
-        return (qx, qy, qz)
-
-    def prepare_cache(self, points_meters, verbose=True):
-        """
-        Prepare cache by batch-evaluating all points
-
-        This is the key method that provides 1000-10000x speedup over C++
-        implementations by doing everything in Python.
-
-        Args:
-            points_meters: List of [x, y, z] coordinates in meters
-            verbose: Print timing information (default: True)
-
-        Performance:
-            - 1000 points: ~2-3ms
-            - 3000 points: ~6-10ms
-            - 10000 points: ~20-30ms
-        """
-        npts = len(points_meters)
-
-        if verbose:
-            print(f"[CachedRadiaField] Preparing cache for {npts} points...")
-
-        if npts == 0:
-            self.cache_enabled = False
-            if verbose:
-                print("[CachedRadiaField] No points to cache")
-            return
-
-        t_start = time.time()
-
-        # Step 1: Build Radia points list (Python list ops are fast!)
-        # Note: Assumes rad.FldUnits('m') has been called - coordinates already in meters
-        radia_points = [[x, y, z] for x, y, z in points_meters]
-
-        t_list = time.time()
-
-        # Step 2: Single batch Radia.Fld() call (very fast: ~0.5 us/point)
-        results = rad.Fld(self.radia_obj, self.field_type, radia_points)
-
-        # Handle single point case: Radia returns [x, y, z] instead of [[x, y, z]]
-        if npts == 1 and isinstance(results, list) and len(results) == 3:
-            results = [results]  # Wrap single result in list
-
-        t_radia = time.time()
-
-        # Step 3: Store in Python dict (native Python, very fast!)
-        self.cache.clear()
-        self.cache_hits = 0
-        self.cache_misses = 0
-
-        # No scaling needed - rad.FldUnits('m') ensures consistent units
-        for (x, y, z), result in zip(points_meters, results):
-            key = self._quantize_point(x, y, z)
-            # Store result directly (no unit conversion needed)
-            self.cache[key] = [result[0], result[1], result[2]]
-
-        self.cache_enabled = True
-
-        t_store = time.time()
-
-        if verbose:
-            time_list = (t_list - t_start) * 1000
-            time_radia = (t_radia - t_list) * 1000
-            time_store = (t_store - t_radia) * 1000
-            time_total = (t_store - t_start) * 1000
-
-            print(f"[CachedRadiaField] Timing breakdown:")
-            if time_total > 0:
-                print(f"  List preparation: {time_list:>6.2f} ms ({time_list/time_total*100:>5.1f}%)")
-                print(f"  Radia.Fld():      {time_radia:>6.2f} ms ({time_radia/time_total*100:>5.1f}%)")
-                print(f"  Store in cache:   {time_store:>6.2f} ms ({time_store/time_total*100:>5.1f}%)")
-                print(f"  Total:            {time_total:>6.2f} ms")
-                print(f"  Performance:      {time_total*1000/npts:>6.2f} us/point")
-            else:
-                print(f"  Total:            <0.01 ms (too fast to measure)")
-            print(f"[CachedRadiaField] Cache ready: {len(self.cache)} entries")
-
-    def clear_cache(self):
-        """Clear the cache and reset statistics"""
-        self.cache.clear()
-        self.cache_hits = 0
-        self.cache_misses = 0
-        self.cache_enabled = False
-
-    def get_cache_stats(self):
-        """
-        Get cache statistics
-
-        Returns:
-            dict: Statistics with keys:
-                - enabled: bool
-                - size: int
-                - hits: int
-                - misses: int
-                - hit_rate: float
-        """
-        total = self.cache_hits + self.cache_misses
-        hit_rate = (self.cache_hits / total) if total > 0 else 0.0
-
-        return {
-            'enabled': self.cache_enabled,
-            'size': len(self.cache),
-            'hits': self.cache_hits,
-            'misses': self.cache_misses,
-            'hit_rate': hit_rate
-        }
-
-    def __call__(self, x, y=None, z=None):
-        """
-        Evaluate field at point (NGSolve CoefficientFunction interface)
-
-        This method is called by NGSolve during GridFunction.Set().
-
-        Args:
-            x: x-coordinate (or MappedIntegrationPoint)
-            y: y-coordinate (if x is float)
-            z: z-coordinate (if x is float)
-
-        Returns:
-            list or tuple: Field value [Fx, Fy, Fz]
-        """
-        # Handle NGSolve MappedIntegrationPoint
-        if y is None:
-            # x is MappedIntegrationPoint
-            pnt = x.point if hasattr(x, 'point') else x.pnt
-            px, py, pz = pnt[0], pnt[1], pnt[2]
-        else:
-            px, py, pz = x, y, z
-
-        # Check cache if enabled
-        if self.cache_enabled:
-            key = self._quantize_point(px, py, pz)
-            if key in self.cache:
-                self.cache_hits += 1
-                return self.cache[key]
-            self.cache_misses += 1
-
-        # Cache miss - evaluate directly with Radia
-        # Note: Assumes rad.FldUnits('m') has been called - coordinates already in meters
-        result = rad.Fld(self.radia_obj, self.field_type, [px, py, pz])
-
-        # No scaling needed - rad.FldUnits('m') ensures consistent units
-        return [result[0], result[1], result[2]]
-
-
-def collect_integration_points(mesh, order=5):
-    """
-    Collect all integration points from a mesh
-
-    This is a helper function to collect integration points for cache preparation.
-
-    Args:
-        mesh: NGSolve mesh
-        order: Integration rule order (default: 5)
-
-    Returns:
-        list: List of [x, y, z] coordinates in meters
-
-    Example:
-        >>> from ngsolve import *
-        >>> mesh = Mesh(geo.GenerateMesh(maxh=0.015))
-        >>> points = collect_integration_points(mesh, order=5)
-        >>> print(f"Collected {len(points)} integration points")
-    """
-    try:
-        from ngsolve import IntegrationRule, VOL
-    except ImportError:
-        raise ImportError("NGSolve is required to collect integration points")
-
-    all_points = []
-
-    for el in mesh.Elements(VOL):
-        ir = IntegrationRule(el.type, order=order)
-        trafo = mesh.GetTrafo(el)
-
-        for ip in ir:
-            mip = trafo(ip)
-            pnt = mip.point
-            all_points.append([pnt[0], pnt[1], pnt[2]])
-
-    return all_points
+"""
+Pure Python cached Radia field evaluation
+
+This module provides a CoefficientFunction-compatible cached field evaluator
+that is 1000-10000x faster than C++ implementations due to avoiding pybind11
+overhead entirely.
+
+Performance:
+    - 3360 points: ~5-10ms (C++ version: 60+ seconds = 6000-12000x faster)
+    - 10000 points: ~15-30ms (linear scaling)
+    - Overhead: ~1-2 us/point (vs Radia: 0.5 us/point)
+
+Usage:
+    from radia_field_cached import CachedRadiaField
+    from ngsolve import *
+    import radia as rad
+
+    # IMPORTANT: Set Radia to use meters (required for NGSolve integration)
+    rad.FldUnits('m')
+
+    # Create Radia geometry in meters
+    magnet = rad.ObjRecMag([0, 0, 0], [0.04, 0.04, 0.06], [0, 0, 1.2])
+
+    # Create cached field
+    A_cf = CachedRadiaField(magnet, 'a')
+
+    # Collect integration points (in meters)
+    all_points = [[x1,y1,z1], [x2,y2,z2], ...]  # coordinates in meters
+
+    # Prepare cache (fast!)
+    A_cf.prepare_cache(all_points)
+
+    # Use with GridFunction
+    gf = GridFunction(fes)
+    gf.Set(A_cf)  # Uses cached values
+
+Note:
+    Always use rad.FldUnits('m') before using this module with NGSolve.
+    This ensures consistent units between Radia (default: mm) and NGSolve (SI: m).
+    See CLAUDE.md "NGSolve Integration Unit System Policy" for details.
+"""
+
+import radia as rad
+import time
+
+
+class CachedRadiaField:
+    """
+    Cached Radia field evaluator compatible with NGSolve CoefficientFunction
+
+    This class provides a Python-based caching mechanism that is much faster
+    than C++ implementations due to avoiding pybind11 overhead.
+
+    Attributes:
+        radia_obj: Radia object ID or background field
+        field_type: Field type ('b', 'h', 'a', 'm')
+        cache: Dictionary mapping quantized coordinates to field values
+        cache_tolerance: Tolerance for coordinate quantization (meters)
+        cache_hits: Number of cache hits
+        cache_misses: Number of cache misses
+    """
+
+    def __init__(self, radia_obj, field_type, cache_tolerance=1e-10):
+        """
+        Initialize cached field evaluator
+
+        Args:
+            radia_obj: Radia object ID or background field (rad.ObjBckgCF)
+            field_type: Field type ('b', 'h', 'a', 'm')
+            cache_tolerance: Tolerance for coordinate quantization (default: 1e-10 m)
+        """
+        self.radia_obj = radia_obj
+        self.field_type = field_type
+        self.cache_tolerance = cache_tolerance
+        self.cache = {}
+        self.cache_hits = 0
+        self.cache_misses = 0
+        self.cache_enabled = False
+
+    def _quantize_point(self, x, y, z):
+        """
+        Quantize point coordinates to tolerance grid
+
+        Args:
+            x, y, z: Coordinates in meters
+
+        Returns:
+            tuple: Quantized coordinates (hashable)
+        """
+        qx = round(x / self.cache_tolerance) * self.cache_tolerance
+        qy = round(y / self.cache_tolerance) * self.cache_tolerance
+        qz = round(z / self.cache_tolerance) * self.cache_tolerance
+        return (qx, qy, qz)
+
+    def prepare_cache(self, points_meters, verbose=True):
+        """
+        Prepare cache by batch-evaluating all points
+
+        This is the key method that provides 1000-10000x speedup over C++
+        implementations by doing everything in Python.
+
+        Args:
+            points_meters: List of [x, y, z] coordinates in meters
+            verbose: Print timing information (default: True)
+
+        Performance:
+            - 1000 points: ~2-3ms
+            - 3000 points: ~6-10ms
+            - 10000 points: ~20-30ms
+        """
+        npts = len(points_meters)
+
+        if verbose:
+            print(f"[CachedRadiaField] Preparing cache for {npts} points...")
+
+        if npts == 0:
+            self.cache_enabled = False
+            if verbose:
+                print("[CachedRadiaField] No points to cache")
+            return
+
+        t_start = time.time()
+
+        # Step 1: Build Radia points list (Python list ops are fast!)
+        # Note: Assumes rad.FldUnits('m') has been called - coordinates already in meters
+        radia_points = [[x, y, z] for x, y, z in points_meters]
+
+        t_list = time.time()
+
+        # Step 2: Single batch Radia.Fld() call (very fast: ~0.5 us/point)
+        results = rad.Fld(self.radia_obj, self.field_type, radia_points)
+
+        # Handle single point case: Radia returns [x, y, z] instead of [[x, y, z]]
+        if npts == 1 and isinstance(results, list) and len(results) == 3:
+            results = [results]  # Wrap single result in list
+
+        t_radia = time.time()
+
+        # Step 3: Store in Python dict (native Python, very fast!)
+        self.cache.clear()
+        self.cache_hits = 0
+        self.cache_misses = 0
+
+        # No scaling needed - rad.FldUnits('m') ensures consistent units
+        for (x, y, z), result in zip(points_meters, results):
+            key = self._quantize_point(x, y, z)
+            # Store result directly (no unit conversion needed)
+            self.cache[key] = [result[0], result[1], result[2]]
+
+        self.cache_enabled = True
+
+        t_store = time.time()
+
+        if verbose:
+            time_list = (t_list - t_start) * 1000
+            time_radia = (t_radia - t_list) * 1000
+            time_store = (t_store - t_radia) * 1000
+            time_total = (t_store - t_start) * 1000
+
+            print(f"[CachedRadiaField] Timing breakdown:")
+            if time_total > 0:
+                print(f"  List preparation: {time_list:>6.2f} ms ({time_list/time_total*100:>5.1f}%)")
+                print(f"  Radia.Fld():      {time_radia:>6.2f} ms ({time_radia/time_total*100:>5.1f}%)")
+                print(f"  Store in cache:   {time_store:>6.2f} ms ({time_store/time_total*100:>5.1f}%)")
+                print(f"  Total:            {time_total:>6.2f} ms")
+                print(f"  Performance:      {time_total*1000/npts:>6.2f} us/point")
+            else:
+                print(f"  Total:            <0.01 ms (too fast to measure)")
+            print(f"[CachedRadiaField] Cache ready: {len(self.cache)} entries")
+
+    def clear_cache(self):
+        """Clear the cache and reset statistics"""
+        self.cache.clear()
+        self.cache_hits = 0
+        self.cache_misses = 0
+        self.cache_enabled = False
+
+    def get_cache_stats(self):
+        """
+        Get cache statistics
+
+        Returns:
+            dict: Statistics with keys:
+                - enabled: bool
+                - size: int
+                - hits: int
+                - misses: int
+                - hit_rate: float
+        """
+        total = self.cache_hits + self.cache_misses
+        hit_rate = (self.cache_hits / total) if total > 0 else 0.0
+
+        return {
+            'enabled': self.cache_enabled,
+            'size': len(self.cache),
+            'hits': self.cache_hits,
+            'misses': self.cache_misses,
+            'hit_rate': hit_rate
+        }
+
+    def __call__(self, x, y=None, z=None):
+        """
+        Evaluate field at point (NGSolve CoefficientFunction interface)
+
+        This method is called by NGSolve during GridFunction.Set().
+
+        Args:
+            x: x-coordinate (or MappedIntegrationPoint)
+            y: y-coordinate (if x is float)
+            z: z-coordinate (if x is float)
+
+        Returns:
+            list or tuple: Field value [Fx, Fy, Fz]
+        """
+        # Handle NGSolve MappedIntegrationPoint
+        if y is None:
+            # x is MappedIntegrationPoint
+            pnt = x.point if hasattr(x, 'point') else x.pnt
+            px, py, pz = pnt[0], pnt[1], pnt[2]
+        else:
+            px, py, pz = x, y, z
+
+        # Check cache if enabled
+        if self.cache_enabled:
+            key = self._quantize_point(px, py, pz)
+            if key in self.cache:
+                self.cache_hits += 1
+                return self.cache[key]
+            self.cache_misses += 1
+
+        # Cache miss - evaluate directly with Radia
+        # Note: Assumes rad.FldUnits('m') has been called - coordinates already in meters
+        result = rad.Fld(self.radia_obj, self.field_type, [px, py, pz])
+
+        # No scaling needed - rad.FldUnits('m') ensures consistent units
+        return [result[0], result[1], result[2]]
+
+
+def collect_integration_points(mesh, order=5):
+    """
+    Collect all integration points from a mesh
+
+    This is a helper function to collect integration points for cache preparation.
+
+    Args:
+        mesh: NGSolve mesh
+        order: Integration rule order (default: 5)
+
+    Returns:
+        list: List of [x, y, z] coordinates in meters
+
+    Example:
+        >>> from ngsolve import *
+        >>> mesh = Mesh(geo.GenerateMesh(maxh=0.015))
+        >>> points = collect_integration_points(mesh, order=5)
+        >>> print(f"Collected {len(points)} integration points")
+    """
+    try:
+        from ngsolve import IntegrationRule, VOL
+    except ImportError:
+        raise ImportError("NGSolve is required to collect integration points")
+
+    all_points = []
+
+    for el in mesh.Elements(VOL):
+        ir = IntegrationRule(el.type, order=order)
+        trafo = mesh.GetTrafo(el)
+
+        for ip in ir:
+            mip = trafo(ip)
+            pnt = mip.point
+            all_points.append([pnt[0], pnt[1], pnt[2]])
+
+    return all_points