treble_tsdk.core.simulation

Simulation definitions, settings and lifecycle utilities.

Contains types to define simulations, configure solvers and mesher, submit jobs and track status/progress.

Classes

`CancelSimulationResult`	Result of a simulation cancellation request.
`DgSolverSettings`	Settings for the discontinuous Galerkin (DG) solver.
`GaSolverSettings`	Settings for the geometrical acoustics (GA) solver.
`GaSolverType`	Available solver types.
`GpuAllocationStrategy`	GPU allocation strategies for simulations.
`MesherSettings`	Mesher settings.
`ResultDataFilter`	Available filters for results
`ResultRenameRule`	Rename rules for results.
`ResultType`	Available result types.
`Simulation`	The Simulation class is used to work with a simulation which has already been added to the project.
`SimulationBasicInfo`	Basic information about a simulation.
`SimulationCategory`	Available simulation categories.
`SimulationDefinition`	Complete definition of a simulation configuration.
`SimulationEstimate`	Cost and runtime estimates for a simulation.
`SimulationOnTaskError`	Available Simulation "on task error" behaviours.
`SimulationProgressInfo`	Progress information for a running simulation.
`SimulationSettings`	Advanced simulation settings.
`SimulationStatus`	Available simulation status values.
`SimulationTokenCost`	Detailed token cost breakdown for a completed simulation.
`SimulationType`	Available simulation types.
`SolveTaskStatus`	Available solve task status values.

class treble_tsdk.core.simulation.CancelSimulationResult

Result of a simulation cancellation request.

Contains status information and list of cancelled tasks.

__init__(dto: CancelSimulationDto)

as_tree(): Display cancellation result as a tree structure.

property cancelled_tasks: list[CancelTaskDto]: List of tasks that were cancelled.

property result_status: ResultStatusDto

Result status of the cancellation request.

Returns ResultStatusDto:: Status of the cancellation operation.

property simulation_id: str

property simulation_name: str

property simulation_status: SimulationStatus: Current status of the simulation after cancellation.

class treble_tsdk.core.simulation.DgSolverSettings

Settings for the discontinuous Galerkin (DG) solver.

Currently no custom settings are exposed for the DG solver.

__init__()

class treble_tsdk.core.simulation.GaSolverSettings

Settings for the geometrical acoustics (GA) solver.

Configures ray tracing parameters including ray count, image source method order, and air absorption.

__init__(number_of_rays: int = 100000, ism_order: int = 2, air_absorption: bool = True, ism_ray_count: int = 500000, solver_type: GaSolverType = GaSolverType.ray_radiosity)

Custom settings for the geometrical acoustics (GA) solver.

Parameters:

number_of_rays (int) – Number of rays to use in GA. defaults to 100_000
ism_order (int) – Image source method order to use in GA. defaults to 2
air_absorption (bool) – Whether to include air absorption in GA simulation, defaults to True
ism_ray_count (int) – How many rays are used in the image source pre-visibility check, accepted range is between 1000 and 5_000_000
write_out_ism_raypaths (bool) – Save raypaths and pressure_per_reflection from ism
solver_type (GaSolverType) – Type of GA solver

property air_absorption: bool

Whether air absorption is enabled.

Returns bool:: True if air absorption is active.

property ism_order: int

Image source method order.

Returns int:: ISM order.

property ism_ray_count: int

Number of rays for image source method.

Returns int:: ISM ray count.

property number_of_rays: int

class treble_tsdk.core.simulation.GpuAllocationStrategy

GPU allocation strategies for simulations.

Controls how GPU resources are allocated for a simulation.

default = 'default'

gpu_count_optimized = 'gpuCountOptimized'

utilization_optimized = 'utilizationOptimized'

class treble_tsdk.core.simulation.MesherSettings

Mesher settings.

Controls mesh generation and simplification behavior.

__init__(simplify_mesh: bool = True)

class treble_tsdk.core.simulation.ResultDataFilter

Available filters for results

ir = 'ir'

none = 'none'

class treble_tsdk.core.simulation.ResultRenameRule

Rename rules for results.

by_label = 'by_label'

lazy_structure = 'lazy_structure'

none = 'none'

class treble_tsdk.core.simulation.ResultType

Available result types.

device_rendering = 'DeviceRendering'

dg = 'DG'

ga = 'GA'

geometrical = 'GA'

hybrid = 'Hybrid'

wave_based = 'DG'

class treble_tsdk.core.simulation.Simulation

The Simulation class is used to work with a simulation which has already been added to the project.

__init__(dto: SimulationDto, project_id: str, client: TSDKClient, model_obj: ModelObj | None = None)

add_receiver_tags(receiver: str | Receiver, tags: list[str] | str) → bool: Add tags to the receiver.

add_source_tags(source: str | Source, tags: list[str] | str) → bool: Add tags to the source.

add_tags(tags: list[str] | str) → bool: Add tags to the simulation.

as_live_progress(): Uses the display_data module to show simulation progress automatically updated until simulation finished.

as_table(): Uses the display_data module to display simulation information as table.

as_tree(): Uses the display_data module to display simulation information as tree.

calculate_sabine_estimate() → list[float]

Calculate Sabine estimate for the simulation

Returns list[float]:: List of the sabine estimated RT for each frequency range valid for materials (63, 125, 250, 500, 1k, 2k, 4k, 8k).

cancel() → CancelSimulationResult

delete() → bool

download_mesh(download_dir: Path | str) → bool

Downloads the mesh files for the simulation to the specified download_dir. Will return False if the simulation type is GA since a mesh is not required.

Returns bool:: True if mesh files were downloaded, False otherwise.

download_results(destination_directory: str | Path, result_type: ResultType = None, rename_rule: ResultRenameRule = ResultRenameRule.none, output_mode: utils.ProgressOutputMode = ProgressOutputMode.TQDM_OUTPUT, progress_leave: bool = True, return_none: bool = False) → 'Results' | None

Download results to a directory.

Parameters:

destination_directory (str | Path) – Directory to download the results to.
result_type (SimulationType) – Optional, if provided will only download results for the specific task type.
rename_rule (ResultRenameRule) – Optional, if provided the result files will be renamed according to the rule given. If rename_rule.by_label is provided, the folder structure will be source_label/receiver_label_...wav and source_label_task_type.json; labels must be valid file/directory names or files will not be renamed.
data_filter (ResultDataFilter) – Optional, if provided it can be used to remove result files the user is not interested in (e.g., to keep only IRs).
output_mode (utils.ProgressOutputMode) – Optional, can be used to set how download progress reporting is handled, defaults to TQDM progress bars.
progress_leave (bool) – If set to False it will remove the TQDM progress bar upon completion.
return_none (bool) – If set to True it will return None and not try and load the downloaded results into a results object.

estimate() → SimulationEstimate

Get total estimated runtime and total cost in tokens for this simulation, as well as estimations for each of the simulaiton’s sources.

Returns SimulationEstimate:: Returns SimulationEstimate object

get_mesh_info() → SimulationMeshInfoCollection | None

Gets information on the meshes generated for simulation. Returns the simulation mesh and additional source meshes, note: if a source does not require special meshing then it will use the simulation mesh. Will return None if the simulation type is GA since a mesh is not required.

Returns SimulationMeshInfoCollection | None:: None if simulation type is GA.

get_model() → ModelObj | GeometryLibraryObj

Get the ModelObj associated to this simulation.

Returns ModelObj:: Returns ModelObj object.

get_progress() → SimulationProgressInfo

Get progress of the simulation.

Returns SimulationProgressInfo:: Returns SimulationProgressInfo object containing progress percentage for the simulation as well as progress for each of the simulation’s source.

Create a results object for simulation results which have been downloaded to a results_directory. If directory does not exist, results will be downloaded to that directory

Parameters:: results_directory (str | Path) – Optional, Path to results directory. If results have already been downloaded to this directory a results object based on that directory will be created. If directory is empty then results will be downloaded to that directory. If not provided the results will be downloaded and cached on a per IR basis when required.
Return Results | FreeFieldResults | None:: The respective results object

get_simulation_definition(name_override: str | None = None) → SimulationDefinition: Returns a SimulationDefinition object with the same specifications as this Simulation object. The simulation definition object can then be used to create/clone a simulation with identical settings.

get_tasks() → list[Source]

Get the simulation’s tasks grouped by source.

Returns list[Source]:: Returns a list of Source objects containing task list for source.

get_token_cost() → SimulationTokenCost: Get the token cost for the simulation.

get_tokens_used() → float | list[float, float] | None

Gets the total amount of tokens used for the simulation.

Returns float | None:: Total amount of tokens used for the simulation. Returns None if simulation is not completed.

plot(with_validation: bool = True, view_2d: View2d | None = None, disable_labels: bool = False, _debug: DebugOptions = {})

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

Parameters:

with_validation – Show validation results. Optional, defaults to true.
view_2d – Show a 2d view, choose between None, View2d.xy, View2d.xz, View2d.yz. Optional, defaults to false.
disable_labels – Disables source and receiver labels. Optional, defaults to false.

remove_receiver_tags(receiver: str | Receiver, tags: list[str] | str) → bool: Remove tags from the receiver.

remove_source_tags(source: str | Source, tags: list[str] | str) → bool: Remove tags from the source.

remove_tags(tags: list[str] | str) → bool: Remove tags from the simulation.

rename(simulation_name: str) → bool

Update the simulation name.

Parameters:: simulation_name (str) – Value of the updated name of the simulation.

set_gpu_count(gpu_count: int) → bool

Update the GPU count for the simulation. Note that this sets the gpu count for each wave-based solve task in the simulation.

Parameters:: gpu_count (int) – Number of GPUS to allocate for each wave-solver task in the simulation.

start(skip_prompt: bool = False) → bool

Start the simulation.

Parameters:: skip_prompt (bool) – If True, automatically confirms without prompting. Useful for notebooks where you want to see the cost first.

update_tags_from_server() → bool: Get tags for the simulation, sources and receivers from the server, note that this will overwrite any unsaved local changes to tags.

validate(): Validate simulation. Validates source/receiver positions. Receivers should be inside model and be placed 0.15m from any surface. Sources should be inside model and placed 0.25m from any surface. All layers should have materials assigned to them.

wait_for_estimate(max_retries=200) → SimulationEstimate

Wait for simulation estimate and then return it.

Parameters:: max_retries (int) – Maximum retries for getting simulation estimate.
Returns SimulationEstimate:: Returns SimulationEstimate object either if estimate is ready or if max_retries seconds have elapsed.

wait_for_token_cost(max_retries=200) → SimulationTokenCost: Wait for token cost to be available and then return it.

write_simulation_info_to_json(destination_file: str | Path)

Writes simulation info as a json string to a file.

Parameters:: destination_file (str) – Path to file to write json data to f.ex. /my/path/simulation_info.json.

property created_at: str

property crossover_frequency: int

property description: str

property id: str

property ir_length: float

property layer_material_assignment: dict[str, MaterialAssignment]: Returns a dictionary where layer name is the key and MaterialAssignmentDto is the value.

property local_mesh_sizing: dict[str, LocalMeshSizing]: Returns a dictionary where layer name is the key and LocalMeshSizingDto is the value.

property mesher_settings: MesherSettings | None

property name: str

property receivers: list[Receiver]

property simulation_settings: SimulationSettings | None

Advanced simulation settings including solver configurations.

Returns SimulationSettings | None:: Simulation settings or None if not set.

property sources: list[Source]

property status: str

property tags: list[str]

property type: SimulationType

property updated_at: str

class treble_tsdk.core.simulation.SimulationBasicInfo

Basic information about a simulation.

Contains core metadata including ID, name, type, and status.

__init__(dto: SimulationDto)

class treble_tsdk.core.simulation.SimulationCategory

Available simulation categories.

classmethod list()

classmethod print()

default = 'Default'

free_field = 'FreeField'

class treble_tsdk.core.simulation.SimulationDefinition

Complete definition of a simulation configuration.

Encapsulates all parameters needed to create and run an acoustic simulation including model, sources, receivers, and solver settings.

__init__(name: str, simulation_type: SimulationType, model: ModelDto | ModelObj | GeometryLibraryObj, receiver_list: list[Receiver], source_list: list[Source], material_assignment: list[MaterialAssignment], crossover_frequency: int | None = None, ir_length: float | None = None, energy_decay_threshold: float | None = None, simulation_settings: SimulationSettings = {'ambisonicsOrder': 2, 'speedOfSound': 343.0}, on_task_error: SimulationOnTaskError = 'StopSimulation', description: str | None = None, local_mesh_sizing: list[LocalMeshSizing] | None = None, mesher_settings: MesherSettings | None = None, metadata: dict[str, str] | ObjectMetadataDto | ObjectMetadata | None = None, tags: list[str] = [])

Define simulation information that can be used to create a Simulation object later on.

Parameters:

name (str) – Name of simulation
simulation_type (SimulationType) – Type of simulation: dg, ga or hybrid.
model (str|ModelDto|ModelObj|GeometryLibraryObj) – Model to be used by simulation. Can either be model id, ModelDto, ModelObj or GeometryLibraryObj.
crossover_frequency (int) – Crossover frequency from DG to GA.
ir_length (float) – Impulse response length in sec.
receiver_list (list[Receiver|dict]) – List of Receiver objects.
source_list (list[Source|dict]) – List of Source objects.
material_assignment (list[MaterialAssignment|dict]) – List of material assignment objects.
energy_decay_threshold (float) – Energy decay threshold in dB
simulation_settings (SimulationSettings) – Optional custom simulation settings.
on_task_error (SimulationOnTaskError) – Optional on task error behaviour. Defaults to “ignore”.
description (str) – Optional description of simulation.
local_mesh_sizing (list[LocalMeshSizing]) – List of local mesh sizing object, used to control the mesh quality of individual elements in a simulation. Can be applied to any number of layers in a simulation.

plot(with_validation=True, project=None, view_2d: View2d | None = None, disable_labels: bool = False, _debug: DebugOptions = {})

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

Parameters:

with_validation (bool) – Show validation results. Optional, defaults to true.
project (Project) – Optional, only required if the “model” property of the simulation is a string containing the model id.
view_2d – Show a 2d view, choose between None, View2d.xy, View2d.xz, View2d.yz. Optional, defaults to false.
disable_labels – Disables source and receiver labels. Optional, defaults to false.

remove_invalid_receivers(): Performs validation and removes receivers that are invalid

remove_invalid_sources(): Performs validation and removes sources that are invalid

validate(project=None)

Validate simulation. Validates source/receiver positions. Receivers should be inside model and be placed 0.15m from any surface. Sources should be inside model and placed 0.25m from any surface. All layers should have materials assigned to them.

Parameters:: project (Project) – Optional, only required if the “model” property of the simulation is a string containing the model id.

class treble_tsdk.core.simulation.SimulationEstimate

Cost and runtime estimates for a simulation.

Provides token cost and runtime estimates per source.

__init__(dto: SimulationEstimateDto)

as_tree(): Uses the display_data module to display estimate information as tree.

property estimate_per_source: list[SourceEstimate]

property result_status: ResultStatusDto

property simulation_id: str

property simulation_name: str

property simulation_status: str

property supported_gpu_counts: GpuCountRangeDto | None

Supported GPU count range for the simulation.

Returns GpuCountRangeDto | None:: GPU count range, or None if not available.

property total_cost_in_tokens: float

property total_estimated_cost_in_tokens: float

property total_estimated_runtime_hours: float

class treble_tsdk.core.simulation.SimulationOnTaskError

Available Simulation “on task error” behaviours.

ignore = 'Ignore'

stop_project = 'StopProject'

stop_simulation = 'StopSimulation'

class treble_tsdk.core.simulation.SimulationProgressInfo

Progress information for a running simulation.

Provides real-time status updates including completion percentage and source-level progress.

__init__(dto: SimulationProgressDto, client: TSDKClient)

as_tree(): Uses the display_data module to display material info as tree.

property project_id: str

property project_name: str

property simulation_id: str

property simulation_name: str

property simulation_progress_percentage: float

property simulation_status: str

property sources: list[Source]

class treble_tsdk.core.simulation.SimulationSettings

Advanced simulation settings.

Configures solver-specific settings, speed of sound, GPU allocation, and other simulation parameters.

Advanced simulation settings.

Parameters:

speed_of_sound (float) – SpeedOfSound (m/s) in medium.
ga_settings (GaSolverSettings) – Settings specific to the GA solver.
dg_settings (DgSolverSettings) – Settings sepcific to the DG solver.
ambisonics_order – Spatial receivers ambisonics order, allowed values: 1 <= order <= 32. This value can be overwritten on a receiver level.
gpu_count (int) – Sets the number of GPUs to allocate for each wave-solver task in the simulation.
free_field_removal_max_distance (float) – If a nonzero value is given, the free field response / direct sound is removed from the response within the given distance. In GA solver, the direct sound is simply skipped in the image source method response, but in the DG solver the analytical free field response of the source is subtracted from the signal in postprocessing. This distance should always be set lower than the minimum distance to any obstructing objects in the space. This is not validated in the simulation, so use with caution!

property ambisonics_order: int | None: Gets the default ambisonics order for spatial receivers. If no ambisonics order is set for a spatial receiver it defaults to 2. The value can be overwritten on a receiver level.

property dg_settings: DgSolverSettings

property freefield_removal_max_distance: float: Maximum distance for free field removal in meters. Every receiver within that distance from the source will have the free field response / direct sound removed from the response.

property ga_settings: GaSolverSettings

property gpu_count: int

Number of GPUs to use for simulation.

Returns int:: GPU count.

property ir_shift_seconds: float

property speed_of_sound: float

Speed of sound in meters per second.

Returns float:: Speed of sound value.

class treble_tsdk.core.simulation.SimulationStatus

Available simulation status values.

Represents the current state of a simulation from creation to completion or error.

static is_final_status(status: 'SimulationStatus' | str) → bool

Check if a simulation status is final.

Parameters:: status (SimulationStatus | str) – Status to check.
Returns bool:: True if status is final (completed, cancelled, or error).

classmethod list()

classmethod print()

cancelled = 'Cancelled'

completed = 'Completed'

completed_with_source_errors = 'CompletedWithSourceErrors'

created = 'Created'

dispatch_error = 'DispatchError'

error = 'Error'

in_progress = 'InProgress'

insufficent_tokens = 'InsufficientTokens'

material_assignment_error = 'MaterialAssignmentError'

mesher_error = 'MesherError'

not_enough_resources_error = 'NotEnoughResourcesError'

processing_results = 'ProcessingResults'

queued = 'Queued'

starting = 'Starting'

class treble_tsdk.core.simulation.SimulationTokenCost

Detailed token cost breakdown for a completed simulation.

Provides comprehensive cost metrics including element counts, runtime, and per-source costs.

__init__(dto: SimulationTokenCostDto)

property cost_per_dg_source: list

property cost_per_ga_source: list

property element_count: int

property element_min_length: float: Minimum element length in meters.

property impulse_length_sec: float

property model_volume: float

Model volume in cubic meters.

Returns float:: Volume in m³.

property number_of_triangles: float

property receiver_count: int

property receiver_count_ambisonics_order: int

property recommended_gpu_count: int

property result_status: ResultStatusDto

property simulation_id: str

property simulation_name: str

property simulation_status: str

property simulation_type: str

property total_billable_tokens: decimal

property total_cost_in_tokens: decimal

property total_estimated_runtime_hours: float

property transition_frequency: int

Crossover frequency between DG and GA solvers.

Returns int:: Transition frequency in Hz.

class treble_tsdk.core.simulation.SimulationType

Available simulation types.

dg = 'DG'

ga = 'GA'

geometrical = 'GA'

hybrid = 'Hybrid'

wave_based = 'DG'

class treble_tsdk.core.simulation.SolveTaskStatus

Available solve task status values.

Represents the current state of an individual solver task within a simulation.

static is_final_status(status: 'SimulationStatus' | str) → bool

Check if a task status is final.

Parameters:: status (SimulationStatus | str) – Status to check.
Returns bool:: True if status is final (completed, cancelled, or error).

static is_queued_status(status: 'SimulationStatus' | str) → bool

Check if a task status is queued.

Parameters:: status (SimulationStatus | str) – Status to check.
Returns bool:: True if status is queued.

static is_running_status(status: 'SimulationStatus' | str) → bool

Check if a task status is running.

Parameters:: status (SimulationStatus | str) – Status to check.
Returns bool:: True if status is provisioning or running.

classmethod list()

classmethod print()

cancelled = 'Cancelled'

completed = 'Completed'

created = 'Created'

dispatch_error = 'DispatchError'

error = 'Error'

provisioning = 'Provisioning'

queued = 'Queued'

running = 'Running'

unknown = 'Unknown'