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

nmesh/mesher/relaxation/forces/simplex.py

@@ -0,0 +1,302 @@
+"""Simplex shape, volume, and relevance forces for the relaxation mesher."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from .._constants import BOUNDARY_FUZZ, DENSITY_EPSILON, STATE_MOBILE
+from .._types import FloatArray
+from ..geometry import FemGeometry
+from ..topology import (
+    _boundary_state_mask,
+    _classify_simplices_with_probes,
+    _simplex_measures,
+    _simplex_volume_order_ratio,
+)
+from .types import ForceParameters, _corner_force_threshold, _regular_simplex_volume
+
+
+def _vertex_angle(points: FloatArray, simplex: np.ndarray, local_index: int, dim: int) -> float:
+    """Return the angle or solid angle covered by a simplex at one vertex."""
+    vertex = points[int(simplex[local_index])]
+    others: list[FloatArray] = [
+        np.asarray(points[int(simplex[index])] - vertex, dtype=float)
+        for index in range(len(simplex))
+        if index != local_index
+    ]
+
+    if dim == 1:
+        return math.pi
+
+    if dim == 2:
+        first = others[0]
+        second = others[1]
+        denom = math.sqrt(float(np.sum(first * first))) * math.sqrt(float(np.sum(second * second)))
+        if denom <= DENSITY_EPSILON:
+            return 0.0
+        cosine = min(1.0, max(-1.0, float(np.sum(first * second)) / denom))
+        return float(math.acos(cosine))
+
+    if dim == 3:
+        a, b, c = others
+        numer = abs(float(np.sum(a * np.cross(b, c))))
+        norm_a = math.sqrt(float(np.sum(a * a)))
+        norm_b = math.sqrt(float(np.sum(b * b)))
+        norm_c = math.sqrt(float(np.sum(c * c)))
+        denom = (
+            norm_a * norm_b * norm_c
+            + float(np.sum(a * b)) * norm_c
+            + float(np.sum(a * c)) * norm_b
+            + float(np.sum(b * c)) * norm_a
+        )
+        if numer <= DENSITY_EPSILON and denom <= DENSITY_EPSILON:
+            return 0.0
+        return float(2.0 * math.atan2(numer, max(denom, DENSITY_EPSILON)))
+
+    return 1.0
+
+
+def _shape_force_matrix(vertices: FloatArray, dim: int) -> FloatArray:
+    """Build the covariance-derived shape force matrix for one simplex."""
+    covariance = np.asarray(np.transpose(vertices) @ vertices, dtype=float)
+    covariance /= max(float(len(vertices) - 1), 1.0)
+
+    eigenvalues, eigenvectors = np.linalg.eigh(covariance)
+    eigenvectors = np.asarray(eigenvectors, dtype=float)
+    safe_eigenvalues = np.maximum(
+        np.asarray(eigenvalues, dtype=float),
+        DENSITY_EPSILON,
+    )
+    product = float(np.prod(safe_eigenvalues))
+    if product <= DENSITY_EPSILON:
+        return np.zeros((dim, dim), dtype=float)
+
+    scaled = safe_eigenvalues * ((1.0 / product) ** (1.0 / max(dim, 1)))
+    diagonal = -np.log(np.maximum(scaled, DENSITY_EPSILON))
+    transformed = np.zeros((dim, dim), dtype=float)
+    transformed[np.arange(dim), np.arange(dim)] = diagonal
+    return np.asarray(eigenvectors @ transformed @ np.transpose(eigenvectors), dtype=float)
+
+
+def _project_force_to_tangent(
+    geometry: FemGeometry,
+    point: FloatArray,
+    force: FloatArray,
+) -> FloatArray:
+    """Remove the normal component of a force at a boundary point."""
+    normal = geometry.boundary_normal(point)
+    normal_norm = float(np.linalg.norm(normal))
+    if normal_norm <= BOUNDARY_FUZZ:
+        return np.asarray(force, dtype=float)
+    unit_normal = normal / normal_norm
+    return np.asarray(force, dtype=float) - float(np.dot(force, unit_normal)) * unit_normal
+
+
+def _simplex_force_contribution(
+    simplex_points: FloatArray,
+    dim: int,
+    density_here: float,
+    a0: float,
+    relaxation_weight: float,
+    shape_force_scale: float,
+    volume_force_scale: float,
+    sliver_correction: float,
+    volume: float,
+) -> FloatArray:
+    """Compute the shape and volume force contribution for one simplex."""
+    center = np.mean(simplex_points, axis=0)
+    vertices = simplex_points - center
+    ideal_edge_length = a0 / (density_here ** (1.0 / max(dim, 1)))
+    ideal_volume = _regular_simplex_volume(ideal_edge_length, dim)
+    return _compute_volume_forces(
+        vertices,
+        relaxation_weight,
+        volume_force_scale,
+        volume,
+        ideal_volume,
+    ) + _compute_shape_forces(
+        vertices=vertices,
+        dim=dim,
+        relaxation_weight=relaxation_weight,
+        shape_force_scale=shape_force_scale,
+        sliver_correction=sliver_correction,
+        volume=volume,
+        ideal_volume=ideal_volume,
+    )
+
+
+def _compute_volume_forces(
+    vertices: FloatArray,
+    relaxation_weight: float,
+    volume_force_scale: float,
+    volume: float,
+    ideal_volume: float,
+) -> FloatArray:
+    """Return the isotropic volume-restoring forces for one simplex."""
+    forces = np.zeros_like(vertices)
+    if volume_force_scale <= 0.0 or volume <= DENSITY_EPSILON or ideal_volume <= DENSITY_EPSILON:
+        return forces
+    volume_factor = volume_force_scale * math.log(ideal_volume / volume)
+    return forces + relaxation_weight * volume_factor * vertices
+
+
+def _compute_shape_forces(
+    *,
+    vertices: FloatArray,
+    dim: int,
+    relaxation_weight: float,
+    shape_force_scale: float,
+    sliver_correction: float,
+    volume: float,
+    ideal_volume: float,
+) -> FloatArray:
+    """Return the covariance-derived shape-correction forces for one simplex."""
+    forces = np.zeros_like(vertices)
+    if shape_force_scale <= 0.0:
+        return forces
+
+    shape_matrix = _shape_force_matrix(vertices, dim)
+    if not np.any(shape_matrix):
+        return forces
+
+    vol_correction = _shape_volume_correction(volume, ideal_volume, dim)
+    for index, vertex in enumerate(vertices):
+        norm = float(np.linalg.norm(vertex))
+        if norm <= DENSITY_EPSILON:
+            continue
+        raw_force = shape_matrix @ vertex
+        normal = vertex / norm
+        projection = float(np.dot(raw_force, normal))
+        angular = raw_force - projection * normal
+        forces[index] += relaxation_weight * vol_correction * shape_force_scale * angular
+        if projection > 0.0 and sliver_correction > 0.0:
+            longitudinal = raw_force - angular
+            forces[index] += (
+                shape_force_scale
+                * sliver_correction
+                * relaxation_weight
+                * max(vol_correction - 1.0, 0.0)
+                * longitudinal
+            )
+    return forces
+
+
+def _shape_volume_correction(volume: float, ideal_volume: float, dim: int) -> float:
+    """Return the volume-dependent multiplier applied to shape forces."""
+    if volume <= DENSITY_EPSILON or ideal_volume <= DENSITY_EPSILON:
+        return 0.0
+    offset = 0.0 if dim <= 2 else 1.0
+    return max(1.0, offset + math.log(ideal_volume / volume))
+
+
+def _simplex_incidence_data(
+    points: FloatArray,
+    simplices: np.ndarray,
+    dim: int,
+) -> tuple[FloatArray, list[list[int]], FloatArray]:
+    """Collect simplex measures plus per-point incident simplex and angle data."""
+    simplex_measures = _simplex_measures(points, simplices, dim)
+    incident_simplices: list[list[int]] = [[] for _ in range(len(points))]
+    angle_sums = np.zeros(len(points), dtype=float)
+    for simplex_index, simplex in enumerate(simplices):
+        for local_index, point_index in enumerate(simplex.tolist()):
+            point_id = int(point_index)
+            incident_simplices[point_id].append(simplex_index)
+            angle_sums[point_id] += _vertex_angle(points, simplex, local_index, dim)
+    return simplex_measures, incident_simplices, angle_sums
+
+
+def _compute_simplex_forces(
+    total_forces: FloatArray,
+    points: FloatArray,
+    states: np.ndarray,
+    geometry: FemGeometry,
+    simplices: np.ndarray,
+    point_densities: FloatArray,
+    simplex_measures: FloatArray,
+    angle_sums: FloatArray,
+    dim: int,
+    a0: float,
+    config: ForceParameters,
+) -> None:
+    """Accumulate simplex shape, volume, and irrelevant-element forces."""
+    del point_densities
+    if len(simplices) == 0:
+        return
+    if (
+        config.shape_force_scale <= 0.0
+        and config.volume_force_scale <= 0.0
+        and config.irrel_force_scale <= 0.0
+    ):
+        return
+
+    relevant_simplices = _classify_relevant_simplices(
+        points,
+        states,
+        geometry,
+        simplices,
+        simplex_measures,
+        dim,
+        config,
+    )
+    suppress_corner_forces = angle_sums < _corner_force_threshold(dim)
+    for simplex_index, simplex in enumerate(simplices):
+        simplex_points = points[simplex]
+        simplex_force = np.zeros_like(simplex_points)
+        volume = float(simplex_measures[simplex_index])
+        if relevant_simplices[simplex_index]:
+            density_here = geometry.density_at(np.mean(simplex_points, axis=0))
+            simplex_force = _simplex_force_contribution(
+                simplex_points=simplex_points,
+                dim=dim,
+                density_here=density_here,
+                a0=a0,
+                relaxation_weight=config.relaxation_weight,
+                shape_force_scale=config.shape_force_scale,
+                volume_force_scale=config.volume_force_scale,
+                sliver_correction=config.sliver_correction,
+                volume=volume,
+            )
+        elif config.irrel_force_scale > 0.0:
+            center = np.mean(simplex_points, axis=0)
+            for local_index, point_index in enumerate(simplex.tolist()):
+                if int(states[point_index]) != STATE_MOBILE:
+                    continue
+                simplex_force[local_index] = config.irrel_force_scale * (
+                    center - simplex_points[local_index]
+                )
+
+        for local_index, point_index in enumerate(simplex.tolist()):
+            point_id = int(point_index)
+            if suppress_corner_forces[point_id]:
+                continue
+            total_forces[point_id] += simplex_force[local_index]
+
+
+def _classify_relevant_simplices(
+    points: FloatArray,
+    states: np.ndarray,
+    geometry: FemGeometry,
+    simplices: np.ndarray,
+    simplex_measures: FloatArray,
+    dim: int,
+    config: ForceParameters,
+) -> np.ndarray:
+    """Return the legacy relevant-simplex mask for force calculation."""
+    if len(simplices) == 0:
+        return np.empty(0, dtype=bool)
+
+    region_ids, probe_consistent = _classify_simplices_with_probes(
+        points,
+        simplices,
+        geometry,
+    )
+    boundary_mask = _boundary_state_mask(points, states, geometry)
+    all_boundary = np.all(boundary_mask[simplices], axis=1)
+    boundary_ratio = _simplex_volume_order_ratio(points, simplices, dim)
+    flat_boundary = all_boundary & (boundary_ratio < config.smallest_allowed_volume_ratio)
+    return (
+        (region_ids >= 0) & probe_consistent & (simplex_measures > BOUNDARY_FUZZ) & ~flat_boundary
+    )

nmesh/mesher/relaxation/forces/summary.py

@@ -0,0 +1,207 @@
+"""Per-point force metrics for the relaxation mesher."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from .._constants import BOUNDARY_FUZZ, DENSITY_EPSILON, STATE_BOUNDARY, STATE_FIXED, STATE_SIMPLE
+from .._types import FloatArray
+from ..geometry import FemGeometry
+from .simplex import _project_force_to_tangent
+from .types import ForceSummary, _sphere_volume
+
+
+def _finalize_force_summary(
+    total_forces: FloatArray,
+    neighbor_map: list[list[int]],
+    simplices: np.ndarray,
+    point_densities: FloatArray,
+    neighbor_force_sums: FloatArray,
+    neighbor_force_counts: np.ndarray,
+    simplex_measures: FloatArray,
+    incident_simplices: list[list[int]],
+    angle_sums: FloatArray,
+    points: FloatArray,
+    states: np.ndarray,
+    geometry: FemGeometry,
+    a0: float,
+    dim: int,
+) -> ForceSummary:
+    """Assemble the per-point density and effective-force metrics."""
+    point_count = len(points)
+    point_density, point_average_force, point_effective_force = _empty_force_arrays(point_count)
+
+    if point_count == 0:
+        return _make_force_summary(
+            total_forces,
+            neighbor_map,
+            simplices,
+            point_density,
+            point_average_force,
+            point_effective_force,
+        )
+
+    boundary_mask = geometry.boundary_mask(points, tolerance=max(0.05 * a0, BOUNDARY_FUZZ))
+
+    for point_index, point in enumerate(points):
+        point_state = int(states[point_index])
+        density_here = float(point_densities[point_index])
+        effective_rod_length = a0 / (density_here ** (1.0 / max(dim, 1)))
+        ideal_local_volume = _sphere_volume(0.5 * effective_rod_length, dim)
+        angle = float(angle_sums[point_index])
+        point_average_force[point_index] = _average_neighbor_force(
+            neighbor_force_sums[point_index],
+            int(neighbor_force_counts[point_index]),
+            angle,
+        )
+        corrected_volume = _corrected_point_volume(
+            simplex_measures=simplex_measures,
+            incident=incident_simplices[point_index],
+            angle=angle,
+            dim=dim,
+            state=point_state,
+            has_multiple_immobile_neighbors=_has_multiple_immobile_neighbors(
+                point_index,
+                states,
+                neighbor_map,
+            ),
+            ideal_local_volume=ideal_local_volume,
+        )
+        point_density[point_index] = ideal_local_volume / max(corrected_volume, DENSITY_EPSILON)
+        point_effective_force[point_index] = _point_effective_force(
+            total_force=total_forces[point_index],
+            state=point_state,
+            geometry=geometry,
+            point=point,
+            is_boundary=bool(boundary_mask[point_index]),
+            density_here=density_here,
+            a0=a0,
+            dim=dim,
+        )
+
+    return _make_force_summary(
+        total_forces,
+        neighbor_map,
+        simplices,
+        point_density,
+        point_average_force,
+        point_effective_force,
+    )
+
+
+def _empty_force_arrays(point_count: int) -> tuple[FloatArray, FloatArray, FloatArray]:
+    """Allocate the per-point summary arrays used by ``_finalize_force_summary``."""
+    return (
+        np.ones(point_count, dtype=float),
+        np.zeros(point_count, dtype=float),
+        np.zeros(point_count, dtype=float),
+    )
+
+
+def _make_force_summary(
+    total_forces: FloatArray,
+    neighbor_map: list[list[int]],
+    simplices: np.ndarray,
+    point_density: FloatArray,
+    point_average_force: FloatArray,
+    point_effective_force: FloatArray,
+) -> ForceSummary:
+    """Construct a ``ForceSummary`` from the completed per-point arrays."""
+    return ForceSummary(
+        total_forces=total_forces,
+        neighbor_map=neighbor_map,
+        simplices=simplices,
+        point_density=point_density,
+        point_average_force=point_average_force,
+        point_effective_force=point_effective_force,
+        max_effective_force=float(np.max(point_effective_force, initial=0.0)),
+    )
+
+
+def _average_neighbor_force(force_sum: float, force_count: int, angle: float) -> float:
+    """Return the mean absolute neighbor-force magnitude for a point."""
+    if angle <= DENSITY_EPSILON:
+        return 1.0e4
+    if force_count <= 0:
+        return 0.0
+    return force_sum / float(force_count)
+
+
+def _has_multiple_immobile_neighbors(
+    point_index: int,
+    states: np.ndarray,
+    neighbor_map: list[list[int]],
+) -> bool:
+    """Return whether a boundary point is trapped between multiple immobile nodes."""
+    if int(states[point_index]) != STATE_BOUNDARY:
+        return False
+    immobile_neighbors = sum(
+        1
+        for neighbor_index in neighbor_map[point_index]
+        if int(states[neighbor_index]) in (STATE_FIXED, STATE_SIMPLE)
+    )
+    return immobile_neighbors > 1
+
+
+def _corrected_point_volume(
+    *,
+    simplex_measures: FloatArray,
+    incident: list[int],
+    angle: float,
+    dim: int,
+    state: int,
+    has_multiple_immobile_neighbors: bool,
+    ideal_local_volume: float,
+) -> float:
+    """Return the local corrected control volume for one point."""
+    if has_multiple_immobile_neighbors or angle <= DENSITY_EPSILON:
+        return 1.0e-4 * ideal_local_volume
+    if not incident:
+        return 1.0e-4 * ideal_local_volume
+
+    incident_measures = simplex_measures[np.asarray(incident, dtype=int)]
+    if len(incident) == 1:
+        local_volume = float(incident_measures[0]) / float(max(dim, 1))
+    else:
+        local_volume = float(np.sum(incident_measures)) / float(dim + 1)
+
+    correction = _voronoi_angle_correction(dim, angle, len(incident))
+    corrected_volume = local_volume * correction
+    if state == STATE_BOUNDARY:
+        corrected_volume *= 1.2
+    return corrected_volume
+
+
+def _voronoi_angle_correction(dim: int, angle: float, incident_count: int) -> float:
+    """Return the legacy angular correction for Voronoi control volumes."""
+    if dim == 1:
+        return 1.5
+    if dim == 2:
+        return 2.0 * math.pi / angle
+    if dim == 3:
+        return 4.0 * math.pi / angle
+    return math.factorial(dim + 1) / float(max(incident_count, 1))
+
+
+def _point_effective_force(
+    *,
+    total_force: FloatArray,
+    state: int,
+    geometry: FemGeometry,
+    point: FloatArray,
+    is_boundary: bool,
+    density_here: float,
+    a0: float,
+    dim: int,
+) -> float:
+    """Return the normalized effective force magnitude for one point."""
+    effective_force = np.asarray(total_force, dtype=float)
+    if state == STATE_BOUNDARY or is_boundary:
+        effective_force = _project_force_to_tangent(geometry, point, effective_force)
+    return (
+        float(np.linalg.norm(effective_force))
+        * (density_here ** (1.0 / max(dim, 1)))
+        / max(a0, DENSITY_EPSILON)
+    )

nmesh/mesher/relaxation/forces/types.py

@@ -0,0 +1,92 @@
+"""Shared types, configuration, and scalar helpers for meshing forces."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from ...meshing_parameters import (
+    default_boundary_node_force_fun,
+    default_initial_relaxation_weight,
+    default_relaxation_force_fun,
+)
+from .._types import FloatArray
+
+
+@dataclass(frozen=True, slots=True)
+class ForceSummary:
+    """Container for the per-step force calculation results."""
+
+    total_forces: FloatArray
+    neighbor_map: list[list[int]]
+    simplices: np.ndarray
+    point_density: FloatArray
+    point_average_force: FloatArray
+    point_effective_force: FloatArray
+    max_effective_force: float
+
+
+@dataclass(frozen=True, slots=True)
+class ForceParameters:
+    """Resolved controller parameters for one relaxation-force evaluation."""
+
+    shape_force_scale: float
+    volume_force_scale: float
+    neigh_force_scale: float
+    irrel_force_scale: float
+    sliver_correction: float
+    smallest_allowed_volume_ratio: float
+    relaxation_weight: float
+    force_fun: Any
+    boundary_force_fun: Any
+
+
+def _corner_force_threshold(dim: int) -> float:
+    """Return the solid-angle threshold below which corner suppression applies."""
+    if dim == 2:
+        return 0.75 * math.pi
+    if dim == 3:
+        return 0.85 * math.pi
+    return -math.inf
+
+
+def _regular_simplex_volume(edge_length: float, dim: int) -> float:
+    """Return the volume of a regular simplex with the supplied edge length."""
+    if dim <= 0:
+        return edge_length
+    numerator = edge_length**dim * math.sqrt(dim + 1.0)
+    denominator = math.factorial(dim) * math.sqrt(2.0**dim)
+    return numerator / denominator
+
+
+def _sphere_volume(radius: float, dim: int) -> float:
+    """Return the d-dimensional volume of a sphere."""
+    return (math.pi ** (0.5 * dim) / math.gamma(0.5 * dim + 1.0)) * (radius**dim)
+
+
+def _extract_force_parameters(params: dict[str, Any], step: int) -> ForceParameters:
+    """Resolve the mesher controller parameters used by ``compute_forces``."""
+    settling_steps = int(params.get("controller_initial_settling_steps", 100))
+    relaxation_weight_fun = params.get(
+        "initial_relaxation_weight_fun",
+        default_initial_relaxation_weight,
+    )
+    return ForceParameters(
+        shape_force_scale=float(params.get("controller_shape_force_scale", 0.1)),
+        volume_force_scale=float(params.get("controller_volume_force_scale", 0.0)),
+        neigh_force_scale=float(params.get("controller_neigh_force_scale", 1.0)),
+        irrel_force_scale=float(params.get("controller_irrel_elem_force_scale", 1.0)),
+        sliver_correction=float(params.get("controller_sliver_correction", 1.0)),
+        smallest_allowed_volume_ratio=float(
+            params.get("controller_smallest_allowed_volume_ratio", 1.0)
+        ),
+        relaxation_weight=float(relaxation_weight_fun(step, settling_steps, 0.0, 1.0)),
+        force_fun=params.get("relaxation_force_fun", default_relaxation_force_fun),
+        boundary_force_fun=params.get(
+            "boundary_node_force_fun",
+            default_boundary_node_force_fun,
+        ),
+    )

nmesh/mesher/relaxation/geometry/__init__.py

@@ -0,0 +1,6 @@
+"""Public compatibility exports for relaxation geometry."""
+
+from .builder import fem_geometry_from_bodies
+from .model import FemGeometry
+
+__all__ = ["FemGeometry", "fem_geometry_from_bodies"]