Skip to main content

Export & work with data

Obtaining results​

As a simulation is completed, the results can be downloaded into a directory of choice. A Results class exists to work with results and it has a wealth of functionalities which are explained in this section.

A simulation result can either be downloaded via the Simulation class or the results from all completed simulations in a single project can be downloaded from the Project class. When downloading results from a whole project, the files get written into subfolders called after the respective simulation ids.

By default result files get named after source ids, but by supplying a ResultsRenameRule, this can be changed to naming them by source labels.

# Download results from a single simulation
destination_directory = "result_directory"
results = simulation.download_results(destination_directory, rename_rule=treble.ResultRenameRule.by_label)

# Download all available results from a proejct
project.download_results(destination_directory, rename_rule=treble.ResultsRenameRule.by_label)

From version 2.1.13 of the SDK it is now also possible to get the results object from a local directory. This is handy if you are working with downloaded results on your local machine.

# Get results from local directory 
results = tsdk.get_results_object_from_results_directory('/my/results/dir')

The Results class​

An instance of the Results class can always be created by pointing to a directory with result files, so there is no need to redownload every time.

results = simulation.get_results_object(destination_directory)

The Results class includes methods to plot, export to files and to numpy arrays. To retrieve individual parts of the dataset, there are a few options.

Impulse responses​

Firstly, there are the impulse response retrievals, get_mono_ir() and get_spatial_ir(). The input to those methods are source and receiver which can either be labels, ids or elements of the lists accessed via simulation.sources and simulation.receivers

# Define source labels
receiver = "receiver_1"
source = "source_1"

# Works for all receivers
mono_ir: MonoIR = results.get_mono_ir(source=source, receiver=receiver)

# Works for spatial receivers
spatial_ir: SpatialIR = results.get_spatial_ir(source=source, receiver=receiver)

It's important to note that Impulse responses do not start at time zero. We apply zero padding at the beginning and end of the impulse responses to mitigate potential unphysical effects of acausal filtering when source-recevier distance is short. The IR classes include information on the zero padding, the time array and additionally include methods of retrieving the unpadded data and time. All IR classes contain methods to export data to numpy arrays or to wav files. When exporting to wav files, the impulse response get's normalized and trimmed to start from time zero by default.


# Mono impulse array:
mono_ir.data
# The associated time vector
mono_ir.time
# Sampling rate
mono_ir.sampling_rate
# Frequency response
mono_ir.frequency_response
# Associated frequency array
mono_ir.frequency

# Export to wav file
mono_ir.write_to_wav(path_to_file="mono_ir.wav")

# Normalization coefficient used to normalize wav export
mono_ir.normalization_coefficient

# Get unpadded array
data = mono_ir.unpadded_data()
time = mono_ir.unpadded_time()

Acoustic Parameters​

The acoustic parameters can be retrieved from the Results class instance by running


ap = results.get_acoustic_parameters(source=source, receiver=receiver)

where acoustic parameters can be accessed via the AcousticParameters dataclass. Each parameter comes as a list where each element in the list is either associated with an octave band or a noise criterion (only for STI). The respective octave band central frequencies.

Streaming results​

From the the SDK version 2.2.10 you can initialize a simulation result object without pre-downloading the whole result set. This can be done by not specifying a directory when getting the results object.

res = simulation.get_results_object()

You can force it to preload (download) the result set by doing

res = simulation.get_results_object(preload=True)

This will give you a 'lazy' results object that functions just like a 'normal' results object but will download/stream results data as you request it. It will download the results data to the SDK Cache so it can be resused between sessions.