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.SimulationProgressInfo

Progress information for a running simulation.

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

__init__(dto: SimulationProgressDto, client: TSDKClient)

property simulation_id: str

property simulation_name: str

property simulation_status: str

property simulation_progress_percentage: float

property project_id: str

property project_name: str

property sources: list[Source]

as_tree()

Uses the display_data module to display material info as tree.

class treble_tsdk.core.simulation.CancelSimulationResult

Result of a simulation cancellation request.

Contains status information and list of cancelled tasks.

__init__(dto: CancelSimulationDto)

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

property cancelled_tasks: list[CancelTaskDto]

as_tree()

Display cancellation result as a tree structure.

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.SimulationEstimate

Cost and runtime estimates for a simulation.

Provides token cost and runtime estimates per source.

__init__(dto: SimulationEstimateDto)

property simulation_id: str

property simulation_name: str

property simulation_status: str

property total_estimated_runtime_hours: float

property total_estimated_cost_in_tokens: float

property total_cost_in_tokens: float

property estimate_per_source: list[SourceEstimate]

property result_status: ResultStatusDto

property supported_gpu_counts: GpuCountRangeDto | None

Supported GPU count range for the simulation.

Returns GpuCountRangeDto | None:

GPU count range, or None if not available.

as_tree()

Uses the display_data module to display estimate information as tree.

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 simulation_id: str

property simulation_name: str

property simulation_type: str

property simulation_status: str

property impulse_length_sec: float

property receiver_count: int

property receiver_count_ambisonics_order: int

property element_count: int

property element_min_length: float

Minimum element length in meters.

Type:

returns float

property number_of_triangles: float

property model_volume: float

Model volume in cubic meters.

Returns float:

Volume in m³.

property transition_frequency: int

Crossover frequency between DG and GA solvers.

Returns int:

Transition frequency in Hz.

property total_cost_in_tokens: decimal

property total_billable_tokens: decimal

property total_estimated_runtime_hours: float

property cost_per_dg_source: list

property cost_per_ga_source: list

property result_status: ResultStatusDto

class treble_tsdk.core.simulation.GaSolverType

Available solver types.

ray_radiosity = 'IsmPressureRayRadiosity'

volumetric_raytracing = 'IsmPressureVolumetricReceiver'

classmethod list()

classmethod print()

class treble_tsdk.core.simulation.SimulationStatus

Available simulation status values.

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

created = 'Created'

starting = 'Starting'

queued = 'Queued'

in_progress = 'InProgress'

processing_results = 'ProcessingResults'

completed = 'Completed'

completed_with_source_errors = 'CompletedWithSourceErrors'

cancelled = 'Cancelled'

error = 'Error'

material_assignment_error = 'MaterialAssignmentError'

mesher_error = 'MesherError'

not_enough_resources_error = 'NotEnoughResourcesError'

dispatch_error = 'DispatchError'

insufficent_tokens = 'InsufficientTokens'

classmethod list()

classmethod print()

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).

class treble_tsdk.core.simulation.SolveTaskStatus

Available solve task status values.

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

unknown = 'Unknown'

created = 'Created'

queued = 'Queued'

provisioning = 'Provisioning'

running = 'Running'

completed = 'Completed'

error = 'Error'

cancelled = 'Cancelled'

dispatch_error = 'DispatchError'

classmethod list()

classmethod print()

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.

class treble_tsdk.core.simulation.ResultRenameRule

Rename rules for results.

none = 'none'

by_label = 'by_label'

lazy_structure = 'lazy_structure'

class treble_tsdk.core.simulation.ResultDataFilter

Available filters for results

none = 'none'

ir = 'ir'

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.SimulationType

Available simulation types.

hybrid = 'Hybrid'

dg = 'DG'

ga = 'GA'

wave_based = 'DG'

geometrical = 'GA'

class treble_tsdk.core.simulation.SimulationCategory

Available simulation categories.

default = 'Default'

free_field = 'FreeField'

classmethod list()

classmethod print()

class treble_tsdk.core.simulation.ResultType

Available result types.

hybrid = 'Hybrid'

dg = 'DG'

ga = 'GA'

wave_based = 'DG'

geometrical = 'GA'

device_rendering = 'DeviceRendering'

class treble_tsdk.core.simulation.SimulationOnTaskError

Available Simulation “on task error” behaviours.

ignore = 'Ignore'

stop_simulation = 'StopSimulation'

stop_project = 'StopProject'

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 number_of_rays: int

property ism_order: int

Image source method order.

Returns int:

ISM order.

property air_absorption: bool

Whether air absorption is enabled.

Returns bool:

True if air absorption is active.

property ism_ray_count: int

Number of rays for image source method.

Returns int:

ISM ray count.

class treble_tsdk.core.simulation.SimulationSettings

Advanced simulation settings.

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

__init__(speed_of_sound: float = 343.0, ga_settings: GaSolverSettings | None = None, dg_settings: DgSolverSettings | None = None, ambisonics_order: int | None = None, ir_shift_seconds: float | None = None, gpu_count: int | None = None, dev_blob: str | None = None, free_field_removal_max_distance: float | None = None)

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, 2, 4, 8, 16, 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 speed_of_sound: float

Speed of sound in meters per second.

Returns float:

Speed of sound value.

property ga_settings: GaSolverSettings

property dg_settings: DgSolverSettings

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 ir_shift_seconds: float

property gpu_count: int

Number of GPUs to use for simulation.

Returns int:

GPU count.

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.

class treble_tsdk.core.simulation.MesherSettings

Mesher settings.

Controls mesh generation and simplification behavior.

__init__(simplify_mesh: bool = True)

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.

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.

remove_invalid_receivers()

Performs validation and removes receivers that are invalid

remove_invalid_sources()

Performs validation and removes sources that are invalid

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)

property id: str

property name: str

property description: str

property status: str

property created_at: str

property updated_at: str

property receivers: list[Receiver]

property sources: list[Source]

property type: SimulationType

property crossover_frequency: int

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 simulation_settings: SimulationSettings | None

Advanced simulation settings including solver configurations.

Returns SimulationSettings | None:

Simulation settings or None if not set.

property tags: list[str]

get_simulation_definition() → 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_model() → ModelObj | GeometryLibraryObj

Get the ModelObj associated to this simulation.

Returns ModelObj:

Returns ModelObj object.

get_token_cost() → SimulationTokenCost

Get the token cost for the simulation.

wait_for_token_cost(max_retries=200) → SimulationTokenCost

Wait for token cost to be available and then return it.

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

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.

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.

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.

cancel() → CancelSimulationResult

delete() → bool

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_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.

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.

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.

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. :param int gpu_count: Number of GPUS to allocate for each wave-solver task in the simulation.

rename(simulation_name: str) → bool

Update the simulation name. :param str simulation_name: Value of the updated name of the simulation.

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.

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 provide 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, f.ex.

if rename_rule.by_label is provided the folder structure will be [source_label]/[receiver_label]…wav and [source_label]_[task_type].json etc. Note when using this rule the labels must be guaranteed to be valid file/directory names, if not then the files will not be renamed. :param ResultDataFilter data_filter: Optional, if provided it can be used to remove result data files that the users is not interested in, f.ex. if user only wan’t to see IRs. :param utils.ProgressOutputMode output_mode: Optional, can be used to set how download progress reporting is handled, defaults to TQDM progress bars. :param bool progress_leave: If set to False it will remove the TQDM progress bar upon completion. :param bool return_none: If set to True it will return None and not try and load the downloaded results into a results object.

get_results_object(results_directory: str | Path | None = None, result_type: SimulationType | ResultType = None, **kwargs) → 'Results' | 'FreeFieldResults' | None

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

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.

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.

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).

as_tree()

Uses the display_data module to display simulation information as tree.

as_table()

Uses the display_data module to display simulation information as table.

as_live_progress()

Uses the display_data module to show simulation progress automatically updated until simulation finished.