Strain-result format

Standalone HDF5 files use root format="lauelab-strain-results" and integer version=1. Root metadata identifies creation time, package version, strain_measure="deviatoric Biot stretch", scale_convention="reference volume", shear_convention="tensor" and result count.

The ordered groups /results/0, /results/1, and so on each contain one successful or failed fit. Saving a single result is a one-item collection; loading always returns a list. An empty collection is valid.

Fields	Storage	Meaning
status	Scalar int8 HDF5 enum	converged=0, insufficient_support=1, ill_conditioned=2, nonconverged=3, invalid_input=4
message, coordinates, fit_mask, provenance_json	Scalar UTF-8 strings	Diagnostic explanation, conventions and effective settings
n_parameters, rank, nfev	int64 scalars	Fit/support diagnostics
condition_number	float64 scalar	Dimensionless joint Jacobian condition, infinity if unavailable
tensor, rotation	float64 (3,3)	Dimensionless tensor and fitted orientation
reciprocal, reference_reciprocal	float64 (3,3)	Reciprocal rows in 1/nm, including 2*pi
cell_parameters, working_cell_parameters	float64 (6,)	Final volume-normalized and pre-normalization fitted a,b,c,alpha,beta,gamma, respectively; lengths in nm and angles in degrees
predicted_qhat, predicted_xy, angular_residual_deg	float64 (n,3), (n,2), (n,)	Predictions and errors aligned to measurement rows
measurements/qhat, measurements/xy	float64 (n,3), (n,2)	Actual direction inputs and available zero-based frame centroids
measurements/hkl, measurements/peak_indices	int64 (n,3), (n,)	Miller indices and original measured-peak IDs
measurements/initial_reciprocal	float64 (3,3)	Starting reciprocal rows; availability recorded separately
measurements/frame_id_json, measurements/pattern_index	UTF-8 JSON scalar, int64 scalar	Source identity without conflating string/integer frame IDs
measurements/provenance_json	UTF-8 scalar	Source precision, selections, effective calibration snapshot and input fingerprint

NaN marks unavailable numerical arrays, including unsuccessful tensors and direction-only pixel columns. Missing initial lattices for invalid-input batch records use a false boolean has_initial attribute and an all-NaN stored matrix. These are not zero-strain measurements.

Dimensioned arrays have a units attribute; dimensionless tensors, rotations, directions and indices have none. The mixed cell-parameter arrays have component_units=["nm","nm","nm","deg","deg","deg"] instead of a single unit. Effective native reference parameters, frozen-value policy, initial projection, optimizer controls and empirical-parity status are retained. Pixel-based measurements include detector calibration parameters and the loaded geometry XML snapshot where available; saved results do not depend on a mutable source geometry path.

Loading validates the marker/version, group counts, scalar types, array shapes/dtypes/units, identity/HKL validity and owned result model. Successful results additionally require finite scientific fields, a proper fitted rotation, reference-volume agreement, and consistency among lattices, tensors, cell parameters, predicted directions and angular errors. This is structural/numerical validation, not an independent check of calibration quality or phase correctness.

Saving writes a temporary file beside the destination, validates by loading, closes the file, then uses the package publication helper. Default publication refuses to overwrite an existing destination. Original indexing inputs cannot be used as destinations.

CSV exports have two row granularities: one per result and one per reflection. Both identify result index, source frame/pattern identity, status, coordinates, strain measure, scale and shear convention. The catalogue includes fitted orientation/reciprocal matrices, tensor components and support diagnostics. The reflection table includes measured/predicted pixels, angular residuals and predicted energy. CSV is an exchange view; HDF5 retains the complete evidence and provenance. The two CSV files are individually published, not an atomic pair.

This standalone collection uses per-fit groups rather than the flat ragged tables in an indexing catalogue. Each group is an independent result with its own reference, model, calibration snapshot and available/failed arrays. The format is written as a complete collection, not an appendable scan. Effective settings and provenance are stored as JSON objects; the scientific arrays and diagnostics remain directly accessible HDF5 datasets.