nmag-python-3 0.0.2__py3-none-any.whl

nmesh/mesher/relaxation/geometry/builder.py

@@ -0,0 +1,154 @@
+"""Construction helpers for relaxation geometry bundles."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import cast
+
+import numpy as np
+
+from ....backend import RawMesh
+from ....geometry.primitives import Body
+from .._constants import BOUNDARY_FUZZ
+from .._types import DensityFunction, FloatArray, RegionFunction
+from ..density import _compile_density_function
+from .model import FemGeometry
+
+
+def _raw_mesh_points(raw_mesh: RawMesh, dim: int) -> FloatArray:
+    """Return mesh points as a validated floating-point array."""
+
+    coords: FloatArray = np.asarray(raw_mesh.points, dtype=np.float64)
+    if coords.size == 0:
+        return np.empty((0, dim), dtype=float)
+    if coords.ndim == 1:
+        coords = coords[np.newaxis, :]
+    if coords.shape[1] != dim:
+        raise ValueError(f"Expected hint mesh points with dimension {dim}, got {coords.shape[1]}")
+    return coords
+
+
+def _dedupe_hint_points(points: FloatArray) -> FloatArray:
+    if len(points) == 0:
+        return points
+    keep_indices: list[int] = []
+    seen: set[tuple[float, ...]] = set()
+    for index, point in enumerate(points):
+        key = tuple(cast(list[float], np.round(np.asarray(point), decimals=10).tolist()))
+        if key not in seen:
+            seen.add(key)
+            keep_indices.append(index)
+    return points[np.asarray(keep_indices, dtype=int)]
+
+
+def _process_bodies_and_hints(
+    bodies: list[Body], hints: Sequence[Sequence[object]], dim: int
+) -> tuple[list[RegionFunction], list[FloatArray], list[int], list[Body | None]]:
+    """Convert bodies and hint meshes into region predicates and hint blocks."""
+
+    body_functions: list[RegionFunction] = []
+    piece_hints: list[FloatArray] = []
+    region_ids: list[int] = []
+    region_bodies: list[Body | None] = []
+    for region_id, body in enumerate(bodies, start=1):
+        body_functions.append(
+            lambda points, member=body: (
+                np.asarray(member.evaluate(points), dtype=float) >= -BOUNDARY_FUZZ
+            )
+        )
+        piece_hints.append(np.empty((0, dim), dtype=float))
+        region_ids.append(region_id)
+        region_bodies.append(body)
+    next_region_id = len(region_ids) + 1
+    for hint in hints:
+        if len(hint) != 2:
+            raise ValueError("Each mesh hint must contain a mesh and a body.")
+        hint_mesh, hint_body = hint
+        if not isinstance(hint_mesh, RawMesh) or not isinstance(hint_body, Body):
+            raise TypeError("Mesh hints must contain a RawMesh and Body.")
+        hint_points = _raw_mesh_points(hint_mesh, dim)
+        if len(hint_points) > 0:
+            mask = np.asarray(hint_body.evaluate(hint_points), dtype=float) >= -BOUNDARY_FUZZ
+            hint_points = _dedupe_hint_points(hint_points[mask])
+        body_functions.append(
+            lambda points, member=hint_body: (
+                np.asarray(member.evaluate(points), dtype=float) >= -BOUNDARY_FUZZ
+            )
+        )
+        piece_hints.append(hint_points)
+        region_ids.append(next_region_id)
+        region_bodies.append(hint_body)
+        next_region_id += 1
+    return body_functions, piece_hints, region_ids, region_bodies
+
+
+def _build_region_lists(
+    bbox_min: FloatArray,
+    bbox_max: FloatArray,
+    body_functions: list[RegionFunction],
+    region_ids: list[int],
+    region_bodies: list[Body | None],
+    *,
+    mesh_exterior: bool,
+) -> tuple[list[RegionFunction], list[int], list[Body | None]]:
+    """Build ordered region lists, including the exterior region when requested."""
+
+    region_functions: list[RegionFunction] = []
+    ordered_region_ids: list[int] = []
+    ordered_region_bodies: list[Body | None] = []
+    if mesh_exterior:
+
+        def exterior(points: FloatArray) -> np.ndarray:
+            bbox_mask = np.all(
+                (points >= bbox_min - BOUNDARY_FUZZ) & (points <= bbox_max + BOUNDARY_FUZZ),
+                axis=1,
+            )
+            inside_any = np.zeros(len(points), dtype=bool)
+            for body_fun in body_functions:
+                inside_any |= body_fun(points)
+            return bbox_mask & ~inside_any
+
+        region_functions.append(exterior)
+        ordered_region_ids.append(0)
+        ordered_region_bodies.append(None)
+    region_functions.extend(body_functions)
+    ordered_region_ids.extend(region_ids)
+    ordered_region_bodies.extend(region_bodies)
+    return region_functions, ordered_region_ids, ordered_region_bodies
+
+
+def fem_geometry_from_bodies(
+    bounding_box: tuple[FloatArray, FloatArray],
+    bodies: list[Body],
+    hints: Sequence[Sequence[object]],
+    *,
+    density: str | DensityFunction | None = None,
+    mesh_exterior: bool = False,
+) -> FemGeometry:
+    """Construct the geometry bundle consumed by the Python meshing engine."""
+
+    bbox_min: FloatArray = np.asarray(bounding_box[0], dtype=np.float64)
+    bbox_max: FloatArray = np.asarray(bounding_box[1], dtype=np.float64)
+    dim = int(len(bbox_min))
+    body_functions, piece_hints, region_ids, region_bodies = _process_bodies_and_hints(
+        bodies, hints, dim
+    )
+    region_functions, ordered_region_ids, ordered_region_bodies = _build_region_lists(
+        bbox_min,
+        bbox_max,
+        body_functions,
+        region_ids,
+        region_bodies,
+        mesh_exterior=mesh_exterior,
+    )
+    return FemGeometry(
+        dim=dim,
+        bbox_min=bbox_min,
+        bbox_max=bbox_max,
+        density_fun=_compile_density_function(density),
+        region_ids=tuple(ordered_region_ids),
+        region_functions=tuple(region_functions),
+        region_bodies=tuple(ordered_region_bodies),
+        piece_hints=tuple(piece_hints),
+        mesh_exterior=bool(mesh_exterior),
+    )

nmesh/mesher/relaxation/geometry/model.py

@@ -0,0 +1,194 @@
+"""Runtime geometry queries for the relaxation meshing pipeline."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+from ....geometry.primitives import Body
+from .._constants import BOUNDARY_FUZZ, DENSITY_EPSILON
+from .._types import DensityFunction, FloatArray, RegionFunction
+
+
+@dataclass(frozen=True, slots=True)
+class FemGeometry:
+    """Geometry bundle used by the Python meshing engine."""
+
+    dim: int
+    bbox_min: FloatArray
+    bbox_max: FloatArray
+    density_fun: DensityFunction
+    region_ids: tuple[int, ...]
+    region_functions: tuple[RegionFunction, ...]
+    region_bodies: tuple[Body | None, ...]
+    piece_hints: tuple[FloatArray, ...]
+    mesh_exterior: bool
+
+    def points_in_bbox(self, points: FloatArray) -> np.ndarray:
+        """Return a mask showing which points lie inside the bounding box."""
+
+        return np.all(
+            (points >= self.bbox_min - BOUNDARY_FUZZ) & (points <= self.bbox_max + BOUNDARY_FUZZ),
+            axis=1,
+        )
+
+    def classify_points(self, points: FloatArray) -> np.ndarray:
+        """Return the first matching region id for each point, or -1 outside."""
+
+        if points.size == 0:
+            return np.empty(0, dtype=int)
+        coords = np.asarray(points, dtype=float)
+        assigned = np.full(len(coords), -1, dtype=int)
+        bbox_mask = self.points_in_bbox(coords)
+        for region_id, region_fun in zip(self.region_ids, self.region_functions, strict=True):
+            mask = bbox_mask & region_fun(coords) & (assigned < 0)
+            assigned[mask] = region_id
+        return assigned
+
+    def density_at(self, point: FloatArray) -> float:
+        """Evaluate the density function with a small positive lower bound."""
+
+        return max(float(self.density_fun(point)), DENSITY_EPSILON)
+
+    def boundary_mask(self, points: FloatArray, tolerance: float) -> np.ndarray:
+        """Return a mask for points that lie close to a region or box boundary."""
+
+        if points.size == 0:
+            return np.empty(0, dtype=bool)
+        coords = np.asarray(points, dtype=float)
+        mask = np.zeros(len(coords), dtype=bool)
+        for body in self.region_bodies:
+            if body is not None:
+                mask |= np.abs(np.asarray(body.evaluate(coords), dtype=float)) <= tolerance
+        if self.mesh_exterior:
+            mask |= np.any(
+                np.isclose(coords, self.bbox_min, atol=tolerance, rtol=0.0)
+                | np.isclose(coords, self.bbox_max, atol=tolerance, rtol=0.0),
+                axis=1,
+            )
+        return mask & self.points_in_bbox(coords)
+
+    def boundary_distance(self, point: FloatArray) -> float:
+        """Return the smallest available distance-like scalar to a boundary."""
+
+        coord = np.asarray(point, dtype=float)
+        distances = [
+            abs(float(body.evaluate(coord))) for body in self.region_bodies if body is not None
+        ]
+        if self.mesh_exterior:
+            distances.extend(
+                min(
+                    abs(float(coord[axis] - self.bbox_min[axis])),
+                    abs(float(coord[axis] - self.bbox_max[axis])),
+                )
+                for axis in range(self.dim)
+            )
+        return min(distances) if distances else math.inf
+
+    def boundary_normal(self, point: FloatArray) -> FloatArray:
+        """Estimate a unit normal for the closest relevant boundary."""
+
+        coord = np.asarray(point, dtype=float)
+        best_distance = math.inf
+        best_normal = np.zeros(self.dim, dtype=float)
+        for body in self.region_bodies:
+            if body is None:
+                continue
+            distance = abs(float(body.evaluate(coord)))
+            if distance > best_distance:
+                continue
+            gradient = self.boundary_gradient(coord, body)
+            norm = float(np.linalg.norm(gradient))
+            if norm > DENSITY_EPSILON:
+                best_distance = distance
+                best_normal = gradient / norm
+        if self.mesh_exterior:
+            for axis in range(self.dim):
+                dist_min = abs(float(coord[axis] - self.bbox_min[axis]))
+                if dist_min < best_distance:
+                    best_distance = dist_min
+                    best_normal = np.zeros(self.dim, dtype=float)
+                    best_normal[axis] = 1.0
+                dist_max = abs(float(coord[axis] - self.bbox_max[axis]))
+                if dist_max < best_distance:
+                    best_distance = dist_max
+                    best_normal = np.zeros(self.dim, dtype=float)
+                    best_normal[axis] = -1.0
+        return best_normal
+
+    def boundary_gradient(self, point: FloatArray, body: Body) -> FloatArray:
+        """Estimate the gradient of one implicit body at a point."""
+
+        coord = np.asarray(point, dtype=float)
+        gradient = np.zeros(self.dim, dtype=float)
+        extent = max(float(np.max(self.bbox_max - self.bbox_min)), 1.0)
+        epsilon = max(BOUNDARY_FUZZ * 10.0, extent * 1.0e-6)
+        for axis in range(self.dim):
+            offset = np.zeros(self.dim, dtype=float)
+            offset[axis] = epsilon
+            gradient[axis] = (
+                float(body.evaluate(coord + offset)) - float(body.evaluate(coord - offset))
+            ) / (2.0 * epsilon)
+        return gradient
+
+    def project_point_to_boundary_from_inside(
+        self, point: FloatArray, *, acceptable_fuzz: float, max_steps: int
+    ) -> FloatArray:
+        """Project an interior point onto implicit boundaries using the legacy correction."""
+
+        coords: FloatArray = np.array(point, dtype=np.float64, copy=True)
+        bodies = [body for body in self.region_bodies if body is not None]
+        if not bodies:
+            return self._project_point_to_box_boundary(coords)
+        for _ in range(max(max_steps, 0)):
+            violated_body: Body | None = None
+            violated_value = 0.0
+            for body in bodies:
+                value = float(body.evaluate(coords))
+                if value > acceptable_fuzz:
+                    violated_body, violated_value = body, value
+                    break
+            if violated_body is None:
+                return coords
+            gradient = self.boundary_gradient(coords, violated_body)
+            gradient_norm_sq = float(np.dot(gradient, gradient))
+            scale = (
+                1.0e-6
+                if gradient_norm_sq <= DENSITY_EPSILON
+                else -violated_value / gradient_norm_sq
+            )
+            coords = coords + scale * gradient
+        return coords
+
+    def _project_point_to_box_boundary(self, point: FloatArray) -> FloatArray:
+        coords: FloatArray = np.array(point, dtype=np.float64, copy=True)
+        distances_min = np.abs(coords - self.bbox_min)
+        distances_max = np.abs(coords - self.bbox_max)
+        min_axis = int(np.argmin(distances_min))
+        max_axis = int(np.argmin(distances_max))
+        if distances_min[min_axis] <= distances_max[max_axis]:
+            coords[min_axis] = self.bbox_min[min_axis]
+        else:
+            coords[max_axis] = self.bbox_max[max_axis]
+        return coords
+
+    def project_segment_to_domain(
+        self, start: FloatArray, end: FloatArray, *, iterations: int = 18
+    ) -> FloatArray:
+        """Project an outside point back into the domain along a segment."""
+
+        lower: FloatArray = np.array(start, dtype=np.float64, copy=True)
+        upper: FloatArray = np.array(end, dtype=np.float64, copy=True)
+        if self.classify_points(lower[np.newaxis, :])[0] < 0:
+            return lower
+        if self.classify_points(upper[np.newaxis, :])[0] >= 0:
+            return upper
+        for _ in range(iterations):
+            middle = 0.5 * (lower + upper)
+            if self.classify_points(middle[np.newaxis, :])[0] >= 0:
+                lower = middle
+            else:
+                upper = middle
+        return lower

nmesh/mesher/relaxation/seeding/__init__.py

@@ -0,0 +1,74 @@
+"""Compatibility exports and seed-point assembly for relaxation meshing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .._constants import STATE_FIXED, STATE_SIMPLE
+from .._types import FloatArray
+from ..geometry import FemGeometry
+from .periodic import _apply_periodic_fixed_states, _periodic_outer_box_points
+from .points import _as_float_array as _as_float_array  # noqa: F401
+from .points import _classify_dynamic_states as _classify_dynamic_states  # noqa: F401
+from .points import _dedupe_fixed_mobile, _filter_relevant_points  # noqa: F401
+from .points import _dedupe_points as _dedupe_points
+from .sampling import _collect_hint_points, _select_generated_points
+
+
+def _prepare_initial_points(
+    geometry: FemGeometry,
+    a0: float,
+    fixed_points: FloatArray,
+    mobile_points: FloatArray,
+    simply_points: FloatArray,
+    periodic: list[float] | list[bool],
+    rng: np.random.Generator,
+    params: dict[str, Any] | None = None,
+) -> tuple[FloatArray, np.ndarray]:
+    """Prepare the initial point cloud and point-state array for relaxation."""
+
+    params = {} if params is None else params
+    fixed_points, mobile_points, simply_points = _dedupe_fixed_mobile(
+        fixed_points, mobile_points, simply_points
+    )
+    fixed_points = _filter_relevant_points(geometry, fixed_points)
+    mobile_points = _filter_relevant_points(geometry, mobile_points)
+    simply_points = _filter_relevant_points(geometry, simply_points)
+
+    if len(simply_points) > 0:
+        states = np.full(len(simply_points), STATE_SIMPLE, dtype=int)
+        _apply_periodic_fixed_states(states, simply_points, geometry, periodic, a0)
+        return simply_points, states
+
+    generated_points = (
+        _select_generated_points(
+            geometry,
+            a0,
+            fixed_points,
+            mobile_points,
+            simply_points,
+            rng,
+            params,
+        )
+        if len(mobile_points) == 0
+        else np.empty((0, geometry.dim), dtype=float)
+    )
+    hint_block = _collect_hint_points(geometry)
+    periodic_block = _periodic_outer_box_points(geometry, a0, periodic)
+    all_points = np.vstack(
+        (fixed_points, simply_points, mobile_points, hint_block, periodic_block, generated_points)
+    )
+    states = np.concatenate(
+        (
+            np.full(len(fixed_points), STATE_FIXED, dtype=int),
+            np.full(len(simply_points), STATE_SIMPLE, dtype=int),
+            _classify_dynamic_states(geometry, mobile_points, a0),
+            np.full(len(hint_block), STATE_FIXED, dtype=int),
+            np.full(len(periodic_block), STATE_FIXED, dtype=int),
+            _classify_dynamic_states(geometry, generated_points, a0),
+        )
+    )
+    _apply_periodic_fixed_states(states, all_points, geometry, periodic, a0)
+    return all_points, states

nmesh/mesher/relaxation/seeding/periodic.py

@@ -0,0 +1,88 @@
+"""Periodic-boundary seed-point and state helpers."""
+
+from __future__ import annotations
+
+import math
+from itertools import product
+
+import numpy as np
+
+from .._constants import BOUNDARY_FUZZ, DENSITY_EPSILON, STATE_FIXED
+from .._types import FloatArray
+from ..geometry import FemGeometry
+from .points import _dedupe_points, _filter_relevant_points
+
+
+def _periodic_outer_box_points(
+    geometry: FemGeometry, a0: float, periodic: list[float] | list[bool]
+) -> FloatArray:
+    """Create paired fixed seed points on periodic outer-box faces."""
+
+    periodic_flags = [bool(value) for value in periodic]
+    if not any(periodic_flags):
+        return np.empty((0, geometry.dim), dtype=float)
+    points: list[FloatArray] = []
+    spacing = max(a0, DENSITY_EPSILON)
+    for periodic_axis, enabled in enumerate(periodic_flags):
+        if not enabled:
+            continue
+        points.extend(_periodic_face_points(geometry, periodic_axis, spacing))
+    if not points:
+        return np.empty((0, geometry.dim), dtype=float)
+    return _filter_relevant_points(geometry, _dedupe_points(np.asarray(points, dtype=float)))
+
+
+def _periodic_face_points(
+    geometry: FemGeometry,
+    periodic_axis: int,
+    spacing: float,
+) -> list[FloatArray]:
+    """Return matching points on the two periodic faces of one axis."""
+
+    other_axes = [axis for axis in range(geometry.dim) if axis != periodic_axis]
+    face_axes: list[FloatArray] = []
+    for axis in other_axes:
+        extent = float(geometry.bbox_max[axis] - geometry.bbox_min[axis])
+        count = max(2, int(math.floor(extent / spacing)) + 1)
+        face_axes.append(
+            np.linspace(
+                float(geometry.bbox_min[axis]),
+                float(geometry.bbox_max[axis]),
+                count,
+                dtype=float,
+            )
+        )
+
+    points: list[FloatArray] = []
+    for coordinates in product(*(axis.tolist() for axis in face_axes)):
+        for side in (geometry.bbox_min[periodic_axis], geometry.bbox_max[periodic_axis]):
+            point = np.zeros(geometry.dim, dtype=float)
+            point[periodic_axis] = side
+            for axis, value in zip(other_axes, coordinates, strict=True):
+                point[axis] = value
+            points.append(point)
+    return points
+
+
+def _apply_periodic_fixed_states(
+    states: np.ndarray,
+    all_points: FloatArray,
+    geometry: FemGeometry,
+    periodic: list[float] | list[bool],
+    a0: float,
+) -> None:
+    """Mark points on periodic boundaries as fixed."""
+
+    _ = a0
+    if len(all_points) == 0:
+        return
+    periodic_mask = np.zeros(len(all_points), dtype=bool)
+    for axis, enabled in enumerate(map(bool, periodic)):
+        if enabled:
+            periodic_mask |= np.isclose(
+                all_points[:, axis], geometry.bbox_min[axis], atol=BOUNDARY_FUZZ, rtol=0.0
+            )
+            periodic_mask |= np.isclose(
+                all_points[:, axis], geometry.bbox_max[axis], atol=BOUNDARY_FUZZ, rtol=0.0
+            )
+    states[periodic_mask] = STATE_FIXED

nmesh/mesher/relaxation/seeding/points.py

@@ -0,0 +1,88 @@
+"""Point normalization and state classification for relaxation seeding."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .._constants import BOUNDARY_FUZZ, STATE_BOUNDARY, STATE_MOBILE
+from .._types import FloatArray
+from ..geometry import FemGeometry
+
+
+def _as_float_array(points: Any, dim: int | None = None) -> FloatArray:
+    """Convert point-like input into a 2D float array with optional dimension validation."""
+
+    if points is None:
+        return np.empty((0, 0 if dim is None else dim), dtype=float)
+    coords = np.asarray(points, dtype=float)
+    if coords.size == 0:
+        return np.empty((0, 0 if dim is None else dim), dtype=float)
+    if coords.ndim == 1:
+        dim = int(coords.shape[0]) if dim is None else dim
+        coords = coords[np.newaxis, :]
+    if dim is not None and coords.shape[1] != dim:
+        raise ValueError(f"Expected points with dimension {dim}, got {coords.shape[1]}")
+    return coords.astype(float, copy=False)
+
+
+def _point_key(point: FloatArray, decimals: int = 10) -> tuple[float, ...]:
+    """Return a rounded tuple key for deduplication of point coordinates."""
+
+    return tuple(np.round(np.asarray(point, dtype=float), decimals=decimals).tolist())
+
+
+def _dedupe_points(points: FloatArray) -> FloatArray:
+    """Drop duplicate points while preserving first-seen order."""
+
+    if len(points) == 0:
+        return points
+    keep_indices: list[int] = []
+    seen: set[tuple[float, ...]] = set()
+    for index, point in enumerate(points):
+        key = _point_key(point)
+        if key not in seen:
+            seen.add(key)
+            keep_indices.append(index)
+    return points[np.asarray(keep_indices, dtype=int)]
+
+
+def _dedupe_fixed_mobile(
+    fixed_points: FloatArray,
+    mobile_points: FloatArray,
+    simply_points: FloatArray,
+) -> tuple[FloatArray, FloatArray, FloatArray]:
+    """Deduplicate seed points across fixed, mobile, and simply categories."""
+
+    seen: set[tuple[float, ...]] = set()
+
+    def filter_points(points: FloatArray) -> FloatArray:
+        keep_indices: list[int] = []
+        for index, point in enumerate(points):
+            key = _point_key(point)
+            if key not in seen:
+                seen.add(key)
+                keep_indices.append(index)
+        if not keep_indices:
+            return np.empty((0, points.shape[1]), dtype=float)
+        return points[np.asarray(keep_indices, dtype=int)]
+
+    return tuple(map(filter_points, (fixed_points, mobile_points, simply_points)))  # type: ignore[return-value]
+
+
+def _classify_dynamic_states(geometry: FemGeometry, points: FloatArray, a0: float) -> np.ndarray:
+    """Return mobile or boundary states for the supplied movable points."""
+
+    _ = a0
+    if len(points) == 0:
+        return np.empty(0, dtype=int)
+    states = np.full(len(points), STATE_MOBILE, dtype=int)
+    states[geometry.boundary_mask(points, tolerance=BOUNDARY_FUZZ)] = STATE_BOUNDARY
+    return states
+
+
+def _filter_relevant_points(geometry: FemGeometry, points: FloatArray) -> FloatArray:
+    """Keep only points that belong to one of the meshed regions."""
+
+    return points if len(points) == 0 else points[geometry.classify_points(points) >= 0]