Simulations

Simulations are the core of the functionality of the SDK.

It is important to understand that Simulation objects represent the state of the simulation in Treble's systems, so changing properties such as name directly will not be saved.

Simulation class

Properties

Property	Type	Description	Example value
id	string	Unique identifier of simulation.	'380a3980-721a-4e80-95df-484f519c525c'
name	string	Name of simulation
description	string	Simulation description
status	string	Simulation status. See treble.SimulationStatus for available values.	"InProgress"
created_at	string		'2023-09-06 10:39:24'
updated_at	string		'2023-09-06 10:39:24'
receivers	List[ReceiverDto]	List of receivers in simulation.
sources	List[SourceDto]	List of sources in simulation.
type	SimulationType	Simulation type.	SimulationType.hybrid
crossover_frequency	int	Simulations set crossover frequency.	1500
layer_material_assignment	Dict[str, MaterialAssignmentDto]	Dictionary where the key is the model layer name and the value is info on the material assignement on said layer.

Methods

get_simulation_definition

Arguments

None

Returns

A SimulationDefinition object with the same settings as the current simulation.

Examples

# Simulation definition contains all information needed to create a identical simulation.
simulation_definition = simulation.get_simulation_definition()
assert simulation_definition.name == simulation.name

get_model

Get geometry object that is used by this simulation.

Arguments

None

Returns

ModelObj or GeometryLibraryObj object.

Examples

model = simulation.get_model()

estimate

Get total estimated runtime and total estimated cost in tokens for this simulation, as well as estimations for each of the simulaiton's sources. Note: For wave-based (DG) or Hybrid simulations the estimation can only be performed after the simulation geometry has been meshed. See wait_for_estimate

Arguments

None

Returns

SimulationEstimateDto

Examples

estimate = simulation.estimate()

# Print result code.
print(f"Result: {estimate.resultStatus.result_code_name} - {estimate.resultStatus.message}")

# Estimation can be visualized as a tree using the display_data module.
dd.as_tree(estimate)

wait_for_estimate

Waits until simulation preparation is finished and estimation can be made.

Arguments

Parameter	Type	Description	Example value
max_retries	int	Optional, Maximum number of seconds to wait for simulation estimates. Defaults to 200

Returns

SimulationEstimateDto

Examples

estimate = simulation.wait_for_estimate()

# Print result code.
print(f"Result: {estimate.resultStatus.result_code_name} - {estimate.resultStatus.message}")

# Estimation can be visualized as a tree using the display_data module.
dd.as_tree(estimate)

start

Start the simulation. Note: calling start() on a simulation that has aleady been started has no effect.

Arguments

None

Returns

bool True if simulation was successfully started, False otherwise.

get_progress

Get progress of the simulation. See also as_live_progress.

Arguments

None

Returns

SimulationProgressDto - Returns SimulationProgressDto object containing progress percentage for the simulation as well as progress for each of the simulation's source.

Examples

progress = simulation.get_progress()

# Display progress dto as a tree.
dd.as_tree(progress)

cancel

Cancels a started/queued simulation.

Arguments

None

Returns

CancelSimulationDto - Returns CancelSimulationDto containing a list of all the simulation's cancelled tasks.

Examples

res = simulation.cancel()

print(f"Result status: {res.resultStatus.result_code_name} - {res.resultStatus.message}")
print(f"Cancelled {len(res.cancelledTasks)} tasks.")
print(f"Simulation status is {res.simulationStatus}")

delete

Delete the simulation. If simulation is running it is cancelled before deletion.

Arguments

None

Returns

bool - True if simulation was deleted successfully, False otherwise.

Examples

simulation.delete()

get_tasks

Get the simulation's tasks.

Note: Tasks are not generated until simulation is started.

Arguments

None

Returns

List[SourceDto] - Returns a list of SourceDtos containing task list for source.

Examples

res = simulation.get_tasks()
# Print out task information.
for source in res:
    print(f'Source: {source.label}')
    for task in source.tasks:
        print(f" - {task.name} - {task.status}")

get_results_json

Get result urls and information.

Note: Result urls are signed and expire a few hours from being generated.

Arguments

Parameter	Type	Description	Example value
result_type	SimulationType	Optional filter for type of results to fetch "wave_based"	"geometrical"
include_subtasks	bool	Optional, if set to True subtasks are also included in the results package. This should be left as False unless you need something really specific.

Returns

List[SourceResultDto] - List of SourceResultDto objects.

Examples

res = simulation.get_results_json()

for data in res:
    print(f'Source: {data.sourceInfo.label}')
    for result in data.results:
        print(f' - {result.taskType}')
        print(f'    - Data url: {result.dataFileUrl}')
        print(f'    - Json url: {result.jsonFileUrl}')

get_mesh_info

Gets information on the mesh generated for simulation.

Will return None if the simulation type is GA since a mesh is not required.

Will also return None if the mesh generation is not completed.

Note: Urls are signed and expire a few hours from being generated.

Arguments

None

Returns

MeshInfoDto - Object containing mesh information.

Examples

mesh_info = simulation.get_mesh_info()

# Display mesh info
print(mesh_info)

download_results

Download results to a directory.

Note: This function downloads the simulated RIRs as .wav files. The RIRs are normalized before exporting them as .wav files to avoid clipping and excessive quantization noise. When simulating multiple sources, or running multiple simulations in the same environment, the normalization must be inverted before working with the RIRs. For this purpose, this function also downloads .json files, which include the entry "IR_normalization”. Multiplying the .wav RIRs with this value will undo the normalization. If you decide to work with the Result object instead of .wav files, the normalization is already applied automatically. However, the normalization can also be accessed via result_obj.get_mono_ir(…).normalization_coefficient.

Arguments

Parameter	Type	Description	Example value
destination_directory	string or Path	Directory to download results to.
result_type	`SimulationType`	Optional. What part of the result package to fetch, by default it will fetch results for all solvers.	treble.SimulationType.hybrid
rename_rule	`ResultRenameRule`	Optional. Tells the SDK to rename result files and directories from their original unique identifier names to source and receiver labels or positions.	treble.ResultRenameRule.by_label
data_filter	`ResultDataFilter`	Optional. Tolles to SDK to perform cleanup on the results and only leave the requested files. Defaults to only keeping IR signals.	treble.ResultDataFilter.ir
include_subtasks	bool	Optional, if set to True subtasks are also included in the results package. This should be left as False unless you need something really specific.

Returns

Results - A results object connected to the downloaded results. Can be used to plot and work further with results.

Examples

results_dir = '/path/to/download/results/to'

# Fetch results and rename package using source/receiver labels.
result = simulation.download_results(
    destination_directory=results_dir, 
    rename_rule=treble.ResultRenameRule.by_label
)
# Example of the structure of results_dir.
#├── My_source_DG
#│   ├── Receiver_1_DG_IR_RAW.wav
#│   └── Receiver_1_DG_IR_SC.wav
#├── My_source_DG.json
#├── My_source_GA
#│   └── Receiver_1_GA_IR.wav
#├── My_source_GA.json
#├── My_source_Hybrid
#│   └── Receiver_1_hybrid_IR.wav
#└── My_source_Hybrid.json

# Only fetch hybridized results, resulting in a smaller download size.
result = simulation.download_results(
    destination_directory=results_dir, 
    result_type=treble.SimulationType.hybrid,
    rename_rule=treble.ResultRenameRule.by_label
)
# Example of the structure of results_dir.
# ├── My_source_Hybrid
# │   └── Receiver_1_hybrid_IR.wav
# └── My_source_Hybrid.json

# Fetch results without renaming, uses source/receiver unique identifiers (Id). 
result = simulation.download_results(destination_directory=results_dir)
# Example of the structure of results_dir.
# ├── b1d7a0e7-4430-4e94-942d-dd0890c47e26_DG
# │   ├── 83eead28-dc16-4cc2-b173-c21d235a7a8f_DG_IR_RAW.wav
# │   └── 83eead28-dc16-4cc2-b173-c21d235a7a8f_DG_IR_SC.wav
# ├── b1d7a0e7-4430-4e94-942d-dd0890c47e26_DG.json
# ├── b1d7a0e7-4430-4e94-942d-dd0890c47e26_GA
# │   └── 83eead28-dc16-4cc2-b173-c21d235a7a8f_GA_IR.wav
# ├── b1d7a0e7-4430-4e94-942d-dd0890c47e26_GA.json
# ├── b1d7a0e7-4430-4e94-942d-dd0890c47e26_Hybrid
# │   └── 83eead28-dc16-4cc2-b173-c21d235a7a8f_hybrid_IR.wav
# └── b1d7a0e7-4430-4e94-942d-dd0890c47e26_Hybrid.json

# Fetch results and rename using source/receiver positions.
result = simulation.download_results(
    destination_directory=results_dir, 
    rename_rule=treble.ResultRenameRule.by_position
)
# Example of the structure of results_dir
# ├── 1.5-1.5-2_DG
# │   ├── 1-1-1_DG_IR_RAW.wav
# │   └── 1-1-1_DG_IR_SC.wav
# ├── 1.5-1.5-2_DG.json
# ├── 1.5-1.5-2_GA
# │   └── 1-1-1_GA_IR.wav
# ├── 1.5-1.5-2_GA.json
# ├── 1.5-1.5-2_Hybrid
# │   └── 1-1-1_hybrid_IR.wav
# └── 1.5-1.5-2_Hybrid.json

get_results_object

Create a results object for simulation results which have previously been downloaded to a results_directory (f.ex. using [download_results](#download_results)).

If directory does not exist or does not contain a result set, results will be downloaded to that directory.

Note: The directory provided must either contain a result set for the simulation or be an empty or non-existent directory.

Arguments

Parameter	Type	Description	Example value
results_directory	string or Path	Directory that contains simulation result set or directory to download results to.

Returns

Results - A results object connected to the downloaded results. Can be used to plot and work further with results.

Examples

# If given a directory with the results already present it will create a new results object using them.
res_dir = '/path/to/my/downloaded/results'
res_obj = simulation.get_results_object(res_dir)

# If given a non-existent directory it will try and create it and then download the simulation results to that directory.
res_dir = '/path/to/download/results/to'
res_obj = simulation.get_results_object(res_dir)

plot

Use the plot module to plot the simulation, plotting the model with sources and receivers.

Note: This function is a shortcut to the treble_tsdk.geometry.plot.plot_simulation function.

Arguments

Parameter	Type	Description	Example value
with_validation	bool	If true: simulation validation will be performed before plotting and the plot will include validation information.

Returns

Displays a PyVista plot window.

validate

Validate simulation.

Note: This function is a shortcut to the treble_tsdk.geometry.validation.validate_simulation function.

Arguments

None

Returns

[SimulationValidationResults](#simulationvalidationresults-class) object.

Examples

# Perform validation
res = simulation.validate()

# View results as tree.
res.as_tree()

calculate_sabine_estimate

Calculate Sabine estimate for the simulation.

Arguments

None

Returns

List[float] - List of the sabine estimated reverberation time for each frequency range valid for materials (63, 125, 250, 500, 1k, 2k, 4k, 8k).

as_tree

Uses the display_data module to display simulation information as tree.

Arguments

None

Returns

Nothing

as_table

Uses the display_data module to display simulation information as table.

Arguments

None

Returns

Nothing

as_live_progress

Uses the display_data module to show simulation progress. Automatically updated/refreshed until simulation finished.

Arguments

None

Returns

Nothing

SimulationValidationResults class

The class represents validation results of a simulation.

Properties

Property	Type	Description	Example value
simulation_id	string	Unique identifier of simulation.	'380a3980-721a-4e80-95df-484f519c525c'
simulation_name	string	Name of simulation
invalid_receivers	`List[[ReceiverDto](dtos/#receiverdto)]]`	List of invalid receivers.
invalid_sources	`List[[SourceDto](dtos/#sourcedto)]]`	List of invalid sources.
layers_without_materials	`List[str]`	List of layer names that are missing material assignment.
invalid_settings	string	List of invalid settings properties.
error_message	string	Error message.
is_valid	boolean	Indicates if simulation was deemed valid or not..

Methods

as_tree

Displays validation results as a tree in console.

Note: Shortcut to treble_tsdk.display_data.as_tree function.

SimulationDefinition class

The SimulationDefinition class contains all information required to create a new simulation in Treble's systems. It can be thought of as a blueprint of a simulation.

Properties

Property	Type	Description
name	string	Name of simulation
simulation_type	SimulationType	Type of simulation: dg, ga or hybrid.
model	string or ModelDto or ModelObj or GeometryLibraryObj	Model to be used by simulation.
crossover_frequency	int	Crossover frequency from DG to GA.
receiver_list	List[Receiver]	List of Receiver objects.
source_list	List[Source]	List of Source objects.
material_assignment	List[MaterialAssignment]	List of material assignment objects.
ir_length	float	Impulse response length in sec.
energy_decay_threshold	float	Optional. Energy decay threshold in dB
simulation_settings	SimulationSettings	Optional. Advanced simulation settings.
on_task_error	SimulationOnTaskError	Optional. On task error behaviour, defaults to "ignore".
description	string	Optional. Description of simulation.
gpu_allocation_strategy	GpuAllocationStrategy	Sets the strategy to use when deciding on how may GPUs to use for the wave-solver tasks in simulation.

Methods

plot

Use the plot module to plot the simulation, plotting the model with sources and receivers.

Note: This function is a shortcut to the treble_tsdk.geometry.plot.plot_simulation function.

Arguments

Parameter	Type	Description	Example value
with_validation	bool	If true: simulation validation will be performed before plotting and the plot will include validation information.

Returns

Displays a PyVista plot window.

validate

Validate simulation.

Note: This function is a shortcut to the treble_tsdk.geometry.validation.validate_simulation function.

Arguments

None

Returns

[SimulationValidationResults](#simulationvalidationresults) object.

Examples

# Example of creating a SimulationDefinition object.
sim_def = treble.SimulationDefinition(
    name="My L-shaped room",
    simulation_type=treble.SimulationType.hybrid,
    model=my_model,
    crossover_frequency=300,
    ir_length=0.1,
    receiver_list=[treble.Receiver(1,1,1, treble.ReceiverType.mono, "Receiver_1")],
    source_list=[treble.Source(1.5, 1.5, 2, treble.SourceType.omni, "My_source")],
    material_assignment=[treble.MaterialAssignment(layer_name, my_material) for layer_name in my_model.layer_names]
)

Source class

Represents a Simulation source.

Properties

Property	Type	Description
x	float	Position of source along the X-axis.
y	float	Position of source along the Y-axis.
z	float	Position of source along the Z-axis.
source_type	`SourceType`	Type of source.
label	string	Source label.
source_properties	`[SourceProperties](#sourceproperties)`	Optional, additional source properties.

Examples

# Create a basic omni source
source = treble.Source(
    x = 1,
    y = 2,
    z = 3,
    source_type=treble.SourceType.omni,
    label="My omni source"
)

# Create a directive source
directive_source = treble.Source(
    x = 1,
    y = 2,
    z = 3,
    source_type=treble.SourceType.directive,
    label="my_directive_source",
    source_properties=treble.SourceProperties(
        azimuth_angle=10,
        elevation_angle=20,
        source_directivity=my_directivity
    )
)

SourceProperties class

Additional source properties.

Properties

Property	Type	Description
azimuth_angle	float	Azimuth rotation angle of source.
elevation_angle	float	Elevation rotation angle of source.
source_directivity	string or SourceDirectivityObj	If the source type is Directive this parameter specifies the source directivity. This can either be the Unique identifier of the directivity or the directivity object itself.

Receiver

Represents a simulation Receiver.

Properties

Property	Type	Description
x	float	Position of receiver along the X-axis.
y	float	Position of receiver along the Y-axis.
z	float	Position of receiver along the Z-axis.
source_type	`ReceiverType`	Type of receiver.
label	string	Receiver label.
receiver_properties	`[ReceiverProperties](#receiverproperties)`	Optional, additional receiver properties used for defining the device related transfer function (DRTF).

Examples

# Basic mono receiver.
receiver = treble.Receiver(
    x = 1,
    y = 2,
    z = 3,
    source_type=treble.ReceiverType.mono,
    label="my_mono_receiver"
)

# Example device receiver
device_receiver = treble.Receiver(
    x = 1,
    y = 2,
    z = 3,
    source_type=treble.ReceiverType.device,
    label="my_mono_receiver",
    receiver_properties=treble.ReceiverProperties(
        device = my_device,
        azimuth_angle=10,
        elevation_angle=20,
        roll_angle=30
    )
)

ReceiverProperties class

Additional receiver properties further defining either spatial or device type receivers. For spatial receivers the only used parameter is the ambisonics_sphere_radius_in_m

For device receivers, all the parameters are used but only the device one is a mandatory input. When the receiver type is device, the receiver properties define the device related transfer function (DRTF) of the device as well as its orientation in the room. The orientation angles are defined as azimuth, elevation and roll and they represent the intrinsic rotation of the device around the Z axis, X' axis and Y'' axis, respectively. Intrinsic means that the coordinate system rotates with the applied rotation and the rotation is applied: 1. Azimuth, 2. Elevation, 3. Roll

Properties

Property	Type	Description	Example value
device	`DeviceObj` or `DeviceDto`	Device object which contains its DRTF already preprocessed from a .sofa file. Mandatory when ReceiverType == device, defaults to None
azimuth_angle	float	Azimuth rotation angle of receiver.	Azimuth rotation angle (counter-clockwise around Z axis) for device receivers. From 0° to 360°, defaults to 0
elevation_angle	float	Elevation rotation angle (counter-clockwise around X' axis) for device receivers. From -90° to 90°, defaults to 0.
roll_angle	float	Roll rotation angle (counter-clockwise around Y'' axis) for device receivers. From 0° to 360°, defaults to 0.
ambisonics_sphere_radius_in_m	float	Optional. The radius in m of the sphere where receiver array will be generated on. From 0.05 to 0.15, defaults to 0.1
ambisonics_order	int	Optional. Ambisonics order of spatial and device receivers, allowed values are 1, 2, 4, 8 and 16. Note: this value overwrites ambisonics order set on simulation level (using SimulationSettings) for this specific receiver

SimulationSettings class

Property	Type	Description
speed_of_sound	float	Optional. SpeedOfSound (m/s) in medium.
ga_settings	GaSolverSettings	Optional. Advanced settings for the geometrical acoustics solver. (GA)
dg_settings	DgSolverSettings	Optional. Advanced settings for the wave-based solver (DG).
ambisonics_order	float	Optional. Sets ambisonics order for spatial receivers in simulation, allowed values: 1, 2, 4, 8, 16. Note: if ambisonics order is set on specific receiver (using ReceiverProperties) then that value overrides this ambisonics order for that specific receiever

DgSolverSettings class

There are currently no advanced settings exposed for the wave-based solver.

GaSolverSettings class

Property	Type	Description
number_of_rays	int	Optional. Number of rays to use in the raytracing part of the simulation. Defaults to 5000.
ism_order	int	Optional. Image source method order to use. Defaults to 2.
air_absorption	bool	Optional. Toggles the inclusion of air absorption in the solver.
ism_ray_count	int	Optional. How many rays are used in the image source pre-visibility check, accepted range is between 1000 and 5000000
write_out_ism_raypaths	bool	Optional. Save raypaths and pressure_per_reflection from ism. Note: this is an advanced setting and may cause the result set to become very large. Default False.

Simulations

Simulation class​

Properties​

Methods​

get_simulation_definition​

get_model​

estimate​

wait_for_estimate​

start​

get_progress​

cancel​

delete​

get_tasks​

get_results_json​

get_mesh_info​

download_results​

get_results_object​

plot​

validate​

calculate_sabine_estimate​

as_tree​

as_table​

as_live_progress​

SimulationValidationResults class​

Properties​

Methods​

as_tree​

SimulationDefinition class​

Properties​

Methods​

plot​

validate​

Examples​

Source class​

Properties​

Examples​

SourceProperties class​

Properties​

Receiver​

Properties​

Examples​

ReceiverProperties class​

Properties​

SimulationSettings class​

DgSolverSettings class​

GaSolverSettings class​

Simulation class

Properties

Methods

get_simulation_definition

get_model

estimate

wait_for_estimate

start

get_progress

cancel

delete

get_tasks

get_results_json

get_mesh_info

download_results

get_results_object

plot

validate

calculate_sabine_estimate

as_tree

as_table

as_live_progress

SimulationValidationResults class

Properties

Methods

as_tree

SimulationDefinition class

Properties

Methods

plot

validate

Examples

Source class

Properties

Examples

SourceProperties class

Properties

Receiver

Properties

Examples

ReceiverProperties class

Properties

SimulationSettings class

DgSolverSettings class

GaSolverSettings class