Skip to main content

core.simulation

ReceiverType Objects

class ReceiverType(str, Enum)

Available receiver types.

ResultRenameRule Objects

class ResultRenameRule(str, Enum)

Rename rules for results.

ResultDataFilter Objects

class ResultDataFilter(str, Enum)

Available filters for results

SourceType Objects

class SourceType(str, Enum)

Available source types.

SimulationType Objects

class SimulationType(str, Enum)

Available simulation types.

SimulationOnTaskError Objects

class SimulationOnTaskError(str, Enum)

Available Simulation "on task error" behaviours.

SourceProperties Objects

class SourceProperties(dict)

__init__

def __init__(azimuth_angle: float, elevation_angle: float)

Additional source properties.

Arguments:

  • azimuth_angle (float): Azimuth rotation angle for directional sources. From 0° to 360°.
  • elevation_angle (float): Elevation rotation angle for directional sources. From 0° to 90°.

Source Objects

class Source(dict)

__init__

def __init__(x: float,
y: float,
z: float,
source_type: SourceType,
label: str,
source_properties: SourceProperties = None)

Represents a Simulation source.

Arguments:

  • x (float): X position of source in meters.
  • y (float): Y position of source in meters.
  • z (float): Z position of source in meters.
  • source_type (SourceType): Type of source.
  • label (str): Source label.
  • float (float): Optional, additional source properties.

ReceiverProperties Objects

class ReceiverProperties(dict)

__init__

def __init__(device: Union[DeviceObj, DeviceDto] = None,
azimuth_angle: float = 0.0,
elevation_angle: float = 0.0,
roll_angle: float = 0.0,
ambisonics_sphere_radius_in_m: float = 0.1)

Additional receiver properties further defining either spatial or device type receivers.

For spatial receivers the only used parameter is the ambisonics_sphere_radius_in_m

For device receivers, all the parameters are used but only the device one is a mandatory input. When the receiver type is device, the receiver properties define the device related transfer function (DRTF) of the device as well as its orientation in the room. The orientation angles are defined as azimuth, elevation and roll and they represent the intrinsic rotation of the device around the Z axis, X' axis and Y'' axis, respectively. Intrinsic means that the coordinate system rotates with the applied rotation and the rotation is applied: 1. Azimuth, 2. Elevation, 3. Roll

Arguments:

  • device (DeviceObj): Device object which contains its DRTF already preprocessed from a .sofa file. Mandatory when ReceiverType == device, defaults to None
  • azimuth_angle (float): Azimuth rotation angle (counter-clockwise around Z axis) for device receivers. From 0° to 360°, defaults to 0
  • elevation_angle (float): Elevation rotation angle (counter-clockwise around X' axis) for device receivers. From -90° to 90°, defaults to 0.
  • roll_angle (float): Roll rotation angle (counter-clockwise around Y'' axis) for device receivers. From 0° to 360°, defaults to 0.
  • ambisonics_sphere_radius_in_m (float): The radius in m of the sphere where receiver array will be generated on. From 0.05 to 0.15, defaults to 0.1

Receiver Objects

class Receiver(dict)

__init__

def __init__(x: float,
y: float,
z: float,
receiver_type: ReceiverType,
label: str,
receiver_properties: ReceiverProperties = None)

Represents a simulation Receiver.

Arguments:

  • x (float): X position of receiver in meters.
  • y (float): Y position of receiver in meters.
  • z (float): Z position of receiver in meters.
  • receiver_type (ReceiverType): Type of receiver.
  • label (str): receiver label.
  • float0 (float1): Optional, additional receiver properties used for defining the device related transfer function (DRTF).

GaSolverSettings Objects

class GaSolverSettings(dict)

__init__

def __init__(number_of_rays: int, ism_order: int)

Custom settings for the geometrical acoustics (GA) solver.

Arguments:

  • numberOfRays (int): Number of rays to use in GA.
  • ISMOrder (int): Image source method order to use in GA.

SimulationSettings Objects

class SimulationSettings(dict)

__init__

def __init__(speed_of_sound: float = None,
ga_settings: GaSolverSettings = None,
dg_settings: DgSolverSettings = None,
ambisonics_order: float = None)

Advanced simulation settings.

Arguments:

  • 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: [2, 4, 6, 8, 16]

SimulationDefinition Objects

class SimulationDefinition()

__init__

def __init__(name: str,
simulation_type: SimulationType,
model: Union[str, ModelDto, ModelObj, GeometryLibraryObj],
crossover_frequency: int,
receiver_list: List[Union[Receiver, Dict]],
source_list: List[Union[Source, Dict]],
material_assignment: List[MaterialAssignment],
ir_length: float = None,
energy_decay_threshold: float = None,
simulation_settings: SimulationSettings = None,
on_task_error: SimulationOnTaskError = "Ignore",
description: str = None)

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

Arguments:

  • 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.
  • 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.
  • ir_length (float): Impulse response length in sec.
  • 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.

plot

def plot(with_validation=True, project=None)

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

Arguments:

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

validate

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

Arguments:

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

Simulation Objects

class Simulation()

The Simulation class can be used to work with a single simulation. F.ex. start a simulation, estimate simulation runtime/cost, etc.

layer_material_assignment

@property
def layer_material_assignment() -> Dict[str, MaterialAssignmentDto]

Returns a dictionary where layer name is the key and MaterialAssignmentDto is the value.

get_model

def get_model() -> ModelObj

Get the ModelObj associated to this simulation.

Returns:

ModelObj: Returns ModelObj object.

estimate

def estimate() -> SimulationEstimateDto

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

Returns:

SimulationEstimateDto: Returns SimulationEstimateDto object

wait_for_estimate

def wait_for_estimate(max_retries=200) -> SimulationEstimateDto

Wait for simulation estimate.

Arguments:

  • max_retries (int): Maximum retries for getting simulation estimate.

Returns:

SimulationEstimateDto: Returns SimulationEstimateDto object either if estimate is ready or if max_retries seconds have elapsed.

start

def start()

Start the simulation.

get_progress

def get_progress() -> SimulationProgressDto

Get progress of the simulation.

Returns:

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

cancel

def cancel() -> CancelSimulationDto

Cancel the simulation.

Returns:

CancelSimulationDto: Returns CancelSimulationDto containing a list of all the simulation's cancelled tasks.

delete

def delete() -> None

Delete the simulation.

update

def update(name: str = None,
description: str = None,
impulse_length_sec: float = None,
crossover_frequency: int = None,
energy_decay_threshold: float = None,
simulationSettings: SimulationSettings = None)

Update the simulation.

Arguments:

  • name (str): New name, if None the name will not be updated.
  • description (str): New description, if None the description will not be updated.
  • impulse_response_length (float): New impulse response length, if None the impulse response length will not be updated.
  • crossover_frequency (int): New crossover frequency, if None the crossover frequency will not be updated.
  • energy_decay_threshold (float): New energy decay threshold, if None the energy decay threshold will not be updated.
  • str0 (str1): New advanced simulation settings, if None the simulation settings will not be updated.

add_receivers

def add_receivers(receivers: Union[List[Receiver], List[ReceiverDto]])

Add receivers to simulation.

Arguments:

  • receivers (List[Receiver|ReceiverDto]): List of receivers to add to the simulation, can be either a list of Receiver object or a list of ReceiverDto

delete_receivers

def delete_receivers(receivers: Union[List[str], List[ReceiverDto]])

Delete receivers.

Arguments:

  • receivers (List[str|ReceiverDto]): Either a list of valid ReceiverDtos or a list of receiver ids.

add_sources

def add_sources(sources: Union[List[Source], List[SourceDto]])

Add sources to simulation.

Arguments:

  • sources (List[Source|SourceDto]): List of sources to add to the simulation, can be either a list of Source object or a list of SourceDto

delete_sources

def delete_sources(sources: Union[List[str], List[SourceDto]])

Delete sources.

Arguments:

  • sources (List[str|SourceDto]): Either a list of valid SourceDtos or a list of source ids.

update_material_assignment

def update_material_assignment(
assignments: Union[List[MaterialAssignment], List[MaterialAssignmentDto]]
) -> ResultStatusDto

Update material assignment for simulation.

Arguments:

  • assignments (List[MaterialAssignment|MaterialAssignmentDto]): Either a list of MaterialAssignment objects or a list of MaterialAssignmentDto objects.

remove_material_assignment

def remove_material_assignment(assignment: Union[str, MaterialAssignmentDto])

Clear/remove layer material assignment

Arguments:

  • assignment (str|MaterialAssignmentDto): Either a MaterialAssignmentDto to clear or the layer id of the layer to remove material assigment from.

get_tasks

def get_tasks() -> List[SourceDto]

Get the simulation's tasks.

Returns:

list[SourceDto]: Returns a list of SourceDtos containing task list for source.

get_results_json

def get_results_json(result_type: SimulationType = None,
include_subtasks: bool = False) -> List[SourceResultDto]

Get results for the simulation.

Arguments:

  • result_type (SimulationType): Optional filter for type of results to fetch "wave_based"|"geometrical"|"hybrid" if None then all results will be fetched.

Returns:

list[SourceResultDto]: List of SourceResultDto objects.

download_results

def download_results(destination_directory: Union[str, Path],
result_type: SimulationType = None,
rename_rule: ResultRenameRule = ResultRenameRule.none,
data_filter: ResultDataFilter = ResultDataFilter.none,
include_subtasks: bool = False)

Download results to a directory.

Arguments:

  • destination_directory (Union[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.
  • data_filter (ResultDataFilter): Optional, if provided it can be used to remove result data files that you are not interested in, f.ex. if you only wan't to see IRs.

plot

def plot(with_validation=True)

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

Arguments:

  • with_validation: Show validation results. Optional, defaults to true.

validate

def 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

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

get_results_object

def get_results_object(
pre_download_results: bool = False
) -> Union["SimulationResultObject", None]

Get results object containing a list of SourceResultDto, each with a list of SolveTaskResultDto which contains the dataFileUrl (download url) for the task's results.

Returns:

SimulationResultObject: Object containing the simulation results.

as_tree

def as_tree()

Uses the display_data module to display simulation information as tree.

as_table

def as_table()

Uses the display_data module to display simulation information as table.

as_live_progress

def as_live_progress()

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