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

nmesh/mesher/relaxation/topology/recovery.py

@@ -0,0 +1,310 @@
+"""Surface-recovery helpers for the relaxation meshing pipeline."""
+
+from __future__ import annotations
+
+import math
+from itertools import combinations
+from typing import cast
+
+import numpy as np
+
+from .._constants import (
+    BOUNDARY_FUZZ,
+    DENSITY_EPSILON,
+    STATE_BOUNDARY,
+    STATE_FIXED,
+    STATE_MOBILE,
+    STATE_SIMPLE,
+)
+from .._types import FloatArray
+from ..geometry import FemGeometry
+from . import _simplex_measures
+
+
+def mirror_surface_recovery_points(
+    points: FloatArray,
+    states: np.ndarray,
+    geometry: FemGeometry,
+    a0: float,
+    simplices: np.ndarray,
+) -> FloatArray:
+    """Return legacy mirror/prevention points for poor boundary simplices."""
+
+    dim = geometry.dim
+    if dim not in (2, 3) or len(simplices) == 0:
+        return np.empty((0, dim), dtype=float)
+
+    simplex_measures = _simplex_measures(points, simplices, dim)
+    seen_surfaces: set[tuple[tuple[float, ...], ...]] = set()
+    additions: list[FloatArray] = []
+
+    for simplex, simplex_volume in zip(simplices, simplex_measures, strict=True):
+        simplex_points = np.asarray(points[simplex], dtype=float)
+        boundary_points, interior_points = _split_boundary_and_interior_points(
+            simplex,
+            simplex_points,
+            states,
+        )
+        if dim == 2:
+            additions.extend(
+                _mirror_points_2d(
+                    boundary_points,
+                    interior_points,
+                    simplex_points,
+                    float(simplex_volume),
+                    geometry,
+                    a0,
+                    seen_surfaces,
+                )
+            )
+        else:
+            additions.extend(
+                _prevention_points_3d(
+                    boundary_points,
+                    simplex_points,
+                    float(simplex_volume),
+                    geometry,
+                    a0,
+                    seen_surfaces,
+                )
+            )
+
+    if not additions:
+        return np.empty((0, dim), dtype=float)
+    return _dedupe_recovery_points(np.asarray(additions, dtype=float))
+
+
+def _split_boundary_and_interior_points(
+    simplex: np.ndarray,
+    simplex_points: FloatArray,
+    states: np.ndarray,
+) -> tuple[list[FloatArray], list[FloatArray]]:
+    """Split simplex vertices into boundary-like and mobile interior vertices."""
+
+    boundary_points: list[FloatArray] = []
+    interior_points: list[FloatArray] = []
+    for local_index, point_index in enumerate(simplex.tolist()):
+        state = int(states[int(point_index)])
+        point = simplex_points[local_index]
+        if state in (STATE_BOUNDARY, STATE_FIXED, STATE_SIMPLE):
+            boundary_points.append(point)
+        elif state == STATE_MOBILE:
+            interior_points.append(point)
+    return boundary_points, interior_points
+
+
+def _mirror_points_2d(
+    boundary_points: list[FloatArray],
+    interior_points: list[FloatArray],
+    simplex_points: FloatArray,
+    simplex_volume: float,
+    geometry: FemGeometry,
+    a0: float,
+    seen_surfaces: set[tuple[tuple[float, ...], ...]],
+) -> list[FloatArray]:
+    """Return mirrored points for the legacy 2D boundary-simplex cases."""
+
+    additions: list[FloatArray] = []
+    if len(boundary_points) == 3:
+        shifted = list(boundary_points)
+        for _ in range(3):
+            vertex_point = shifted[0]
+            surface_points = np.asarray(shifted[1:], dtype=float)
+            if _register_surface(surface_points, seen_surfaces):
+                shifted = shifted[1:] + shifted[:1]
+                continue
+            additions.extend(
+                _node_action_2d(
+                    surface_points, vertex_point, simplex_points, simplex_volume, geometry, a0
+                )
+            )
+            shifted = shifted[1:] + shifted[:1]
+        return additions
+
+    if len(boundary_points) == 2 and len(interior_points) == 1:
+        surface_points = np.asarray(boundary_points, dtype=float)
+        if not _register_surface(surface_points, seen_surfaces):
+            additions.extend(
+                _node_action_2d(
+                    surface_points,
+                    interior_points[0],
+                    simplex_points,
+                    simplex_volume,
+                    geometry,
+                    a0,
+                )
+            )
+    return additions
+
+
+def _node_action_2d(
+    surface_points: FloatArray,
+    vertex_point: FloatArray,
+    simplex_points: FloatArray,
+    simplex_volume: float,
+    geometry: FemGeometry,
+    a0: float,
+) -> list[FloatArray]:
+    """Mirror one 2D point when the surface angle and volume tests request it."""
+
+    angle = _solid_angle_2d(surface_points, vertex_point)
+    if (
+        angle > 0.55 * math.pi
+        and _volume_ratio(simplex_points, simplex_volume, geometry, a0) > 3.0e-2
+    ):
+        return [_mirror_point(surface_points, vertex_point, 2)]
+    return []
+
+
+def _prevention_points_3d(
+    boundary_points: list[FloatArray],
+    simplex_points: FloatArray,
+    simplex_volume: float,
+    geometry: FemGeometry,
+    a0: float,
+    seen_surfaces: set[tuple[tuple[float, ...], ...]],
+) -> list[FloatArray]:
+    """Return midpoint prevention points for legacy 3D boundary edges."""
+
+    if len(boundary_points) < 2:
+        return []
+
+    additions: list[FloatArray] = []
+    for left, right in combinations(boundary_points, 2):
+        surface_points = np.asarray([left, right], dtype=float)
+        already_seen = _register_surface(surface_points, seen_surfaces)
+        if already_seen:
+            continue
+        middle_point = 0.5 * (surface_points[0] + surface_points[1])
+        middle_density = geometry.density_at(middle_point)
+        middle_rod_length = a0 / (middle_density ** (1.0 / max(geometry.dim, 1)))
+        distance = float(np.linalg.norm(surface_points[0] - surface_points[1]))
+        if (
+            distance > 1.2 * middle_rod_length
+            and _volume_ratio(simplex_points, simplex_volume, geometry, a0) > 3.0e-2
+            and _is_outer_region_constrained(geometry, middle_point)
+        ):
+            additions.append(middle_point)
+    return additions
+
+
+def _surface_key(surface_points: FloatArray) -> tuple[tuple[float, ...], ...]:
+    """Return a stable set-like key for a boundary surface."""
+
+    return tuple(
+        sorted(
+            tuple(
+                cast(
+                    list[float],
+                    np.asarray(np.round(point, decimals=10), dtype=float).tolist(),
+                )
+            )
+            for point in surface_points
+        )
+    )
+
+
+def _register_surface(
+    surface_points: FloatArray,
+    seen_surfaces: set[tuple[tuple[float, ...], ...]],
+) -> bool:
+    """Register a surface and return whether it had already been processed."""
+
+    key = _surface_key(surface_points)
+    if key in seen_surfaces:
+        return True
+    seen_surfaces.add(key)
+    return False
+
+
+def _solid_angle_2d(surface_points: FloatArray, vertex_point: FloatArray) -> float:
+    """Return the angle subtended by two surface points from a vertex."""
+
+    first = surface_points[0] - vertex_point
+    second = surface_points[1] - vertex_point
+    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))
+
+
+def _mirror_point(surface_points: FloatArray, point: FloatArray, dim: int) -> FloatArray:
+    """Mirror a point across a line/plane defined by boundary points."""
+
+    if len(surface_points) == dim:
+        origin = surface_points[0]
+        directions = surface_points[1:] - origin
+        _, _, vh = np.linalg.svd(directions, full_matrices=True)
+        normal = np.asarray(vh[-1], dtype=float)
+        normal_norm_sq = float(np.dot(normal, normal))
+        if normal_norm_sq <= DENSITY_EPSILON:
+            return np.asarray(point, dtype=float)
+        factor = float(np.dot(point - origin, normal)) / normal_norm_sq
+        projection = point - factor * normal
+        return np.asarray(2.0 * projection - point, dtype=float)
+
+    if len(surface_points) == dim - 1 and dim == 3:
+        start = surface_points[0]
+        segment = surface_points[1] - start
+        denom = float(np.dot(segment, segment))
+        if denom <= DENSITY_EPSILON:
+            return np.asarray(point, dtype=float)
+        fraction = float(np.dot(point - start, segment)) / denom
+        projection = start + fraction * segment
+        return np.asarray(2.0 * projection - point, dtype=float)
+
+    return np.asarray(point, dtype=float)
+
+
+def _volume_ratio(
+    simplex_points: FloatArray,
+    simplex_volume: float,
+    geometry: FemGeometry,
+    a0: float,
+) -> float:
+    """Return the legacy real-to-ideal simplex volume ratio."""
+
+    if simplex_volume <= DENSITY_EPSILON:
+        return 0.0
+    center = np.mean(simplex_points, axis=0)
+    density_here = geometry.density_at(center)
+    rod_scaled = a0 / (density_here ** (1.0 / max(geometry.dim, 1)))
+    ideal_volume = _regular_simplex_volume(rod_scaled, geometry.dim)
+    return abs(simplex_volume / max(ideal_volume, DENSITY_EPSILON))
+
+
+def _regular_simplex_volume(edge_length: float, dim: int) -> float:
+    """Return the volume of a regular simplex with the supplied edge length."""
+
+    numerator = edge_length**dim * math.sqrt(dim + 1.0)
+    denominator = math.factorial(dim) * math.sqrt(2.0**dim)
+    return numerator / denominator
+
+
+def _is_outer_region_constrained(geometry: FemGeometry, point: FloatArray) -> bool:
+    """Return whether a point satisfies the legacy outer-region boundary check."""
+
+    if not geometry.points_in_bbox(np.asarray(point, dtype=float)[np.newaxis, :])[0]:
+        return False
+    for body in geometry.region_bodies:
+        if body is None:
+            continue
+        if float(body.evaluate(point)) >= BOUNDARY_FUZZ:
+            return False
+    return True
+
+
+def _dedupe_recovery_points(points: FloatArray) -> FloatArray:
+    """Deduplicate generated recovery points while preserving order."""
+
+    keep_indices: list[int] = []
+    seen: set[tuple[float, ...]] = set()
+    for index, point in enumerate(points):
+        rounded = np.asarray(np.round(point, decimals=10), dtype=float)
+        key = tuple(cast(list[float], rounded.tolist()))
+        if key in seen:
+            continue
+        seen.add(key)
+        keep_indices.append(index)
+    return points[np.asarray(keep_indices, dtype=int)]

nmesh/mesher/sectioned_config.py

@@ -0,0 +1,70 @@
+"""Case-preserving, sectioned INI data used by meshing parameters."""
+
+from __future__ import annotations
+
+import configparser
+from collections.abc import ItemsView
+from io import StringIO
+from os import PathLike
+from typing import Any
+
+
+class _CasePreservingConfigParser(configparser.ConfigParser):
+    def optionxform(self, optionstr: str) -> str:
+        return optionstr
+
+
+class SectionedConfig:
+    """Small mutable INI container with typed scalar coercion."""
+
+    def __init__(self) -> None:
+        self._data: dict[str, dict[str, Any]] = {}
+
+    @staticmethod
+    def _coerce_value(value: str) -> Any:
+        text = value.strip()
+        if not text:
+            return text
+        if text.lower() in {"true", "false"}:
+            return text.lower() == "true"
+        try:
+            return int(text)
+        except ValueError:
+            pass
+        try:
+            return float(text)
+        except ValueError:
+            return text
+
+    def _load_from_parser(self, parser: configparser.ConfigParser) -> None:
+        for section in parser.sections():
+            self.add_section(section)
+            for name, value in parser.items(section):
+                self.set(section, name, self._coerce_value(value))
+
+    def from_file(self, file_path: str | PathLike[str]) -> None:
+        parser = _CasePreservingConfigParser(delimiters=("=", ":"), interpolation=None)
+        with open(file_path, encoding="utf-8") as stream:
+            parser.read_file(stream)
+        self._load_from_parser(parser)
+
+    def from_string(self, string: str) -> None:
+        parser = _CasePreservingConfigParser(delimiters=("=", ":"), interpolation=None)
+        parser.read_file(StringIO(string))
+        self._load_from_parser(parser)
+
+    def add_section(self, section: str) -> None:
+        self._data.setdefault(section, {})
+
+    def get(self, section: str, name: str, raw: bool = False) -> Any:
+        del raw
+        return self._data.get(section, {}).get(name)
+
+    def set(self, section: str, name: str, value: Any) -> None:
+        self._data.setdefault(section, {})[name] = value
+
+    def items(self, section: str) -> ItemsView[str, Any]:
+        return self._data.get(section, {}).items()
+
+    def to_string(self) -> str:
+        return str(self._data)

nmesh/nmesh.py

@@ -0,0 +1,99 @@
+"""Public nmesh compatibility façade with lazy geometry and driver exports."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .mesh_generation import Mesh, get_default_meshing_parameters
+from .mesh_io import (
+    MeshFromFile,
+    hdf5_mesh_get_permutation,
+    load,
+    mesh_from_points_and_simplices,
+    save,
+    write_mesh,
+)
+from .mesh_model import MeshBase, Point, Simplex
+from .mesh_utilities import (
+    generate_1d_mesh,
+    generate_1d_mesh_components,
+    memory_report,
+    outer_corners,
+    to_lists,
+    tolists,
+)
+
+if TYPE_CHECKING:
+    pass
+
+_GEOMETRY_EXPORTS = {
+    "AffineTransform",
+    "Body",
+    "Box",
+    "Conic",
+    "Ellipsoid",
+    "Helix",
+    "MeshObject",
+    "bc_box",
+    "bc_ellipsoid",
+    "bc_frustum",
+    "bc_helix",
+    "difference",
+    "intersect",
+    "inverse_axis_rotation",
+    "inverse_plane_rotation",
+    "inverse_scale",
+    "inverse_shift",
+    "union",
+}
+_MESHER_EXPORTS = {
+    "Callback",
+    "EngineFunc",
+    "MeshEngineCommand",
+    "MeshEngineStatus",
+    "MeshingParameters",
+    "do_every_n_steps_driver",
+    "make_mg_gendriver",
+}
+__all__ = [
+    "Mesh",
+    "MeshBase",
+    "MeshFromFile",
+    "Point",
+    "Simplex",
+    "generate_1d_mesh",
+    "generate_1d_mesh_components",
+    "get_default_meshing_parameters",
+    "hdf5_mesh_get_permutation",
+    "load",
+    "memory_report",
+    "mesh_from_points_and_simplices",
+    "outer_corners",
+    "save",
+    "to_lists",
+    "tolists",
+    "write_mesh",
+    *_GEOMETRY_EXPORTS,
+    *_MESHER_EXPORTS,
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name in _GEOMETRY_EXPORTS:
+        from . import geometry
+
+        value = getattr(geometry, name)
+        globals()[name] = value
+        return value
+    if name == "MeshingParameters":
+        from .mesher.meshing_parameters import MeshingParameters
+
+        globals()[name] = MeshingParameters
+        return MeshingParameters
+    if name in _MESHER_EXPORTS:
+        from .mesher import driver
+
+        value = getattr(driver, name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

nmesh/py.typed

@@ -0,0 +1 @@
+# Marker for PEP 561 inline type information.

nmesh/utils/__init__.py

@@ -0,0 +1,33 @@
+from .array_list_utils import (
+    array_filter,
+    array_one_shorter,
+    array_position,
+    array_position_if,
+    cross_product_3d,
+    det_and_inv,
+    determinant,
+    inverse,
+)
+from .constants import BOUNDARY_FUZZ, MIN_ABS_SCALE_FACTOR, MIN_DIVISION_MAGNITUDE
+from .timing_memory_utils import memstats, time_passed, time_vmem_rss
+from .types import BoolArray, FloatArray, IntArray
+
+__all__ = [
+    "BOUNDARY_FUZZ",
+    "BoolArray",
+    "FloatArray",
+    "IntArray",
+    "MIN_ABS_SCALE_FACTOR",
+    "MIN_DIVISION_MAGNITUDE",
+    "array_filter",
+    "array_one_shorter",
+    "array_position",
+    "array_position_if",
+    "cross_product_3d",
+    "det_and_inv",
+    "determinant",
+    "inverse",
+    "memstats",
+    "time_passed",
+    "time_vmem_rss",
+]

nmesh/utils/array_list_utils.py

@@ -0,0 +1,128 @@
+from collections.abc import Callable, Sequence
+from typing import Any, TypeVar
+
+import numpy as np
+from numpy.typing import NDArray
+
+T = TypeVar("T")
+
+
+def array_filter(p: Callable[[T], bool], arr: Sequence[T]) -> NDArray[Any]:
+    """Filter array elements using a predicate function.
+
+    Args:
+        p: Predicate function returning True for elements to keep
+        arr: Input array or sequence
+
+    Returns:
+        NumPy array containing only elements where p(x) is True
+    """
+    arr_np = np.asanyarray(arr)
+    mask = np.array([p(x) for x in arr_np], dtype=bool)
+    return arr_np[mask]
+
+
+def array_position(x: T, arr: Sequence[T], start: int = 0) -> int:
+    """Find first position of element x in array starting from index start.
+
+    Args:
+        x: Element to find
+        arr: Array to search
+        start: Starting index (default 0)
+
+    Returns:
+        Index of first occurrence, or -1 if not found
+    """
+    arr_np = np.asanyarray(arr)
+    sub_arr = arr_np[start:]
+    indices = np.where(sub_arr == x)[0]
+    if len(indices) > 0:
+        return int(indices[0] + start)
+    return -1
+
+
+def array_position_if(p: Callable[[T], bool], arr: Sequence[T], start: int = 0) -> int:
+    """Find first position where predicate p is True, starting from index start.
+
+    Args:
+        p: Predicate function
+        arr: Array to search
+        start: Starting index (default 0)
+
+    Returns:
+        Index of first match, or -1 if not found
+    """
+    arr_np = np.asanyarray(arr)
+    sub_arr = arr_np[start:]
+    mask = np.array([p(x) for x in sub_arr], dtype=bool)
+    indices = np.where(mask)[0]
+    if len(indices) > 0:
+        return int(indices[0] + start)
+    return -1
+
+
+def array_one_shorter(arr: Sequence[T], pos: int) -> NDArray[Any]:
+    """Remove element at position pos from array.
+
+    Args:
+        arr: Input array
+        pos: Index of element to remove
+
+    Returns:
+        New array with element removed
+    """
+    return np.delete(np.asanyarray(arr), pos)
+
+
+def determinant(mx: Sequence[Sequence[float]]) -> float:
+    """Compute determinant of a matrix.
+
+    Args:
+        mx: Square matrix
+
+    Returns:
+        Determinant as float
+    """
+    return float(np.linalg.det(np.asanyarray(mx)))
+
+
+def inverse(mx: Sequence[Sequence[float]]) -> NDArray[np.float64]:
+    """Compute inverse of a matrix.
+
+    Args:
+        mx: Square invertible matrix
+
+    Returns:
+        Inverse matrix as NumPy array
+    """
+    return np.linalg.inv(np.asanyarray(mx))
+
+
+def det_and_inv(
+    mx: Sequence[Sequence[float]],
+) -> tuple[float, NDArray[np.float64]]:
+    """Compute determinant and inverse of a matrix simultaneously.
+
+    Args:
+        mx: Square invertible matrix
+
+    Returns:
+        Tuple of (determinant, inverse_matrix)
+    """
+    arr = np.asanyarray(mx)
+    det = np.linalg.det(arr)
+    inv = np.linalg.inv(arr)
+    return float(det), inv
+
+
+def cross_product_3d(v1: Sequence[float], v2: Sequence[float]) -> NDArray[np.float64]:
+    """Compute 3D cross product of two vectors.
+
+    Args:
+        v1: First 3D vector
+        v2: Second 3D vector
+
+    Returns:
+        Cross product v1 × v2 as NumPy array
+    """
+    return np.cross(np.asanyarray(v1), np.asanyarray(v2))

nmesh/utils/constants.py

@@ -0,0 +1,22 @@
+"""
+Common numerical constants used throughout the nmesh package.
+
+These constants provide consistent numerical tolerance values across different
+modules for operations like scale validation, division safety checks, and
+floating-point comparisons.
+"""
+
+__all__ = [
+    "BOUNDARY_FUZZ",
+    "MIN_ABS_SCALE_FACTOR",
+    "MIN_DIVISION_MAGNITUDE",
+]
+
+# Default tolerance used when testing whether points lie on or near boundaries.
+BOUNDARY_FUZZ = 1e-6
+
+# Smallest allowed absolute scale factor for affine transformations.
+MIN_ABS_SCALE_FACTOR = 1e-12
+
+# Smallest divisor magnitude accepted before force-law clamping kicks in.
+MIN_DIVISION_MAGNITUDE = 1e-15