treble_tsdk.core.project¶
Project management interface.
Provides classes and functions to create, estimate, monitor and manage projects and their simulations.
Classes
Container for acoustic simulation models and simulations. |
|
Cost and runtime estimates for a project. |
|
Real-time progress information for a project. |
|
Detailed token cost breakdown for a completed project. |
|
Result of starting simulations in a project. |
- class treble_tsdk.core.project.ProjectProgressInfo¶
Real-time progress information for a project.
Tracks overall project status and progress for all simulations within the project.
- property status: SimulationStatus¶
Overall project status.
- Returns SimulationStatus:
Status of the project.
- property project_progress_percentage: float¶
Overall project progress as percentage.
- Returns float:
Progress percentage (0-100).
- property simulations: list[SimulationProgressInfo]¶
Progress information for all simulations in the project.
- Returns list[SimulationProgressInfo]:
List of simulation progress info objects.
- as_table()¶
Uses the display_data module to display project progress as table.
- class treble_tsdk.core.project.ProjectEstimation¶
Cost and runtime estimates for a project.
Aggregates estimation data for all simulations in the project.
- __init__(dto: ProjectEstimateDto)¶
- property result_status: ResultStatusDto¶
Status of the estimation request.
- Returns ResultStatusDto:
Result status of the estimation.
- property total_estimated_runtime_hours: int | None¶
Total estimated runtime for all simulations in hours.
- Returns int | None:
Estimated runtime in hours, or None if not available.
- property total_cost_in_tokens: int | None¶
Total estimated cost in tokens for all simulations.
- Returns int | None:
Total cost in tokens, or None if not available.
- property simulation_estimates: list[SimulationEstimate]¶
Estimation details for each simulation in the project.
- Returns list[SimulationEstimate]:
List of simulation estimates.
- as_tree()¶
Uses the display_data module to display project estimate as tree.
- as_table()¶
Uses the display_data module to display project estimate as table.
- class treble_tsdk.core.project.ProjectTokenCost¶
Detailed token cost breakdown for a completed project.
Provides comprehensive cost metrics for all simulations in the project.
- __init__(dto: ProjectTokenCostDto)¶
- property result_status: ResultStatusDto¶
Status of the token cost request.
- Returns ResultStatusDto:
Result status of the token cost calculation.
- property total_estimated_runtime_hours: float¶
Total estimated runtime for all simulations in hours.
- Returns float:
Estimated runtime in hours.
- property total_cost_in_tokens: float¶
Total cost in tokens for all simulations.
- Returns float:
Total cost in tokens.
- class treble_tsdk.core.project.StartProjectResult¶
Result of starting simulations in a project.
Categorizes simulations by their state after the start operation.
- property started: list[SimulationBasicInfo]¶
List of simulations that were started by project.start_simulations.
- property already_started: list[SimulationBasicInfo]¶
List of simulations that were already started when project.start_simulations was called.
- property already_in_end_state: list[SimulationBasicInfo]¶
List of simulations that were already in an end state when project.start_simulations was called.
- property queued: list[SimulationBasicInfo]¶
List of simulations that were queued when project.start_simulations was called.
- property finished: list[SimulationBasicInfo]¶
List of simulations that were finished when project.start_simulations was called.
- property finished_with_errors: list[SimulationBasicInfo]¶
List of simulations that were finished with errors when project.start_simulations was called.
- property cancelled: list[SimulationBasicInfo]¶
List of simulations that were cancelled when project.start_simulations was called.
- as_tree()¶
Uses the display_data module to display start project result as tree.
- class treble_tsdk.core.project.Project¶
Container for acoustic simulation models and simulations.
Manages models, simulations, and results for a collection of related acoustic analyses.
- __init__(dto: ProjectDto, client: TSDKClient)¶
- property created_at: str¶
Project creation timestamp.
- Returns str:
ISO timestamp when project was created.
- property updated_at: str¶
Project last update timestamp.
- Returns str:
ISO timestamp when project was last updated.
- property tags: list[str]¶
Project tags for organization and filtering.
- Returns list[str]:
List of tag strings.
- add_model(model_name: str, model_file_path: str | 'GeometryDefinition', model_description: str = None, geometry_checker_settings: GeometryCheckerSettings | GeometryCheckerSettingsDto = None, metadata: dict[str, str] | ObjectMetadataDto | ObjectMetadata = None, tags: list[str] = []) ModelObj | None¶
Upload a model to project.
- Parameters:
- Returns ModelObj | None:
Returns the uploaded ModelObj object or None if model upload failed.
- add_models_bulk(model_upload_infos: list[ModelUploadInfo], output_mode: ProgressOutputMode = ProgressOutputMode.TQDM_OUTPUT, progress_leave: bool = True) list[ModelObj]¶
Upload a model to project.
- Parameters:
model_upload_infos (list[ModelUploadInfo]) – List of ModelUploadInfo objects containing the model name, file path, and metadata.
- Returns list[ModelObj]:
Returns a list of ModelObj objects.
- join_models(source_model: str | ModelObj | ModelDto, target_models: list[str | Path | 'MeshCollection'], target_transforms: list[Transform3d], new_model_name: str, new_model_description: str = None, geometry_checker_settings: GeometryCheckerSettingsDto = None, merge_by_layer_name: bool = True) ModelObj¶
joins a model (source_model) with a list of models (target_models). Each of the target models can be given a transform to locate it inside of the source model.
This method can be used to for example insert sound sources in connection with the boundary velocity functionality or to modify existing spaces by inserting furniture and other objects into an existing space
- Parameters:
source_model (str) – Name of model to insert the target model into
target_models (list[str | MeshCollection]) – Path to the target model file to be uploaded or MeshCollection containing the geometry.
target_model_transform (list[Transform3d]) – Transform of the target model.
new_model_name (str) – Optional description of your model.
new_model_description (str) – Optional description of your model.
geometry_checker_settings (GeometryCheckerSettingsDto) – Optional advanced settings for geometry checking service.
merge_by_layer_name (bool) – If true, objects in layers that share the same name will be merged into one layer. If False the layers will be kept separate by appending a number to the layer name.
- Returns ModelObj:
Returns the uploaded ModelObj object.
- get_model(model: str | ModelObj | ModelDto) ModelObj | None¶
Get model information as ModelDto.
- Parameters:
model (str|ModelDto) – Can either be a model id string or a ModelDto object.
- Returns ModelObj:
Returns the ModelObj object or None if model was not found.
- get_model_by_name(name: str) ModelObj | None¶
Get Model information as ModelDto. If multiple models match name then the model most recently created is returned. Returns None if model is not found.
- Parameters:
name (str) – Name of model to find.
- Returns ModelObj:
Returns the ModelObj object or None if model was not found.
- get_models() list[ModelObj]¶
Get all models associated with this project.
- Returns list[ModelDto]:
Returns a list of ModelDto objects.
- delete_model(model: str | ModelDto | ModelObj, force: bool = False) bool¶
Delete model from project.
- delete_simulation(simulation, force: bool = False) bool¶
Delete simulation from project.
- Parameters:
simulation – Simulation object or id of the simulation to delete.
force (bool) – If True, the simulation will be canceled and deleted if it is running.
- get_simulations(simulation_status: SimulationStatus | None = None, name: str | None = None, category: SimulationCategory | None = None) list[Simulation]¶
Get all simulations in project. Optional filter on simulation status, available values: created, starting, queued, in_progress, processing_results, completed, completed_with_source_errors, cancelled, error Optional filter on simulation category, available values: default, free_field
- Return list[Simulation]:
Returns a list of Simulation objects
- get_simulation(simulation_id: str) Simulation | None¶
Get a project simulation by simulation id.
- Parameters:
simulation_id (str) – Id of the simulation to fetch
- Return Simulation:
Returns a Simulation object.
- get_simulation_by_name(name: str) Simulation | None¶
Get a project simulation by simulation name.
- Parameters:
name (str) – Name of the simulation to fetch
- Return Simulation:
Returns a Simulation object.
- add_simulation(definition: SimulationDefinition) Simulation | None¶
Create a simulation and add it to project. :param SimulationDefinition definition: Simulation definition. :returns Simulation: Returns a Simulation object which can be used to start and monitor the simulation
- add_simulations(definitions: list[SimulationDefinition]) list[Simulation | None]¶
Add multiple simulations from a list of SimulationDefinition objects
- Parameters:
definitions (list[SimulationDefinition]) – List of Simulations to create.
- Returns list[Simulation]:
Returns a list of simulation objects.
- estimate() ProjectEstimation¶
Estimate simulation runtime and tokens for the project.
- Returns ProjectEstimate:
Returns ProjectEstimate containing total estimated runtime and total cost in tokens, as well as estimations for each simulation.
- wait_for_estimate(max_retries: int = 200) ProjectEstimation¶
Wait for project estimate. Returns estimate object either if estimate is ready or if operation timed out.
- Parameters:
max_retries (int) – Maximum number of retries for getting estimate, defaults to 200.
- wait_for_token_cost(max_retries: int = 200) ProjectTokenCost¶
Wait for project token cost. Returns token cost object either if token cost is ready or if operation timed out.
- get_token_cost() ProjectTokenCost¶
Get token cost for the project.
- get_progress() ProjectProgressInfo¶
Get progress of simulations in a project.
- Returns ProjectProgressInfo:
Returns ProjectProgressInfo object with total project progress percentage as well as progress for each simulation.
- start_simulations(skip_prompt: bool = False) StartProjectResult | None¶
Start all the simulations added to this project. The simulations are run in the cloud and do thus not keep your computer busy. The simulations can be monitored, cancelled or the results can be downloaded once the simulations are completed.
- Parameters:
skip_prompt (bool) – If True, starts without prompting. Useful for notebooks where you want to see the cost first.
- Returns StartProjectDto:
Data container with information on the simulations which were started
- cancel_simulations() list[CancelSimulationResult] | None¶
Cancel all project simulations that have not reached an end state.
- Returns CancelSimulationDto:
Data container with information about the cancelled simulation
- setup_drtf_simulation(simulation_name: str, device_geometry: str | Path | ModelObj, freefield_model_name: str, device_microphone_placements: Sequence[Point3d | list[float]], frequency: float, ambisonics_order: int) SimulationDefinition¶
Set up a simulation definition to create a device related transfer function (DRTF) from a device geometry.
- Parameters:
simulation_name (str) – Name of the freefield simulation
device_geometry (str) – Name of the device to be created
device_microphone_placement (Sequence[Point3d | list[float]]) – points coordinates of the microphones of the device
frequency (float) – Upper frequency of the simulation and validity of device
ambisonics_order (int) – Ambisonic order of the device [2, 4, 8, 16, 32]
- Returns SimulationDefinition:
Returns a SimulationDefinition object.
- update(name: str | None, description: str | None)¶
Update project.
- Parameters:
name – New name, if None the name will not be updated.
description – New description, if None the description will not be updated.
- download_results(destination_directory: str | Path, result_type: ResultType | None = None, rename_rule: ResultRenameRule = ResultRenameRule.none, output_mode: ProgressOutputMode = ProgressOutputMode.TQDM_OUTPUT)¶
Download results for all simulations in the project to the destination directory.
- Parameters:
destination_directory (str|Path) – Destination directory to download results to.
result_type (SimulationType | None) – Optional filter for result type.
output_mode – Optional, set how download progress is reported.
- as_live_progress()¶
Uses the display_data module to show simulation progress, automatically updated until all simulations are completed or interrupt signal is received (CTRL+C).