FEM-Helmholtz

This section explains how Numav can perform acoustic simulations based on the Helmholtz equation.

Quick start

Here is a complete example of a simulation code:

using Numav

# Create the simulation object
s = create_simulation(
    numerical_method = Fem,
    equation = Helmholtz,
    element_shape = Tetrahedron,
    element_order = Linear
)

# Set simulated frequencies
set_frequency!(s, max=200) # (Hz)

# Load mesh
load_mesh!(s, "path/to/mesh_file.bdf")

# Define material (frequency-dependent)
rho(f) = 1.20
c(f) = 343
add_volume_material!(s, physical_group=1, density=rho, speed_of_sound=c)

# Add a surface impedance boundary condition
Z(f) = 1f + 2im
add_surface_material!(s, physical_group=4, specific_acoustic_impedance=Z)

# Add a monopole volume velocity source at a point
Q(f) = 10/f
add_sound_source!(s, coordinates=[1.0, 1.5, 2.0], volume_velocity=Q)

# Add a particle velocity source on a surface
U(f) = 15/f
add_sound_source!(s, physical_group=2, particle_velocity=U)

# Add pressure sources (to point or surface)
P(f) = 2f
add_sound_source!(s, coordinates=[2.0, 2.5, 1.0], pressure=P)
add_sound_source!(s, physical_group=3, pressure=P)

# Set output file and run
set_result_export_path!(s, "result.h5")
run!(s)

For more details, look at the Functions section.

Keyword arguments	Type	Supported options	Description
`numerical_method`	`Numav.Option`	`Fem`	Numerical method used.
`equation`	`Numav.Option`	`Helmholtz`	Differential equation to be solved.
`element_shape`	`Numav.Option`	`Tetrahedron`	Geometrical shape of elements.
`element_order`	`Numav.Option`	`Linear`, `Quadratic`	Polynomial order of the finite elements.

Mode	Description
`Quadratic` (default)	Frequency discretization density grows quadratically with frequency. It tends to follow the modal density of rooms, being the recommended option for good accuracy and computation time balance.
`Constant`	Frequency steps are evenly spaced (uniform spacing). Suitable for broadband analyses where equal resolution at all frequencies is desired.

Loads the mesh file. It defines the geometry of the domain and must contain the physical groups that are referenced when assigning boundary conditions. To generate meshes, a good open-source option is Gmsh.

Positional arguments	Type	Description
`simulation`	`Simulation`	The simulation instance.
`path_to_mesh`	`String`	Path to the mesh file (`.bdf`).

Examples

load_mesh!(s, "some_mesh_file.bdf")

Warning

Currently, only meshes in the small field BDF format are supported.

Warning

The coordinates in the mesh file must be given in meters.

source

Numav.add_volume_material! — Function

Assigns acoustic material properties to a volumetric region of the mesh, identified by its physical group tag.

Positional arguments	Type	Description
`simulation`	`Simulation`	The simulation instance.
Keyword arguments
`physical_group`	`Integer`, `Vector{Integer}`	Physical group ID (or vector of IDs) from the mesh.
`density`	frequency-dependent physical quantity	Density in kg/m³.
`speed_of_sound`	frequency-dependent physical quantity	Speed of sound in m/s.

Examples

rho(f) = 1.20 # air density in kg/m³
c(f) = 343 # speed of sound in m/s
add_volume_material!(s, physical_group=1, density=rho, speed_of_sound=c)

Physical quantities can by complex to model sound absorption:
rho(f) = 1.20 + 0.001*f
c(f) = 340 + 0.1*sqrt(f)
add_volume_material!(s, physical_group=1, density=rho, speed_of_sound=c)

Multiple physical groups can be assigned at once:
add_volume_material!(s, physical_group=[4,6], density=1.2, speed_of_sound=343)

source

Numav.add_surface_material! — Function

Assigns a specific acoustic impedance boundary condition to a surface in the mesh. This is used to model absorbers, reflecting surfaces or other boundary treatments.

The specific acoustic impedance is the ratio of complex amplitude of acoustic pressure to complex amplitude of normal particle velocity (in Pa·s/m).

Positional arguments	Type	Description
`simulation`	`Simulation`	The simulation instance.
Keyword arguments
`physical_group`	`Integer`, `Vector{Integer}`	Physical group ID of the boundary surface.
`specific_acoustic_impedance`	frequency-dependent physical quantity	specific surface acoustic impedance (Pa·s/m).

Examples

Z(f) = 1f + 2im
add_surface_material!(s, physical_group=4, specific_acoustic_impedance=Z)

Multiple physical groups can be assigned at once:
add_surface_material!(s, physical_group=[3,1], specific_acoustic_impedance=1.0)

source

Numav.add_sound_source! — Function

Adds sound sources either at a specific point in space (via coordinates) or over a surface region (via physical_group). Three excitation types are supported: volume_velocity, particle velocity, and pressure.

Positional arguments	Type	Description
`simulation`	`Simulation`	The simulation instance.
Keyword arguments
`coordinates`	`Vector{Real}`, `Vector{Vector{Real}}`	`[x, y, z]` location of a point source in m.
`physical_group`	`Integer`, `Vector{Integer}`	Physical group ID of a surface or volume region.
`volume_velocity`	frequency-dependent physical quantity	Volume velocity in m³/s.
`particle_velocity`	frequency-dependent physical quantity	Normal particle velocity in m/s.
`pressure`	frequency-dependent physical quantity	Acoustic pressure in Pa.

Examples

Volume velocity source (monopole):
Q(f) = 10/f # Volume velocity in m³/s as a function of frequency
add_sound_source!(s, coordinates=[1.0, 1.5, 2.0], volume_velocity=Q)
Suitable for modeling punctual omnidirectional sources.

Particle velocity source (vibrating surface):
U(f) = 15/f # Particle velocity in m/s
add_sound_source!(s, physical_group=2, particle_velocity=U)
Prescribes the normal component of particle velocity on all surfaces of a physical group. Useful for modeling vibrating panels or pistons.

Pressure source:

P(f) = 2f # Pressure in Pa as a function of frequency

# At a point in space
add_sound_source!(s, coordinates=[2.0, 2.5, 1.0], pressure=P)

# On a mesh surface
add_sound_source!(s, physical_group=3, pressure=P)

Prescribes acoustic pressure, either at a point or on a surface.

Multiple points or physical groups can be assigned at once:

p1 = [1.0, 3.0, 2.0]
p2 = [3.0, 1.0, 1.0]
add_sound_source!(s, coordinates=[p1,p2], volume_velocity=0.01)
add_sound_source!(s, physical_group=[3,5,9,2], particle_velocity=0.01)

Note

Each call to add_sound_source! should specify either coordinates or physical_group (not both), and exactly one excitation type keyword.

source

Numav.set_result_export_path! — Function

Specifies the file path where simulation results will be written when calling run!.

Positional arguments	Type	Description
`simulation`	`Simulation`	The simulation instance.
`file_path`	`String`	Result file path (`.h5`).

Examples

set_result_export_path!(s, "result.h5")

source

Numav.run! — Function

Assembles and solves the system of equations for all frequencies in the defined range while writing the results to the specified export path during the solution.

Positional arguments	Type	Description
`simulation`	`Simulation`	The simulation instance.

Examples

run!(s)

Output format

Results are exported as files in the HDF5 format (.h5). It contains all the results and passed inputs to setup the simulation. To read the results, it is recommended to use HDF5.jl or HDFView.

Tip

With HDF5.jl, you can post-process results in Julia like:

using HDF5
r = h5open("result.h5", "r")
# inspect contents

source

Numav.plot_pressure_field — Function

Plots a 3D graph of the pressure field for all space and frequncies.

Positional arguments	Type	Description
`file_path`	`String`	Result file path (`.h5`).
Keyword arguments
`db`	`Bool`	Controls if the plot uses the decibel scale. Defaults to `false`.
`colormap`	`Symbol`	Colors used for the scale. Available options here. Defaults to `:rainbow1`.

Examples

plot_pressure_field("result.h5")

Warning

This function is not accurate for second order elements. The graph shown does not account for the non-vertex nodes.

source

Positional arguments	Type	Description
`simulation`	`Simulation`	The simulation instance.
Keyword arguments
`max`	`Real`	Upper frequency limit (Hz). Required unless `steps` is provided. Mutually exclusive with `steps`.
`min`	`Real`	Lower bound of the frequency range (Hz). Only usable together with `max`. Defaults to `0` if omitted.
`length`	`Integer`	Number of frequency steps to compute within the `min`/`max` range. Only usable together with `max`. Defaults to `4096` if omitted.
`sampling_density`	`Numav.Option`	Sampling strategy to use within the range. Only usable together with `max`. Defaults to `Quadratic` if omitted.
`step`	`Real`	Difference in Hertz between each frequency step, supposing equally spaced steps. Only usable together with `max`. Cannot be used together with `length` and `sampling_density`.
`vector`	`Vector{Real}`	List of frequencies in Hertz to solve at. Cannot be used together with `max`, `min`, `length`, `sampling_density` and `step`.