Project reference
Getting a project
Projects can be viewed and fetched via the TSDK session object.
dd.as_table(tsdk.list_projects())
Project Properties
| Property | Type | Description | Example value |
|---|---|---|---|
| id | string | The unique identifier given to this project by the SDK | '380a3980-721a-4e80-95df-484f519c525c' |
| name | string | Name of the project | |
| description | string | Description of project given by the user | |
| created_at | string | Timestamp when project was created | '2023-09-06 10:39:24' |
| updated_at | string | Timestamp when project data was changed e.g. name, description. | '2023-09-06 10:39:24' |
| created_by | string | The unique identifier of user that created this project. | '380a3980-721a-4e80-95df-484f519c525c' |
Project Methods
update
Update project name and description of project.
Arguments
| Parameter | Type | Description | Example value |
|---|---|---|---|
| name | string | New name, if None the name will not be updated. | |
| description | string | New description, if None the description will not be updated. |
Returns
Nothing.
Model related methods
add_model
Upload a model file to project. Note, the model is not ready to be used in simulations until it's processing is completed. See TODO - ref geometry processing notebook.
Arguments
| Parameter | Type | Description | Example value |
|---|---|---|---|
| model_name | string | Name of model. | |
| model_file_path | string | Path to model file to be uploaded. | |
| model_description | string | Optional, description of your model. | |
| geometry_checker_settings | GeometryCheckerSettingsDto | Optional advanced settings for the geometry processor. |
Returns
ModelObj object.
Examples
model_obj = project.add_model(
model_name ='My model',
model_file_path='/path/to/my/model.3dm'
)
assert model_obj
get_model
Get model by an identifier. Will log errors if input was invalid.
Arguments
| Parameter | Type | Description | Example value |
|---|---|---|---|
| model | str, ModelObj or ModelDto | Model to fetch. |
Returns
ModelObj object if model was found, None otherwise.
Examples
# Valid request.
model_obj = project.get_model('380a3980-721a-4e80-95df-484f519c525c')
assert model_obj
# Model not found.
model_obj = project.get_model('00000000-0000-0000-0000-000000000000')
assert model_obj is None
# Invalid input.
model_obj = project.get_model('hello')
assert model_obj is None
get_models
Get a list of all models that belong to the project.
Arguments
None
Returns
List[ModelObj]
Examples
all_models = project.get_models()
# Display model list as a table.
dd.as_table(all_models)
delete_model
Delete model from project.
Arguments
| Parameter | Type | Description | Example value |
|---|---|---|---|
| model | str, ModelObj or ModelDto | Model to delete. |
Returns
bool - Returns True if model was deleted successfully, False otherwise.
Examples
# Valid request.
res = project.delete_model('380a3980-721a-4e80-95df-484f519c525c')
assert res is True
# Model note found.
res = project.delete_model('00000000-0000-0000-0000-000000000000')
assert res is False
# Invalid input.
res = project.delete_model('hello')
assert res is False
Simulation related methods
get_simulations
Get simulations in a project.
Arguments
| Parameter | Type | Description | Example value |
|---|---|---|---|
| simulation_status | SimulationStatus | Optional, filter on simulation status. | treble.SimulationStatus.completed |
Returns
List[Simulation] List of simulation objects.
Examples
# Get all simulations
all_simulations = project.get_simulations()
# Display all simulations in a table.
dd.as_table(all_simulations)
# Get completed simulations
completed_simulations = project.get_simulations(treble.SimulationStatus.completed)
# Invalid input
error = project.get_simulations('hello')
assert len(error) == 0
get_simulation
Get a simulation in a project.
Arguments
| Parameter | Type | Description | Example value |
|---|---|---|---|
| simulation_status | string | Simulation unique identifier. | 'c302115c-d00f-4e22-a444-a969d872b7bc' |
Returns
Simulation Returns simulation object if found, None otherwise.
Examples
# Get a simulation
simulation = project.get_simulation('c302115c-d00f-4e22-a444-a969d872b7bc')
# Simulation not found
simulation = project.get_simulation('00000000-0000-0000-0000-000000000000')
assert simulation is None
# Invalid input
simulation = project.get_simulation('hello')
assert simulation is None
add_simulation
Add a simulation to project from a SimulationDefinition.
Arguments
| Parameter | Type | Description | Example value |
|---|---|---|---|
| definition | SimulationDefinition | Simulation definition to use when creating simulation. |
Returns
Simulation - Returns a Simulation object which can be used to start and monitor the simulation
Examples
# Create a simulation from simulation definition.
simulation_obj = project.add_simulation(simulation_definition)
# Invalid input
simulation_obj = project.add_simulation('hello')
assert simulation_obj is None
add_simulations
Add multiple simulations from a list of SimulationDefinition objects.
Arguments
| Parameter | Type | Description | Example value |
|---|---|---|---|
| definitions | List[SimulationDefinition] | Simulation definitions to use when creating simulations. |
Returns
List[Simulation] - Returns a list of simulation objects created.
Examples
# Create a simulation from simulation definition.
simulation_objs = project.add_simulations(definition_list)
# Invalid input
simulation_objs = project.add_simulations('hello')
assert simulation_objs is None
estimate
Estimate simulation runtime and tokens for the project. Note, estimation of a simulation can only be performed once the model has finished processing and in case of Hybrid or Wave-based simulations the model must also be completed meshing, see wait-for-estimation.
Arguments
None
Returns
ProjectEstimateDto
Examples
estimation = project.estimate()
# Display project estimation as a table.
dd.as_table(estimation)
wait_for_estimate
Wait for project estimate. Returns estimate object either if estimate is ready or if operation timed out.
Arguments
| Parameter | Type | Description | Example value |
|---|---|---|---|
| max_retries | int | Optional, Maximum number of retries for getting estimate, defaults to 200. |
Returns
ProjectEstimateDto
Examples
estimation = project.wait_for_estimate()
# Display project estimation as a table.
dd.as_table(estimation)
get_progress
Get progress of simulations in the project.
Arguments
None
Returns
ProjectProgressDto - Returns ProjectProgressDto object with total project progress percentage as well as progress for each simulation.
Examples
progress = project.get_progress()
# Display progress as table
dd.as_table(progress)
start_simulations
Start all the simulations added to this project. Note, this will only attempt to start simulations that have not already been started and have not reached an end state.
Arguments
None
Returns
StartProjectDto - Data container with information on the simulations which were started.
Examples
res = project.start_simulations()
# Display started simulations as table.
dd.as_table(res.started)
start_simulations
Cancel all project simulations that have not reached an end state.
Arguments
None
Returns
CancelSimulationDto - Data container with information about the cancelled simulation, it will return None if request resulted in an error.
Examples
cancelled_simulation_list = project.cancel_simulations()
# Display cancelled simulation info as table.
dd.as_table(cancelled_simulation_list)
get_results
Cancel all project simulations that have not reached an end state.
Arguments
None
Returns
SimulationResultDto - Data container with information about all simulation results. Including signed urls to result files. Note, signed urls expire and become invalid after a few hours after being created.
Examples
result_dtos = project.get_results()
# Print out result urls.
for result_dto in result_dtos:
print(f'Simulation: {result_dto.name}')
for source_result_dto in result_dto.sourceResults:
print(f'Source: {source_result_dto.sourceInfo.label}')
for task_result_dto in source_result_dto.results:
print(f'Task: {task_result_dto.taskType} - {task_result_dto.dataFileUrl}')
download_results
Download results for all simulations in the project to the destination directory.
Arguments
| Parameter | Type | Description | Example value |
|---|---|---|---|
| destination_directory | string or Path object | Destination directory to download results to. | |
| result_type | SimulationType | Optional, filter for result type. | treble.SimulationType.hybrid |
| rename_rule | ResultRenameRule | Optional, rename result files from ids to source and receiver labels. | treble.ResultRenameRule.by_label |
| data_filter | ResultDataFilter | Optional, remove files that do not match filter. | treble.ResultDataFilter.ir |
| include_subtasks | bool | Optional, this is an advanced feature. If True the result set will include tasks that are not considered to contain final results. F.ex. Dipole and Omni results before being processed to a single Directive IR. |
Returns
Nothing
Examples
project.download_results(
destination_directory='/path/to/results/directory',
result_type=treble.SimulationType.hybrid,
rename_rule=treble.ResultRenameRule.by_label
)
validate
Performs validation on all simulations in the project.
Arguments
None
Returns
List[SimulationValidationResults]
Examples
validation_results = project.validate()
# Display validation results as table.
dd.as_table(validation_results)