fem-post 0.1.2__py3-none-any.whl

fem_post/__init__.py

@@ -0,0 +1,41 @@
+"""
+fem-post: VTK post-processing for fem-core results.
+
+Create a PostProcessor for a mesh, add views to it -- the mesh, a field, a
+frequency sweep, mode shapes -- then update them (new data, display settings,
+current step) and export them (.vtu, .png) or show them interactively:
+
+    from fem_post import PostProcessor
+
+    post = PostProcessor(mesh)
+    post.add_mesh_view("mesh").export_png("out/mesh.png")
+    sweep = post.add_frequency_sweep_view("pressure", sweep_result)
+    sweep.export_vtu("out/sweep")
+    sweep.configure(part="real", value_range=(-1.0, 1.0)).export_pngs("out")
+
+Solver results are consumed by shape (fem_post.results), so fem_post does not
+depend on fem_core itself.
+"""
+
+from fem_post.conversion import MATERIAL_FIELD, MeshSampler, mesh_to_grid
+from fem_post.manager import PostProcessor
+from fem_post.naming import complex_field_names, frequency_sweep_field_name, modal_field_name, modal_frequency_hz
+from fem_post.settings import DisplaySettings
+from fem_post.views import FieldView, FrequencySweepView, MeshView, ModalView, View
+
+__all__ = [
+    "MATERIAL_FIELD",
+    "DisplaySettings",
+    "FieldView",
+    "FrequencySweepView",
+    "MeshSampler",
+    "MeshView",
+    "ModalView",
+    "PostProcessor",
+    "View",
+    "complex_field_names",
+    "frequency_sweep_field_name",
+    "mesh_to_grid",
+    "modal_field_name",
+    "modal_frequency_hz",
+]

fem_post/conversion.py

@@ -0,0 +1,338 @@
+"""
+In-memory conversion of an ngsolve mesh (plus fields on it) to a
+vtkUnstructuredGrid -- no .vtu file round-trip needed to render.
+
+Each volume element (a TRIG/QUAD of a 2D mesh, a TET/HEX/PRISM/PYRAMID of a
+3D one) is refined `subdivision` times on its *reference* element into a
+lattice of linear VTK cells. The lattice points are mapped to physical space
+and every field is evaluated there in one vectorized call per field
+(ngsolve.Mesh.MapToAllElements), so:
+
+- curved (mesh_config.curvature order > 1) elements render with their true
+  curved geometry, since the coordinates themselves are evaluated through
+  the element transformation, not interpolated from the straight vertices;
+- a higher-order field renders smoothly instead of piecewise-linear on the
+  raw (often coarse) elements -- `subdivision` is purely a rendering-density
+  knob, independent of the FEM order actually solved with;
+- points are per element (shared vertices are duplicated), so a field that
+  is discontinuous across elements -- a material index, an L2 field --
+  renders sharply instead of being averaged.
+
+A complex-valued field "name" is split into three real point-data arrays,
+complex_field_names("name") -- "name_re", "name_im" and "name_abs" (the
+pointwise Euclidean norm of the complex vector, i.e. ngsolve.Norm) -- since
+VTK has no complex arrays. A 2-component (2D vector) field is padded to 3
+components (z = 0): vtkWarpVector always reads 3 components, and padding
+leaves magnitudes, and so coloring, unchanged.
+"""
+
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Tuple
+
+import ngsolve as ngs
+import numpy as np
+import vtk
+from vtkmodules.util.numpy_support import numpy_to_vtk, numpy_to_vtkIdTypeArray, vtk_to_numpy
+
+from fem_post.naming import complex_field_names
+
+MATERIAL_FIELD = "material"
+
+IntPoint = Tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class ReferenceLattice:
+    """A reference element refined into linear VTK cells.
+
+    points: (n_points, dim) reference coordinates (ngsolve's conventions).
+    cells: (n_cells, n_vertices) indices into points.
+    cell_type: the VTK cell type every cell in `cells` has.
+    """
+
+    points: np.ndarray
+    cells: np.ndarray
+    cell_type: int
+
+
+class _LatticeBuilder:
+    """Collects integer lattice points (coordinates scaled by `scale`),
+    deduplicating them, and the cells that reference them."""
+
+    def __init__(self, scale: int) -> None:
+        self.scale = scale
+        self._index: Dict[IntPoint, int] = {}
+        self.cells: List[List[int]] = []
+
+    def point(self, p: IntPoint) -> int:
+        if p not in self._index:
+            self._index[p] = len(self._index)
+        return self._index[p]
+
+    def add_cell(self, points: Iterable[IntPoint]) -> None:
+        self.cells.append([self.point(p) for p in points])
+
+    def build(self, cell_type: int) -> ReferenceLattice:
+        points = np.array(list(self._index), dtype=float) / self.scale
+        return ReferenceLattice(points, np.array(self.cells, dtype=np.int64), cell_type)
+
+
+def _mid(a: IntPoint, b: IntPoint) -> IntPoint:
+    # Exact: every coordinate is a multiple of 2**(levels left), see _refine_*.
+    return tuple((i + j) // 2 for i, j in zip(a, b))
+
+
+def _refine_triangle(tri: Tuple[IntPoint, ...], levels: int) -> List[Tuple[IntPoint, ...]]:
+    if levels == 0:
+        return [tri]
+    a, b, c = tri
+    ab, bc, ca = _mid(a, b), _mid(b, c), _mid(c, a)
+    children = [(a, ab, ca), (ab, b, bc), (ca, bc, c), (ab, bc, ca)]
+    return [t for child in children for t in _refine_triangle(child, levels - 1)]
+
+
+def _refine_tetrahedron(tet: Tuple[IntPoint, ...], levels: int) -> List[Tuple[IntPoint, ...]]:
+    """Red refinement: 4 corner tets plus the inner octahedron cut into 4
+    tets around its ac-bd diagonal."""
+    if levels == 0:
+        return [tet]
+    a, b, c, d = tet
+    ab, ac, ad, bc, bd, cd = _mid(a, b), _mid(a, c), _mid(a, d), _mid(b, c), _mid(b, d), _mid(c, d)
+    children = [
+        (a, ab, ac, ad),
+        (ab, b, bc, bd),
+        (ac, bc, c, cd),
+        (ad, bd, cd, d),
+        (ac, bd, ab, ad),
+        (ac, bd, ad, cd),
+        (ac, bd, cd, bc),
+        (ac, bd, bc, ab),
+    ]
+    return [t for child in children for t in _refine_tetrahedron(child, levels - 1)]
+
+
+@lru_cache(maxsize=None)
+def reference_lattice(element_type: Any, subdivision: int) -> ReferenceLattice:
+    """The reference lattice for one ngsolve.ET element type, refined
+    `subdivision` times (2**subdivision cells per edge). PYRAMID elements
+    are never refined -- they are rare in netgen meshes and have no
+    conforming self-similar split -- and render as one linear cell."""
+    if subdivision < 0:
+        raise ValueError(f"subdivision must be >= 0, got {subdivision}")
+    n = 2**subdivision
+    builder = _LatticeBuilder(n)
+
+    if element_type == ngs.ET.TRIG:
+        for tri in _refine_triangle(((n, 0), (0, n), (0, 0)), subdivision):
+            builder.add_cell(tri)
+        return builder.build(vtk.VTK_TRIANGLE)
+
+    if element_type == ngs.ET.TET:
+        for tet in _refine_tetrahedron(((n, 0, 0), (0, n, 0), (0, 0, n), (0, 0, 0)), subdivision):
+            builder.add_cell(tet)
+        return builder.build(vtk.VTK_TETRA)
+
+    if element_type == ngs.ET.QUAD:
+        for i in range(n):
+            for j in range(n):
+                builder.add_cell([(i, j), (i + 1, j), (i + 1, j + 1), (i, j + 1)])
+        return builder.build(vtk.VTK_QUAD)
+
+    if element_type == ngs.ET.HEX:
+        for i in range(n):
+            for j in range(n):
+                for k in range(n):
+                    bottom = [(i, j, k), (i + 1, j, k), (i + 1, j + 1, k), (i, j + 1, k)]
+                    builder.add_cell(bottom + [(x, y, z + 1) for x, y, z in bottom])
+        return builder.build(vtk.VTK_HEXAHEDRON)
+
+    if element_type == ngs.ET.PRISM:
+        for tri in _refine_triangle(((n, 0), (0, n), (0, 0)), subdivision):
+            for k in range(n):
+                builder.add_cell([(x, y, k) for x, y in tri] + [(x, y, k + 1) for x, y in tri])
+        return builder.build(vtk.VTK_WEDGE)
+
+    if element_type == ngs.ET.PYRAMID:
+        builder = _LatticeBuilder(1)
+        builder.add_cell([(0, 0, 0), (1, 0, 0), (1, 1, 0), (0, 1, 0), (0, 0, 1)])
+        return builder.build(vtk.VTK_PYRAMID)
+
+    raise NotImplementedError(f"Unsupported volume element type {element_type}")
+
+
+def _positively_oriented(cells: np.ndarray, cell_type: int, xyz: np.ndarray) -> np.ndarray:
+    """Swap the first two vertices of every simplex whose physical signed
+    volume (tets) or z-normal area (planar triangles) is negative, so every
+    cell follows VTK's right-hand orientation -- the lattice refinement and
+    the element maps don't preserve orientation on their own, and filters
+    that integrate signed measures (e.g. vtkIntegrateAttributes) or compute
+    normals rely on it."""
+    if cell_type == vtk.VTK_TETRA:
+        p = xyz[cells]
+        signed = np.einsum("ij,ij->i", np.cross(p[:, 1] - p[:, 0], p[:, 2] - p[:, 0]), p[:, 3] - p[:, 0])
+    elif cell_type == vtk.VTK_TRIANGLE:
+        p = xyz[cells]
+        signed = np.cross(p[:, 1] - p[:, 0], p[:, 2] - p[:, 0])[:, 2]
+    else:
+        return cells
+    flipped = cells.copy()
+    negative = signed < 0
+    flipped[negative, 0], flipped[negative, 1] = cells[negative, 1], cells[negative, 0]
+    return flipped
+
+
+def _as_2d(values: Any, n_points: int) -> np.ndarray:
+    return np.asarray(values).reshape(n_points, -1)
+
+
+def _pad_planar(array: np.ndarray) -> np.ndarray:
+    if array.ndim == 2 and array.shape[1] == 2:
+        return np.column_stack([array, np.zeros(len(array), dtype=array.dtype)])
+    return array
+
+
+def _squeeze_scalar(array: np.ndarray) -> np.ndarray:
+    return array[:, 0] if array.ndim == 2 and array.shape[1] == 1 else array
+
+
+def _add_point_array(grid: "vtk.vtkDataSet", name: str, values: np.ndarray) -> None:
+    array = numpy_to_vtk(np.ascontiguousarray(values, dtype=float), deep=True)
+    array.SetName(name)
+    grid.GetPointData().AddArray(array)
+
+
+def _real_point_arrays(name: str, values: np.ndarray) -> Dict[str, np.ndarray]:
+    """Split one evaluated field into the real arrays VTK stores for it."""
+    if np.iscomplexobj(values):
+        re_name, im_name, abs_name = complex_field_names(name)
+        return {
+            re_name: _squeeze_scalar(_pad_planar(values.real)),
+            im_name: _squeeze_scalar(_pad_planar(values.imag)),
+            abs_name: np.linalg.norm(values, axis=1),
+        }
+    return {name: _squeeze_scalar(_pad_planar(values))}
+
+
+class MeshSampler:
+    """Samples one ngsolve mesh at the refined reference lattice of its
+    elements, once: the mapped points, the physical coordinates and the VTK
+    cells are computed on construction and shared by every grid built from
+    it. evaluate() then evaluates any field at those points with a single
+    vectorized call, which is all it takes to add or refresh a field.
+
+    subdivision refines each element that many times (2**subdivision cells
+    per edge) -- see the module docstring. Pass 0 to see the true, unrefined
+    element boundaries.
+    """
+
+    def __init__(self, mesh: Any, subdivision: int = 2) -> None:
+        self.mesh = mesh
+        self.subdivision = subdivision
+
+        elements = list(mesh.Elements(ngs.VOL))
+        element_types = [el.type for el in elements]
+        lattices = {et: reference_lattice(et, subdivision) for et in set(element_types)}
+
+        points_per_element = np.array([len(lattices[et].points) for et in element_types], dtype=np.int64)
+        point_offsets = np.concatenate([[0], np.cumsum(points_per_element)[:-1]]).astype(np.int64)
+        self.n_points = int(points_per_element.sum())
+
+        rules = {
+            et: ngs.IntegrationRule([tuple(p) for p in lattice.points], [0.0] * len(lattice.points))
+            for et, lattice in lattices.items()
+        }
+        self._mapped = mesh.MapToAllElements(rules, ngs.VOL)
+
+        coordinates = (ngs.x, ngs.y, ngs.z)[: mesh.dim]
+        xyz = _as_2d(ngs.CoefficientFunction(coordinates)(self._mapped), self.n_points)
+        if xyz.shape[1] < 3:
+            xyz = np.column_stack([xyz, np.zeros((self.n_points, 3 - xyz.shape[1]))])
+
+        # Cells, grouped by element type (cell order is irrelevant to VTK).
+        connectivity_parts: List[np.ndarray] = []
+        type_parts: List[np.ndarray] = []
+        size_parts: List[np.ndarray] = []
+        element_type_array = np.array([str(et) for et in element_types])
+        for et, lattice in lattices.items():
+            offsets = point_offsets[element_type_array == str(et)]
+            cells = (lattice.cells[None, :, :] + offsets[:, None, None]).reshape(-1, lattice.cells.shape[1])
+            cells = _positively_oriented(cells, lattice.cell_type, xyz)
+            connectivity_parts.append(cells.ravel())
+            size_parts.append(np.full(len(cells), cells.shape[1], dtype=np.int64))
+            type_parts.append(np.full(len(cells), lattice.cell_type, dtype=np.uint8))
+
+        connectivity = np.concatenate(connectivity_parts).astype(np.int64)
+        cell_offsets = np.concatenate([[0], np.cumsum(np.concatenate(size_parts))]).astype(np.int64)
+
+        self._cells = vtk.vtkCellArray()
+        self._cells.SetData(
+            numpy_to_vtkIdTypeArray(cell_offsets, deep=True), numpy_to_vtkIdTypeArray(connectivity, deep=True)
+        )
+        self._cell_types = numpy_to_vtk(np.concatenate(type_parts), deep=True, array_type=vtk.VTK_UNSIGNED_CHAR)
+        self._points = vtk.vtkPoints()
+        self._points.SetData(numpy_to_vtk(np.ascontiguousarray(xyz, dtype=float), deep=True))
+
+        # Region index into mesh.GetMaterials() at every sample point.
+        self.material_index = np.repeat([el.index for el in elements], points_per_element)
+
+    def new_grid(self) -> "vtk.vtkUnstructuredGrid":
+        """A new grid with this mesh's geometry and no point data. Grids share
+        the (read-only) points and cells, so each one is cheap."""
+        grid = vtk.vtkUnstructuredGrid()
+        grid.SetPoints(self._points)
+        grid.SetCells(self._cell_types, self._cells)
+        return grid
+
+    def evaluate(self, name: str, field: Any) -> Dict[str, np.ndarray]:
+        """Evaluate `field` (GridFunction or CoefficientFunction, real or
+        complex, scalar or vector) at every sample point, as the real point
+        arrays VTK stores for it: {name: values}, or name_re/name_im/name_abs
+        for a complex field."""
+        return _real_point_arrays(name, _as_2d(field(self._mapped), self.n_points))
+
+
+def set_point_arrays(grid: "vtk.vtkDataSet", arrays: Mapping[str, np.ndarray]) -> None:
+    """Add (or replace, by name) point-data arrays on `grid`."""
+    for name, values in arrays.items():
+        _add_point_array(grid, name, values)
+    grid.Modified()
+
+
+def mesh_to_grid(
+    mesh: Any,
+    fields: Optional[Mapping[str, Any]] = None,
+    *,
+    subdivision: int = 2,
+    color_by_material: bool = False,
+) -> "vtk.vtkUnstructuredGrid":
+    """One-off vtkUnstructuredGrid of `mesh` carrying every field in `fields`
+    (name -> GridFunction/CoefficientFunction) as point data -- see
+    MeshSampler. color_by_material adds a MATERIAL_FIELD ("material") array:
+    each element's region index into mesh.GetMaterials()."""
+    sampler = MeshSampler(mesh, subdivision)
+    grid = sampler.new_grid()
+    if color_by_material and mesh.GetMaterials():
+        set_point_arrays(grid, {MATERIAL_FIELD: sampler.material_index})
+    for name, field in (fields or {}).items():
+        set_point_arrays(grid, sampler.evaluate(name, field))
+    return grid
+
+
+def field_names(grid: "vtk.vtkDataSet") -> List[str]:
+    """Every point-data array name in `grid`, in storage order."""
+    point_data = grid.GetPointData()
+    return [point_data.GetArrayName(i) for i in range(point_data.GetNumberOfArrays())]
+
+
+def pad_planar_point_arrays(grid: "vtk.vtkDataSet") -> None:
+    """Pad every 2-component point-data array of `grid` to 3 components
+    (z = 0), in place. For grids read from a .vtu some other writer produced
+    -- ngsolve.VTKOutput writes a 2D vector field with 2 components, which
+    vtkWarpVector would misread."""
+    point_data = grid.GetPointData()
+    for name in field_names(grid):
+        array = point_data.GetArray(name)
+        if array is None or array.GetNumberOfComponents() != 2:
+            continue
+        _add_point_array(grid, name, _pad_planar(vtk_to_numpy(array)))  # replaces the same-named array

fem_post/export.py

@@ -0,0 +1,46 @@
+"""
+.vtu file I/O used by the views (View.export_vtu, PostProcessor.export_vtu).
+"""
+
+from pathlib import Path
+from typing import Union
+
+import vtk
+
+from fem_post.conversion import pad_planar_point_arrays
+
+PathLike = Union[str, Path]
+
+
+def vtu_path(filename: PathLike) -> Path:
+    """`filename` with ".vtu" appended unless it already ends with it."""
+    path = Path(filename)
+    return path if path.suffix == ".vtu" else path.with_name(path.name + ".vtu")
+
+
+def write_vtu(grid: "vtk.vtkUnstructuredGrid", filename: PathLike) -> str:
+    """Write `grid` to `filename` (".vtu" appended unless already there) as a
+    binary XML file, creating the directory if missing. Returns the path."""
+    path = vtu_path(filename)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    writer = vtk.vtkXMLUnstructuredGridWriter()
+    writer.SetFileName(str(path))
+    writer.SetInputData(grid)
+    writer.SetDataModeToBinary()
+    if writer.Write() != 1:
+        raise OSError(f"Failed to write {path}")
+    return str(path)
+
+
+def read_vtu(filename: PathLike) -> "vtk.vtkUnstructuredGrid":
+    """Read a .vtu file, padding 2-component vector arrays to 3 components
+    (as written by ngsolve.VTKOutput for a 2D vector field)."""
+    path = Path(filename)
+    if not path.is_file():
+        raise FileNotFoundError(path)
+    reader = vtk.vtkXMLUnstructuredGridReader()
+    reader.SetFileName(str(path))
+    reader.Update()
+    grid = reader.GetOutput()
+    pad_planar_point_arrays(grid)
+    return grid

fem_post/manager.py

@@ -0,0 +1,131 @@
+"""
+PostProcessor: the entry point of fem_post.
+
+One PostProcessor wraps one ngsolve mesh. It samples the mesh once (see
+fem_post.conversion.MeshSampler) and creates named views on it -- the mesh
+itself, a single field, a frequency sweep, a set of mode shapes -- that all
+share that sampling. Views are updated and exported individually (see
+fem_post.views); PostProcessor.export_vtu() writes several of them into one
+file.
+"""
+
+from typing import Any, Dict, Iterator, List, Optional, Sequence, TypeVar
+
+from fem_post.conversion import MeshSampler, field_names
+from fem_post.export import PathLike, write_vtu
+from fem_post.results import FrequencySweepResultLike, ModalResultLike
+from fem_post.settings import DisplaySettings
+from fem_post.views import FieldView, FrequencySweepView, MeshView, ModalView, View
+
+ViewT = TypeVar("ViewT", bound=View)
+
+
+class PostProcessor:
+    """Creates, holds and exports the views of one mesh.
+
+    subdivision refines each element that many times (2**subdivision cells
+    per edge) when sampling geometry and fields, so curved elements and
+    higher-order fields render smoothly; 0 shows the raw elements.
+
+    Every add_*_view() takes display settings as keyword arguments (see
+    DisplaySettings: part, edges, deformed, warp_scale, value_range,
+    colorbar_title, background, azimuth, elevation) and returns the view.
+    View names are unique within a PostProcessor.
+
+        post = PostProcessor(mesh)
+        modes = post.add_modal_view("modes", modal.result, deformed=True)
+        modes.export_vtu("out/modes")
+        modes.export_pngs("out")
+        modes.update(new_modal.result).configure(warp_scale=50.0).select_step(2).export_png("out/mode3.png")
+    """
+
+    def __init__(self, mesh: Any, *, subdivision: int = 2) -> None:
+        self._sampler = MeshSampler(mesh, subdivision)
+        self._views: Dict[str, View] = {}
+
+    @property
+    def mesh(self) -> Any:
+        return self._sampler.mesh
+
+    @property
+    def subdivision(self) -> int:
+        return self._sampler.subdivision
+
+    # -- view registry --------------------------------------------------------
+
+    @property
+    def views(self) -> Dict[str, View]:
+        """A copy of the name -> view mapping, in creation order."""
+        return dict(self._views)
+
+    def __getitem__(self, name: str) -> View:
+        if name not in self._views:
+            raise KeyError(f"No view named {name!r}; views: {list(self._views)}")
+        return self._views[name]
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._views
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._views)
+
+    def __len__(self) -> int:
+        return len(self._views)
+
+    def remove_view(self, name: str) -> View:
+        """Forget view `name` and return it."""
+        view = self[name]
+        del self._views[name]
+        return view
+
+    def _register(self, view: ViewT) -> ViewT:
+        self._views[view.name] = view
+        return view
+
+    def _new_settings(self, name: str, settings: Dict[str, Any]) -> DisplaySettings:
+        if name in self._views:
+            raise ValueError(f"A view named {name!r} already exists")
+        return DisplaySettings().updated(**settings)
+
+    # -- view factories --------------------------------------------------------
+
+    def add_mesh_view(self, name: str = "mesh", *, color_by_material: bool = True, **settings: Any) -> MeshView:
+        """The mesh geometry, colored by material region by default."""
+        return self._register(
+            MeshView(self._sampler, name, self._new_settings(name, settings), color_by_material=color_by_material)
+        )
+
+    def add_field_view(self, name: str, field: Any, **settings: Any) -> FieldView:
+        """One field: a GridFunction, CoefficientFunction or StaticResult."""
+        return self._register(FieldView(self._sampler, name, field, self._new_settings(name, settings)))
+
+    def add_frequency_sweep_view(
+        self, name: str, result: FrequencySweepResultLike, **settings: Any
+    ) -> FrequencySweepView:
+        """One step per swept frequency; `name` is the field's name (e.g.
+        "pressure"), used in step labels "pressure_0", "pressure_1", ... (one per
+        entry of result.frequencies, in order)."""
+        return self._register(FrequencySweepView(self._sampler, name, result, self._new_settings(name, settings)))
+
+    def add_modal_view(self, name: str, result: ModalResultLike, **settings: Any) -> ModalView:
+        """One step per mode shape, labeled "mode1", "mode2", ..."""
+        return self._register(ModalView(self._sampler, name, result, self._new_settings(name, settings)))
+
+    # -- exports ----------------------------------------------------------------
+
+    def export_vtu(self, filename: PathLike, views: Optional[Sequence[str]] = None) -> str:
+        """Write the arrays of several views (default: all) into one .vtu.
+        Raises ValueError if two views carry an array of the same name.
+        Returns the path written."""
+        names: List[str] = list(self._views) if views is None else list(views)
+        grid = self._sampler.new_grid()
+        point_data = grid.GetPointData()
+        owner: Dict[str, str] = {}
+        for name in names:
+            source = self[name].grid.GetPointData()
+            for array_name in field_names(self[name].grid):
+                if array_name in owner:
+                    raise ValueError(f"Views {owner[array_name]!r} and {name!r} both have an array {array_name!r}")
+                owner[array_name] = name
+                point_data.AddArray(source.GetArray(array_name))
+        return write_vtu(grid, filename)

fem_post/naming.py

@@ -0,0 +1,37 @@
+"""
+Field-naming conventions shared by every fem_post exporter/renderer.
+
+Kept in one place so an exported .vtu, a rendered PNG and an interactive
+view of the same result all agree on what a field is called -- e.g. a
+frequency sweep's "pressure_2_abs" -- without re-deriving the format
+string in several modules.
+"""
+
+import math
+from typing import Tuple
+
+
+def complex_field_names(name: str) -> Tuple[str, str, str]:
+    """The (real, imaginary, magnitude) point-data field names a
+    complex-valued field "name" is split into."""
+    return f"{name}_re", f"{name}_im", f"{name}_abs"
+
+
+def frequency_sweep_field_name(field_name: str, step_index: int) -> str:
+    """The field name used for swept frequency number `step_index` (0-based,
+    the same index as in the sweep's frequency list) of `field_name`, e.g.
+    "pressure_0". Built from the index, not the frequency value, so code can
+    rebuild it without matching a formatted number."""
+    return f"{field_name}_{step_index}"
+
+
+def modal_field_name(mode_index: int) -> str:
+    """The field name used for mode number `mode_index` (1-based), e.g.
+    "mode1". The natural frequency is not part of the name; it is in the
+    view's colorbar title and ModalView.frequencies_hz."""
+    return f"mode{mode_index}"
+
+
+def modal_frequency_hz(eigenvalue: float) -> float:
+    """Natural frequency (Hz) from a modal eigenvalue (omega^2)."""
+    return math.sqrt(max(eigenvalue, 0.0)) / (2 * math.pi)

fem_post/render.py

@@ -0,0 +1,50 @@
+"""
+Off-screen rendering of a Scene to PNG -- the engine behind View.export_png().
+
+Rendering needs a working OpenGL context but no visible display
+(SetOffScreenRendering(1)); on headless Linux run under `xvfb-run -a`.
+Without it VTK logs a "bad X server connection" warning and produces a
+blank image instead of failing outright.
+"""
+
+from pathlib import Path
+from typing import Callable, List, Sequence, Tuple
+
+import vtk
+
+from fem_post.export import PathLike
+from fem_post.scene import Scene
+
+# (prepare the scene for one image, where to write it)
+Shot = Tuple[Callable[[], None], PathLike]
+
+
+def render_pngs(scene: Scene, shots: Sequence[Shot], *, width: int = 1200, height: int = 900) -> List[str]:
+    """Render several images of one scene, reusing one off-screen window:
+    for each shot, call its prepare function (which calls scene.show() and
+    scene.fit_camera()) and write the window to its PNG path. Returns the
+    paths written."""
+    render_window = vtk.vtkRenderWindow()
+    render_window.SetOffScreenRendering(1)
+    scene.attach(render_window)
+    render_window.SetSize(width, height)
+
+    written = []
+    for prepare, output_png in shots:
+        prepare()
+        render_window.Render()
+
+        to_image = vtk.vtkWindowToImageFilter()
+        to_image.SetInput(render_window)
+        to_image.ReadFrontBufferOff()
+        to_image.Update()
+
+        path = Path(output_png)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        writer = vtk.vtkPNGWriter()
+        writer.SetFileName(str(path))
+        writer.SetInputConnection(to_image.GetOutputPort())
+        writer.Write()
+        written.append(str(path))
+    render_window.Finalize()
+    return written

fem_post/results.py

@@ -0,0 +1,42 @@
+"""
+Structural (duck-typed) views of the solver results fem_post post-processes.
+
+fem_post deliberately does not import fem_core: these Protocols mirror the
+attributes of fem_core.models.study_result's StaticResult, ModalResult and
+FrequencySweepResult, so any object with the same shape -- fem-core's own
+results, or a hand-built stand-in -- is accepted.
+"""
+
+from typing import Any, Protocol, Sequence
+
+
+class StaticResultLike(Protocol):
+    """One solved field: a StaticResult, or one point of a frequency sweep."""
+
+    @property
+    def gridfunction(self) -> Any: ...  # ngsolve.GridFunction
+
+
+class ModalResultLike(Protocol):
+    """Eigenvalues (omega^2, ascending) and their mode-shape GridFunctions."""
+
+    @property
+    def eigenvalues(self) -> Sequence[float]: ...
+
+    @property
+    def eigenvectors(self) -> Sequence[Any]: ...
+
+
+class FrequencySweepResultLike(Protocol):
+    """One StaticResultLike per swept frequency (Hz)."""
+
+    @property
+    def frequencies(self) -> Sequence[float]: ...
+
+    @property
+    def results(self) -> Sequence[StaticResultLike]: ...
+
+
+def is_complex(gridfunction: Any) -> bool:
+    """True if `gridfunction` (or CoefficientFunction) is complex-valued."""
+    return bool(getattr(gridfunction, "is_complex", False))