Measured API behavior / synthetic test inputs

HDF5 virtual dataset dependency observations

Eight controlled cases distinguish a byte-identical virtual dataset file from complete and correctly resolved source arrays.

Metadata / Raw JSON / Python harness / Full analysis

Method

Eight fresh private fixtures per repetition. Each VDS maps two three-element int32 arrays into fixed (2,3) shape, once with default fill and once with -999. Every final observation uses a fresh Python process and empty working directory; HDF5_VDS_PREFIX is unset except in the named override case. All handles close before mutations. A separately materialized baseline is a control. Each case was repeated three times with identical returned values. The numeric payloads have no physical units. All 24 readers completed without an error; no probability estimate is inferred from those runs.

Interpretation

The missing-file and legitimate-zero cases return the same default-fill values for different reasons. An explicit -999 fill distinguishes them in this fixture. It does not distinguish a substituted source: both fill policies return the replacement values. In the prefix-override case, even hashes of the two files beside the VDS match, because the reader obtains its second row from a different directory.

colocatedSourceHashesMatch is deliberately narrow: it compares the two files beside the view against baseline hashes. It is not a dependency-resolution validator. The materialized control was captured before mutations while the complete source arrays were checked; copying values after sources disappear could simply preserve fill values.

Reproduce

Download the harness and pinned requirements into one directory. The runner creates private temporary files, bounds each subprocess wait and retains checks under optimized Python. Use --temp-dir to choose the temporary parent directory.

python3 -m venv .venv
.venv/bin/pip install --only-binary=:all: -r hdf5-vds-requirements.txt
.venv/bin/python hdf5-vds.py --repetitions 3 > observations.json

Environment: Python 3.12.3, h5py 3.15.0, HDF5 1.14.6, NumPy 2.3.3, Linux 6.8.0-146-generic; sec2 driver, v110 format bounds. The CSV/metadata generator validates the full fixture and source hashes before emitting tables. For a downloaded copy, put the raw JSON, harness and requirements in replay/public/research/, then run node build-hdf5-vds.mjs --root ./replay. Validated tables are written to replay/public/data/datasets/; the output directories are created automatically.

Limits

• Synthetic integers without physical units; not a scientific instrument dataset.
• One host and pinned library build; repetitions are not independent reliability trials.
• No power failure, concurrent writer, corrupt source, permissions fault or network filesystem test.
• Fixed relative filenames only; no unlimited selections, printf mappings, nested VDS or external links.
• Colocated hashes cover named files beside the VDS, not the library's complete resolution environment.
• The materialized control preserves this array only, not every group, attribute or scientific dependency.

Column definitions

repetition

One-based repeat on the same host, not an independent reliability trial.

case

Controlled source-availability or resolution change.

readerExitCode

Final reader process exit code; zero means it completed all three dataset reads.

viewHashMatches

VDS file SHA-256 equals its pre-change hash.

colocatedSourceHashesMatch

Both named source files beside the VDS match baseline hashes; not a resolver audit.

prefixOverride

Reader received a controlled HDF5_VDS_PREFIX containing a replacement b.h5.

defaultValues

Full fixed-shape VDS array with default fill value zero; dimensionless synthetic integers.

sentinelValues

Full fixed-shape VDS array with explicit fill value -999.

materializedValues

Ordinary array copied while baseline sources were present, before any mutation.

Sources and reuse

CC0-1.0 for Hesela's original harness and observations; upstream libraries and documents retain their licenses.

1. h5py 3.15.0: Virtual Datasets
2. The HDF Group: Introduction to the Virtual Dataset
3. The HDF Group: H5Pset_virtual source-file resolution and H5Pset_fill_value
4. h5py 3.15.0: Dataset.is_virtual and Dataset.virtual_sources

Definitions: HDF5 virtual dataset, HDF5 hyperslab, HDF5 fill value and HDF5.