Skip to main content

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. The SDK also allows it's users to import custom materials.

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 contains a variety of different materials separated into categories.

# View available material categories and the number of materials within the category as a table.
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(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.

material.as_tree()
materials = tsdk.material_library.get(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.

# tsdk.material_library.get(category="...") returns all materials belonging to category as a list.
wooden = tsdk.material_library.get(category="Wood")
perforated_panel = tsdk.material_library.get(category="Perforated panels")
acoustic_ceiling = tsdk.material_library.get(category="Porous")
gypsum = tsdk.material_library.get(category="Gypsum")
rigid = tsdk.material_library.get(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),
]

Note: in the assignment we specified a 'custom' scattering coefficient for each material, if a custom scattering coefficient is not provided then the default scattering coefficient for the selected material is used. A custom scattering coefficient can either be assigned as a single value or as a list of 8 values, one for each octave band. If the scattering coefficient is a single value the geometrical solver will extrapolate the scattering coefficient for each octave band using a S-shaped curve.

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.