calculation

This package includes central calculation packages for the Helmholtz-Resonator. Includes geometrical descriptions, medium characteristics, acoustic Simulations and parameter management.

Inhalte:

• geometry: Calculation of Volume and validation of the form

• medium: density, ciscosity and speed of sound

• resonator: container for geometry and aperture class

• simulation: Calculation of impedances, absorbtion and q-Factor

• simulation_parameters: Frequenz, Wellenzahl, etc.

• soptimizer:Optimization for target resonance frequency and q-factor

—

calculation.geometry

class calculation.geometry.Geometry(**kwargs)

Bases: HasTraits

Represents the geometry of a Helmholtz resonator, wich function a acoustic cavity. Forms of cylinder and cuboid ar both possible. Calculates and stores the volume based on specified shape and dimensions.

form

Shape of the resonator. Must be either ‘cylinder’ or ‘cuboid’.

Type:

str

x, y, z

Dimensions of the cuboid in meters.

Type:

float or None

radius, height

Dimensions of the cylinder in meters.

Type:

float or None

volume

Calculated volume of the geometry in cubic meters.

Type:

float

classmethod from_dict(data)

Creates a Geometry instance from a dictionary.

Parameters:

data (dict) – Dictionary containing form and dimension fields.

Returns:

A new Geometry instance.

Return type:

Geometry

to_dict()

Converts the geometry instance to a dictionary.

Returns:

Serialized geometry data including form, dimensions, and volume.

Return type:

dict

validate_and_calculate()

Validates input dimensions based on geometry type and calculates volume.

Raises:

TraitError – If required parameters are missing or non-positive.

Class: Geometry

class calculation.geometry.Geometry(**kwargs)

Bases: HasTraits

Represents the geometry of a Helmholtz resonator, wich function a acoustic cavity. Forms of cylinder and cuboid ar both possible. Calculates and stores the volume based on specified shape and dimensions.

form

Shape of the resonator. Must be either ‘cylinder’ or ‘cuboid’.

Type:

str

x, y, z

Dimensions of the cuboid in meters.

Type:

float or None

radius, height

Dimensions of the cylinder in meters.

Type:

float or None

volume

Calculated volume of the geometry in cubic meters.

Type:

float

classmethod from_dict(data)

Creates a Geometry instance from a dictionary.

Parameters:

data (dict) – Dictionary containing form and dimension fields.

Returns:

A new Geometry instance.

Return type:

Geometry

to_dict()

Converts the geometry instance to a dictionary.

Returns:

Serialized geometry data including form, dimensions, and volume.

Return type:

dict

validate_and_calculate()

Validates input dimensions based on geometry type and calculates volume.

Raises:

TraitError – If required parameters are missing or non-positive.

—

calculation.medium

class calculation.medium.Medium(**kwargs)

Bases: HasTraits

Represents the physical properties of the medium (typically air) used in simulations.

Automatically calculates density, speed of sound, and kinematic viscosity based on temperature and humidity if not explicitly provided.

temperature_celsius

Ambient temperature in °C (-50 to 60).

Type:

float

rel_humidity

Relative humidity as a value between 0 and 1.

Type:

float

density

Air density in kg/m³ (calculated or provided).

Type:

float

speed_of_sound

Speed of sound in m/s (calculated or provided).

Type:

float

c

Alias for speed_of_sound.

Type:

float

temperature_kelvin

Temperature in Kelvin.

Type:

float

kinematic_viscosity

Kinematic viscosity of air in m²/s.

Type:

float

calc_density()

Calculates air density using the Magnus equation.

The density is calculated as:

\[\rho = \frac{p - p_v}{R_d \, T} + \frac{p_v}{R_v \, T}\]

where:

• \(p\) atmospheric pressure (Pa)

• \(p_v = \phi \; p_{\mathrm{sat}}\) partial vapor pressure (Pa)

• \(p_{\mathrm{sat}} = 6.112 \, \exp\biggl(\frac{17.62 \, T}{243.12 + T}\biggr) \times 100\) (Pa)

• \(\phi\) relative humidity (0…1)

• \(T\) absolute temperature in Kelvin

• \(R_d = 287.05 \; \mathrm{J/(kg \cdot K)}\) gas constant for dry air

• \(R_v = 461.5 \; \mathrm{J/(kg \cdot K)}\) gas constant for water vapor

Raises: TraitError: If the result is non-positive.

calc_kinematic_viscosity()

Calculates the kinematic viscosity of air using Sutherland’s formula.

The dynamic viscosity :math:mu is calculated using:

\[\]

mu = mu_0 left( frac{T}{T_0} right)^{3/2} cdot frac{T_0 + C}{T + C}

where:

• :math:mu_0 = 1.716 times 10^{-5}text{Pa·s} (reference viscosity),

• :math:T_0 = 273.15text{K} (reference temperature),

• :math:C = 111text{K} (Sutherland’s constant),

• :math:T temperature in Kelvin.

The kinematic viscosity :math:nu is then:

\[\nu = \frac{\mu}{\rho}\]

where :math:rho air density in kg/m³.

calc_speed_of_sound()

Approximates the speed of sound based on DIN ISO 9613-1:1993.

The formula used is:

\[c = 331.3 + 0.606 \,T + 0.0124 \,\phi\]

where:

• \(T\) ambient temperature in °C

• \(\phi\) relative humidity (0…1)

• \(c\) speed of sound in m/s

classmethod from_dict(data)

Creates a Medium instance from a dictionary.

Parameters:

data (dict) – Dictionary with keys matching Medium attributes.

Returns:

A new Medium instance.

Return type:

Medium

to_dict()

Converts the medium’s properties to a dictionary.

Returns:

Dictionary containing all relevant physical parameters.

Return type:

dict

Class: Medium

class calculation.medium.Medium(**kwargs)

Bases: HasTraits

Represents the physical properties of the medium (typically air) used in simulations.

Automatically calculates density, speed of sound, and kinematic viscosity based on temperature and humidity if not explicitly provided.

temperature_celsius

Ambient temperature in °C (-50 to 60).

Type:

float

rel_humidity

Relative humidity as a value between 0 and 1.

Type:

float

density

Air density in kg/m³ (calculated or provided).

Type:

float

speed_of_sound

Speed of sound in m/s (calculated or provided).

Type:

float

c

Alias for speed_of_sound.

Type:

float

temperature_kelvin

Temperature in Kelvin.

Type:

float

kinematic_viscosity

Kinematic viscosity of air in m²/s.

Type:

float

calc_density()

Calculates air density using the Magnus equation.

The density is calculated as:

\[\rho = \frac{p - p_v}{R_d \, T} + \frac{p_v}{R_v \, T}\]

where:

• \(p\) atmospheric pressure (Pa)

• \(p_v = \phi \; p_{\mathrm{sat}}\) partial vapor pressure (Pa)

• \(p_{\mathrm{sat}} = 6.112 \, \exp\biggl(\frac{17.62 \, T}{243.12 + T}\biggr) \times 100\) (Pa)

• \(\phi\) relative humidity (0…1)

• \(T\) absolute temperature in Kelvin

• \(R_d = 287.05 \; \mathrm{J/(kg \cdot K)}\) gas constant for dry air

• \(R_v = 461.5 \; \mathrm{J/(kg \cdot K)}\) gas constant for water vapor

Raises: TraitError: If the result is non-positive.

calc_kinematic_viscosity()

Calculates the kinematic viscosity of air using Sutherland’s formula.

The dynamic viscosity :math:mu is calculated using:

\[\]

mu = mu_0 left( frac{T}{T_0} right)^{3/2} cdot frac{T_0 + C}{T + C}

where:

• :math:mu_0 = 1.716 times 10^{-5}text{Pa·s} (reference viscosity),

• :math:T_0 = 273.15text{K} (reference temperature),

• :math:C = 111text{K} (Sutherland’s constant),

• :math:T temperature in Kelvin.

The kinematic viscosity :math:nu is then:

\[\nu = \frac{\mu}{\rho}\]

where :math:rho air density in kg/m³.

calc_speed_of_sound()

Approximates the speed of sound based on DIN ISO 9613-1:1993.

The formula used is:

\[c = 331.3 + 0.606 \,T + 0.0124 \,\phi\]

where:

• \(T\) ambient temperature in °C

• \(\phi\) relative humidity (0…1)

• \(c\) speed of sound in m/s

classmethod from_dict(data)

Creates a Medium instance from a dictionary.

Parameters:

data (dict) – Dictionary with keys matching Medium attributes.

Returns:

A new Medium instance.

Return type:

Medium

to_dict()

Converts the medium’s properties to a dictionary.

Returns:

Dictionary containing all relevant physical parameters.

Return type:

dict

—

calculation.aperture module

class calculation.aperture.Aperture(**kwargs)

Bases: HasTraits

Models the aperture of a Helmholtz resonator, either as a tube or a slit.

form

Shape of the aperture (‘tube’ or ‘slit’).

Type:

str

length

Length of the aperture.

Type:

float

radius

Radius for ‘tube’ form.

Type:

float

width

Width for ‘slit’ form.

Type:

float

height

Height for ‘slit’ form.

Type:

float

amount

Number of apertures.

Type:

int

inner_ending

Boundary condition inside (‘open’ or ‘flange’).

Type:

str

outer_ending

Boundary condition outside (‘open’ or ‘flange’).

Type:

str

additional_dampening

Whether porous damping is used.

Type:

bool

xi

Damping coefficient (required if damping enabled).

Type:

float

area

Computed cross-sectional area.

Type:

float

inner_end_correction

End correction at inner boundary.

Type:

float

outer_end_correction

End correction at outer boundary.

Type:

float

classmethod from_dict(data)

Creates an Aperture instance from a dictionary.

get_slit_end_correction(x: float, y: float) → float

Calculates end correction for slits using Mechel’s formulation.

Parameters:

• x (float) – Width of slit.

• y (float) – Height of slit.

Returns:

End correction length.

Return type:

float

get_tube_correction(ending)

Returns the empirical end correction for a tube end.

Parameters:

ending (str) – ‘open’ or ‘flange’.

Returns:

End correction length.

Return type:

float

to_dict()

Returns the aperture as a dictionary, including only relevant fields based on form.

Class: Aperture

class calculation.aperture.Aperture(**kwargs)

Bases: HasTraits

Models the aperture of a Helmholtz resonator, either as a tube or a slit.

form

Shape of the aperture (‘tube’ or ‘slit’).

Type:

str

length

Length of the aperture.

Type:

float

radius

Radius for ‘tube’ form.

Type:

float

width

Width for ‘slit’ form.

Type:

float

height

Height for ‘slit’ form.

Type:

float

amount

Number of apertures.

Type:

int

inner_ending

Boundary condition inside (‘open’ or ‘flange’).

Type:

str

outer_ending

Boundary condition outside (‘open’ or ‘flange’).

Type:

str

additional_dampening

Whether porous damping is used.

Type:

bool

xi

Damping coefficient (required if damping enabled).

Type:

float

area

Computed cross-sectional area.

Type:

float

inner_end_correction

End correction at inner boundary.

Type:

float

outer_end_correction

End correction at outer boundary.

Type:

float

classmethod from_dict(data)

Creates an Aperture instance from a dictionary.

get_slit_end_correction(x: float, y: float) → float

Calculates end correction for slits using Mechel’s formulation.

Parameters:

• x (float) – Width of slit.

• y (float) – Height of slit.

Returns:

End correction length.

Return type:

float

get_tube_correction(ending)

Returns the empirical end correction for a tube end.

Parameters:

ending (str) – ‘open’ or ‘flange’.

Returns:

End correction length.

Return type:

float

to_dict()

Returns the aperture as a dictionary, including only relevant fields based on form.

—

calculation.optimizer

class calculation.optimizer.Optimizer(f_target, q_target)

Bases: object

This class optimizes the geometry and aperture to achieve a target resonance frequency and Q factor.

create_default_sim(result) → Simulation

Generates a simulation object from the return value of scipy.optimize.minimize

Parameters:

result (_type_) – result object from minimize

Returns:

Simulation object with given parameters and defaults for rest.

Return type:

Simulation

display_results(sim)

Displays data regarding a given simulation in regards to the target values.

Parameters:

sim (Simulation) – simulation object whose data is to display

generate_initial_set()

Uses f_R approximation function to generate a set of plausible initial values.

objective(vars)

This function is called by the optimizer to evaluate a Helmholtz simulation for the given parameters and returns a penalty for the deviation from the target resonance frequency and Q factor.

Parameters:

vars (list) – geometry and aperture parameters in the order [x, y, z, radius, length, xi].

Returns:

penalized peak value of the simulation result, where a lower value is better.

Return type:

float

run_single_optimization(x0)

tries to optimize the target parameters within the objective function

Parameters:

• x0 (np.array) – initial parameters

• bounds (list) – value boundaries for each parameter

• f_target (float) – target frequency

• q_target (float) – target q-factor

Returns:

optimal parameters, None when optimization failed

Return type:

np.array

search_optimal()

Call this function to start the optimization process. It will try to find the optimal geometry and aperture parameters that achieve the target resonance frequency and Q factor.

Class: Medium

class calculation.medium.Medium(**kwargs)

Bases: HasTraits

Represents the physical properties of the medium (typically air) used in simulations.

Automatically calculates density, speed of sound, and kinematic viscosity based on temperature and humidity if not explicitly provided.

temperature_celsius

Ambient temperature in °C (-50 to 60).

Type:

float

rel_humidity

Relative humidity as a value between 0 and 1.

Type:

float

density

Air density in kg/m³ (calculated or provided).

Type:

float

speed_of_sound

Speed of sound in m/s (calculated or provided).

Type:

float

c

Alias for speed_of_sound.

Type:

float

temperature_kelvin

Temperature in Kelvin.

Type:

float

kinematic_viscosity

Kinematic viscosity of air in m²/s.

Type:

float

calc_density()

Calculates air density using the Magnus equation.

The density is calculated as:

\[\rho = \frac{p - p_v}{R_d \, T} + \frac{p_v}{R_v \, T}\]

where:

• \(p\) atmospheric pressure (Pa)

• \(p_v = \phi \; p_{\mathrm{sat}}\) partial vapor pressure (Pa)

• \(p_{\mathrm{sat}} = 6.112 \, \exp\biggl(\frac{17.62 \, T}{243.12 + T}\biggr) \times 100\) (Pa)

• \(\phi\) relative humidity (0…1)

• \(T\) absolute temperature in Kelvin

• \(R_d = 287.05 \; \mathrm{J/(kg \cdot K)}\) gas constant for dry air

• \(R_v = 461.5 \; \mathrm{J/(kg \cdot K)}\) gas constant for water vapor

Raises: TraitError: If the result is non-positive.

calc_kinematic_viscosity()

Calculates the kinematic viscosity of air using Sutherland’s formula.

The dynamic viscosity :math:mu is calculated using:

\[\]

mu = mu_0 left( frac{T}{T_0} right)^{3/2} cdot frac{T_0 + C}{T + C}

where:

• :math:mu_0 = 1.716 times 10^{-5}text{Pa·s} (reference viscosity),

• :math:T_0 = 273.15text{K} (reference temperature),

• :math:C = 111text{K} (Sutherland’s constant),

• :math:T temperature in Kelvin.

The kinematic viscosity :math:nu is then:

\[\nu = \frac{\mu}{\rho}\]

where :math:rho air density in kg/m³.

calc_speed_of_sound()

Approximates the speed of sound based on DIN ISO 9613-1:1993.

The formula used is:

\[c = 331.3 + 0.606 \,T + 0.0124 \,\phi\]

where:

• \(T\) ambient temperature in °C

• \(\phi\) relative humidity (0…1)

• \(c\) speed of sound in m/s

classmethod from_dict(data)

Creates a Medium instance from a dictionary.

Parameters:

data (dict) – Dictionary with keys matching Medium attributes.

Returns:

A new Medium instance.

Return type:

Medium

to_dict()

Converts the medium’s properties to a dictionary.

Returns:

Dictionary containing all relevant physical parameters.

Return type:

dict

—

calculation.aperture module

class calculation.aperture.Aperture(**kwargs)

Bases: HasTraits

Models the aperture of a Helmholtz resonator, either as a tube or a slit.

form

Shape of the aperture (‘tube’ or ‘slit’).

Type:

str

length

Length of the aperture.

Type:

float

radius

Radius for ‘tube’ form.

Type:

float

width

Width for ‘slit’ form.

Type:

float

height

Height for ‘slit’ form.

Type:

float

amount

Number of apertures.

Type:

int

inner_ending

Boundary condition inside (‘open’ or ‘flange’).

Type:

str

outer_ending

Boundary condition outside (‘open’ or ‘flange’).

Type:

str

additional_dampening

Whether porous damping is used.

Type:

bool

xi

Damping coefficient (required if damping enabled).

Type:

float

area

Computed cross-sectional area.

Type:

float

inner_end_correction

End correction at inner boundary.

Type:

float

outer_end_correction

End correction at outer boundary.

Type:

float

classmethod from_dict(data)

Creates an Aperture instance from a dictionary.

get_slit_end_correction(x: float, y: float) → float

Calculates end correction for slits using Mechel’s formulation.

Parameters:

• x (float) – Width of slit.

• y (float) – Height of slit.

Returns:

End correction length.

Return type:

float

get_tube_correction(ending)

Returns the empirical end correction for a tube end.

Parameters:

ending (str) – ‘open’ or ‘flange’.

Returns:

End correction length.

Return type:

float

to_dict()

Returns the aperture as a dictionary, including only relevant fields based on form.

Class: Aperture

class calculation.aperture.Aperture(**kwargs)

Bases: HasTraits

Models the aperture of a Helmholtz resonator, either as a tube or a slit.

form

Shape of the aperture (‘tube’ or ‘slit’).

Type:

str

length

Length of the aperture.

Type:

float

radius

Radius for ‘tube’ form.

Type:

float

width

Width for ‘slit’ form.

Type:

float

height

Height for ‘slit’ form.

Type:

float

amount

Number of apertures.

Type:

int

inner_ending

Boundary condition inside (‘open’ or ‘flange’).

Type:

str

outer_ending

Boundary condition outside (‘open’ or ‘flange’).

Type:

str

additional_dampening

Whether porous damping is used.

Type:

bool

xi

Damping coefficient (required if damping enabled).

Type:

float

area

Computed cross-sectional area.

Type:

float

inner_end_correction

End correction at inner boundary.

Type:

float

outer_end_correction

End correction at outer boundary.

Type:

float

classmethod from_dict(data)

Creates an Aperture instance from a dictionary.

get_slit_end_correction(x: float, y: float) → float

Calculates end correction for slits using Mechel’s formulation.

Parameters:

• x (float) – Width of slit.

• y (float) – Height of slit.

Returns:

End correction length.

Return type:

float

get_tube_correction(ending)

Returns the empirical end correction for a tube end.

Parameters:

ending (str) – ‘open’ or ‘flange’.

Returns:

End correction length.

Return type:

float

to_dict()

Returns the aperture as a dictionary, including only relevant fields based on form.

—

calculation.resonator module

class calculation.resonator.Resonator(geometry: Geometry, aperture: Aperture)

Bases: object

Combines a geometry and an aperture to define a Helmholtz resonator.

This class acts as a simple data container bundling both a cavity (geometry) and an acoustic opening (aperture).

geometry

The internal volume of the resonator.

Type:

Geometry

aperture

The acoustic aperture (tube or slit).

Type:

Aperture

classmethod from_dict(data: dict) → Resonator

Reconstructs a Resonator instance from a dictionary representation.

Parameters:

data (dict) – Dictionary with ‘geometry’ and ‘aperture’ keys.

Returns:

A new Resonator object with loaded parameters.

Return type:

Resonator

to_dict() → dict

Serializes the Resonator instance into a dictionary format.

Returns:

A dictionary containing serialized geometry and aperture information.

Return type:

dict

Class: Resonator

class calculation.resonator.Resonator(geometry: Geometry, aperture: Aperture)

Bases: object

Combines a geometry and an aperture to define a Helmholtz resonator.

This class acts as a simple data container bundling both a cavity (geometry) and an acoustic opening (aperture).

geometry

The internal volume of the resonator.

Type:

Geometry

aperture

The acoustic aperture (tube or slit).

Type:

Aperture

classmethod from_dict(data: dict) → Resonator

Reconstructs a Resonator instance from a dictionary representation.

Parameters:

data (dict) – Dictionary with ‘geometry’ and ‘aperture’ keys.

Returns:

A new Resonator object with loaded parameters.

Return type:

Resonator

to_dict() → dict

Serializes the Resonator instance into a dictionary format.

Returns:

A dictionary containing serialized geometry and aperture information.

Return type:

dict

—

calculation.simulation

class calculation.simulation.Simulation(resonator: Resonator, sim_params: SimulationParameters)

Bases: object

Represents a full simulation of a Helmholtz resonator.

This class performs acoustic simulations in relationship to geometric and physical properties, including calculation of impedances, absorption behavior, resonance frequency, and Q-factor.

resonator

The Helmholtz resonator configuration.

Type:

Resonator

sim_params

Frequency and medium parameters.

Type:

SimulationParameters

z_porous

Additional impedance from porous damping.

Type:

float

z_radiation

Radiation impedance across frequency range.

Type:

np.array

z_stiff_mass

Stiffness and mass impedance.

Type:

np.array

z_friction

Viscous (friction) impedance.

Type:

np.array

k

Wavenumber.

Type:

np.array

absorbtion_area

Resulting absorption area vs. frequency.

Type:

np.array

absorbtion_area_diffuse

Not used currently.

Type:

np.array

max_absorbtion_area

Theoretical maximum absorption area.

Type:

np.array

q_factor

Calculated Q-factor.

Type:

float

f_q_low

Lower -3 dB frequency point.

Type:

float

f_q_high

Upper -3 dB frequency point.

Type:

float

f_resonance

Calculated resonance frequency.

Type:

float

peak_absorbtion_area

Max absorption at resonance.

Type:

float

calc_absorbtion_area() → array

Computes the absorption area as a function of frequency.

The absorption area A is calculated from the total impedance Z_total and radiation impedance Z_rad in a diffuse field as:

\[A(f) = 2 \; \frac{\Re\{Z_{\text{total}}(f)\}}{\lvert Z_{\text{total}}(f) + Z_{\text{rad}}(f)\rvert^2} \; (2 \rho c)\]

If not assuming diffuse field, includes angle of incidence (theta):

\[A(f) = \frac{\Re\{Z_{\text{total}}(f)\}}{\lvert Z_{\text{total}}(f) + Z_{\text{rad}}(f)\rvert^2} \; \frac{2 \rho c}{\cos(\theta)}\]

where:

• \(Z_{\text{total}} = Z_{\text{friction}} + Z_{\text{porous}} + Z_{\text{stiff\_mass}}\)

• \(Z_{\text{rad}}\) radiation impedance

• \(\rho\) air density (kg/m³)

• \(c\) speed of sound (m/s)

• \(\theta\) angle of incidence (rad)

Returns:

Absorption area vector (m²).

Return type:

np.ndarray

calc_all()

Convenience method to calculate absorption area, resonance frequency, and Q-factor in one step.

calc_max_absorbtion_area(plot: bool = True)

Calculates the theoretical maximum absorption area.

The maximum absorption area A_max as a function of wavelength λ is given by:

\[A_{\mathrm{max}}(\lambda) = \frac{\lambda^2}{2\pi}\]

where:

• \(\lambda\) is the wavelength (m)

• \(A_{\mathrm{max}}\) is the maximum absorption area (m²)

Parameters:

plot (bool) – Whether to plot the curve using a semilogarithmic frequency axis.

calc_q_factor() → float

Calculates the Q factor from the -3 dB bandwidth.

The quality factor Q is defined as:

\[Q = \frac{f_{\mathrm{res}}}{f_2 - f_1}\]

where:

• \(f_{\mathrm{res}}\) resonance frequency (Hz)

• \(f_1\) and \(f_2\) lower and upper -3 dB frequencies, respectively

Returns:

Quality factor (Q), or None if the -3 dB points cannot be determined.

Return type:

float

calc_resonance_frequency_and_peak_area() → float

Determines the resonance frequency and peak absorption value.

The resonance frequency f_res is the frequency at which the absorption area A(f) is maximal:

\[f_{\mathrm{res}} = \operatorname*{arg\,max}_{f}\; A(f)\]

and the peak absorption area is:

\[A_{\mathrm{peak}} = \max_{f} \; A(f)\]

Returns:

(f_resonance in Hz, peak_absorption_area in m²)

Return type:

tuple[float, float]

calc_z_friction() → array

Calculates the real-valued friction impedance from viscosity using:

\[Z_{\text{friction}} = 8 \; \nu \; \rho \; \frac{L}{r^2 \; S}\]

with a cutoff for high frequencies where k r ≥ 0.2:

\[\begin{split}Z_{\text{friction}}(f) = \begin{cases} 8 \; \nu \; \rho \; \dfrac{L}{r^2 \; S}, & k r < 0.2, \\ 0, & k r \ge 0.2. \end{cases}\end{split}\]

where:

• \(\nu\) kinematic viscosity (m²/s)

• \(\rho\) air density (kg/m³)

• \(L\) aperture length (m)

• \(r\) aperture radius (m)

• \(S\) cross-sectional area (m²)

• \(k\) wave number (1/m)

Returns:

Friction impedance vector (Pa·s/m).

Return type:

np.ndarray

calc_z_porous() → float

Calculates the real-valued porous impedance for additional damping.

The impedance is given by:

\[\begin{split}Z_{\text{porous}} = \begin{cases} \dfrac{\xi \; L}{S}, & \text{if additional damping is enabled}, \\ 0, & \text{otherwise}. \end{cases}\end{split}\]

where:

• :math:`xi`damping coefficient

• \(L\) aperture length

• \(S\) cross-sectional area

Returns:

Porous impedance (Pa·s/m) if enabled; otherwise 0.

Return type:

float

calc_z_radiation() → array

Calculates the complex radiation impedance over frequency using:

\[Z_\text{rad}(f) = \rho \; c \; \Bigl(\alpha \, k^2 r^2 + i \; k \, \delta \Bigr)\]

where:

• \(\rho\) air density (kg/m³)

• \(c\) speed of sound (m/s)

• \(k\) wave number (1/m)

• \(r\) aperture radius (m)

• \(\delta\) outer end correction (m)

• :math:`alpha = begin{cases}

  tfrac{1}{4pi}, & text{if open},\ tfrac{1}{2pi}, & text{if flanged}

end{cases}`

Returns:

Radiation impedance vector (Pa·s/m).

Return type:

np.ndarray

calc_z_stiff_mass() → array

Calculates the impedance contribution from stiffness and mass using:

\[Z_{ ext{stiff\_mass}}(\omega) = \frac{\rho \; c^2}{i\,\omega\,V} + i\,\omega\,\rho\,\frac{L + \Delta L}{S}\]

where:

• \(\rho\) air density (kg/m³)

• \(c\) speed of sound (m/s)

• \(\omega\) angular frequency (rad/s)

• \(V\) cavity volume (m³)

• \(L\) effective aperture length (m)

• \(\Delta L\) total end correction (inner + outer) (m)

• \(S\) is the cross-sectional area (m²)

Returns:

np.ndarray: Complex impedance vector (Pa·s/m).

classmethod from_dict(data)

Reconstructs a Simulation instance from dictionary data.

Parameters:

data (dict) – Serialized simulation data.

Returns:

Restored simulation instance.

Return type:

Simulation

plot_absorbtion_area(ion: bool = False)

Plots the absorption area across the frequency range.

Parameters:

ion (bool) – Whether to enable interactive plotting.

to_dict()

Serializes the simulation and results into a dictionary.

Returns:

Serialized simulation data.

Return type:

dict

Class: Simulation

class calculation.simulation.Simulation(resonator: Resonator, sim_params: SimulationParameters)

Bases: object

Represents a full simulation of a Helmholtz resonator.

This class performs acoustic simulations in relationship to geometric and physical properties, including calculation of impedances, absorption behavior, resonance frequency, and Q-factor.

resonator

The Helmholtz resonator configuration.

Type:

Resonator

sim_params

Frequency and medium parameters.

Type:

SimulationParameters

z_porous

Additional impedance from porous damping.

Type:

float

z_radiation

Radiation impedance across frequency range.

Type:

np.array

z_stiff_mass

Stiffness and mass impedance.

Type:

np.array

z_friction

Viscous (friction) impedance.

Type:

np.array

k

Wavenumber.

Type:

np.array

absorbtion_area

Resulting absorption area vs. frequency.

Type:

np.array

absorbtion_area_diffuse

Not used currently.

Type:

np.array

max_absorbtion_area

Theoretical maximum absorption area.

Type:

np.array

q_factor

Calculated Q-factor.

Type:

float

f_q_low

Lower -3 dB frequency point.

Type:

float

f_q_high

Upper -3 dB frequency point.

Type:

float

f_resonance

Calculated resonance frequency.

Type:

float

peak_absorbtion_area

Max absorption at resonance.

Type:

float

calc_absorbtion_area() → array

Computes the absorption area as a function of frequency.

The absorption area A is calculated from the total impedance Z_total and radiation impedance Z_rad in a diffuse field as:

\[A(f) = 2 \; \frac{\Re\{Z_{\text{total}}(f)\}}{\lvert Z_{\text{total}}(f) + Z_{\text{rad}}(f)\rvert^2} \; (2 \rho c)\]

If not assuming diffuse field, includes angle of incidence (theta):

\[A(f) = \frac{\Re\{Z_{\text{total}}(f)\}}{\lvert Z_{\text{total}}(f) + Z_{\text{rad}}(f)\rvert^2} \; \frac{2 \rho c}{\cos(\theta)}\]

where:

• \(Z_{\text{total}} = Z_{\text{friction}} + Z_{\text{porous}} + Z_{\text{stiff\_mass}}\)

• \(Z_{\text{rad}}\) radiation impedance

• \(\rho\) air density (kg/m³)

• \(c\) speed of sound (m/s)

• \(\theta\) angle of incidence (rad)

Returns:

Absorption area vector (m²).

Return type:

np.ndarray

calc_all()

Convenience method to calculate absorption area, resonance frequency, and Q-factor in one step.

calc_max_absorbtion_area(plot: bool = True)

Calculates the theoretical maximum absorption area.

The maximum absorption area A_max as a function of wavelength λ is given by:

\[A_{\mathrm{max}}(\lambda) = \frac{\lambda^2}{2\pi}\]

where:

• \(\lambda\) is the wavelength (m)

• \(A_{\mathrm{max}}\) is the maximum absorption area (m²)

Parameters:

plot (bool) – Whether to plot the curve using a semilogarithmic frequency axis.

calc_q_factor() → float

Calculates the Q factor from the -3 dB bandwidth.

The quality factor Q is defined as:

\[Q = \frac{f_{\mathrm{res}}}{f_2 - f_1}\]

where:

• \(f_{\mathrm{res}}\) resonance frequency (Hz)

• \(f_1\) and \(f_2\) lower and upper -3 dB frequencies, respectively

Returns:

Quality factor (Q), or None if the -3 dB points cannot be determined.

Return type:

float

calc_resonance_frequency_and_peak_area() → float

Determines the resonance frequency and peak absorption value.

The resonance frequency f_res is the frequency at which the absorption area A(f) is maximal:

\[f_{\mathrm{res}} = \operatorname*{arg\,max}_{f}\; A(f)\]

and the peak absorption area is:

\[A_{\mathrm{peak}} = \max_{f} \; A(f)\]

Returns:

(f_resonance in Hz, peak_absorption_area in m²)

Return type:

tuple[float, float]

calc_z_friction() → array

Calculates the real-valued friction impedance from viscosity using:

\[Z_{\text{friction}} = 8 \; \nu \; \rho \; \frac{L}{r^2 \; S}\]

with a cutoff for high frequencies where k r ≥ 0.2:

\[\begin{split}Z_{\text{friction}}(f) = \begin{cases} 8 \; \nu \; \rho \; \dfrac{L}{r^2 \; S}, & k r < 0.2, \\ 0, & k r \ge 0.2. \end{cases}\end{split}\]

where:

• \(\nu\) kinematic viscosity (m²/s)

• \(\rho\) air density (kg/m³)

• \(L\) aperture length (m)

• \(r\) aperture radius (m)

• \(S\) cross-sectional area (m²)

• \(k\) wave number (1/m)

Returns:

Friction impedance vector (Pa·s/m).

Return type:

np.ndarray

calc_z_porous() → float

Calculates the real-valued porous impedance for additional damping.

The impedance is given by:

\[\begin{split}Z_{\text{porous}} = \begin{cases} \dfrac{\xi \; L}{S}, & \text{if additional damping is enabled}, \\ 0, & \text{otherwise}. \end{cases}\end{split}\]

where:

• :math:`xi`damping coefficient

• \(L\) aperture length

• \(S\) cross-sectional area

Returns:

Porous impedance (Pa·s/m) if enabled; otherwise 0.

Return type:

float

calc_z_radiation() → array

Calculates the complex radiation impedance over frequency using:

\[Z_\text{rad}(f) = \rho \; c \; \Bigl(\alpha \, k^2 r^2 + i \; k \, \delta \Bigr)\]

where:

• \(\rho\) air density (kg/m³)

• \(c\) speed of sound (m/s)

• \(k\) wave number (1/m)

• \(r\) aperture radius (m)

• \(\delta\) outer end correction (m)

• :math:`alpha = begin{cases}

  tfrac{1}{4pi}, & text{if open},\ tfrac{1}{2pi}, & text{if flanged}

end{cases}`

Returns:

Radiation impedance vector (Pa·s/m).

Return type:

np.ndarray

calc_z_stiff_mass() → array

Calculates the impedance contribution from stiffness and mass using:

\[Z_{ ext{stiff\_mass}}(\omega) = \frac{\rho \; c^2}{i\,\omega\,V} + i\,\omega\,\rho\,\frac{L + \Delta L}{S}\]

where:

• \(\rho\) air density (kg/m³)

• \(c\) speed of sound (m/s)

• \(\omega\) angular frequency (rad/s)

• \(V\) cavity volume (m³)

• \(L\) effective aperture length (m)

• \(\Delta L\) total end correction (inner + outer) (m)

• \(S\) is the cross-sectional area (m²)

Returns:

np.ndarray: Complex impedance vector (Pa·s/m).

classmethod from_dict(data)

Reconstructs a Simulation instance from dictionary data.

Parameters:

data (dict) – Serialized simulation data.

Returns:

Restored simulation instance.

Return type:

Simulation

plot_absorbtion_area(ion: bool = False)

Plots the absorption area across the frequency range.

Parameters:

ion (bool) – Whether to enable interactive plotting.

to_dict()

Serializes the simulation and results into a dictionary.

Returns:

Serialized simulation data.

Return type:

dict

—

calculation.simulation_parameters module

class calculation.simulation_parameters.SimulationParameters(**traits)

Bases: HasTraits

Contains all parameters related to frequency and medium parameters required for the simulation

This class manages the frequency range, discretization (values per octave), and calculates all dependent physical quantities (angular frequency, wave number, wavelength).

medium

The propagation medium.

Type:

Medium

freq_range

Frequency range for the simulation (min, max).

Type:

Tuple

values_per_octave

Discretization of the frequency axis.

Type:

int

angle_of_incidence

Angle of sound incidence (°). Ignored if assume_diffuse is True.

Type:

float

assume_diffuse

If True, sets angle_of_incidence to 0 and assumes diffuse field.

Type:

bool

frequencies

Frequency vector.

Type:

np.ndarray

omega

Angular frequency (rad/s).

Type:

np.ndarray

k

Wave number (1/m).

Type:

np.ndarray

wavelength

Wavelength (m).

Type:

np.ndarray

calc_k(omega, c)

Calculate the wave number vector based on:

\[\]

k = frac{omega}{c}

Parameters:

• omega (np.ndarray) – Angular frequency (rad/s)

• c (float) – Speed of sound in the medium (m/s)

Returns:

Wave number vector (1/m)

Return type:

np.ndarray

calc_lambda(omega, c)

Calculate wavelength based on:

\[\lambda = \frac{c}{f} = \frac{2\pi\,c}{\omega}\]

Parameters:

• omega (np.ndarray) – Angular frequency vector (rad/s)

• c (float) – Speed of sound in the medium (m/s)

Returns:

Wavelength vector (m)

Return type:

np.ndarray

calc_omega(frequencies)

Calculate angular frequency vector based on:

\[\omega = 2\pi f\]

Parameters:

frequencies (np.ndarray) – Frequency vector (Hz)

Returns:

Angular frequency vector (rad/s)

Return type:

np.ndarray

calculate_frequencies()

Compute the logarithmic frequency vector based on the frequency range and values per octave.

The frequency vector is calculated as:

\[\]

f_i = 10^{log_{10}(f_{min}) + tfrac{i}{N-1}(log_{10}(f_{max}) - log_{10}(f_{min}))},quad i = 0,1,dots,N-1

where:

• \(f_{\min}\) and \(f_{\max}\) frequency range limits

• \(N = \lceil\log_2(\tfrac{f_{\max}}{f_{\min}}) \times \text{values\_per\_octave}\rceil\)

• \(f_i\) logarithmically spaced frequencies

classmethod from_dict(data)

Reconstructs a SimulationParameters instance from a dictionary.

Parameters:

data (dict) – Dictionary with serialized values.

Returns:

A con

Return type:

SimulationParameters

to_dict()

Convert all relevant parameters to a dictionary for serialization.

Returns:

Dictionary representation of the simulation parameters.

Return type:

dict

update()

Recalculate all dependent parameters from the current configuration. Called automatically after initialization and whenever parameters change.

Class: SimulationParameters

class calculation.simulation_parameters.SimulationParameters(**traits)

Bases: HasTraits

Contains all parameters related to frequency and medium parameters required for the simulation

This class manages the frequency range, discretization (values per octave), and calculates all dependent physical quantities (angular frequency, wave number, wavelength).

medium

The propagation medium.

Type:

Medium

freq_range

Frequency range for the simulation (min, max).

Type:

Tuple

values_per_octave

Discretization of the frequency axis.

Type:

int

angle_of_incidence

Angle of sound incidence (°). Ignored if assume_diffuse is True.

Type:

float

assume_diffuse

If True, sets angle_of_incidence to 0 and assumes diffuse field.

Type:

bool

frequencies

Frequency vector.

Type:

np.ndarray

omega

Angular frequency (rad/s).

Type:

np.ndarray

k

Wave number (1/m).

Type:

np.ndarray

wavelength

Wavelength (m).

Type:

np.ndarray

calc_k(omega, c)

Calculate the wave number vector based on:

\[\]

k = frac{omega}{c}

Parameters:

• omega (np.ndarray) – Angular frequency (rad/s)

• c (float) – Speed of sound in the medium (m/s)

Returns:

Wave number vector (1/m)

Return type:

np.ndarray

calc_lambda(omega, c)

Calculate wavelength based on:

\[\lambda = \frac{c}{f} = \frac{2\pi\,c}{\omega}\]

Parameters:

• omega (np.ndarray) – Angular frequency vector (rad/s)

• c (float) – Speed of sound in the medium (m/s)

Returns:

Wavelength vector (m)

Return type:

np.ndarray

calc_omega(frequencies)

Calculate angular frequency vector based on:

\[\omega = 2\pi f\]

Parameters:

frequencies (np.ndarray) – Frequency vector (Hz)

Returns:

Angular frequency vector (rad/s)

Return type:

np.ndarray

calculate_frequencies()

Compute the logarithmic frequency vector based on the frequency range and values per octave.

The frequency vector is calculated as:

\[\]

f_i = 10^{log_{10}(f_{min}) + tfrac{i}{N-1}(log_{10}(f_{max}) - log_{10}(f_{min}))},quad i = 0,1,dots,N-1

where:

• \(f_{\min}\) and \(f_{\max}\) frequency range limits

• \(N = \lceil\log_2(\tfrac{f_{\max}}{f_{\min}}) \times \text{values\_per\_octave}\rceil\)

• \(f_i\) logarithmically spaced frequencies

classmethod from_dict(data)

Reconstructs a SimulationParameters instance from a dictionary.

Parameters:

data (dict) – Dictionary with serialized values.

Returns:

A con

Return type:

SimulationParameters

to_dict()

Convert all relevant parameters to a dictionary for serialization.

Returns:

Dictionary representation of the simulation parameters.

Return type:

dict

update()

Recalculate all dependent parameters from the current configuration. Called automatically after initialization and whenever parameters change.

—

Module contents