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

nmesh/mesh_generation.py

@@ -0,0 +1,182 @@
+"""Construction of meshes from geometry and point/simplicial inputs."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from .backend import backend
+from .mesh_model import MeshBase, Point, Simplex
+
+if TYPE_CHECKING:
+    from .geometry import Body, MeshObject
+    from .mesher.meshing_parameters import MeshingParameters
+
+MeshCallback = Callable[[int, int, object], None]
+
+
+def _as_float_points(points: Sequence[Sequence[float]] | None) -> list[Point]:
+    return [list(map(float, point)) for point in (points or [])]
+
+
+def _as_int_simplices(simplices: Sequence[Sequence[int]] | None) -> list[Simplex]:
+    return [list(map(int, simplex)) for simplex in (simplices or [])]
+
+
+def _as_region_ids(regions: Sequence[int] | None) -> list[int]:
+    return [int(region) for region in (regions or [])]
+
+
+def _normalise_periodic(periodic: Sequence[bool] | Sequence[float] | None, dim: int) -> list[float]:
+    if not periodic:
+        return [0.0] * dim
+    return [1.0 if bool(value) else 0.0 for value in periodic]
+
+
+def get_default_meshing_parameters() -> MeshingParameters:
+    """Returns default meshing parameters."""
+    from .mesher.meshing_parameters import MeshingParameters
+
+    return MeshingParameters()
+
+
+# --- Loading Utilities ---
+
+
+class Mesh(MeshBase):
+    """Generate a simplex mesh from implicit geometric objects.
+
+    Args:
+        bounding_box: Lower and upper coordinate corners enclosing the model.
+        objects: Geometry primitives or boolean combinations to mesh.
+        a0: Target initial point spacing in mesh-coordinate units.
+        density: Optional legacy density expression.
+        periodic: Periodic coordinate selectors for bounding-box meshing.
+        fixed_points: Additional points held fixed during relaxation.
+        mobile_points: Additional mobile seed points.
+        simply_points: Additional simple seed points.
+        callback: Mesher progress callback and interval.
+        mesh_bounding_box: Mesh the complete bounding box when true.
+        meshing_parameters: Explicit mesher controls.
+        cache_name: Optional compatibility cache label.
+        hints: Mesh/object hint pairs.
+        **kwargs: Named meshing-parameter overrides.
+
+    Raises:
+        ValueError: If the bounding box or object configuration is invalid.
+    """
+
+    def __init__(
+        self,
+        bounding_box: Sequence[Sequence[float]] | None,
+        objects: Sequence[MeshObject] | None = None,
+        a0: float = 1.0,
+        density: str = "",
+        periodic: Sequence[bool] | Sequence[float] | None = None,
+        fixed_points: Sequence[Sequence[float]] | None = None,
+        mobile_points: Sequence[Sequence[float]] | None = None,
+        simply_points: Sequence[Sequence[float]] | None = None,
+        callback: tuple[MeshCallback, int] | None = None,
+        mesh_bounding_box: bool = False,
+        meshing_parameters: MeshingParameters | None = None,
+        cache_name: str = "",
+        hints: Sequence[tuple[MeshBase, MeshObject]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if bounding_box is None:
+            raise ValueError("Bounding box must be provided.")
+
+        object_list = list(objects or [])
+        hint_list = list(hints or [])
+        bb = _as_float_points(bounding_box)
+        dim = len(bb[0])
+        mesh_ext = 1 if mesh_bounding_box else 0
+
+        self.bounding_box = bb
+        self.mesh_exterior = mesh_ext
+
+        if not object_list and not mesh_bounding_box:
+            raise ValueError("No objects to mesh and bounding box meshing disabled.")
+
+        if periodic and not mesh_bounding_box and any(periodic):
+            raise ValueError("Can only produce periodic meshes when meshing the bounding box.")
+
+        params = meshing_parameters or get_default_meshing_parameters()
+        self.meshing_parameters = params
+        for k, v in kwargs.items():
+            params[k] = v
+
+        obj_bodies: list[Body] = []
+        self.obj = obj_bodies
+        self.cache_name = cache_name
+        self.density = density
+        self._fixed_points = _as_float_points(fixed_points)
+        self._mobile_points = _as_float_points(mobile_points)
+        self._simply_points = _as_float_points(simply_points)
+
+        for obj in object_list:
+            obj_bodies.append(obj._require_body())
+            self._fixed_points.extend(obj.fixed_points)
+            self._mobile_points.extend(obj.mobile_points)
+
+        resolved_hints = [
+            [hint_mesh.raw_mesh, hint_object._require_body()]
+            for hint_mesh, hint_object in hint_list
+        ]
+
+        from .mesher.driver import make_mg_gendriver
+
+        periodic_floats = _normalise_periodic(periodic, dim)
+        self.periodic = periodic_floats
+
+        def no_callback(_piece: int, _step: int, _mesh: object) -> None:
+            return None
+
+        cb_func, cb_interval = callback if callback else (no_callback, 1_000_000)
+        self.fun_driver = cb_func
+        self.driver = make_mg_gendriver(cb_interval, cb_func)
+        self.mesher_config = backend.copy_mesher_defaults(backend.mesher_defaults)
+        params.apply_to_mesher(self.mesher_config, dim)
+
+        raw = backend.mesh_bodies_raw(
+            self.driver,
+            self.mesher_config,
+            bb[0],
+            bb[1],
+            mesh_ext,
+            obj_bodies,
+            float(a0),
+            density,
+            self._fixed_points,
+            self._mobile_points,
+            self._simply_points,
+            periodic_floats,
+            cache_name,
+            resolved_hints,
+        )
+
+        super().__init__(raw)
+
+    def default_fun(self, nr_piece: int, n: int, mesh: object) -> None:
+        """Default callback function."""
+        pass
+
+    def extended_fun_driver(self, nr_piece: int, iteration_nr: int, mesh: object) -> None:
+        """Extended driver callback."""
+        if hasattr(self, "fun_driver"):
+            self.fun_driver(nr_piece, iteration_nr, mesh)
+
+    def fixed_points(self, points: Sequence[Sequence[float]] | None) -> None:
+        """Adds fixed points to the mesh configuration."""
+        if points:
+            self._fixed_points.extend(_as_float_points(points))
+
+    def mobile_points(self, points: Sequence[Sequence[float]] | None) -> None:
+        """Adds mobile points to the mesh configuration."""
+        if points:
+            self._mobile_points.extend(_as_float_points(points))
+
+    def simply_points(self, points: Sequence[Sequence[float]] | None) -> None:
+        """Adds simply points to the mesh configuration."""
+        if points:
+            self._simply_points.extend(_as_float_points(points))

nmesh/mesh_io.py

@@ -0,0 +1,227 @@
+"""Legacy and modern mesh file loading and serialization helpers."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TextIO
+
+from .backend import RawMesh, backend
+from .mesh_generation import _as_float_points, _as_int_simplices, _as_region_ids
+from .mesh_model import MeshBase
+
+log = logging.getLogger(__name__)
+
+
+def _is_nmesh_ascii_file(filename: str | Path) -> bool:
+    try:
+        with Path(filename).open(encoding="utf-8") as stream:
+            return stream.readline().startswith("# PYFEM")
+    except (OSError, UnicodeDecodeError):
+        return False
+
+
+def _is_nmesh_hdf5_file(filename: str | Path) -> bool:
+    from .io.legacy_nmesh_hdf5 import is_legacy_nmesh_hdf5
+
+    return is_legacy_nmesh_hdf5(filename)
+
+
+def hdf5_mesh_get_permutation(filename: str | Path) -> list[int] | None:
+    """Stub for retrieving permutation from HDF5."""
+    log.warning("hdf5_mesh_get_permutation: HDF5 support is stubbed.")
+    return None
+
+
+# --- Mesh Classes ---
+
+
+class MeshFromFile(MeshBase):
+    """Loads a mesh from a file."""
+
+    def __init__(
+        self,
+        filename: str | Path,
+        reorder: bool = False,
+        distribute: bool = True,
+    ) -> None:
+        if reorder:
+            raise NotImplementedError("Mesh reordering is not implemented.")
+        if not distribute:
+            raise NotImplementedError("Manual mesh distribution is not implemented.")
+        path = Path(filename)
+        if not path.exists():
+            raise FileNotFoundError(f"File {filename} not found")
+
+        if _is_nmesh_ascii_file(path):
+            from .io.ascii import read_ascii_nmesh
+
+            raw = read_ascii_nmesh(path)
+        elif _is_nmesh_hdf5_file(path):
+            from .io.legacy_nmesh_hdf5 import load_raw_mesh_from_legacy_nmesh_hdf5
+
+            raw = load_raw_mesh_from_legacy_nmesh_hdf5(path)
+        else:
+            from .io import load_raw_mesh_with_meshio
+
+            raw = load_raw_mesh_with_meshio(path)
+
+        super().__init__(raw)
+
+
+class mesh_from_points_and_simplices(MeshBase):
+    """Construct a mesh from explicit points, simplex indices, and regions.
+
+    Args:
+        points: Coordinate vectors with a consistent dimension.
+        simplices_indices: Point-index vectors defining simplex cells.
+        simplices_regions: Positive region ID for every simplex.
+        periodic_point_indices: Optional groups of equivalent periodic points.
+            The micromagnetic simulation does not currently support periodic
+            boundary physics.
+        initial: Use ``1`` to convert one-based simplex indices to zero-based.
+        do_reorder: Request unsupported legacy node reordering.
+        do_distribute: Keep true; manual distribution is unsupported.
+
+    Raises:
+        ValueError: If points, simplices, regions, or indices are inconsistent.
+        NotImplementedError: If reordering or manual distribution is requested.
+    """
+
+    def __init__(
+        self,
+        points: Sequence[Sequence[float]] | None = None,
+        simplices_indices: Sequence[Sequence[int]] | None = None,
+        simplices_regions: Sequence[int] | None = None,
+        periodic_point_indices: Sequence[Sequence[int]] | None = None,
+        initial: int = 0,
+        do_reorder: bool = False,
+        do_distribute: bool = True,
+    ) -> None:
+        if do_reorder:
+            raise NotImplementedError("Mesh reordering is not implemented.")
+        if not do_distribute:
+            raise NotImplementedError("Manual mesh distribution is not implemented.")
+        points_list = _as_float_points(points)
+        simplices_list = _as_int_simplices(simplices_indices)
+        if initial == 1:
+            simplices_list = [[index - 1 for index in simplex] for simplex in simplices_list]
+
+        raw = backend.mesh_from_points_and_simplices(
+            len(points_list[0]) if points_list else 3,
+            points_list,
+            simplices_list,
+            _as_region_ids(simplices_regions),
+            [list(map(int, group)) for group in (periodic_point_indices or [])],
+            do_reorder,
+            do_distribute,
+        )
+        super().__init__(raw)
+
+
+def load(
+    filename: str | Path,
+    reorder: bool = False,
+    distribute: bool = True,
+) -> MeshFromFile:
+    """Load legacy Nmesh or a Meshio-supported mesh file.
+
+    Args:
+        filename: Source mesh path.
+        reorder: Request unsupported legacy node reordering.
+        distribute: Keep true; manual distribution is unsupported.
+
+    Returns:
+        Mesh wrapper containing points, simplices, regions, and topology.
+
+    Raises:
+        FileNotFoundError: If ``filename`` does not exist.
+        ValueError: If the mesh layout or supported cells are invalid.
+        NotImplementedError: If reordering or manual distribution is requested.
+    """
+    return MeshFromFile(filename, reorder, distribute)
+
+
+def save(mesh: MeshBase, filename: str | Path) -> None:
+    """Save a mesh using the format selected by the destination suffix.
+
+    Args:
+        mesh: Mesh to serialize.
+        filename: Destination. ``.h5`` selects Nmesh HDF5, ``.nmesh`` selects
+            Nmesh ASCII, and other suffixes are delegated to Meshio.
+    """
+    mesh.save(filename)
+
+
+# --- Utilities ---
+
+
+def write_mesh(
+    mesh_data: RawMesh
+    | tuple[
+        Sequence[Sequence[float]],
+        Sequence[tuple[int, Sequence[int]]],
+        Sequence[tuple[int, Sequence[int]]],
+    ],
+    out: str | Path | TextIO | None = None,
+    check: bool = True,
+    float_fmt: str = " %.17g",
+) -> None:
+    """
+    Writes mesh data to a file in nmesh format.
+
+    `mesh_data` may be a `RawMesh` or a legacy `(points, simplices, surfaces)` tuple.
+    """
+    if isinstance(mesh_data, RawMesh):
+        points = mesh_data.points
+        simplices = list(
+            zip(
+                mesh_data.regions or [1] * len(mesh_data.simplices),
+                mesh_data.simplices,
+                strict=True,
+            )
+        )
+        surfaces = list(
+            zip(
+                [1] * len(mesh_data.surfaces),
+                mesh_data.surfaces,
+                strict=True,
+            )
+        )
+        periodic_groups = mesh_data.periodic_point_indices
+    else:
+        points, simplices, surfaces = mesh_data
+        periodic_groups = []
+
+    lines = ["# PYFEM mesh file version 1.0"]
+    dim = len(points[0]) if points else 0
+    lines.append(
+        f"# dim = {dim} \t nodes = {len(points)} \t simplices = {len(simplices)} "
+        f"\t surfaces = {len(surfaces)} \t periodic = {len(periodic_groups)}"
+    )
+
+    lines.append(str(len(points)))
+    for p in points:
+        lines.append("".join(float_fmt % x for x in p))
+
+    lines.append(str(len(simplices)))
+    for body, nodes in simplices:
+        lines.append(f" {body} " + " ".join(str(n) for n in nodes))
+
+    lines.append(str(len(surfaces)))
+    for body, nodes in surfaces:
+        lines.append(f" {body} " + " ".join(str(n) for n in nodes))
+
+    lines.append(str(len(periodic_groups)))
+    for group_index, point_indices in enumerate(periodic_groups):
+        lines.append(f" {group_index} " + " ".join(str(index) for index in point_indices))
+
+    content = "\n".join(lines) + "\n"
+
+    if out is None:
+        print(content)
+    elif isinstance(out, (str, Path)):
+        Path(out).write_text(content, encoding="utf-8")
+    else:
+        out.write(content)

nmesh/mesh_model.py

@@ -0,0 +1,147 @@
+"""Mesh model wrapper and backend-backed cached accessors."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, TypeVar, cast
+
+from .backend import RawMesh, backend
+
+PYFEM_SUFFIXES = {"", ".nmesh", ".pyfem"}
+Point = list[float]
+Simplex = list[int]
+_T = TypeVar("_T")
+
+
+class MeshBase:
+    """Expose mesh geometry and topology through cached Python values.
+
+    Attributes:
+        points: Node coordinates.
+        simplices: Point indices for every simplex cell.
+        regions: Region ID for every simplex.
+        dim: Coordinate dimension.
+        surfaces: Boundary simplex indices.
+        point_regions: Incident region IDs for every point.
+        links: Unique mesh edges as point-index pairs.
+        region_volumes: Computed volume for each region.
+    """
+
+    def __init__(self, raw_mesh: RawMesh) -> None:
+        self.raw_mesh = raw_mesh
+        self._cache: dict[str, Any] = {}
+
+    def _cached_backend_value(
+        self,
+        cache_key: str,
+        getter: Callable[[RawMesh], _T],
+    ) -> _T:
+        if cache_key not in self._cache:
+            self._cache[cache_key] = getter(self.raw_mesh)
+        return cast(_T, self._cache[cache_key])
+
+    def scale_node_positions(self, scale: float) -> None:
+        """Multiply every node coordinate by ``scale`` and clear caches."""
+        backend.mesh_scale_node_positions(self.raw_mesh, float(scale))
+        for key in (
+            "points",
+            "simplices",
+            "regions",
+            "point_regions",
+            "links",
+            "region_volumes",
+            "periodic_indices",
+        ):
+            self._cache.pop(key, None)
+
+    def save(self, filename: str | Path) -> None:
+        """Save the mesh using the format selected by the filename suffix."""
+        path = Path(filename)
+        suffix = path.suffix.lower()
+        if suffix == ".h5":
+            from .io import save_raw_mesh_as_legacy_nmesh_hdf5
+
+            save_raw_mesh_as_legacy_nmesh_hdf5(path, self.raw_mesh)
+            return
+
+        if suffix not in PYFEM_SUFFIXES:
+            from .io import save_raw_mesh_with_meshio
+
+            save_raw_mesh_with_meshio(path, self.raw_mesh)
+            return
+
+        from .mesh_io import write_mesh
+
+        write_mesh(self.raw_mesh, out=path)
+
+    def __str__(self) -> str:
+        pts = backend.mesh_nr_points(self.raw_mesh)
+        simps = backend.mesh_nr_simplices(self.raw_mesh)
+        return f"Mesh with {pts} points and {simps} simplices"
+
+    def to_lists(self) -> list[object]:
+        """Return the backend's legacy mesh-data list representation."""
+        return backend.mesh_plotinfo(self.raw_mesh)
+
+    @property
+    def points(self) -> list[Point]:
+        """Return node coordinates."""
+        return self._cached_backend_value("points", backend.mesh_plotinfo_points)
+
+    @property
+    def simplices(self) -> list[Simplex]:
+        """Return point indices for every simplex cell."""
+        return self._cached_backend_value("simplices", backend.mesh_plotinfo_simplices)
+
+    @property
+    def regions(self) -> list[int]:
+        """Return the region ID for every simplex cell."""
+        return self._cached_backend_value("regions", backend.mesh_plotinfo_simplicesregions)
+
+    @property
+    def dim(self) -> int:
+        """Return the mesh coordinate dimension."""
+        return backend.mesh_dim(self.raw_mesh)
+
+    @property
+    def surfaces(self) -> list[list[int]]:
+        """Return point indices for detected boundary simplices."""
+        return backend.mesh_plotinfo_surfaces_and_surfacesregions(self.raw_mesh)[0]
+
+    @property
+    def point_regions(self) -> list[list[int]]:
+        """Return incident region IDs for each point."""
+        return self._cached_backend_value("point_regions", backend.mesh_plotinfo_pointsregions)
+
+    @property
+    def links(self) -> list[tuple[int, int]]:
+        """Return unique mesh edges as point-index pairs."""
+        return self._cached_backend_value("links", backend.mesh_plotinfo_links)
+
+    @property
+    def region_volumes(self) -> list[float]:
+        """Return geometric volume for each region."""
+        return self._cached_backend_value("region_volumes", backend.mesh_plotinfo_regionvolumes)
+
+    @property
+    def num_regions(self) -> int:
+        """Return the number of mesh regions."""
+        return len(self.region_volumes)
+
+    @property
+    def periodic_point_indices(self) -> list[list[int]]:
+        """Return groups of equivalent periodic point indices."""
+        return self._cached_backend_value(
+            "periodic_indices",
+            backend.mesh_plotinfo_periodic_points_indices,
+        )
+
+    @property
+    def permutation(self) -> list[int]:
+        """Return the node permutation mapping."""
+        return backend.mesh_get_permutation(self.raw_mesh)
+
+    def set_vertex_distribution(self, dist: object) -> None:
+        """Sets vertex distribution."""
+        backend.mesh_set_vertex_distribution(self.raw_mesh, dist)

nmesh/mesh_utilities.py

@@ -0,0 +1,79 @@
+"""Small utility constructors and reporting helpers for mesh objects."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+from . import utils
+from .mesh_io import mesh_from_points_and_simplices
+from .mesh_model import MeshBase, Point, Simplex
+
+log = logging.getLogger(__name__)
+
+
+def memory_report(tag: str) -> None:
+    """Reports memory usage."""
+    t, vmem, rss = utils.time_vmem_rss()
+    log.log(15, f"Memory report: T= {t:f} VMEM= {int(vmem)} KB RSS= {int(rss)} KB {tag}")
+
+
+# --- Configuration ---
+
+
+def outer_corners(mesh: MeshBase) -> tuple[Point | None, Point | None]:
+    """Determines the bounding box of the mesh nodes."""
+    coords = mesh.points
+    if not coords:
+        return None, None
+    transpose = list(zip(*coords, strict=True))
+    return [min(t) for t in transpose], [max(t) for t in transpose]
+
+
+def generate_1d_mesh_components(
+    regions: Sequence[tuple[float, float]],
+    discretization: float,
+) -> tuple[list[Point], list[Simplex], list[int]]:
+    """Generates 1D mesh components (points, simplices, regions)."""
+    points: list[Point] = []
+    simplices: list[Simplex] = []
+    regions_ids: list[int] = []
+    point_map: dict[float, int] = {}
+
+    def get_idx(value: float) -> int:
+        vk = round(value, 8)
+        if vk not in point_map:
+            point_map[vk] = len(points)
+            points.append([float(value)])
+        return point_map[vk]
+
+    for rid, (start, end) in enumerate(regions, 1):
+        if start > end:
+            start, end = end, start
+        steps = max(1, int(abs((end - start) / discretization)))
+        step = (end - start) / steps
+        last = get_idx(start)
+        for i in range(1, steps + 1):
+            curr = get_idx(start + i * step)
+            simplices.append([last, curr])
+            regions_ids.append(rid)
+            last = curr
+
+    return points, simplices, regions_ids
+
+
+def generate_1d_mesh(
+    regions: Sequence[tuple[float, float]],
+    discretization: float,
+) -> MeshBase:
+    """Generates a 1D mesh with specified regions and step size."""
+    pts, simps, regs = generate_1d_mesh_components(regions, discretization)
+    return mesh_from_points_and_simplices(pts, simps, regs)
+
+
+def to_lists(mesh: MeshBase) -> list[object]:
+    """Returns mesh data as Python lists."""
+    return mesh.to_lists()
+
+
+tolists = to_lists

nmesh/mesher/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from .driver import (
+    Callback,
+    EngineFunc,
+    MeshEngineCommand,
+    MeshEngineStatus,
+    do_every_n_steps_driver,
+    make_mg_gendriver,
+)
+from .meshing_parameters import MeshingParameters
+
+__all__ = [
+    "Callback",
+    "EngineFunc",
+    "MeshingParameters",
+    "MeshEngineCommand",
+    "MeshEngineStatus",
+    "do_every_n_steps_driver",
+    "make_mg_gendriver",
+]