.. _atr_dynamics-label:

===============
Dynamics module
===============
The dynamics module contains functionality for dynamical analyses. You can use the functionality by importing the
dynamics module:

.. code-block:: python

    from haskoning_atr_tools.dynamics import *

Wave speed
==========
The function :py:func:`~haskoning_atr_tools.dynamics.generic_formulas.calculate_wave_speed` is available to calculate
the speed of a wave in a solid material. The speed of a wave is fixed by the type of wave and the physical properties of
the medium in which it travels. For transverse waves in a solid (earthquake S-waves) the speed, in [m/s], is determined
by:

.. code-block:: python

    print(calculate_wave_speed(E=210e9, nu=0.3, density=7850))
    >>> 5421.932703208199

The formula used for the calculation is:

.. math::

   v = \sqrt{\frac{E}{\rho (1 - \nu^2)}}

where:

  - :math:`v` is the wave speed [m/s],
  - :math:`E` is the Young’s modulus [N/m²],
  - :math:`\rho` is the density [kg/m³],
  - :math:`\nu` is Poisson’s ratio [-]

Wavelength
==========
The function :py:func:`~haskoning_atr_tools.dynamics.generic_formulas.calculate_wavelength` is available to calculate
the length of the wave. There is a relationship between the period, wavelength and speed of the wave. The period of a
cork floating in the water is affected by how fast the wave passes (wave speed) and the distance between peaks
(wavelength). The relationship between speed, period and wavelength of a sine wave is given by :math:`v = \lambda/T`
where wavelength [m] and period for a sine wave were defined previously. This can also be written as
:math:`v = \lambda f` since frequency [Hz] is the inverse of period and is true for all linear waves.

Hence, the wavelength, in [m], is given by:

.. code-block:: python

    print(calculate_wavelength(E=210E+9, nu=0.3, density=7800, frequency=50))
    >>> 108.78565864408424

The formula used in the calculation is:

.. math::

   \lambda = \frac{v}{f}

where:

  - :math:`\lambda` is the wavelength [m],
  - :math:`v` is the wave speed [m/s],
  - :math:`f` is the frequency [Hz].

Maximum mesh size
=================
In Finite Element Analysis (FEA), the maximum mesh size (h) depends on the specific requirements of your analysis and
the level of accuracy you need. Generally, the mesh size should be small enough to capture the critical details of the
geometry and the expected stress or strain gradients.

The formula used in the calculation of
:py:func:`~haskoning_atr_tools.dynamics.generic_formulas.calculate_maximum_mesh_element_size` is:

.. math::

   h = \lambda/n

where:

  - :math:`n` is the minimum number of divisions.

The minimal number of divisions per wavelength is a crucial factor in determining the mesh element size for accurate
simulations. This number depends on several factors:

- geometry_complexity (float): A factor representing the complexity of the geometry. This can be quantified by analysing
  the number of features, edges, and faces in the geometry. More complex geometries with intricate details will have
  higher values. `LINK <https://www.cad-journal.net/files/vol_7/CAD_7%285%29_2010_685-700.pdf>`__
- material_property (float): A factor representing the material properties. This factor can be derived from the
  material’s mechanical properties such as Young’s modulus, Poisson’s ratio, and density. These properties are often
  available in material property databases or engineering handbooks.
  `LINK <https://www.comsol.com/blogs/damping-in-structural-dynamics-theory-and-sources>`__
- physics_factor (float): A factor representing the physics of the problem. This depends on the type of physical
  phenomena being modeled. For example, in structural analysis, this could relate to the type of loading conditions
  (static, dynamic, thermal). The more complex the physical interactions, the higher the value.
- accuracy_requirement (float): A factor representing the accuracy requirements. This is determined by the precision
  needed for the analysis. Higher accuracy requirements will result in higher values.
  `LINK <https://enterfea.com/correct-mesh-size-quick-guide/>`__
- computational_resource (float): A factor representing the available computational resources. This factor is based on
  the available computational power, such as the number of processors, memory, and computational time. However, a higher
  number of elements used will increase the demand for computational resources such as memory and processor time.
  `LINK <https://www.simscale.com/blog/fea-for-beginners/>`__

Hence, the minimum number of divisions can be calculated considering all those factors in
:py:func:`~haskoning_atr_tools.dynamics.generic_formulas.calculate_minimum_divisions`:

.. code-block:: python

    print(calculate_minimum_divisions(
        geometry_complexity=2.0, material_property=2.0, physics_factor=2.0, accuracy_requirement=2.0,
        computational_resource=2.0))
    >>> 8

But a common guideline is to have the minimum division number equal to 8. Example of a calculation of maximum mesh size
for steel with Young's modulus of 210e9 N/m², Poisson's ratio nu of 0.3  and density of 7800 kg/m³. The frequency of the
wave of 50 Hz and minimum divisions taken as default (8 divisions). The maximum mesh element size, in [m], is:

.. code-block:: python

    print(calculate_maximum_mesh_element_size(E=210e9, nu=0.3, density=7800, frequency=50))
    >>> 13.59820733051053

Reference
=========
This is the documentation of the functions in the dynamics module.

.. automodule:: haskoning_atr_tools.dynamics.generic_formulas
   :members: