Skip to content

Release notes for porous_media 0.4.0

Version 0.4.0 separates the reusable library from project research workflows and improves numerical correctness, performance, output safety, and resource handling.

Library and research separation

  • SPT, SimLiva, droplet studies, geometry reconstruction, and historical scripts now live in the repository's research/ subspace. They are excluded from wheels and source distributions. Bundled examples remain part of the installed library.
  • Research dependencies have their own uv dependency group. Private datasets, workstation paths, and external FEBio installations are not prerequisites for library use or the portable test suite.
  • Installation, quickstart, API, research, contributor, and release documentation are consolidated under docs/, with a Zensical documentation site.

Correctness and performance

  • Mesh zonation processes all cell blocks and uses spatial indexes for nearest boundary queries. Distances are no longer capped at one coordinate unit, fixing incorrect zonation in larger meshes. Invalid boundary labels and volumes fail before the mesh is modified.
  • Random zonation uses a local or caller-supplied NumPy generator. Weighted random patterns are normalized consistently, and exponential profiles respect their requested endpoints.
  • Scalar Xarray datasets use preallocated arrays, preserve single-cell dimensions and mixed field dtypes, and concatenate unequal cell blocks in mesh order. Incompatible time-series schemas produce explicit errors.
  • Directory cache generation bounds worker counts and supports serial execution with max_workers=1. Workers avoid returning unused datasets to the parent.
  • XDMF metadata reports actual array shapes and supports six-component tensor attributes. Field-limit scans avoid stacking individual scalar values and merge fields across inputs. Fresh conversions refresh their limits cache.
  • Image montages read one source image at a time, reducing open file handles.

Safer outputs and predictable rendering

  • FEBio rendering uses strict, sandboxed Jinja templates with XML escaping. Simulation identifiers and export filenames are validated for portable paths.
  • FEBio generation and VTU conversion require explicit overwrite=True to replace outputs. Output checks reject symlinks and protect unrelated HDF sidecars. XDMF references remain relative to their colocated HDF files.
  • vtu_to_xdmf now writes the requested XDMF/HDF output and returns the mesh.
  • PyVista plotters, Matplotlib figures, image files, and dataset readers close reliably. Rendering uses local themes, honors timecourse window sizes, and applies display conversion factors without changing source meshes.
  • Image annotation uses a portable default font and accepts an explicit font path. Image helpers create output parents as needed.
  • Importing plotting and console helpers no longer changes global plot styling or the Python display hook. Logger setup avoids duplicate handlers.

Migration

  • Replace imports under porous_media.analyses with research imports and run studies from a repository checkout. There is no installed compatibility alias. See the research migration guide for data and results environment variables.
  • The library no longer exports repository-specific BASE_DIR, DATA_DIR, RESULTS_DIR, or EXAMPLE_* constants. Pass explicit paths in applications; RESOURCES_DIR remains available for bundled examples.
  • Supply every FEBio template parameter and review existing templates for XML escaping. Use an explicit safe filter only for trusted XML fragments.
  • Opt into intentional replacement with overwrite=True for FEBio and VTU outputs. Directory conversions can produce different portable output names; update downstream paths where necessary.
  • Pass rng=np.random.default_rng(seed) to reproduce random zonation rather than relying on np.random.seed. Updated numerical results can differ from 0.3.0.
  • Consumers of XDMF metadata should use the actual array shapes rather than artificial stacking dimensions. Regenerate local NetCDF and JSON caches with overwrite=True after changing source data.
  • Use the porous_media.visualization.plots.plot_style() context when the package's Matplotlib styling is desired.

Python support and release tooling

  • Python 3.13 and 3.14 are supported. Installed-wheel CI covers both on Linux and Python 3.14 on Windows and macOS.
  • Python 3.15 has an experimental, nonblocking CI job. VTK distributions are still unavailable for that interpreter, so full Python 3.15 installation is not yet supported. Track issue #2.
  • Dependencies and development tooling are updated and locked with uv. Ruff and ty check library, tests, scripts, and research code; research regressions run separately from installed-library tests.
  • Release automation validates versioned notes and tags before publishing through ci-cd.yml. Manual release previews build and validate without publishing.

The archived code review report documents the findings, migration details, validation, and a synthetic zonation benchmark.