I/O¶

On-disk RF storage and interchange. RFDataset is the internal, crash-safe checkpoint format (one compressed .npz per TX event); save_rf_hdf5 exports a self-describing, UFF/MATLAB-compatible HDF5 file.

RFDataset¶

RFDataset ¶

RFDataset(
    path,
    config: dict | None = None,
    *,
    meta: dict | None = None,
)

Resumable folder of per-event RF files with a JSON contents file.

Parameters:

Name	Type	Description	Default
`path`	`str or Path`	Dataset folder. Created if missing.	required
`config`	`dict`	Configuration identifying the simulation (see `config_fingerprint`). Required when creating a new dataset. When opening an existing one, it is compared against the stored fingerprint: any difference raises `ValueError` listing the changed keys. `None` opens read-only without checking (loading data for beamforming).	`None`
`meta`	`dict`	Free-form JSON-serializable info stored once at creation (e.g. `{"n_events": 18, "fs": 1e8, "note": "..."}`).	`None`

Raises:

Type	Description
`ValueError`	If `config` differs from the fingerprint stored in an existing contents file, or if a new dataset is created without `config`.

write_event ¶

write_event(
    idx: int, rf, t0: float, dt: float, **info
) -> None

Atomically store one TX event's RF and mark it completed.

Parameters:

Name	Type	Description	Default
`idx`	`int`	TX event index in the sequence.	required
`rf`	`(Erx, Nt) numpy.ndarray`	Per-receive-channel RF of this event.	required
`t0`	`float`	Beam-axis time reference of this event (s), as returned by the reception simulator: echoes peak at their geometric round-trip time.	required
`dt`	`float`	Sample period (s).	required
`**info`		Extra JSON-serializable fields recorded in the contents file (e.g. `duration_s=12.3`).	`{}`

read_event ¶

read_event(idx: int, *, verify: bool = False)

Load one event's RF.

Parameters:

Name	Type	Description	Default
`idx`	`int`	TX event index.	required
`verify`	`bool`	Re-hash the file and compare with the contents file checksum.	`False`

Returns:

Name	Type	Description
`rf`	`(Erx, Nt) numpy.ndarray`	Per-receive-channel RF of the event.
`t0`	`float`	Beam-axis time origin of the first sample (s).
`dt`	`float`	Sample period (s).

Raises:

Type	Description
`KeyError`	If the event is not in the contents file.
`ValueError`	If `verify` is True and the checksum does not match.

load_all ¶

load_all()

Assemble all completed events into the sequence_rf return format.

Traces are zero-padded at the end to the longest event (only the time origin differs between events; dt is shared).

When the dataset was written with checkpoint_chunks > 1 (each TX event split into scatterer chunks, one file per chunk), the chunk RFs of each event share one time grid and are summed here — the RF is linear in the scatterers, so the sum equals the unchunked event.

Returns:

Name	Type	Description
`rf`	`(N_events, Erx, Nt) numpy.ndarray`	Per-event, per-channel RF (float32).
`coords`	`dict`	`"t0"`/`"dt"` of the first event plus `"t0_per_event"` and, when recorded at write time, the `"pulse_center_lag_s"` two-way pulse lag (already removed from `t0`; carried for provenance).

Raises:

Type	Description
`ValueError`	If the dataset has no completed events, or if it is chunked and not yet complete (partial chunk groups cannot be summed).

to_hdf5 ¶

to_hdf5(
    path,
    *,
    probe_geometry_mm=None,
    sound_speed: float = 1540.0,
)

Export the whole dataset to one interchange HDF5 file.

Consolidates the per-event .npz checkpoint store into a single self-describing .h5 (channel data + timing) that MATLAB, USTB and other Python tools read natively — see save_rf_hdf5.

Parameters:

Name	Type	Description	Default
`path`	`str or Path`	Output `.h5` file.	required
`probe_geometry_mm`	`(Erx, 3) numpy.ndarray`	Receive-element centres in mm, stored so the file is beamformable on its own.	`None`
`sound_speed`	`float`	Speed of sound (m/s) recorded in the file.	`1540.0`

Returns:

Type	Description
`Path`	The written file path.

summary ¶

summary() -> str

Human-readable status table (also returned as a string).

Returns:

Type	Description
`str`	The status table text (printed and returned).

save_rf_hdf5¶

save_rf_hdf5 ¶

save_rf_hdf5(
    path,
    rf: NDArray[floating],
    coords: dict,
    *,
    probe_geometry_mm: NDArray[floating] | None = None,
    sound_speed: float = 1540.0,
    meta: dict | None = None,
) -> Path

Write per-channel RF and its timing to a single HDF5 file.

Parameters:

Name	Type	Description	Default
`path`	`str or Path`	Output `.h5` file (created/overwritten).	required
`rf`	`(N_events, Erx, Nt) or (Erx, Nt) numpy.ndarray`	Per-event, per-receive-channel RF, as returned by `sequence_rf` (3-D) or `pulse_echo_rf` (2-D). A 2-D array is stored as a one-event acquisition.	required
`coords`	`dict`	Timing from the reception simulator / `RFDataset.load_all`: `"dt"` (sample period, s), `"t0"` (first-sample time, s), optionally `"t0_per_event"` (s) and `"pulse_center_lag_s"` (the two-way pulse lag, already removed from `t0`; stored for provenance).	required
`probe_geometry_mm`	`(Erx, 3) numpy.ndarray`	Receive-element centres in mm (`rx.element_centers * 1e3`), stored so the file is beamformable on its own. Omitted if `None`.	`None`
`sound_speed`	`float`	Speed of sound (m/s), stored as the `sound_speed` attribute.	`1540.0`
`meta`	`dict`	Any extra JSON-serializable acquisition info; stored as a JSON string in the `meta` attribute (e.g. probe name, sequence description).	`None`

Returns:

Type	Description
`Path`	The written file path.