Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 49 additions & 1 deletion src/ymf/xdmf.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,8 @@
import json
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple
from xml.etree.ElementTree import Element, ElementTree, ParseError, SubElement, parse as et_parse
from xml.etree.ElementTree import (Element, ElementTree, ParseError, SubElement, fromstring,
parse as et_parse)

from ymf.archive import YmfArchiveError, canonicalize_domain

Expand Down Expand Up @@ -392,6 +393,53 @@ def grid_element_time(grid_elem: Element, where: str = "Grid") -> Optional[float
return float(_attr(time_elem, ("Value",), where + ".Time"))


def read_grid_fragment(text: str | bytes) -> Tuple[Dict[str, Any], Optional[float]]:
"""Parse one serialized ``<Grid>`` element: ``(grid, time)``.

For the per-step metadata that Proteus <= 1.9.x stored inside its HDF5
files, one XDMF ``<Grid>`` fragment per rank and step, and that a
current Proteus still reads when it hot starts from or converts such an
archive. The time is the fragment's own ``<Time>`` when it has one and
``None`` otherwise; Proteus recorded it on only one of its two write
paths, so the reader tells the two apart by its presence.

This is the only XML a Proteus archive reader needs, and it lives here
so that Proteus itself imports no XML parser: XDMF is this module's
business.
"""
try:
grid_elem = fromstring(text)
except ParseError as exc:
raise YmfArchiveError("grid fragment is not XML (%s)" % (exc,)) from exc
if grid_elem.tag != "Grid":
raise YmfArchiveError(
"grid fragment: expected a <Grid> element, got <%s>" % (grid_elem.tag,))
return parse_grid_element(grid_elem), grid_element_time(grid_elem)


def collection_names(path: str | Path) -> List[str]:
"""The names of the top-level grids of an ``.xmf`` file, in order.

What a reader needs from the ``.xmf`` that Proteus <= 1.9.x wrote
beside its archive and nothing else: the order of the temporal
collections, which that Proteus recorded nowhere else and which a hot
start must reproduce. Only the ``<Domain>``'s direct ``<Grid>``
children are read, so a file holding grids the archive model cannot
represent still yields its names.
"""
try:
root = et_parse(path).getroot()
except ParseError as exc:
raise YmfArchiveError("%s is not an XML document (%s)" % (path, exc)) from exc
domain_elem = root.find("Domain")
if domain_elem is None:
return []
names = []
for ci, grid_elem in enumerate(domain_elem.findall("Grid")):
names.append(grid_elem.attrib.get("Name", "Grid %d" % (ci,)))
return names


def _encode_ymf_extra(ymf_extra: Any) -> str:
"""Serialize a YMF (sub-)document to base64-encoded JSON text.

Expand Down
87 changes: 87 additions & 0 deletions tests/test_xdmf_fragments.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
"""The two XDMF reads a Proteus archive reader needs, so Proteus imports no XML parser.

Proteus <= 1.9.x stored one ``<Grid>`` fragment per rank and step inside its
HDF5 files and wrote the collection order only into the ``.xmf`` beside them.
A current Proteus reads both when it hot starts from or converts such an
archive; these are the functions it reads them with.
"""
import pytest

from ymf.archive import YmfArchiveError
from ymf.xdmf import collection_names, read_grid_fragment

FRAGMENT = (
'<Grid GridType="Uniform">'
'<Time Value="2.5e-01" Name="3"/>'
'<Topology Type="Triangle" NumberOfElements="2">'
'<DataItem Format="HDF" DataType="Int" Precision="4" Dimensions="2 3">run.h5:/e3</DataItem>'
'</Topology>'
'<Geometry Type="XYZ">'
'<DataItem Format="HDF" DataType="Float" Precision="8" Dimensions="4 3">run.h5:/n3</DataItem>'
'</Geometry>'
'<Attribute Name="u" AttributeType="Scalar" Center="Node">'
'<DataItem Format="HDF" DataType="Float" Precision="8" Dimensions="4">run.h5:/u_t3</DataItem>'
'</Attribute>'
'</Grid>'
)


def test_a_fragment_with_a_time_gives_the_grid_and_the_time():
grid, time = read_grid_fragment(FRAGMENT)
assert time == 0.25
assert grid["topology"]["data_item"]["data"] == "run.h5:/e3"
assert grid["geometry"]["data_item"]["dimensions"] == [4, 3]
assert [a["name"] for a in grid["attributes"]] == ["u"]
assert "time" not in grid


def test_a_fragment_without_a_time_says_so():
without = FRAGMENT.replace('<Time Value="2.5e-01" Name="3"/>', "")
grid, time = read_grid_fragment(without)
assert time is None
assert grid["topology"]["type"] == "Triangle"


def test_bytes_are_read_as_well_as_text():
# HDF5 hands the stored fragment back as bytes
grid, time = read_grid_fragment(FRAGMENT.encode("utf-8"))
assert time == 0.25 and grid["topology"]["number_of_elements"] == 2


def test_something_that_is_not_a_grid_is_refused():
with pytest.raises(YmfArchiveError, match="expected a <Grid>"):
read_grid_fragment("<Domain/>")
with pytest.raises(YmfArchiveError, match="not XML"):
read_grid_fragment("<Grid")


def test_collection_names_come_in_file_order(tmp_path):
path = tmp_path / "run.xmf"
path.write_text(
'<?xml version="1.0" ?>\n'
'<Xdmf Version="2.0"><Domain>'
'<Grid Name="Mesh Spatial_Domain" GridType="Collection" CollectionType="Temporal"/>'
'<Grid Name="EBMesh Spatial_Domain" GridType="Collection" CollectionType="Temporal"/>'
'<Grid Name="Mesh_c0p2_Lagrange" GridType="Collection" CollectionType="Temporal">'
'<Grid GridType="Collection" CollectionType="Spatial"><Grid GridType="Uniform"/></Grid>'
'</Grid>'
'</Domain></Xdmf>\n')
# EBMesh sorts ahead of Mesh, which is why the order has to be read
assert collection_names(path) == ["Mesh Spatial_Domain", "EBMesh Spatial_Domain",
"Mesh_c0p2_Lagrange"]


def test_an_unnamed_collection_is_numbered(tmp_path):
path = tmp_path / "run.xmf"
path.write_text('<Xdmf><Domain><Grid GridType="Uniform"/>'
'<Grid Name="Mesh" GridType="Uniform"/></Domain></Xdmf>')
assert collection_names(path) == ["Grid 0", "Mesh"]


def test_a_file_without_a_domain_has_no_collections(tmp_path):
path = tmp_path / "run.xmf"
path.write_text("<Xdmf/>")
assert collection_names(path) == []
path.write_text("<Xdmf")
with pytest.raises(YmfArchiveError, match="not an XML document"):
collection_names(path)
Loading