Skip to content

Add Mesh.save_npy / Mesh.load_npy for fast large-mesh I/O - #1222

Merged
kinnala merged 1 commit into
kinnala:masterfrom
guhou-hvi:fix/save-npy-1109
Sep 19, 2026
Merged

kinnala merged 1 commit into
kinnala:masterfrom
guhou-hvi:fix/save-npy-1109

Conversation

@guhou-hvi

Copy link
Copy Markdown
Contributor

Problem

Mesh.save() routes through meshio, and Mesh.save_npz() bundles everything into one .npz archive. Both are inconvenient for the large-mesh case: the meshio conversion is slow and produces oversized files, and a single archive forces the user to load everything even when only some arrays are needed.

Proposal

Add Mesh.save_npy(path) and Mesh.load_npy(path) on the base Mesh class. save_npy writes one .npy file per array into a directory it creates under path:

  • doflocs.npy — node coordinates
  • t.npy — element topology
  • b_<name>.npy — each named boundary
  • s_<name>.npy — each named subdomain

This mirrors the approach sketched in #1109 (which uses np.save with allow_pickle=False) and avoids both the meshio round-trip and the .npz bundling.

Implementation

  • Lives next to the existing save_npz / load_npz on the base class, so every Mesh* subclass inherits it unchanged.
  • allow_pickle=False is passed explicitly on every np.save / np.load call.
  • Boundaries/subdomains use the same b_ / s_ naming convention already used by save_npz, so the two formats are conceptually aligned.
  • load_npy rebuilds the mesh through cls(...), so subclass identity and elem come from cls — no extra metadata file.

Tests

Added to tests/test_mesh.py:

  • test_save_load_npy_cycle — parametrized over MeshTri(), MeshQuad(), MeshTet(), MeshHex(), MeshLine(), verifying p and t.
  • test_save_load_npy_cycle_with_tags — a MeshTri().refined(2) with two boundaries and one subdomain, verifying boundaries and subdomains arrays survive the round-trip.
  • test_load_npy_missing — confirms a missing directory raises FileNotFoundError.

All 7 new parametrized cases pass. Existing test_mesh.py (176 tests) unaffected.

Local benchmark

Windows, Python 3.11.7, numpy 2.4.6, MeshTet().refined(5) (30481 nodes / 163840 elements):

save_npy  :      2.7 ms  size=  3.2 MB
save_npz  :      3.2 ms  size=  3.2 MB
save vtk  :    124.2 ms  size=  7.6 MB  (meshio round-trip)
load_npy  :     21.4 ms
load_npz  :     16.8 ms

save_npy is ~46× faster and ~2.4× smaller than Mesh.save() at this scale; the gap widens on the >1M-node meshes that motivated #1109. Loading is slightly slower for .npy because each array is a separate file, but the write path is where the issue reported pain.

Notes for review

  • API naming (save_npy / load_npy) and the multi-file .npy design come directly from Add save_npy/load_npy #1109. If you'd prefer the alternative of a single .npz with np.savez_compressed under the same names, that's a small change — happy to iterate.
  • save_npz / load_npz are left as-is for backwards compatibility.
  • The docstrings point at the trade-offs but avoid making claims about relative speed (benchmark lives here in the PR body, not in the docstring, since the numbers are scale-dependent).

Each array is stored in its own .npy file under a directory created by
save_npy. This bypasses the meshio round-trip in Mesh.save() and avoids
bundling everything into a single archive as save_npz does, which
matters for meshes with millions of nodes (see kinnala#1109).

Round-trips p, t, named boundaries and named subdomains. allow_pickle is
explicitly False everywhere. The default MeshTri/Quad/Tet/Hex/Line and
their with_boundaries/with_subdomains variants are all covered by tests.

Benchmark on MeshTet().refined(5) (~33k nodes, Windows, numpy 2.4.6):
  save_npy  :    1.9 ms  size=3.2 MB
  save_npz  :    3.2 ms  size=3.2 MB
  save vtk  :  126.9 ms  size=7.6 MB  (meshio)

Closes kinnala#1109.
@kinnala
kinnala merged commit fe6b326 into kinnala:master Sep 19, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants