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

nmesh/io/ascii.py

@@ -0,0 +1,132 @@
+"""Reader for the legacy ASCII ``.nmesh``/PYFEM mesh format."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from ..backend import RawMesh
+
+
+def read_ascii_nmesh(path: str | Path) -> RawMesh:
+    """Read a legacy ASCII ``.nmesh``/PYFEM mesh into :class:`RawMesh`."""
+    source = Path(path)
+    lines = [
+        line.strip()
+        for line in source.read_text(encoding="utf-8").splitlines()
+        if line.strip() and not line.lstrip().startswith("#")
+    ]
+    cursor = 0
+    point_count = int(lines[cursor])
+    cursor += 1
+    points = [_parse_float_row(lines[cursor + index]) for index in range(point_count)]
+    cursor += point_count
+    dim = len(points[0]) if points else 0
+
+    simplex_count = int(lines[cursor])
+    cursor += 1
+    simplices: list[list[int]] = []
+    regions: list[int] = []
+    for _ in range(simplex_count):
+        values = _parse_int_row(lines[cursor])
+        cursor += 1
+        regions.append(values[0])
+        simplices.append(values[1:])
+
+    surface_count = int(lines[cursor])
+    cursor += 1
+    surfaces: list[list[int]] = []
+    for _ in range(surface_count):
+        values = _parse_int_row(lines[cursor])
+        cursor += 1
+        surfaces.append(values[-dim:] if dim > 0 else [])
+
+    periodic_groups: list[list[int]] = []
+    if cursor < len(lines):
+        periodic_count = int(lines[cursor])
+        cursor += 1
+        for _ in range(periodic_count):
+            values = _parse_int_row(lines[cursor])
+            cursor += 1
+            periodic_groups.append(values[1:])
+
+    return RawMesh(
+        points=points,
+        simplices=simplices,
+        regions=regions,
+        point_regions=_build_point_regions(len(points), simplices, regions),
+        surfaces=surfaces,
+        links=_build_links(simplices),
+        region_volumes=_region_volumes(points, simplices, regions, dim),
+        periodic_point_indices=periodic_groups,
+        permutation=list(range(len(points))),
+        dim=dim,
+    )
+
+
+def _parse_float_row(line: str) -> list[float]:
+    return [float(value) for value in line.split()]
+
+
+def _parse_int_row(line: str) -> list[int]:
+    return [int(value) for value in line.split()]
+
+
+def _build_point_regions(
+    point_count: int,
+    simplices: list[list[int]],
+    regions: list[int],
+) -> list[list[int]]:
+    memberships: list[set[int]] = [set() for _ in range(point_count)]
+    for simplex, region in zip(simplices, regions, strict=True):
+        for point_index in simplex:
+            memberships[int(point_index)].add(int(region))
+    return [sorted(group) for group in memberships]
+
+
+def _build_links(simplices: list[list[int]]) -> list[tuple[int, int]]:
+    links: set[tuple[int, int]] = set()
+    for simplex in simplices:
+        for left_index, left in enumerate(simplex):
+            for right in simplex[left_index + 1 :]:
+                a = int(left)
+                b = int(right)
+                links.add((a, b) if a <= b else (b, a))
+    return sorted(links)
+
+
+def _region_volumes(
+    points: list[list[float]],
+    simplices: list[list[int]],
+    regions: list[int],
+    dim: int,
+) -> list[float]:
+    if not simplices:
+        return []
+    coords = np.asarray(points, dtype=float)
+    simplex_array = np.asarray(simplices, dtype=int)
+    measures = _simplex_measures(coords, simplex_array, dim)
+    totals = {int(region): 0.0 for region in regions}
+    for region, measure in zip(regions, measures, strict=True):
+        totals[int(region)] += float(measure)
+    return [totals[region] for region in sorted(totals)]
+
+
+def _simplex_measures(points: np.ndarray, simplices: np.ndarray, dim: int) -> np.ndarray:
+    if len(simplices) == 0:
+        return np.empty(0, dtype=float)
+    if dim == 1:
+        edges = points[simplices[:, 1]] - points[simplices[:, 0]]
+        return np.linalg.norm(edges, axis=1)
+
+    edge_matrices = points[simplices[:, 1:]] - points[simplices[:, [0]]]
+    gram_matrices = edge_matrices @ np.swapaxes(edge_matrices, 1, 2)
+    return np.sqrt(np.abs(np.linalg.det(gram_matrices))) / float(_factorial(dim))
+
+
+def _factorial(value: int) -> int:
+    result = 1
+    for item in range(2, value + 1):
+        result *= item
+    return result

nmesh/io/legacy_nmesh_hdf5.py

@@ -0,0 +1,318 @@
+"""Support for the legacy ``.nmesh.h5`` mesh format."""
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, cast
+
+import h5py
+import numpy as np
+from numpy.typing import NDArray
+
+from ..backend import RawMesh
+from .ascii import _build_links, _build_point_regions, _region_volumes
+
+FloatArray = NDArray[np.float64]
+IntArray = NDArray[np.int_]
+
+_REQUIRED_MESH_DATASETS = frozenset({"points", "simplices", "simplicesregions"})
+
+
+def _require_group(
+    parent: h5py.File | h5py.Group,
+    name: str,
+    *,
+    path: Path,
+) -> h5py.Group:
+    """Return a required child group after validating its HDF5 node type."""
+    node = parent.get(name)
+    if node is None:
+        raise ValueError(f"{path} is missing the /{name} group")
+    if not isinstance(node, h5py.Group):
+        raise ValueError(f"{path} has /{name}, but it is not an HDF5 group")
+    return node
+
+
+def _optional_dataset(
+    parent: h5py.File | h5py.Group,
+    name: str,
+    *,
+    path: Path,
+    hdf5_path: str,
+) -> h5py.Dataset | None:
+    """Return an optional dataset after validating its HDF5 node type."""
+    node = parent.get(name)
+    if node is None:
+        return None
+    if not isinstance(node, h5py.Dataset):
+        raise ValueError(f"{path} has {hdf5_path}, but it is not an HDF5 dataset")
+    return node
+
+
+def _require_dataset(
+    parent: h5py.File | h5py.Group,
+    name: str,
+    *,
+    path: Path,
+    hdf5_path: str,
+) -> h5py.Dataset:
+    """Return a required dataset after validating its HDF5 node type."""
+    dataset = _optional_dataset(
+        parent,
+        name,
+        path=path,
+        hdf5_path=hdf5_path,
+    )
+    if dataset is None:
+        raise ValueError(
+            f"{path} is missing one of /mesh/points, /mesh/simplices, or /mesh/simplicesregions"
+        )
+    return dataset
+
+
+def _decode_hdf5_string(value: Any) -> str | None:
+    """Convert HDF5 scalar or array string values into plain Python strings."""
+    if value is None:
+        return None
+    if isinstance(value, bytes):
+        return value.decode("utf-8")
+    if isinstance(value, str):
+        return value
+    if isinstance(value, np.ndarray):
+        array = np.asarray(value, dtype=object)
+        if array.shape == () or array.size == 1:
+            return _decode_hdf5_string(array.item())
+    return str(cast(object, value))
+
+
+def is_legacy_nmesh_hdf5(path: str | Path) -> bool:
+    """Return whether *path* has the recognizable legacy Nmesh HDF5 layout.
+
+    Older Nmesh files identify themselves with ``/etc/filetype == "nmesh"``.
+    Some valid historical files omit that optional marker, so the complete set
+    of required datasets in ``/mesh`` is also accepted as a signature.
+    """
+    path = Path(path)
+    is_hdf5 = cast(Callable[[str], bool], vars(h5py)["is_hdf5"])
+    if not is_hdf5(str(path)):
+        return False
+
+    try:
+        with h5py.File(str(path), "r") as handle:
+            filetype_node = handle.get("etc/filetype")
+            if isinstance(filetype_node, h5py.Dataset):
+                return _decode_hdf5_string(filetype_node[()]) == "nmesh"
+
+            mesh_group = handle.get("mesh")
+            return isinstance(mesh_group, h5py.Group) and _REQUIRED_MESH_DATASETS.issubset(
+                mesh_group.keys()
+            )
+    except OSError:
+        return False
+
+
+def _infer_dim(points: FloatArray, simplices: IntArray) -> int:
+    """Infer the mesh dimension from simplex arity or point coordinates."""
+    if simplices.ndim == 2 and simplices.shape[1] in (2, 3, 4):
+        return simplices.shape[1] - 1
+    if points.ndim == 2 and points.shape[1] > 0:
+        return int(points.shape[1])
+    return 3
+
+
+def _periodic_points_from_hdf5(
+    periodic_raw: IntArray | None,
+) -> list[list[int]]:
+    """Decode periodic-point rows, dropping the legacy ``-1`` padding markers."""
+    if periodic_raw is None:
+        return []
+
+    periodic = np.asarray(periodic_raw, dtype=int)
+    if periodic.size == 0:
+        return []
+    if periodic.ndim == 1:
+        periodic = periodic[np.newaxis, :]
+
+    return [[idx for idx in row.tolist() if idx != -1] for row in periodic]
+
+
+def load_raw_mesh_from_legacy_nmesh_hdf5(path: str | Path) -> RawMesh:
+    """Load a :class:`RawMesh` from the legacy ``.nmesh.h5`` file layout."""
+    path = Path(path)
+
+    with h5py.File(str(path), "r") as handle:
+        mesh_group = _require_group(handle, "mesh", path=path)
+
+        filetype_node = _optional_dataset(
+            handle,
+            "etc/filetype",
+            path=path,
+            hdf5_path="/etc/filetype",
+        )
+        filetype = _decode_hdf5_string(filetype_node[()] if filetype_node is not None else None)
+        if filetype not in (None, "nmesh"):
+            raise ValueError(f"{path} has filetype '{filetype}', expected 'nmesh'")
+
+        points_dataset = _require_dataset(
+            mesh_group,
+            "points",
+            path=path,
+            hdf5_path="/mesh/points",
+        )
+        simplices_dataset = _require_dataset(
+            mesh_group,
+            "simplices",
+            path=path,
+            hdf5_path="/mesh/simplices",
+        )
+        regions_dataset = _require_dataset(
+            mesh_group,
+            "simplicesregions",
+            path=path,
+            hdf5_path="/mesh/simplicesregions",
+        )
+        points: FloatArray = np.asarray(points_dataset[...], dtype=np.float64)
+        simplices: IntArray = np.asarray(simplices_dataset[...], dtype=np.int_)
+        regions: IntArray = np.asarray(regions_dataset[...], dtype=np.int_).flatten()
+
+        periodic_dataset = _optional_dataset(
+            mesh_group,
+            "periodicpointindices",
+            path=path,
+            hdf5_path="/mesh/periodicpointindices",
+        )
+        permutation_dataset = _optional_dataset(
+            mesh_group,
+            "permutation",
+            path=path,
+            hdf5_path="/mesh/permutation",
+        )
+
+        periodic_point_indices = _periodic_points_from_hdf5(
+            None if periodic_dataset is None else np.asarray(periodic_dataset[...], dtype=np.int_)
+        )
+        permutation: list[int] = (
+            []
+            if permutation_dataset is None
+            else cast(
+                list[int],
+                np.asarray(permutation_dataset[...], dtype=np.int_).flatten().tolist(),
+            )
+        )
+
+    # Validate data consistency
+    if len(points) == 0:
+        raise ValueError(f"{path} contains no points")
+    if len(simplices) == 0:
+        raise ValueError(f"{path} contains no simplices")
+    if len(regions) != len(simplices):
+        raise ValueError(
+            f"{path} has mismatched regions ({len(regions)}) and simplices ({len(simplices)})"
+        )
+
+    # Validate simplex indices are within bounds
+    simplices_list = simplices.tolist()
+    max_index = max(max(simplex) for simplex in simplices_list)
+    if max_index >= len(points):
+        raise ValueError(
+            f"{path} has simplex with out-of-bounds point index {max_index} "
+            f"(only {len(points)} points)"
+        )
+
+    points_list = points.tolist()
+    simplices_list = simplices.tolist()
+    regions_list = regions.tolist()
+    dim = _infer_dim(points, simplices)
+
+    return RawMesh(
+        points=points_list,
+        simplices=simplices_list,
+        regions=regions_list,
+        point_regions=_build_point_regions(len(points_list), simplices_list, regions_list),
+        links=_build_links(simplices_list),
+        region_volumes=_region_volumes(points_list, simplices_list, regions_list, dim),
+        periodic_point_indices=periodic_point_indices,
+        permutation=permutation,
+        dim=dim,
+    )
+
+
+def save_raw_mesh_as_legacy_nmesh_hdf5(path: str | Path, raw_mesh: RawMesh) -> None:
+    """Write a :class:`RawMesh` using the legacy ``.nmesh.h5`` file layout."""
+
+    path = Path(path)
+    points = np.asarray(raw_mesh.points, dtype=float)
+    simplices = np.asarray(raw_mesh.simplices, dtype=np.int32)
+    regions = np.asarray(raw_mesh.regions or [1] * len(raw_mesh.simplices), dtype=np.int32)
+    if len(points) == 0:
+        raise ValueError("Cannot save an empty mesh without points.")
+    if len(simplices) == 0:
+        raise ValueError("Cannot save an empty mesh without simplices.")
+    if len(regions) != len(simplices):
+        raise ValueError(
+            f"Cannot save mesh with {len(regions)} regions for {len(simplices)} simplices."
+        )
+
+    with h5py.File(str(path), "w") as handle:
+        _set_pytables_group_attrs(handle, title="")
+        etc_group = handle.create_group("etc")
+        mesh_group = handle.create_group("mesh")
+        _set_pytables_group_attrs(etc_group, title="Configuration and version data")
+        _set_pytables_group_attrs(mesh_group, title="Mesh data")
+
+        filetype = etc_group.create_dataset("filetype", data=np.asarray([b"nmesh"]))
+        _set_pytables_array_attrs(filetype, title="data file type", version="2.3")
+        fileversion = etc_group.create_dataset("fileversion", data=np.asarray([b"1.0"]))
+        _set_pytables_array_attrs(fileversion, title="data file type version", version="2.3")
+        points_dataset = mesh_group.create_dataset("points", data=points)
+        _set_pytables_array_attrs(
+            points_dataset,
+            title="Positions of mesh nodes (=points)",
+        )
+        simplices_dataset = mesh_group.create_dataset("simplices", data=simplices)
+        _set_pytables_array_attrs(
+            simplices_dataset,
+            title="Indices of nodes (starting from zero). Each row is one simplex.",
+        )
+        regions_dataset = mesh_group.create_dataset("simplicesregions", data=regions)
+        _set_pytables_array_attrs(
+            regions_dataset,
+            title="Region ids (one for each simplex).",
+        )
+
+        if raw_mesh.periodic_point_indices:
+            periodic = _padded_int_rows(raw_mesh.periodic_point_indices, fill=-1)
+            periodic_dataset = mesh_group.create_dataset("periodicpointindices", data=periodic)
+            _set_pytables_array_attrs(periodic_dataset, title="Periodic point indices")
+        if raw_mesh.permutation:
+            permutation_dataset = mesh_group.create_dataset(
+                "permutation",
+                data=np.asarray(raw_mesh.permutation, dtype=np.int32),
+            )
+            _set_pytables_array_attrs(permutation_dataset, title="Node permutation")
+
+
+def _padded_int_rows(rows: list[list[int]], *, fill: int) -> np.ndarray:
+    width = max(len(row) for row in rows)
+    result = np.full((len(rows), width), fill, dtype=np.int32)
+    for row_index, row in enumerate(rows):
+        result[row_index, : len(row)] = np.asarray(row, dtype=np.int32)
+    return result
+
+
+def _set_pytables_group_attrs(group: h5py.Group | h5py.File, *, title: str) -> None:
+    group.attrs["CLASS"] = np.bytes_(b"GROUP")
+    group.attrs["TITLE"] = np.bytes_(title.encode("utf-8"))
+    group.attrs["VERSION"] = np.bytes_(b"1.0")
+    if isinstance(group, h5py.File):
+        group.attrs["PYTABLES_FORMAT_VERSION"] = np.bytes_(b"2.0")
+
+
+def _set_pytables_array_attrs(
+    dataset: h5py.Dataset,
+    *,
+    title: str,
+    version: str = "1.0",
+) -> None:
+    dataset.attrs["CLASS"] = np.bytes_(b"CARRAY")
+    dataset.attrs["TITLE"] = np.bytes_(title.encode("utf-8"))
+    dataset.attrs["VERSION"] = np.bytes_(version.encode("utf-8"))

nmesh/io/meshio_support.py

@@ -0,0 +1,170 @@
+"""Mesh file IO built around ``meshio`` and legacy Nmesh HDF5 support."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Protocol, cast
+
+import meshio
+import numpy as np
+from numpy.typing import NDArray
+
+from ..backend import RawMesh
+from ..utils.types import ArrayLike
+from .legacy_nmesh_hdf5 import (
+    is_legacy_nmesh_hdf5,
+    load_raw_mesh_from_legacy_nmesh_hdf5,
+)
+
+_CELL_TYPE_BY_DIM = {
+    1: "line",
+    2: "triangle",
+    3: "tetra",
+}
+
+_DIM_BY_CELL_TYPE = {value: key for key, value in _CELL_TYPE_BY_DIM.items()}
+
+_REGION_DATA_KEYS = ("region", "gmsh:physical", "cell_tags", "gmsh:geometrical")
+
+
+class _CellBlock(Protocol):
+    type: str
+    data: NDArray[np.integer]
+
+
+class _MeshData(Protocol):
+    points: NDArray[np.floating]
+    cells: Sequence[_CellBlock]
+    cell_data: Mapping[str, Sequence[ArrayLike]]
+
+
+def _read_meshio(path: Path) -> _MeshData:
+    read = cast("object", vars(meshio)["read"])
+    if not callable(read):
+        raise TypeError("meshio.read is not callable")
+    return cast(_MeshData, read(path))
+
+
+def _write_meshio(path: Path, mesh: object) -> None:
+    write = cast("object", vars(meshio)["write"])
+    if not callable(write):
+        raise TypeError("meshio.write is not callable")
+    write(path, mesh)
+
+
+def _cell_type_for(raw_mesh: RawMesh) -> str:
+    """Return the meshio cell type that matches the raw mesh topology."""
+    if raw_mesh.simplices and len(raw_mesh.simplices) > 0:
+        simplex_size = len(raw_mesh.simplices[0])
+        if simplex_size == 2:
+            return "line"
+        if simplex_size == 3:
+            return "triangle"
+        if simplex_size == 4:
+            return "tetra"
+
+    return _CELL_TYPE_BY_DIM.get(raw_mesh.dim, "tetra")
+
+
+def _regions_from_meshio(
+    mesh: _MeshData,
+    cell_blocks: Sequence[tuple[int, _CellBlock]],
+) -> list[int]:
+    """Extract region ids aligned with the selected meshio cell blocks."""
+    cell_data = getattr(mesh, "cell_data", {})
+    total_count = sum(len(cell_block.data) for _, cell_block in cell_blocks)
+    for key in _REGION_DATA_KEYS:
+        if key not in cell_data:
+            continue
+
+        values_by_block = cell_data[key]
+        regions: list[int] = []
+        for block_index, cell_block in cell_blocks:
+            if block_index >= len(values_by_block):
+                raise ValueError(
+                    f"Region data {key!r} has no entry for cell block {block_index} "
+                    f"({cell_block.type})"
+                )
+
+            values = np.asarray(values_by_block[block_index])
+            expected_count = len(cell_block.data)
+            if values.size != expected_count:
+                raise ValueError(
+                    f"Region data {key!r} for cell block {block_index} "
+                    f"({cell_block.type}) has {values.size} values; "
+                    f"expected {expected_count}"
+                )
+            integer_values = np.asarray(values, dtype=np.int_)
+            regions.extend(cast(list[int], integer_values.tolist()))
+        return regions
+
+    return [1] * total_count
+
+
+def _load_raw_mesh_from_meshio(path: Path) -> RawMesh:
+    """Load a supported simplex mesh directly through ``meshio``."""
+    mesh = _read_meshio(path)
+    supported_blocks = [
+        (index, cell_block)
+        for index, cell_block in enumerate(mesh.cells)
+        if cell_block.type in _DIM_BY_CELL_TYPE
+    ]
+    if not supported_blocks:
+        raise ValueError(f"No supported simplex cells found in {path}")
+
+    dim = max(_DIM_BY_CELL_TYPE[cell_block.type] for _, cell_block in supported_blocks)
+    selected_blocks = [
+        (index, cell_block)
+        for index, cell_block in supported_blocks
+        if _DIM_BY_CELL_TYPE[cell_block.type] == dim
+    ]
+    simplices = [
+        simplex
+        for _, cell_block in selected_blocks
+        for simplex in np.asarray(cell_block.data, dtype=int).tolist()
+    ]
+    return RawMesh(
+        points=mesh.points.astype(float).tolist(),
+        simplices=simplices,
+        regions=_regions_from_meshio(mesh, selected_blocks),
+        dim=dim,
+    )
+
+
+def save_raw_mesh_with_meshio(path: str | Path, raw_mesh: RawMesh) -> None:
+    """Write a raw mesh to any meshio-supported format."""
+    cell_type = _cell_type_for(raw_mesh)
+    cells: list[tuple[str, ArrayLike] | meshio.CellBlock] = [
+        (cell_type, np.asarray(raw_mesh.simplices, dtype=int))
+    ]
+    cell_data: dict[str, list[ArrayLike]] | None = None
+    if raw_mesh.regions:
+        cell_data = {"region": [np.asarray(raw_mesh.regions, dtype=int)]}
+
+    mesh = meshio.Mesh(
+        points=np.asarray(raw_mesh.points, dtype=float),
+        cells=cells,
+        cell_data=cell_data,
+    )
+    _write_meshio(Path(path), mesh)
+
+
+def load_raw_mesh_with_meshio(path: str | Path) -> RawMesh:
+    """Load a raw mesh through ``meshio`` or the recognized legacy HDF5 loader.
+
+    Args:
+        path: Path to the mesh file.
+
+    Returns:
+        The loaded mesh as a RawMesh object.
+
+    Raises:
+        ValueError: If the file format is not supported or the file is malformed.
+        IOError/OSError: If the file cannot be read.
+    """
+    path = Path(path)
+    if is_legacy_nmesh_hdf5(path):
+        return load_raw_mesh_from_legacy_nmesh_hdf5(path)
+
+    return _load_raw_mesh_from_meshio(path)