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.Project
Container for acoustic simulation models and simulations.
Manages models, simulations, and results for a collection of related acoustic analyses.
- add_model(model_name: str, model_file_path: str | 'GeometryDefinition' | 'DeviceGeometryObj', 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.
- add_simulation(definition: SimulationDefinition) Simulation | None
Create a simulation and add it to project.
- Parameters:
definition (SimulationDefinition) – 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.
- 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).
- 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
- 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.
- 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.
- estimate() ProjectEstimation
Estimate simulation runtime and tokens for the project.
- Returns:
ProjectEstimation containing total estimated runtime and total cost in tokens, as well as estimations for each simulation.
- 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.
- get_progress() ProjectProgressInfo
Get progress of simulations in a project.
- Returns:
ProjectProgressInfo object with total project progress percentage as well as progress for each simulation.
- 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.
- 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_token_cost() ProjectTokenCost
Get token cost for the project.
- Returns:
ProjectTokenCost object with the token cost.
- rename(project_name: str) bool
Update the project name.
- Parameters:
project_name (str) – Value of the updated name of the project.
- 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 1 <= order <= 32
- Returns SimulationDefinition:
Returns a SimulationDefinition object.
- 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:
StartProjectResult with information on the simulations which were started, or None if cancelled.
- update_tags_from_server() bool
Get tags for the project from the server, note that this will overwrite any unsaved local changes to tags.
- 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.
- Returns:
ProjectEstimation object with the estimate results.
- 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.
- Returns:
ProjectTokenCost object with the token cost results.
- property created_at: str
Project creation timestamp.
- Returns str:
ISO timestamp when project was created.
- property created_by: str
Project creator identifier.
- Returns str:
User ID of project creator.
- property description: str
Project description.
- Returns str:
Description of the project.
- property id: str
Project identifier.
- Returns str:
Project ID.
- property name: str
Project name.
- Returns str:
Name of the project.
- property tags: list[str]
Project tags for organization and filtering.
- Returns list[str]:
List of tag strings.
- property updated_at: str
Project last update timestamp.
- Returns str:
ISO timestamp when project was last updated.
- class treble_tsdk.core.project.ProjectEstimation
Cost and runtime estimates for a project.
Aggregates estimation data for all simulations in the project.
- property project_id: str
Project identifier.
- Returns str:
Project ID.
- property result_status: ResultStatusDto
Status of the estimation request.
- Returns ResultStatusDto:
Result status of the estimation.
- property simulation_estimates: list[SimulationEstimate]
Estimation details for each simulation in the project.
- Returns list[SimulationEstimate]:
List of simulation estimates.
- 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.
- __init__(dto: ProjectProgressDto, client: TSDKClient | None = None)
- property project_id: str
Project identifier.
- Returns str:
Project ID.
- property project_name: str
Project name.
- Returns str:
Name 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.
- property status: SimulationStatus
Overall project status.
- Returns SimulationStatus:
Status of the project.
- class treble_tsdk.core.project.ProjectTokenCost
Detailed token cost breakdown for a completed project.
Provides comprehensive cost metrics for all simulations in the project.
- property project_id: str
Project identifier.
- Returns str:
Project ID.
- property project_name: str
Project name.
- Returns str:
Name of the project.
- property result_status: ResultStatusDto
Status of the token cost request.
- Returns ResultStatusDto:
Result status of the token cost calculation.
- property simulation_token_costs: list[SimulationTokenCostDto]
Token cost details for each simulation in the project.
- Returns list[SimulationTokenCostDto]:
List of simulation token costs.
- property total_billable_tokens: float
Total billable tokens for the project.
- Returns float:
Total billable tokens.
- property total_cost_in_tokens: float
Total cost in tokens for all simulations.
- Returns float:
Total cost in tokens.
- property total_estimated_runtime_hours: float
Total estimated runtime for all simulations in hours.
- Returns float:
Estimated runtime in hours.
- class treble_tsdk.core.project.StartProjectResult
Result of starting simulations in a project.
Categorizes simulations by their state after the start operation.
- property already_in_end_state: list[SimulationBasicInfo]
List of simulations that were already in an end state when project.start_simulations was called.
- property already_started: list[SimulationBasicInfo]
List of simulations that were already started when project.start_simulations was called.
- property cancelled: list[SimulationBasicInfo]
List of simulations that were cancelled 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 queued: list[SimulationBasicInfo]
List of simulations that were queued when project.start_simulations was called.
- property started: list[SimulationBasicInfo]
List of simulations that were started by project.start_simulations.