Motivation
Users currently reach for an external application (HDFView, silx, ...) to browse gpec.h5, because the file is opaque: group and dataset names carry no inline documentation, so there is no way to learn what a quantity is or its units without reading source or docs.
The h5 already has a sensible group structure (input/, info/, equil/, splines/, locstab/, integration/, singular/, vacuum/, perturbed_equilibrium/, ...). It just doesn't document itself.
Proposed change
- Attach
units and description HDF5 attributes at the write sites. Wherever datasets are written (src/Equilibrium/Equilibrium.jl, src/PerturbedEquilibrium/Utils.jl, src/KineticForces/Output.jl, src/GeneralizedPerturbedEquilibrium.jl, the src/Analysis/* writers, etc.), add short units/description attributes. Source the wording from the same struct docstrings used elsewhere so it stays consistent.
- Add
GPEC.describe("gpec.h5") that prints the group tree with, per dataset: shape, units, and the one-line description. This makes the file browsable directly in the REPL.
Together these make the external browser optional rather than required.
Notes
- Consider a tiny helper to write a dataset together with its attributes so annotation is one call and hard to forget, and so new outputs are self-describing by default.
describe() pairs naturally with the GPECResult summary (companion issue): show(result) gives the high-level state, describe() gives the full annotated tree.- Longer-term ecosystem angle (out of scope here): we already integrate
IMASdd.dd; leaning outputs toward the IMAS data dictionary where they map cleanly would let community tools (OMAS/OMFIT) browse results for free. Tracked separately if pursued.
Related
Motivation
Users currently reach for an external application (HDFView, silx, ...) to browse
gpec.h5, because the file is opaque: group and dataset names carry no inline documentation, so there is no way to learn what a quantity is or its units without reading source or docs.The h5 already has a sensible group structure (
input/,info/,equil/,splines/,locstab/,integration/,singular/,vacuum/,perturbed_equilibrium/, ...). It just doesn't document itself.Proposed change
unitsanddescriptionHDF5 attributes at the write sites. Wherever datasets are written (src/Equilibrium/Equilibrium.jl,src/PerturbedEquilibrium/Utils.jl,src/KineticForces/Output.jl,src/GeneralizedPerturbedEquilibrium.jl, thesrc/Analysis/*writers, etc.), add shortunits/descriptionattributes. Source the wording from the same struct docstrings used elsewhere so it stays consistent.GPEC.describe("gpec.h5")that prints the group tree with, per dataset: shape, units, and the one-line description. This makes the file browsable directly in the REPL.Together these make the external browser optional rather than required.
Notes
describe()pairs naturally with theGPECResultsummary (companion issue):show(result)gives the high-level state,describe()gives the full annotated tree.IMASdd.dd; leaning outputs toward the IMAS data dictionary where they map cleanly would let community tools (OMAS/OMFIT) browse results for free. Tracked separately if pursued.Related