Release notes for porous_media 0.5.0¶

Version 0.5.0 makes long simulation histories small enough to keep. XDMF time series and NetCDF caches are compressed, a whole series can share one dataset per attribute, and the reader understands the references that layout writes.

Compressed NetCDF caches¶

• New porous_media.data.netcdf module with write_netcdf, load_netcdf, open_netcdf, and netcdf_encoding. Compression settings live in one place rather than at each call site.
• Datasets are deflated at level 4 with the byte-shuffle filter. One run's uncompressed cell dataset measured 70 MB; the same float32 arrays with deflate and shuffle took 13 MB. Compression is lossless and stored dtypes are unchanged.
• NetCDF3, which scipy writes, cannot compress at all, so writing now uses the HDF5-backed h5netcdf engine. Reading accepts both layouts, so a dataset written before this release stays readable.
• mesh_datasets_from_xdmf writes and reads its cells and points caches through the new module.
• h5netcdf>=1.8.3 is a new required dependency.

Stacked XDMF time series¶

• XDMFTimeSeriesWriter accepts stack_time_steps. Each attribute becomes one growing dataset spanning the whole series, and every step references its slice through an XDMF HyperSlab. A dataset written one step at a time gives the compressor a single frame to work with, while a chunk spanning consecutive steps exposes how little changes between them: on reconstructed scalar fields this measured 3.5 times smaller than one dataset per step.
• XDMFTimeSeriesWriter also accepts share_identical_arrays, which stores an array identical to one already written as an HDF link instead of a second copy. It is not the default, because it makes the sidecar unsafe to edit in place.
• New XDMFTimeSeriesReader reads HyperSlab data items, which meshio's reader does not support, and falls back to meshio's behavior otherwise. mesh_datasets_from_xdmf and the PyVista timecourse visualization use it.

Research workflows¶

• The SPT analysis stores about 8.7 GB where the same workflow previously produced 97 GB. Only the fields the analysis reads are cached, artifacts are written compressed, and figures export as SVG and PNG without PDF duplicates.
• CYP2E1 joins the study as the seventh zonation pattern, with its own lobule, figure rows, icon, and color map. An unnamed pattern index is catalogued and plotted as pattern <index> rather than rejected, so a new study design is read without a code change.
• Necrosis uses its physical zero to one scale everywhere. The solver writes float32, so a cell meant to be exactly alive can land a few units of round-off below zero; that round-off is clipped to the physical state instead of reaching a shared colorbar.
• A simulation whose solver stops before the model duration no longer fails the manuscript figures. It keeps its place in the pattern-by-dose necrosis matrix as a marked panel naming the run and its actual end time, and nothing is extrapolated.
• The mixed-pattern lobule compares every pattern beside CYP2E1, which is the measured profile rather than one of the synthetic ones.
• pipeline.py accepts --no-combinations to skip the mixed views.

Repository policy¶

• develop is the default and integration branch; main carries the released versions. Neither accepts a direct push. main accepts only merge commits, so promoting develop never rewrites the promoted commits.
• The versioned ruleset definitions live in .github/rulesets/ and are applied with .github/rulesets/apply.sh.

Migration¶

• Install the new h5netcdf dependency, which uv sync and pip install resolve automatically.
• Caches written from this release are NetCDF4. Code that opens them by passing engine="scipy" explicitly must use h5netcdf, or load_netcdf, which selects the engine for the file it is given. Existing NetCDF3 caches do not need regenerating.
• Reading a series written with stack_time_steps=True requires XDMFTimeSeriesReader; meshio.xdmf.TimeSeriesReader raises on its HyperSlab references. Series written without the option stay readable by meshio.