.. _theoretical_background_vibration_contour_plot_tool-label:

Theoretical background
======================
This tool computes the target vibration **velocity** levels per frequency using a distance- and frequency-dependent
attenuation model combining geometric spreading and material damping. This document describes the theoretical concepts
the tool uses.

The tool computes vibration level at a target location using a combined **geometric spreading** and **material damping**
model. The attenuation ratio between target and source velocity levels is:

.. math::

   \frac{v_b}{v_a} =
   \left( \frac{r_a}{r_b} \right)^{\gamma}
   \exp\!\big( \rho_B \pi f (r_a - r_b) \big)

where:

- :math:`v_a` = vibration velocity at source distance :math:`r_a`, in [m/s]
- :math:`v_b` = vibration velocity at target distance :math:`r_b`, in [m/s]
- :math:`f` = frequency, in [Hz]
- :math:`\gamma` = geometric spreading exponent, in [-]
- :math:`\rho_B` = Barkan damping parameter, in [s/m]
- :math:`r_a, r_b` = source and target distances, in [m]

Wave types and spreading
------------------------
Ground-borne vibrations in the near-surface are commonly dominated by **Rayleigh waves** and, depending on layering and
frequency, **Love waves**. Idealised geometric spreading describes how amplitude decays due to energy distribution over
expanding wavefronts:

- **Spherical spreading** (body waves in 3D media): :math:`A \propto r^{-2}`
- **Cylindrical spreading** (surface waves along a line source): :math:`A \propto r^{-1}`
- **Layered/heterogeneous media** may exhibit intermediate or frequency-dependent spreading.

The factor :math:`\left(\tfrac{r_a}{r_b}\right)^{\gamma}` captures this phenomenologically, with :math:`\gamma`
calibrated to site conditions. :math:`\gamma=0.5` is used for Rayleigh waves in an ideal half-space because their
geometric spreading is weaker than cylindrical or spherical spreading. It reflects the physics of surface-confined
energy propagation. If your source is traffic on a road (effectively a line source), :math:`\gamma≈1` is common. If you
model a point source on the surface in a homogeneous half-space, :math:`\gamma≈0.5` is theoretically correct. In
reality, soil heterogeneity and damping often push the effective exponent higher (0.7–1.2).

Material damping and frequency dependence
-----------------------------------------
Propagation through soils introduces **intrinsic damping** (hysteretic losses due to internal friction), **scattering**
(from heterogeneities), and **radiation damping** (energy leakage). A simple frequency-dependent attenuation is modeled
by:

.. math::

   A(r_b,f) = A(r_a,f)\,\exp\!\left(-\alpha(f)\,(r_b - r_a)\right),

with :math:`\alpha(f) \propto f` under many practical assumptions. In the implemented form

.. math::

   \exp\!\left(\rho_B \pi f (r_a - r_b)\right),

the exponent is negative when :math:`r_b > r_a`, producing decay that intensifies with both **frequency** and
**path length**. Choosing :math:`\rho_B` so that :math:`\rho_B\, f\, r` is dimensionless (e.g., :math:`\rho_B` in s/m)
ensures physical consistency.

Barkan parameter
^^^^^^^^^^^^^^^^
The frequency-dependent attenuation term uses the **Barkan parameter** :math:`\rho_B`, which controls exponential decay
with distance and frequency:

.. math::

   \exp\!\big(\rho_B \pi f (r_a - r_b)\big)

Two common formulations exist for :math:`\rho_B`:

1. **Basic attenuation model** (from quality factor and wave speed):

   .. math::

      \rho_B = \frac{1}{Q \, v}

   where:
   - :math:`Q` = quality factor, in [-]
   - :math:`v` = wave speed, in [m/s], often shear or Rayleigh wave speed

2. **Barkan-based model** (includes factor 2 for damping ratio):

   .. math::

      \rho_B = \frac{2}{Q \, v}

   This version accounts for the relationship between damping ratio :math:`\xi` and quality factor:

   .. math::

      \xi = \frac{1}{2Q}

   and is widely used in soil vibration engineering following Barkan's approach.