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

nmesh/mesher/relaxation/engine/topology.py

@@ -0,0 +1,230 @@
+"""Topology refresh and point insertion/deletion for relaxation meshing."""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ...meshing_parameters import PointFate, default_handle_point_density_fun
+from .._constants import BOUNDARY_FUZZ, STATE_BOUNDARY, STATE_MOBILE
+from .._types import FloatArray
+from ..forces import ForceSummary
+from ..seeding import _classify_dynamic_states, _dedupe_points
+from ..topology.recovery import mirror_surface_recovery_points
+
+
+class RelaxationEngineTopologyMixin:
+    if TYPE_CHECKING:
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _mark_topology_stale(self) -> None:
+        """Request a fresh Delaunay triangulation before the next force step."""
+
+        self.current_simplices = None
+        self.max_rel_movement_since_last_triangulation = 0.0
+        self.points_at_last_triangulation = np.array(self.points, copy=True)
+
+    def _refresh_boundary_states(self) -> None:
+        """Refresh dynamic points between mobile and boundary states."""
+
+        dynamic_mask = np.isin(self.states, [STATE_MOBILE, STATE_BOUNDARY])
+        if not np.any(dynamic_mask):
+            return
+        refreshed = _classify_dynamic_states(self.geometry, self.points[dynamic_mask], self.a0)
+        self.states[dynamic_mask] = refreshed
+
+    def _effective_time_step(self, force_summary: ForceSummary) -> float:
+        """Compute the controller-like time step for the current force field."""
+
+        freedom = float(self.params.get("controller_movement_max_freedom", 3.0))
+        movement_weight = self._initial_relaxation_weight(freedom, 1.0)
+        capped_max_time_step = movement_weight * self.max_time_step
+        if force_summary.max_effective_force <= BOUNDARY_FUZZ:
+            return capped_max_time_step
+        return min(
+            capped_max_time_step,
+            (movement_weight * self.time_step_scale) / force_summary.max_effective_force,
+        )
+
+    def _initial_relaxation_weight(self, init_val: float, final_val: float) -> float:
+        """Evaluate the legacy initial-relaxation ramp for this step."""
+
+        settling_steps = int(self.params.get("controller_initial_settling_steps", 100))
+        weight_fun = self.params.get("initial_relaxation_weight_fun")
+        if callable(weight_fun):
+            result: Any = weight_fun(self.step, settling_steps, init_val, final_val)
+            return float(result)
+        fraction = min(1.0, float(self.step) / max(float(settling_steps), 1.0))
+        return init_val + (final_val - init_val) * fraction
+
+    def _density_thresholds(self) -> tuple[float, float]:
+        """Return add/delete thresholds with the legacy initial relaxation ramp."""
+
+        freedom = float(self.params.get("controller_movement_max_freedom", 3.0))
+        thresh_add = self._initial_relaxation_weight(-0.1 * freedom, 0.0) + float(
+            self.params.get("controller_thresh_add", 1.0)
+        )
+        thresh_del = self._initial_relaxation_weight(0.1 * freedom, 0.0) + float(
+            self.params.get("controller_thresh_del", 2.0)
+        )
+        return thresh_add, thresh_del
+
+    @staticmethod
+    def _is_positive_square_number(value: int) -> bool:
+        """Return whether ``value`` is a positive perfect square."""
+
+        if value <= 0:
+            return False
+        root = int(math.sqrt(value) + 0.5)
+        return root * root == value
+
+    def _should_attempt_point_change(self) -> bool:
+        """Return whether the legacy controller schedules point fate changes."""
+
+        return self.step < self.max_steps and self._is_positive_square_number(self.step - 10)
+
+    def _step_limit_reached(self) -> bool:
+        """Return whether the legacy max-step and post-change settling rules are met."""
+
+        return (
+            self.step >= self.max_steps
+            and self.step >= self.last_addition_deletion_step + self.post_change_settling_steps
+        )
+
+    def _topology_threshold(self) -> float:
+        """Return the relaxed legacy threshold for topology refresh."""
+
+        freedom = float(self.params.get("controller_movement_max_freedom", 3.0))
+        threshold = float(self.params.get("controller_topology_threshold", 0.2))
+        return self._initial_relaxation_weight(freedom, 1.0) * threshold
+
+    def _record_triangulation(self, force_summary: ForceSummary) -> None:
+        """Cache the current topology after a force calculation builds it."""
+
+        if self.current_simplices is None:
+            self.current_simplices = np.asarray(force_summary.simplices, dtype=int)
+            self.points_at_last_triangulation = np.array(self.points, copy=True)
+            self.max_rel_movement_since_last_triangulation = 0.0
+
+    def _update_topology_movement(self) -> None:
+        """Track movement since the last triangulation in OCaml controller units."""
+
+        if len(self.points) != len(self.points_at_last_triangulation):
+            self._mark_topology_stale()
+            return
+
+        if len(self.points) == 0:
+            self.max_rel_movement_since_last_triangulation = 0.0
+            return
+
+        displacements = np.linalg.norm(self.points - self.points_at_last_triangulation, axis=1)
+        density_scale = np.asarray(
+            [
+                self.geometry.density_at(point) ** (1.0 / max(self.geometry.dim, 1))
+                for point in self.points
+            ],
+            dtype=float,
+        )
+        scaled = displacements * density_scale / max(self.a0, BOUNDARY_FUZZ)
+        self.max_rel_movement_since_last_triangulation = max(
+            self.max_rel_movement_since_last_triangulation,
+            float(np.max(scaled, initial=0.0)),
+        )
+
+    def _refresh_topology_if_needed(self) -> None:
+        """Invalidate cached topology when movement exceeds the legacy threshold."""
+
+        if self.max_rel_movement_since_last_triangulation > self._topology_threshold():
+            self._mark_topology_stale()
+
+    def _attempt_add_delete_points(self, force_summary: ForceSummary) -> None:
+        """Apply the mesher density heuristic to add or remove mobile points."""
+
+        if len(self.points) == 0:
+            return
+
+        additions, removals = self._evaluate_point_densities(force_summary)
+        recovery_points = mirror_surface_recovery_points(
+            self.points,
+            self.states,
+            self.geometry,
+            self.a0,
+            force_summary.simplices,
+        )
+        if len(recovery_points) > 0:
+            additions.extend(recovery_points)
+        self._apply_point_changes(additions, removals)
+        self._refresh_boundary_states()
+
+    def _evaluate_point_densities(
+        self,
+        force_summary: ForceSummary,
+    ) -> tuple[list[FloatArray], list[int]]:
+        """Decide which points to add or remove from the current cloud."""
+
+        handler = self.params.get("handle_point_density_fun", default_handle_point_density_fun)
+        thresh_add, thresh_del = self._density_thresholds()
+        additions: list[FloatArray] = []
+        removals: list[int] = []
+
+        for index, state in enumerate(self.states):
+            if state not in (STATE_MOBILE, STATE_BOUNDARY) or index in removals:
+                continue
+
+            neigh = force_summary.neighbor_map[index]
+            if not neigh:
+                continue
+
+            point = self.points[index]
+            avg_density = float(force_summary.point_density[index])
+            avg_force = float(force_summary.point_average_force[index])
+
+            fate = handler(self.rng, (avg_density, avg_force), thresh_add, thresh_del)
+            if fate == PointFate.ADD_ANOTHER:
+                additions.append(self._random_point_close_to(point))
+            elif (
+                fate == PointFate.DELETE
+                and len(self.points) - len(removals) > self.geometry.dim + 1
+            ):
+                removals.append(index)
+
+        return additions, removals
+
+    def _random_point_close_to(self, point: FloatArray) -> FloatArray:
+        """Return a Gaussian insertion candidate using the legacy rod-length scale."""
+
+        density_here = self.geometry.density_at(point)
+        effective_rod_length = self.a0 * (density_here ** (-1.0 / max(self.geometry.dim, 1)))
+        candidate = np.asarray(
+            self.rng.normal(loc=np.asarray(point, dtype=float), scale=effective_rod_length),
+            dtype=float,
+        )
+        if self.geometry.classify_points(candidate[np.newaxis, :])[0] >= 0:
+            return candidate
+        return self.geometry.project_segment_to_domain(np.asarray(point, dtype=float), candidate)
+
+    def _apply_point_changes(self, additions: list[FloatArray], removals: list[int]) -> None:
+        """Mutate the point cloud according to the evaluated add/remove plan."""
+
+        if removals:
+            keep = np.ones(len(self.points), dtype=bool)
+            keep[np.asarray(removals, dtype=int)] = False
+            self.points = self.points[keep]
+            self.states = self.states[keep]
+            self._mark_topology_stale()
+
+        if additions:
+            additions_arr = _dedupe_points(np.asarray(additions, dtype=float))
+            if len(additions_arr) > 0:
+                self.points = np.vstack((self.points, additions_arr))
+                addition_states = _classify_dynamic_states(self.geometry, additions_arr, self.a0)
+                self.states = np.concatenate(
+                    (
+                        self.states,
+                        addition_states,
+                    )
+                )
+                self._mark_topology_stale()

nmesh/mesher/relaxation/forces/__init__.py

@@ -0,0 +1,96 @@
+"""Compatibility facade and orchestration for relaxation meshing forces."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .._types import FloatArray
+from ..geometry import FemGeometry
+from ..topology import _triangulate_points
+from .neighbors import (
+    _build_neighbor_map,
+    _compute_neighbor_forces,
+)
+from .simplex import (
+    _classify_relevant_simplices,
+    _compute_simplex_forces,
+    _simplex_incidence_data,
+)
+from .summary import _finalize_force_summary
+from .types import (
+    ForceParameters,
+    ForceSummary,
+    _extract_force_parameters,
+)
+
+__all__ = [
+    "ForceParameters",
+    "ForceSummary",
+    "_classify_relevant_simplices",
+    "_extract_force_parameters",
+    "compute_forces",
+]
+
+
+def compute_forces(
+    points: FloatArray,
+    states: np.ndarray,
+    geometry: FemGeometry,
+    a0: float,
+    params: dict[str, Any],
+    step: int,
+    simplices: np.ndarray | None = None,
+) -> ForceSummary:
+    """Compute neighbor, shape, volume, and irrelevant-element forces."""
+    point_count = len(points)
+    dim = geometry.dim
+    if simplices is None:
+        simplices = _triangulate_points(points, dim, states)
+    neighbor_map = _build_neighbor_map(point_count, simplices)
+    config = _extract_force_parameters(params, step)
+    point_densities = np.asarray([geometry.density_at(point) for point in points], dtype=float)
+
+    total_forces, neighbor_force_sums, neighbor_force_counts = _compute_neighbor_forces(
+        points,
+        states,
+        simplices,
+        neighbor_map,
+        point_densities,
+        dim,
+        a0,
+        config,
+    )
+    simplex_measures, incident_simplices, angle_sums = _simplex_incidence_data(
+        points, simplices, dim
+    )
+    _compute_simplex_forces(
+        total_forces,
+        points,
+        states,
+        geometry,
+        simplices,
+        point_densities,
+        simplex_measures,
+        angle_sums,
+        dim,
+        a0,
+        config,
+    )
+    return _finalize_force_summary(
+        total_forces=total_forces,
+        neighbor_map=neighbor_map,
+        simplices=simplices,
+        point_densities=point_densities,
+        neighbor_force_sums=neighbor_force_sums,
+        neighbor_force_counts=neighbor_force_counts,
+        simplex_measures=simplex_measures,
+        incident_simplices=incident_simplices,
+        angle_sums=angle_sums,
+        points=points,
+        states=states,
+        geometry=geometry,
+        a0=a0,
+        dim=dim,
+    )

nmesh/mesher/relaxation/forces/jit.py

@@ -0,0 +1,102 @@
+"""Numba-accelerated kernels for the relaxation meshing pipeline."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from numba import njit
+
+from ....utils.constants import MIN_DIVISION_MAGNITUDE
+from .._constants import DENSITY_EPSILON, STATE_BOUNDARY, STATE_FIXED, STATE_MOBILE, STATE_SIMPLE
+
+
+@njit
+def _default_relaxation_force(reduced_distance: float) -> float:
+    """Return the legacy default mobile-mobile force law."""
+
+    if reduced_distance > 1.0:
+        return 0.0
+    return 1.0 - reduced_distance
+
+
+@njit
+def _default_boundary_force(reduced_distance: float) -> float:
+    """Return the legacy default boundary interaction force law."""
+
+    if reduced_distance > 1.0:
+        return 0.0
+    if reduced_distance < MIN_DIVISION_MAGNITUDE:
+        return 1.0e12
+    return 1.0 / reduced_distance - 1.0
+
+
+@njit
+def accumulate_neighbor_forces_default(
+    points: np.ndarray,
+    states: np.ndarray,
+    point_densities: np.ndarray,
+    neighbor_pairs: np.ndarray,
+    a0: float,
+    neigh_force_scale: float,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Accumulate default neighbor forces and controller statistics."""
+
+    point_count, dim = points.shape
+    total_forces = np.zeros((point_count, dim), dtype=np.float64)
+    neighbor_force_sums = np.zeros(point_count, dtype=np.float64)
+    neighbor_force_counts = np.zeros(point_count, dtype=np.int64)
+    inv_dim = 1.0 / float(max(dim, 1))
+    a0_safe = max(a0, DENSITY_EPSILON)
+
+    for pair_index in range(len(neighbor_pairs)):
+        left = int(neighbor_pairs[pair_index, 0])
+        right = int(neighbor_pairs[pair_index, 1])
+        state_left = int(states[left])
+        state_right = int(states[right])
+        left_dynamic = state_left == STATE_MOBILE or state_left == STATE_BOUNDARY
+        right_dynamic = state_right == STATE_MOBILE or state_right == STATE_BOUNDARY
+        if not left_dynamic and not right_dynamic:
+            continue
+
+        true_distance_sq = 0.0
+        for axis in range(dim):
+            delta = points[right, axis] - points[left, axis]
+            true_distance_sq += delta * delta
+        true_distance = math.sqrt(true_distance_sq)
+        if true_distance <= DENSITY_EPSILON:
+            continue
+
+        avg_density = 0.5 * (point_densities[left] + point_densities[right])
+        inv_length_scale = math.pow(avg_density, inv_dim) / a0_safe
+        reduced_distance = true_distance * inv_length_scale
+        boundary_interaction = (
+            state_left == STATE_FIXED
+            or state_left == STATE_BOUNDARY
+            or state_left == STATE_SIMPLE
+            or state_right == STATE_FIXED
+            or state_right == STATE_BOUNDARY
+            or state_right == STATE_SIMPLE
+        )
+        scalar_force = (
+            _default_boundary_force(reduced_distance)
+            if boundary_interaction
+            else _default_relaxation_force(reduced_distance)
+        )
+
+        scaled_force = neigh_force_scale * abs(scalar_force)
+        neighbor_force_sums[left] += scaled_force
+        neighbor_force_sums[right] += scaled_force
+        neighbor_force_counts[left] += 1
+        neighbor_force_counts[right] += 1
+
+        if scalar_force == 0.0:
+            continue
+
+        force_factor = neigh_force_scale * (-scalar_force)
+        for axis in range(dim):
+            contribution = force_factor * (points[right, axis] - points[left, axis])
+            total_forces[left, axis] += contribution
+            total_forces[right, axis] -= contribution
+
+    return total_forces, neighbor_force_sums, neighbor_force_counts

nmesh/mesher/relaxation/forces/neighbors.py

@@ -0,0 +1,186 @@
+"""Neighbor-pair force calculations for the relaxation mesher."""
+
+from __future__ import annotations
+
+from itertools import combinations
+from typing import Any
+
+import numpy as np
+
+from ...meshing_parameters import default_boundary_node_force_fun, default_relaxation_force_fun
+from .._constants import DENSITY_EPSILON, STATE_BOUNDARY, STATE_FIXED, STATE_MOBILE, STATE_SIMPLE
+from .._types import FloatArray
+from .jit import accumulate_neighbor_forces_default
+from .types import ForceParameters
+
+
+def _build_neighbor_pairs(simplices: np.ndarray) -> np.ndarray:
+    """Return sorted unique point-pair edges induced by the simplices."""
+    if len(simplices) == 0:
+        return np.empty((0, 2), dtype=np.int64)
+
+    pairs: set[tuple[int, int]] = set()
+    for simplex in simplices:
+        for left, right in combinations(simplex.tolist(), 2):
+            i = int(left)
+            j = int(right)
+            pairs.add((i, j) if i <= j else (j, i))
+    return np.asarray(sorted(pairs), dtype=np.int64)
+
+
+def _is_dynamic_state(state: int) -> bool:
+    """Return whether the state participates in relaxation movement."""
+    return state in (STATE_MOBILE, STATE_BOUNDARY)
+
+
+def _is_boundary_interaction(state_a: int, state_b: int) -> bool:
+    """Return whether a neighbor interaction should use the boundary law."""
+    return state_a in (STATE_FIXED, STATE_BOUNDARY, STATE_SIMPLE) or state_b in (
+        STATE_FIXED,
+        STATE_BOUNDARY,
+        STATE_SIMPLE,
+    )
+
+
+def _neighbor_forces_python(
+    points: FloatArray,
+    states: np.ndarray,
+    point_densities: FloatArray,
+    neighbor_map: list[list[int]],
+    dim: int,
+    a0: float,
+    neigh_force_scale: float,
+    force_fun: Any,
+    boundary_force_fun: Any,
+) -> tuple[FloatArray, FloatArray, np.ndarray]:
+    """Fallback neighbor-force path for custom Python force callbacks."""
+    total_forces = np.zeros((len(points), dim), dtype=float)
+    neighbor_force_sums = np.zeros(len(points), dtype=float)
+    neighbor_force_counts = np.zeros(len(points), dtype=int)
+
+    for left, neighbors in enumerate(neighbor_map):
+        point_left = points[left]
+        state_left = int(states[left])
+        for right in neighbors:
+            if right <= left:
+                continue
+            contribution, scalar_force = _apply_pairwise_force(
+                point_left=point_left,
+                point_right=points[right],
+                state_left=state_left,
+                state_right=int(states[right]),
+                density_left=float(point_densities[left]),
+                density_right=float(point_densities[right]),
+                dim=dim,
+                a0=a0,
+                neigh_force_scale=neigh_force_scale,
+                force_fun=force_fun,
+                boundary_force_fun=boundary_force_fun,
+            )
+            if scalar_force is None:
+                continue
+            neighbor_force_sums[left] += abs(scalar_force)
+            neighbor_force_sums[right] += abs(scalar_force)
+            neighbor_force_counts[left] += 1
+            neighbor_force_counts[right] += 1
+            if contribution is None:
+                continue
+            total_forces[left] += contribution
+            total_forces[right] -= contribution
+
+    return total_forces, neighbor_force_sums, neighbor_force_counts
+
+
+def _apply_pairwise_force(
+    *,
+    point_left: FloatArray,
+    point_right: FloatArray,
+    state_left: int,
+    state_right: int,
+    density_left: float,
+    density_right: float,
+    dim: int,
+    a0: float,
+    neigh_force_scale: float,
+    force_fun: Any,
+    boundary_force_fun: Any,
+) -> tuple[FloatArray | None, float | None]:
+    """Compute the pairwise neighbor contribution for one point pair."""
+    if not _is_dynamic_state(state_left) and not _is_dynamic_state(state_right):
+        return None, None
+
+    delta = point_right - point_left
+    true_distance = float(np.linalg.norm(delta))
+    if true_distance <= DENSITY_EPSILON:
+        return None, None
+
+    avg_density = 0.5 * (density_left + density_right)
+    inv_length_scale = (avg_density ** (1.0 / max(dim, 1))) / max(a0, DENSITY_EPSILON)
+    reduced_distance = true_distance * inv_length_scale
+    scalar_force = float(
+        (boundary_force_fun if _is_boundary_interaction(state_left, state_right) else force_fun)(
+            reduced_distance
+        )
+    )
+    scaled_force = neigh_force_scale * abs(scalar_force)
+    if scalar_force == 0.0:
+        return None, scaled_force
+    return neigh_force_scale * (-scalar_force) * delta, scaled_force
+
+
+def _build_neighbor_map(point_count: int, simplices: np.ndarray) -> list[list[int]]:
+    """Build undirected point adjacency from simplices."""
+    neighbors: list[set[int]] = [set() for _ in range(point_count)]
+    for simplex in simplices:
+        for left, right in combinations(simplex.tolist(), 2):
+            i = int(left)
+            j = int(right)
+            neighbors[i].add(j)
+            neighbors[j].add(i)
+    return [sorted(group) for group in neighbors]
+
+
+def _compute_neighbor_forces(
+    points: FloatArray,
+    states: np.ndarray,
+    simplices: np.ndarray,
+    neighbor_map: list[list[int]],
+    point_densities: FloatArray,
+    dim: int,
+    a0: float,
+    config: ForceParameters,
+) -> tuple[FloatArray, FloatArray, np.ndarray]:
+    """Compute neighbor-force contributions through the JIT or Python path."""
+    point_count = len(points)
+    if len(simplices) == 0:
+        return (
+            np.zeros((point_count, dim), dtype=float),
+            np.zeros(point_count, dtype=float),
+            np.zeros(point_count, dtype=int),
+        )
+
+    if (
+        config.force_fun is default_relaxation_force_fun
+        and config.boundary_force_fun is default_boundary_node_force_fun
+    ):
+        neighbor_pairs = _build_neighbor_pairs(simplices)
+        return accumulate_neighbor_forces_default(
+            np.asarray(points, dtype=np.float64),
+            np.asarray(states, dtype=np.int64),
+            point_densities.astype(np.float64, copy=False),
+            neighbor_pairs,
+            float(a0),
+            config.neigh_force_scale,
+        )
+
+    return _neighbor_forces_python(
+        points,
+        states,
+        point_densities,
+        neighbor_map,
+        dim,
+        a0,
+        config.neigh_force_scale,
+        config.force_fun,
+        config.boundary_force_fun,
+    )