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

nmesh/mesher/relaxation/density.py

@@ -0,0 +1,170 @@
+"""Density-function parsing and compilation helpers."""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Any
+
+import numpy as np
+
+from ._constants import DENSITY_EPSILON
+from ._types import DensityFunction, FloatArray
+
+
+def _strip_c_comments(source: str) -> str:
+    """Remove C-style block comments from a legacy density script."""
+
+    return re.sub(r"/\*.*?\*/", "", source, flags=re.S)
+
+
+def _translate_density_source(source: str) -> str:
+    """Translate a small subset of legacy C-like density syntax into Python."""
+
+    cleaned = _strip_c_comments(source)
+    cleaned = cleaned.replace("\r\n", "\n")
+    cleaned = cleaned.replace("{", "\n{\n").replace("}", "\n}\n").replace(";", ";\n")
+    lines = [line.strip() for line in cleaned.splitlines() if line.strip()]
+
+    py_lines = ["def __compiled_density(x):", "    density = 1.0"]
+    indent = 1
+
+    for line in lines:
+        if line == "{":
+            indent += 1
+            continue
+        if line == "}":
+            indent = max(1, indent - 1)
+            continue
+
+        translated = line.rstrip(";").strip()
+        translated = re.sub(r"\bdouble\s+", "", translated)
+        translated = translated.replace("&&", " and ").replace("||", " or ")
+        translated = re.sub(r"(?<![<>=!])!(?!=)", " not ", translated)
+        translated = re.sub(r"\bexp\s*\(", "math.exp(", translated)
+        translated = re.sub(r"\bsqrt\s*\(", "math.sqrt(", translated)
+        translated = re.sub(r"\bsin\s*\(", "math.sin(", translated)
+        translated = re.sub(r"\bcos\s*\(", "math.cos(", translated)
+        translated = re.sub(r"\btan\s*\(", "math.tan(", translated)
+        translated = re.sub(r"\bpow\s*\(", "math.pow(", translated)
+
+        if translated.startswith("if "):
+            condition = translated[2:].strip()
+            if condition.startswith("(") and condition.endswith(")"):
+                condition = condition[1:-1].strip()
+            py_lines.append(f"{'    ' * indent}if {condition}:")
+            continue
+
+        if translated == "else":
+            py_lines.append(f"{'    ' * indent}else:")
+            continue
+
+        py_lines.append(f"{'    ' * indent}{translated}")
+
+    py_lines.append("    return float(density)")
+    return "\n".join(py_lines)
+
+
+def _clamp_density_value(value: float) -> float:
+    """Clamp a density sample to the smallest supported positive value."""
+
+    return max(float(value), DENSITY_EPSILON)
+
+
+def _expression_density_scope(point: FloatArray) -> dict[str, object]:
+    """Build the safe eval scope for single-expression density snippets."""
+
+    x = np.asarray(point, dtype=float)
+    return {
+        "x": x,
+        "math": math,
+        "exp": math.exp,
+        "sqrt": math.sqrt,
+        "sin": math.sin,
+        "cos": math.cos,
+        "tan": math.tan,
+        "abs": abs,
+        "min": min,
+        "max": max,
+    }
+
+
+def _build_callable_density(density: DensityFunction) -> DensityFunction:
+    """Wrap a user callable with array coercion and positive clamping."""
+
+    def density_wrapper(point: FloatArray) -> float:
+        """Evaluate a user density callable safely."""
+
+        return _clamp_density_value(float(density(np.asarray(point, dtype=float))))
+
+    return density_wrapper
+
+
+def _compile_expression_density(source: str) -> DensityFunction | None:
+    """Compile a single-expression density assignment when available."""
+
+    expression = re.search(r"density\s*=\s*(.+?)\s*;", source, flags=re.S)
+    if expression is None or "if" in source or "{" in source:
+        return None
+
+    code = compile(expression.group(1), "<density>", "eval")
+
+    def expression_density(point: FloatArray) -> float:
+        """Evaluate a single-expression density snippet."""
+
+        value = float(eval(code, {"__builtins__": {}}, _expression_density_scope(point)))
+        return _clamp_density_value(value)
+
+    return expression_density
+
+
+def _script_density_namespace() -> dict[str, object]:
+    """Return the restricted execution namespace for translated density scripts."""
+
+    return {
+        "__builtins__": {},
+        "math": math,
+        "float": float,
+        "abs": abs,
+        "min": min,
+        "max": max,
+    }
+
+
+def _compile_script_density(source: str) -> DensityFunction:
+    """Compile a translated multi-line legacy density script."""
+
+    translated = _translate_density_source(source)
+    namespace = _script_density_namespace()
+    exec(translated, namespace, namespace)
+    compiled = namespace["__compiled_density"]
+    if not callable(compiled):
+        raise TypeError("Translated density script did not define a callable")
+
+    def script_density(point: FloatArray) -> float:
+        """Evaluate a translated multi-line density script."""
+
+        x = np.asarray(point, dtype=float)
+        result: Any = compiled(x)
+        return _clamp_density_value(float(result))
+
+    return script_density
+
+
+def _compile_density_function(density: str | DensityFunction | None) -> DensityFunction:
+    """Compile a legacy density string or callable into a normalized density function."""
+
+    if density is None or density == "":
+        return lambda _point: 1.0
+
+    if callable(density):
+        return _build_callable_density(density)
+
+    source = str(density).strip()
+    try:
+        expression_density = _compile_expression_density(source)
+        if expression_density is not None:
+            return expression_density
+        return _compile_script_density(source)
+    except Exception as exc:
+        raise ValueError(f"Could not compile density function: {source!r}") from exc

nmesh/mesher/relaxation/engine/__init__.py

@@ -0,0 +1,18 @@
+"""Public relaxation-engine façade composed from focused implementation phases."""
+
+from .state import RelaxationEngineStateMixin
+from .steps import (
+    RelaxationEngineStepMixin,
+)
+from .steps import (
+    mesh_bodies_raw as mesh_bodies_raw,  # noqa: F401
+)
+from .topology import RelaxationEngineTopologyMixin
+
+
+class RelaxationEngine(
+    RelaxationEngineStateMixin,
+    RelaxationEngineTopologyMixin,
+    RelaxationEngineStepMixin,
+):
+    """Iterative meshing engine that exposes the legacy driver protocol."""

nmesh/mesher/relaxation/engine/state.py

@@ -0,0 +1,155 @@
+"""State initialization and configuration access for relaxation meshing."""
+
+from __future__ import annotations
+
+import logging
+import math
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from .._constants import BOUNDARY_FUZZ, DEFAULT_RNG_SEED, STATE_BOUNDARY, STATE_MOBILE
+from .._types import FloatArray
+from ..geometry import FemGeometry
+from ..seeding import _prepare_initial_points
+from ..topology import assemble_raw_mesh
+from ..topology.finalize import snap_final_boundary_points
+
+log = logging.getLogger(__name__)
+
+
+class RelaxationEngineStateMixin:
+    if TYPE_CHECKING:
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def __init__(
+        self,
+        geometry: FemGeometry,
+        mesher: dict[str, Any],
+        a0: float,
+        fixed_points: FloatArray,
+        mobile_points: FloatArray,
+        simply_points: FloatArray,
+        periodic: list[float] | list[bool],
+        *,
+        rng: np.random.Generator | None = None,
+    ) -> None:
+        """Initialize the engine state from geometry, seeds, and mesher parameters."""
+
+        self.geometry = geometry
+        self.params = dict(mesher.get("parameters", {}))
+        self.a0 = float(a0)
+        self.periodic = list(periodic)
+        self.rng = rng or np.random.default_rng(DEFAULT_RNG_SEED)
+        self.points, self.states = _prepare_initial_points(
+            geometry,
+            self.a0,
+            fixed_points,
+            mobile_points,
+            simply_points,
+            self.periodic,
+            self.rng,
+            self.params,
+        )
+        self.step = 0
+        self.finished = False
+        self.last_addition_deletion_step = 0
+        self.last_max_displacement = math.inf
+        self.last_max_effective_force = math.inf
+        self.last_point_density = np.zeros(len(self.points), dtype=float)
+        self.max_rel_movement_since_last_triangulation = 0.0
+        self.current_simplices: np.ndarray | None = None
+        self.points_at_last_triangulation = np.array(self.points, copy=True)
+        self._refresh_boundary_states()
+        self.cached_raw_mesh = assemble_raw_mesh(
+            self.points,
+            self.geometry,
+            self.periodic,
+            states=self.states,
+            params=self.params,
+        )
+
+    @property
+    def max_steps(self) -> int:
+        """Return the configured maximum relaxation-step budget."""
+
+        return int(self.params.get("controller_step_limit_max", 1000))
+
+    @property
+    def tolerated_rel_move(self) -> float:
+        """Return the relative movement threshold used for convergence."""
+
+        return float(self.params.get("controller_tolerated_rel_movement", 0.002))
+
+    @property
+    def time_step_scale(self) -> float:
+        """Return the scale factor applied to each relaxation displacement."""
+
+        return float(self.params.get("controller_time_step_scale", 0.1))
+
+    @property
+    def max_time_step(self) -> float:
+        """Return the largest time-step magnitude allowed by the controller."""
+
+        return float(self.params.get("controller_max_time_step", 10.0))
+
+    @property
+    def boundary_drift_tolerance(self) -> float:
+        """Return the tolerated increase in boundary distance for boundary points.
+
+        Legacy boundary points are only allowed to move when they do not drift
+        farther from the boundary. The Python port keeps only the global
+        floating-point boundary fuzz here; it does not scale this tolerance with
+        ``a0`` because that would turn a numerical guard into different meshing
+        behavior.
+        """
+
+        return BOUNDARY_FUZZ
+
+    @property
+    def min_equilibrium_steps(self) -> int:
+        """Return the minimum number of steps before equilibrium can stop the loop."""
+
+        return int(self.params.get("controller_step_limit_min", 500))
+
+    @property
+    def post_change_settling_steps(self) -> int:
+        """Return the legacy settling window after point add/delete checks."""
+
+        return 50
+
+    def _rebuild_mesh(self, *, final: bool = False) -> None:
+        """Refresh the cached ``RawMesh`` snapshot from the current point cloud."""
+
+        points, states = (
+            self._final_output_points_and_states() if final else (self.points, self.states)
+        )
+        self.cached_raw_mesh = assemble_raw_mesh(
+            points,
+            self.geometry,
+            self.periodic,
+            states=states,
+            params=self.params,
+        )
+
+    def _final_output_points_and_states(self) -> tuple[FloatArray, np.ndarray]:
+        """Return the final point cloud after the legacy high-density cleanup."""
+
+        if len(self.last_point_density) != len(self.points):
+            return self.points, self.states
+        dynamic_mask = np.isin(self.states, [STATE_MOBILE, STATE_BOUNDARY])
+        keep = (~dynamic_mask) | (self.last_point_density < 100.0)
+        if np.all(keep):
+            points = self.points
+            states = self.states
+        else:
+            points = self.points[keep]
+            states = self.states[keep]
+        dynamic_mask = np.isin(states, [STATE_MOBILE, STATE_BOUNDARY])
+        domain_mask = self.geometry.classify_points(points) >= 0
+        keep_domain = (~dynamic_mask) | domain_mask
+        if not np.all(keep_domain):
+            points = points[keep_domain]
+            states = states[keep_domain]
+        return snap_final_boundary_points(points, states, self.geometry, self.a0, self.params)

nmesh/mesher/relaxation/engine/steps.py

@@ -0,0 +1,248 @@
+"""Relaxation displacement, convergence, and command execution phases."""
+
+from __future__ import annotations
+
+import logging
+import math
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ....backend import RawMesh
+from ....geometry.primitives import Body
+from ...driver import MeshEngineCommand, MeshEngineStatus
+from .._constants import BOUNDARY_FUZZ, DEFAULT_RNG_SEED, STATE_BOUNDARY, STATE_MOBILE
+from .._types import DensityFunction, EngineResult, FloatArray
+from ..forces import ForceSummary, compute_forces
+from ..geometry import FemGeometry, fem_geometry_from_bodies
+from ..seeding import _as_float_array
+from ..topology import _callback_mesh_info
+
+log = logging.getLogger(__name__)
+
+
+class RelaxationEngineStepMixin:
+    if TYPE_CHECKING:
+        geometry: FemGeometry
+        params: dict[str, Any]
+        a0: float
+        periodic: list[float] | list[bool]
+        points: FloatArray
+        states: np.ndarray[Any, Any]
+        step: int
+        finished: bool
+        last_addition_deletion_step: int
+        last_max_displacement: float
+        last_max_effective_force: float
+        last_point_density: FloatArray
+        max_rel_movement_since_last_triangulation: float
+        current_simplices: np.ndarray[Any, Any] | None
+        points_at_last_triangulation: FloatArray
+        cached_raw_mesh: RawMesh
+
+        def __getattr__(self, name: str) -> Any: ...
+
+    def _compute_constrained_displacement(
+        self,
+        point: FloatArray,
+        state: int,
+        displacement: FloatArray,
+        max_norm: float,
+    ) -> FloatArray:
+        """Return a clipped, boundary-aware candidate position for one point."""
+
+        bounded_displacement = np.array(displacement, copy=True)
+        if state == STATE_BOUNDARY:
+            normal = self.geometry.boundary_normal(point)
+            normal_norm = float(np.linalg.norm(normal))
+            if normal_norm > BOUNDARY_FUZZ:
+                bounded_displacement -= float(np.dot(bounded_displacement, normal)) * (
+                    normal / normal_norm
+                )
+
+        disp_norm = float(np.linalg.norm(bounded_displacement))
+        if disp_norm > max_norm > 0.0:
+            bounded_displacement *= max_norm / disp_norm
+
+        candidate = point + bounded_displacement
+        if state == STATE_BOUNDARY:
+            old_boundary_distance = self.geometry.boundary_distance(point)
+            new_boundary_distance = self.geometry.boundary_distance(candidate)
+            if new_boundary_distance > old_boundary_distance + self.boundary_drift_tolerance:
+                return np.asarray(point, dtype=float)
+
+        if self.geometry.classify_points(candidate[np.newaxis, :])[0] < 0:
+            candidate = self.geometry.project_segment_to_domain(point, candidate)
+
+        if self.geometry.classify_points(candidate[np.newaxis, :])[0] >= 0:
+            return np.asarray(candidate, dtype=float)
+        return np.asarray(point, dtype=float)
+
+    def _apply_relaxation_displacements(
+        self,
+        force_summary: ForceSummary,
+        time_step: float,
+    ) -> float:
+        """Move dynamic points and return the largest density-scaled relative step."""
+
+        new_points = np.array(self.points, copy=True)
+        max_relative_displacement = 0.0
+        max_norm = math.inf
+        for index, state in enumerate(self.states):
+            if state not in (STATE_MOBILE, STATE_BOUNDARY):
+                continue
+
+            point = self.points[index]
+            displacement = np.array(force_summary.total_forces[index], copy=True) * time_step
+            candidate = self._compute_constrained_displacement(
+                point, int(state), displacement, max_norm
+            )
+            new_points[index] = candidate
+            density_scale = self.geometry.density_at(candidate) ** (1.0 / max(self.geometry.dim, 1))
+            relative_displacement = (
+                float(np.linalg.norm(candidate - point))
+                * density_scale
+                / max(self.a0, BOUNDARY_FUZZ)
+            )
+            max_relative_displacement = max(max_relative_displacement, relative_displacement)
+        self.points = new_points
+        return max_relative_displacement
+
+    def _check_convergence(self) -> None:
+        """Update the engine state when a convergence condition is satisfied."""
+
+        if (
+            self.step > self.min_equilibrium_steps
+            and self.last_max_displacement <= self.tolerated_rel_move
+        ):
+            log.debug(
+                "Relaxation finished by movement convergence at step %d (rel_move=%g, effective_force=%g)",
+                self.step,
+                self.last_max_displacement,
+                self.last_max_effective_force,
+            )
+            self.finished = True
+            return
+
+        if self.step >= 2 and self.last_max_effective_force <= BOUNDARY_FUZZ:
+            log.debug(
+                "Relaxation finished by effective-force equilibrium at step %d (effective_force=%g, rel_move=%g)",
+                self.step,
+                self.last_max_effective_force,
+                self.last_max_displacement,
+            )
+            self.finished = True
+
+    def _step_once(self) -> None:
+        """Execute one relaxation step over all currently mobile or boundary points."""
+
+        if len(self.points) < self.geometry.dim + 1:
+            self.finished = True
+            return
+
+        force_summary = compute_forces(
+            self.points,
+            self.states,
+            self.geometry,
+            self.a0,
+            self.params,
+            self.step,
+            simplices=self.current_simplices,
+        )
+        self._record_triangulation(force_summary)
+        self.last_point_density = np.asarray(force_summary.point_density, dtype=float)
+        time_step = self._effective_time_step(force_summary)
+        self.last_max_displacement = self._apply_relaxation_displacements(force_summary, time_step)
+        self.last_max_effective_force = force_summary.max_effective_force
+        self._refresh_boundary_states()
+        self._update_topology_movement()
+        self._refresh_topology_if_needed()
+
+        if self._should_attempt_point_change():
+            self.last_addition_deletion_step = self.step
+            self._attempt_add_delete_points(force_summary)
+
+        self._check_convergence()
+
+    def callback_payload(self) -> list[list[Any]]:
+        """Return the callback payload for the engine's current mesh snapshot."""
+
+        return _callback_mesh_info(self.cached_raw_mesh)
+
+    def run(self, command: MeshEngineCommand) -> EngineResult:
+        """Handle one driver command and return the next engine status tuple."""
+
+        if command == MeshEngineCommand.DO_EXTRACT:
+            self._rebuild_mesh()
+            return MeshEngineStatus.PRODUCED_INTERMEDIATE_MESH, (
+                self.callback_payload(),
+                self.run,
+            )
+
+        if command != MeshEngineCommand.DO_STEP:
+            raise ValueError(f"Unsupported mesh engine command: {command!r}")
+
+        if self.finished or self._step_limit_reached():
+            self._rebuild_mesh(final=True)
+            return MeshEngineStatus.FINISHED_STEP_LIMIT_REACHED, None
+
+        self.step += 1
+        self._step_once()
+
+        if self.finished:
+            self._rebuild_mesh(final=True)
+            return MeshEngineStatus.FINISHED_FORCE_EQUILIBRIUM_REACHED, None
+
+        if self._step_limit_reached():
+            self._rebuild_mesh(final=True)
+            return MeshEngineStatus.FINISHED_STEP_LIMIT_REACHED, None
+
+        return MeshEngineStatus.CAN_CONTINUE, self.run
+
+
+def mesh_bodies_raw(
+    gendriver: Any,
+    mesher: dict[str, Any],
+    bb_min: list[float],
+    bb_max: list[float],
+    mesh_ext: int,
+    objects: list[Body],
+    a0: float,
+    density: str | DensityFunction | None,
+    fixed: list[list[float]],
+    mobile: list[list[float]],
+    simply: list[list[float]],
+    periodic: list[float] | list[bool],
+    hints: list[list[Any]],
+) -> RawMesh:
+    """Public backend entry point for meshing bodies with the Python engine."""
+
+    geometry = fem_geometry_from_bodies(
+        (np.asarray(bb_min, dtype=float), np.asarray(bb_max, dtype=float)),
+        list(objects),
+        list(hints),
+        density=density,
+        mesh_exterior=bool(mesh_ext),
+    )
+
+    # Import lazily so the public façade can compose the engine mixins first.
+    from . import RelaxationEngine
+
+    engine = RelaxationEngine(
+        geometry,
+        mesher,
+        float(a0),
+        _as_float_array(fixed, dim=geometry.dim),
+        _as_float_array(mobile, dim=geometry.dim),
+        _as_float_array(simply, dim=geometry.dim),
+        list(periodic),
+        rng=np.random.default_rng(DEFAULT_RNG_SEED),
+    )
+
+    if callable(gendriver):
+        gendriver(engine.run)
+    else:
+        engine.run(MeshEngineCommand.DO_STEP)
+
+    engine._rebuild_mesh(final=True)
+    return engine.cached_raw_mesh