treble_tsdk.results.results

Results management and acoustic parameter analysis.

Provides classes for loading, analyzing and visualizing simulation results including acoustic parameters, impulse responses, and result metadata.

Functions

get_results_object(simulation, results_directory)

Create a Results object for accessing simulation results.

Classes

AcousticParameters	Container for acoustic parameter measurements.
Results	Simulation results accessor with methods for retrieving impulse responses and acoustic parameters.

class treble_tsdk.results.results.AcousticParameters

Container for acoustic parameter measurements.

Stores frequency-dependent acoustic metrics including reverberation times, clarity, and SPL values.

__init__(edt: list[float] | None = None, t20: list[float] | None = None, t30: list[float] | None = None, c50: list[float] | None = None, c80: list[float] | None = None, d50: list[float] | None = None, ts: list[float] | None = None, g: list[float] | None = None, spl: list[float] | None = None, spl_a: list[float] | None = None, spl_c: list[float] | None = None, spl_z: list[float] | None = None, sti: list[float] | None = None, sti_using_spl: list[float] | None = None, mtf: list[float] | None = None, center_bands: list[float] | None = None, l_j: list[float] | None = None, l_j_avg: list[float] | None = None, j_lf: list[float] | None = None, **kwargs)

plot()

Open an interactive widget to visualize acoustic parameters.

static supported_parameters() → list[str]

List all supported acoustic parameter names.

Returns list[str]:

Names of available acoustic parameters.

class treble_tsdk.results.results.Results

Simulation results accessor with methods for retrieving impulse responses and acoustic parameters.

Provides lazy-loading access to simulation results including mono IRs, spatial IRs, and acoustic metrics.

__init__(simulation: Simulation, data_reader: DataReaderBase, result_type: ResultType = None)

A class which is designed to contain the results of a simulation.

Parameters:

• simulation (Simulation) – The relevant simulation object

• data_reader (DataReaderBase) – The data reader to read the results from

• result_type (ResultType | None) – The type of results to be used. If omitted, per-source simulation type overrides are still honored when reading source data.

get_acoustic_parameters(source: SourceDto | str, receiver: ReceiverDto | str) → AcousticParameters

Get acoustic result parameters for a particular source and receiver, if receiver is not given

Parameters:

• source (SourceDto) – A source associated with the simulation

• receiver (ReceiverDto | None) – A receiver associated with the simulation and source, defaults to None

Returns:

Acoustic parameters for the source and receiver. If device is true, the parameters for each microphone on the device are returned as a list of AcousticParameters.

get_device_ir(source: Source | str, device_owner: Receiver | Source | str, source_layer: Source | str | Sequence[Source | str] | None = None) → DeviceIR

Receive a device rendered impulse response object from the simulation for a specific source and device source or device receiver.

A device source (Source.make_device) is addressed as a whole: its source layers are summed into the impulse response of the device, unless source_layer selects one or some of them.

Parameters:

• source (Source | str) – A source associated with the simulation

• device_owner (Receiver | Source | str) – A device source or device receiver associated with the simulation and source

• source_layer – Source layer(s) of a device source to read: one layer by layer name, sub-source label/id or sub-source object, or a list of those to sum. When omitted all layers are summed.

Return DeviceIR:

A device IR object corresponding to the input specifications

get_device_source_ir(source: SourceDto | str, receiver: ReceiverDto | str | None = None, apply_device_filters: bool = True) → DeviceSourceIR

Get the impulse responses of a device source (Source.make_device) to one receiver, addressed per source layer of the device.

Parameters:

• source (SourceDto | str) – A device source associated with the simulation (parent or one of its layers).

• receiver (ReceiverDto | str) – The receiver to read results for. Defaults to the device’s own microphones (the device receiver created alongside the device source).

• apply_device_filters (bool) – Apply the filters the device prescribes for each source layer (DeviceObj.source_filters) and, for a device receiver, for each of its microphones (DeviceObj.mic_filters), as every other get_*_ir does. Set to False to get the unfiltered solver output of the layers.

Return DeviceSourceIR:

Per-layer accessor with get_ir(layer), sum() and convolve_with_audio_signal.

get_mono_ir(source: SourceDto | str, receiver: ReceiverDto | str, source_layer: SourceLayerSelector = None) → MonoIR

Receive a mono impulse response object from the simulation for a specific source and receiver

A device source (Source.make_device) is addressed as a whole: its source layers are summed into the impulse response of the device, unless source_layer selects one or some of them.

Parameters:

• source (SourceDto) – A source associated with the simulation

• receiver (ReceiverDto) – A receiver associated with the simulation and source

• source_layer – Source layer(s) of a device source to read: one layer by layer name, sub-source label/id or sub-source object, or a list of those to sum. When omitted all layers are summed.

Return MonoIR:

A MonoIR object corresponding to the input specifications

get_mono_irs_batch(source: SourceDto | str, receivers: list['ReceiverDto | str'], progress_callback=None, source_layer: SourceLayerSelector = None) → list[MonoIR | None]

Batch-read mono IRs for multiple receivers from the same source.

Opens the underlying H5 file once and reads all requested receiver datasets in a single pass — much faster than calling get_mono_ir() in a loop (which opens/closes the file per receiver). The IR data itself is cached on disk by the underlying reader.

Parameters:

• source – A source associated with the simulation

• receivers – List of receivers to read IRs for

• progress_callback – Optional object with an update(n) method (e.g. a tqdm bar) called once per receiver as it is loaded.

• source_layer – Source layer of a device source to read, see get_mono_ir. When omitted (or a list) the layers of a device source are summed per receiver.

Returns:

List of MonoIR objects (or None for receivers that failed)

get_moving_ir(source: SourceDto | str, receiver: ReceiverDto | str) → MovingIR

Receive a moving impulse response object from the simulation for a specific source and receiver.

get_source_receiver_device_ir(source: SourceDto | str) → SourceReceiverDeviceIR

Deprecated, use get_device_source_ir(source, receiver).

Deprecated

‘get_source_receiver_device_ir’ is deprecated, use ‘get_device_source_ir(source, receiver)’ instead.

Use Results.get_device_source_ir instead.

Parameters:

source (SourceDto | str) – A device source associated with the simulation

Return SourceReceiverDeviceIR:

An accessor for device IRs

get_source_result_metadata(source: SourceDto | str) → dict

Get the source result metadata for a source

get_spatial_ir(source: SourceDto | str, receiver: ReceiverDto | str, source_layer: SourceLayerSelector = None) → SpatialIR

Receive a spatial impulse response object from the simulation for a specific source and receiver. If receiver type was mono, will raise an exception

A device source (Source.make_device) is addressed as a whole: its source layers are summed into the impulse response of the device, unless source_layer selects one or some of them.

Parameters:

• source (SourceDto | str) – A source associated to the simulation.

• receiver (ReceiverDto | str) – A receiver associated to the simulation and source

• source_layer – Source layer(s) of a device source to read: one layer by layer name, sub-source label/id or sub-source object, or a list of those to sum. When omitted all layers are summed.

Return SpatialIR:

A spatial IR object corresponding to the input specifications

plot()

Open an interactive widget to visualize simulation results.

plot_acoustic_parameters()

Open an interactive widget to visualize acoustic parameters across multiple source-receiver pairs.

treble_tsdk.results.results.get_results_object(simulation: Simulation, results_directory: Path | str, result_type: ResultType = None) → Results | 'FreeFieldResults' | None

Create a Results object for accessing simulation results.

Parameters:

• simulation (Simulation) – Simulation object to load results for.

• results_directory (Path | str) – Local directory path or None for S3 lazy loading.

• result_type (ResultType) – Type of results to load, defaults to simulation type.

Returns Results | FreeFieldResults | None:

Results accessor object.