Boundary Materials

The following documentation is presented as Python code running inside a Jupyter Notebook. To run it yourself you can copy/type each individual cell or directly download the full notebook, including all required files.

Download Jupyter Notebook

How waves interact with the boundaries of their media plays an integral role in room acoustics. Aside from air absorption (attenuation), this is where the waves loose their energy. Either via transmission through the materials or via mechanical-to-thermal energy conversions within the materials.

The Treble SDK comes with an extensive database of realistic materials which we reccommend using. But we also plan on including some custom material import functionalities soon.

Now let's start by getting the project.

from pathlib import Path
import random

from treble_tsdk.tsdk import TSDK
from treble_tsdk import tsdk_namespace as treble
from treble_tsdk import display_data as dd

tsdk = TSDK()
project_name = "Tutorial"
p = tsdk.get_or_create_project(name=project_name)

Material Library

Treble's material database currently contains 459 different materials separated into categories.

material_library = tsdk.material_library.get_categories_with_count()
dd.as_table(material_library)

The materials in the Treble database are all either based on measurements or on empirical models of the material buildups. This does not apply to the materials in the Other category though. Each material contains information on random-incidence absorption coefficients and the complex reflection coefficient and surface impedance.

The materials come with a default scattering coefficient which is used in the geometrical acoustics solver, but keep in mind that this is inherently not a material parameter but rather a parameter designed to account for the level of heterogeneity of the surface. Such heterogeneity would result in scattering of waves, especially at higher frequencies, and can thus be a useful parameter to achieve more realistic simulations.

As an example we can plot the information of one of the materials.

material = tsdk.material_library.get_by_category("Porous")[0]
material.plot()

We can also print detailed information about the material or print an overview of a selection of materials in a table view.

dd.as_tree(material)

materials = tsdk.material_library.get_by_category("Porous")[5:10]
dd.as_table(materials)

We can now take a look at the layers in the room model we defined to know which layers we need to attach materials to:

room = treble.GeometryGenerator.create_l_shaped_room(
    project=p, 
    model_name="l-shaped", 
    a_side=3, 
    b_side=3, 
    c_side=1, 
    d_side=1, 
    height_z=2.2,
    join_wall_layers=False,
)

print("Layers which need materials: \n")
for layer in room.layer_names:
    print(f"{layer}")

To see where each of the layers are located in the geometry, the geometry can be plotted.

room.plot()

We can now attach materials to these layers. We can either assign specific materials from the database or we can make a random selection based on a category that we find appropriate for each surface.

Here we use the latter approach. Let's first pick the material categories.

wooden = tsdk.material_library.get_by_category("Wood")
perforated_panel = tsdk.material_library.get_by_category("Perforated panels")
acoustic_ceiling = tsdk.material_library.get_by_category("Porous")
gypsum = tsdk.material_library.get_by_category("Gypsum")
rigid = tsdk.material_library.get_by_category("Rigid")

When assigning materials to surface layers of a model, we create a list of MaterialAssignment objects.

material_assignment = [
    treble.MaterialAssignment(layer_name="lshape_wall_0", material=random.choice(rigid), scattering_coefficient=0.15),
    treble.MaterialAssignment(layer_name="lshape_wall_1", material=random.choice(gypsum), scattering_coefficient=0.1),
    treble.MaterialAssignment(layer_name="lshape_wall_2", material=random.choice(gypsum), scattering_coefficient=0.1),
    treble.MaterialAssignment(layer_name="lshape_wall_3", material=random.choice(perforated_panel), scattering_coefficient=0.2),
    treble.MaterialAssignment(layer_name="lshape_wall_4", material=random.choice(gypsum), scattering_coefficient=0.1),
    treble.MaterialAssignment(layer_name="lshape_wall_5", material=random.choice(gypsum), scattering_coefficient=0.1),
    treble.MaterialAssignment(layer_name="lshape_floor", material=random.choice(wooden), scattering_coefficient=0.1),
    treble.MaterialAssignment(layer_name="lshape_ceiling", material=random.choice(acoustic_ceiling), scattering_coefficient=0.15),
]

This material_assignment list we can later pass to a Simulation object when creating a simulation. Which we'll do in the next tutorial.

We have now showed how to query the material library and how to attach the resulting materials to the surface layers of a model. As previously stated, we will soon implement options to generate custom materials by importing either absorption coefficients, surface impedance or reflection coefficients. As soon as that happens, this tutorial will be updated.

Boundary Materials

Material Library​

Material Library