Compose records from open fields and axes

A Record has a producer-supplied identity, optional scene identity, named Field values, and open JSON metadata. Every field contains one NumPy array and one ordered axis per dimension.

Coordinates may be explicit values, a linear start/step rule, or a reference to another field or shared axis ID. Shared IDs let several fields declare the same logical axis and coordinate. Synchronization, clock identity, phase coherence, and reference-plane semantics require explicit producer metadata; structural validation does not infer them.

Supported dtypes are Boolean, signed and unsigned integers, float16, float32, float64, and native complex64. Convert complex128 explicitly to complex64; encode strings and heterogeneous objects in JSON metadata rather than object arrays.

import numpy as np
import signal_dataset as sds

sample_rate_hz = 20_000_000
samples = np.zeros((4, 4096), dtype=np.complex64)   # 4 receivers, 4096 samples each

record = sds.Record(
    id="array-007",
    scene_id="site-a",
    fields={
        "samples": sds.Field(
            samples,
            axes=(
                sds.Axis("receiver", samples.shape[0]),
                sds.Axis(
                    "time",
                    samples.shape[1],
                    coordinate=sds.Coordinate(start=0, step=1 / sample_rate_hz, unit="s"),
                ),
            ),
            metadata={"unit": "normalized_amplitude"},
        )
    },
    metadata={"sample_rate_hz": sample_rate_hz},
)

Names such as samples, receiver, and sample_rate_hz are producer-defined, not reserved.