Units, Conventions, and Data Contracts

A numerical file is not self-describing merely because its arrays can be opened. The values become physical data only after units, coordinates, tensor index order, basis, metric and curvature signs, normalizations, and schema version are fixed. A data contract makes those choices explicit and machine-checkable. Its most important behavior is refusal: a consumer should reject an ambiguous file before a plausible-looking convention mismatch contaminates a waveform, horizon measure, or synthetic observation.

Required background. Calculus and Linear Algebra for Relativity supplies tensor components, basis changes, and dimensional scaling; Differential Equations for Relativity supplies the role of variables, parameters, and boundary data in a finite problem.

Helpful background. Formulations of General Relativity explains the spacetime and hypersurface conventions being encoded; Probability and Inference for Gravity helps propagate calibration and conversion uncertainty.

Values need semantic coordinates

Suppose an array named K has shape $(3,3,N_x,N_y,N_z)$. It could contain the extrinsic curvature $K_{ij}$, a mixed tensor $K^i{}_j$, a kernel, or a curvature scalar with two parameter axes. Even if it is extrinsic curvature, the sign may be opposite to the convention expected by the reader, the first two axes may be $(j,i)$, and the spatial components may be expressed in a coordinate or orthonormal basis. Shape and name do not settle any of these questions.

For a relativistic field product, the contract should declare at least:

• the physical system, solution family, parameter values, and validity domain;
• the coordinate chart, coordinate order, coordinate units, domain, orientation, and periodic identifications;
• the metric signature, Riemann-tensor sign, extrinsic-curvature sign, Fourier convention, and complex-polarization convention;
• every tensor’s variance, index order, basis or tetrad, symmetry, component layout, and unit;
• the normalization of harmonics, null vectors, four-velocities, fluxes, and dimensionless variables;
• the initial and boundary data, gauge choices, numerical method, resolution or tolerance, and precision;
• a schema identifier and version, producer version, immutable input identifiers, and checksums.

The site’s inherited conventions use metric signature $(-,+,+,+)$, explicit $G$ unless a sustained geometrized-unit switch is declared, and Fourier dependence $e^{-i\omega t}$. A file must still carry those choices because it can leave the site and meet software with different defaults. “Standard convention” is not a value.

Unit strings also require a grammar. Msun, M_sun, and solMass cannot safely be treated as intuitive synonyms; an exponent, scale prefix, or solid-angle unit can be parsed differently across systems. The IVOA recommendation gives a normative unit-string grammar and rules in IVOA VOUnits 1.1, §§ 1.5–2 and Appendix C.4. A project may choose another documented grammar, but producers and consumers must choose the same one and reject unrecognized tokens.

Geometrized and SI representations

Geometrized units make black-hole calculations compact by setting $G=c=1$ and measuring lengths and times relative to the geometrized length

$$M_{\rm geom}=\frac{G M_{\rm phys}}{c^2},$$

associated with a physical mass $M_{\rm phys}$. They do not remove dimensions; they hide conversion factors in the declared scale. In particular,

$$t_{\rm SI}=\frac{G M_{\rm phys}}{c^3}\,\bar t, \qquad r_{\rm SI}=\frac{G M_{\rm phys}}{c^2}\,\bar r, \qquad f_{\rm SI}=\frac{c^3}{G M_{\rm phys}}\,\bar f,$$

where barred quantities are dimensionless. A consumer cannot reconstruct seconds or metres from $\bar t$ and $\bar r$ unless it knows both $M_{\rm phys}$ and the constants convention. The SI Brochure defines the unit system and notation in BIPM 2026, 9th ed., §§ 2 and 5.

Consider an equatorial circular geodesic at Schwarzschild radius $r=6M_{\rm geom}$. In geometrized coordinates its nonzero four-velocity components are

$$u^t=\sqrt{2}, \qquad u^\phi=\frac{1}{6\sqrt{3}\,M_{\rm geom}}.$$

With $g_{tt}=-(1-2M_{\rm geom}/r)$ and $g_{\phi\phi}=r^2$, the invariant check is

$$g_{\mu\nu}u^\mu u^\nu =-\frac23(\sqrt2)^2 +36M_{\rm geom}^2\left(\frac{1}{6\sqrt3M_{\rm geom}}\right)^2 =-1.$$

The specific conserved quantities are

$$\mathcal E=-u_t=\frac{2\sqrt2}{3}, \qquad \frac{\mathcal L}{M_{\rm geom}}= \frac{u_\phi}{M_{\rm geom}}=2\sqrt3.$$

An SI representation using coordinates $(t_{\rm s},r_{\rm m},\theta,\phi)$ instead has $g_{tt}=-(1-2GM_{\rm phys}/(c^2r))c^2$, $u^t=dt/d\tau=\sqrt2$, and $u^\phi=c^3/(6\sqrt3G M_{\rm phys})$. Its normalization is $-c^2$, while the dimensionless invariants $-u_t/c^2$ and $c u_\phi/(G M_{\rm phys})$ remain $2\sqrt2/3$ and $2\sqrt3$. A round trip must compare these invariant forms, not demand numerically identical dimensional components.

Checking conventions in code

A hierarchical format such as HDF5 provides groups, datasets, datatypes, dataspaces, and attributes, but the application must assign their scientific meaning; those primitives are specified in The HDF Group n.d., HDF5 Data Model, “Groups” through “Attributes”. One compact contract for the orbit benchmark could require fields equivalent to:

schema: black-hole-state/1.0
constants: SI-Brochure-9-2026
coordinates: [t, r, theta, phi]
coordinate_units: [s, m, rad, rad]
metric_signature: -+++
riemann_sign: declared-symbolically
four_velocity: {variance: contravariant, axis_order: [component, sample]}
mass: {value: ..., unit: kg}
radius: {value: ..., unit: m}
input_sha256: ...

The illustrative schema name is not a standard and this page supplies no parser. A real schema must specify required fields, types, allowed unit grammar, shapes, array order, byte order, missing-value policy, coordinate domains, and compatibility rules. It should distinguish additive changes that old readers may ignore from semantic changes that require a major version. A generic schema language can enforce types and conditional requirements; JSON Schema’s core model and validation vocabulary are defined in JSON Schema 2020-12, Core §§ 4–10 and Validation §§ 4–10.

Validation occurs at three levels:

1. structural: required keys, types, shapes, versions, checksums, and unit syntax;
2. dimensional: compatible dimensions for every conversion and operation;
3. physical: invariant identities, constraints, symmetries, and known benchmark values.

A file can pass the first two while carrying a wrong sign. It can pass structural checks with two tensor axes swapped if both have length four. Physical checks close those gaps.

Schwarzschild round-trip benchmark

Construct two independently serialized records of the $r=6M_{\rm geom}$ orbit: one in $G=c=M_{\rm geom}=1$ variables and one in SI units for a declared $M_{\rm phys}$ and constants version. The producer records its operating system or container, language and numerical-library versions, source revision, binary64 arithmetic, coordinate and tensor layout, and the canonical input SHA-256 digest. The consumer starts from the schema, not producer-specific defaults.

For each record and after both conversion directions, require

$$\left|\frac{u\cdot u}{c_*^2}+1\right|<10^{-13}, \quad \left|\mathcal E-\frac{2\sqrt2}{3}\right|<10^{-13}, \quad \left|\ell_*-2\sqrt3\right|<10^{-13},$$

where $c_*=1$ and $\ell_*=u_\phi/M_{\rm geom}$ in the geometrized record, while $c_*=c$ and $\ell_*=c u_\phi/(G M_{\rm phys})$ in the SI record. Also require a byte-stable canonical metadata representation and the same input digest after a clean rerun. Repeat the conversion in 80-digit arithmetic; binary64 and high-precision invariant discrepancies should agree within $10^{-13}$. Tightening that tolerance without recording the constants version would be meaningless.

Negative tests must use fixtures sensitive to the intended defect. Delete the unit of $r$, delete the signature, or change the time coordinate from seconds to metres without changing $g_{tt}$: each must cause rejection or a failed physical identity. Transposing a symmetric metric or $K_{ij}$ changes nothing, so it cannot test index-order detection. Instead use a nonsymmetric mixed tensor with known signed components and distinct index meanings. Similarly, time-symmetric Schwarzschild data have $K_{ij}=0$, and the vacuum Hamiltonian constraint is quadratic in $K_{ij}$; neither detects a global sign reversal. Test a nonzero $K_{ij}$ against the independently evaluated signed metric-evolution relation in the declared convention. Silently inserting a default or choosing an insensitive fixture leaves the contract untested even if the orbit looks smooth.

The fully specified rerun sequence is: generate both records from one canonical parameter file; verify their hashes; validate schema and dimensions; compute invariants through two independent conversion routines; sweep binary64 and 80-digit precision; apply every negative mutation; and emit a machine-readable table of actual discrepancies and rejection outcomes. The calculation is valid only for the stated Schwarzschild chart and circular timelike orbit outside the horizon. It does not test horizon-penetrating coordinates, generic tensors, adaptive meshes, or waveform mode conventions.

Common failure modes

A conversion factor is applied twice. A filename such as waveform_M60.h5 is not authoritative metadata. Preserve a dimension vector and the exact scale transformation, and check a scalar invariant after conversion.

A convention-insensitive test is used. The Kretschmann scalar cannot reveal every Riemann-sign choice because it is quadratic. Include signed components or identities that respond to the convention being tested.

An old reader guesses a new schema. Unknown required fields and changed meanings must fail loudly. Compatibility is a declared relation between versions, not the absence of a parser exception.

Check your understanding

A producer using $(-,+,+,+)$ writes a normalized timelike four-velocity with $u\cdot u=-1$. A consumer assumes $(+,-,-,-)$ and checks only $|u\cdot u|=1$. Has the contract protected the calculation?

Solution

No. The absolute-value test is insensitive to the sign convention, so it can bless a semantic mismatch. The schema must carry the signature, the consumer must require the supported value or perform an explicit complete conversion, and the physical test must check the signed identity $u\cdot u=-1$ in the adopted convention. A second signed quantity—such as $\mathcal E=-u_t>0$ for the future-directed Schwarzschild orbit—provides an additional independent guard.

References

• Bureau International des Poids et Mesures. The International System of Units (SI). 9th ed., updated 2026. Sèvres: BIPM, 2026. DOI.
• HDF Group. “HDF5 Data Model and File Format Specification.” HDF5 Field Guide, current documentation, n.d. Data-model guide. File-format specification.
• International Virtual Observatory Alliance. Units in the VO, Version 1.1. IVOA Recommendation, 15 December 2023. Specification.
• JSON Schema. JSON Schema Core and Validation: Draft 2020-12. 2022. Core specification. Validation specification.