.. _atr_vibration_contour_plot-label: ============================= Vibration contour plot module ============================= This tool enables vibration simulations to assess the impact of equipment-induced vibrations on the surrounding environment and on sensitive targets. It is developed by the Advanced Technology and Research (ATR) Competence Center at Haskoning as part of the AT&R software package. .. warning:: The Vibration Contour Plot module is currently under active development. Functionality may change in future updates, and formal validation is still pending. Please verify your results carefully before using them in critical applications. Getting Started =============== Before you start with the Vibration Contour Plot module, make sure to install the latest version of the AT&R package. Refer to :ref:`ATR installation guide`. This section introduces the basic workflow for using the vibration contour plot tool. Before diving into an example, here are the core ideas: - **Simulation**: Represents the central simulation tool for the assessment. - **VibrationSource**: Defines the equipment producing vibrations in the assessment. - **Target**: Defines locations to assess for certain vibration limits. Example - Basic Usage --------------------- This example shows the basic usage of the tool. :download:`Example basic usage<_downloads/example_basics.py>` Start the project with the following code: .. code-block:: python from haskoning_atr_tools import ATRProject project = ATRProject(name='My Project', location='Building location', project_code='XXXX') Provide the folder where you want to collect the results from the simulation. .. code-block:: python project.results_folder = rf'C:\Users\xxxxxx\Documents\YourProject\Results' **Step 1 - Define the equipments in the project** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Load the data for the equipments in the project. You can provide the data in the default structure or provide a custom mapping for the data. Use function :py:func:`~haskoning_atr_tools.vibration_contour_plot.equipment.equipment_functions.create_equipments_from_file`. .. code-block:: python project.create_equipments_from_file( file_path=equipment_excel_path, sheet_name='equipments', activity_filter='continuous') The equipment are the sources of the vibrations in the simulation. For these the following properties should be provided (some of the properties are optional). A template for the equipment inputs can be downloaded here (sheet for equipments): :download:`Template equipments<_downloads/template_inputs.xlsx>` .. figure:: _static/excel_equipments.png :alt: Equipments excel :align: center :width: 150% Example Excel for equipment inputs. The inputs in the Excel are described in the following table. .. list-table:: :class: center-second-third :widths: 25 10 10 50 :header-rows: 1 * - Input - Type - Unit - Description * - Name - str - [-] - The name of the equipment. * - ID - int - [-] - The identifier of the equipment. * - Calculate - bool - [-] - Select if the equipment should be used in the calculation. * - X, Y, Z coordinate - float - [m] - The coordinates of the equipment's location. * - Vibration source level - float - [dB] or [m/s] - The source vibration level emitted by the equipment. * - Unit - str - [-] - Specifies the unit of the vibration source level in 'dB' or 'm/s'. * - Center frequency - float - [Hz] - The center frequency of the vibration range the equipment produces. * - Min frequency - float - [Hz] - The minimum frequency of the vibration range the equipment produces. * - Max frequency - float - [Hz] - The maximum frequency of the vibration range the equipment produces. * - Flat noise - float - [%] - Percentage of flat noise added to the vibration signal. * - Activity - str - [-] - Description of the activity or operational state of the equipment. Select from 'continuous', 'intermittent' or 'emergency'. A filter can be applied on the activity column, to only load the equipments active in certain situations for the simulation. .. note:: The vibration source level is always stored in the instance in decibel, [dB]. **Step 2 - Define the targets in the project** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The next step is to load the data for the targets. These are the points of interest, and might be the locations of the vibration sensitive equipments for which the assessment is executed. A template for the target inputs can be downloaded here (sheet for targets): :download:`Template inputs<_downloads/template_inputs.xlsx>` .. figure:: _static/excel_targets.png :alt: Targets excel :align: center Example Excel for target inputs. Use function :py:func:`~haskoning_atr_tools.vibration_contour_plot.target.target_functions.create_targets_from_file` to load the Excel-file with the properties of the targets. This can be the same Excel as the one with the equipments, just specify the correct sheet-name. It is possible to provide a custom mapping for the data. .. code-block:: python project.create_targets_from_file(file_path=target_excel_path, sheet_name='targets') The inputs in the Excel are described in the following table. .. list-table:: :class: center-second-third :widths: 25 10 10 50 :header-rows: 1 * - Input - Type - Unit - Description * - ID - int - [-] - The identifier of the target. * - Calculate - bool - [-] - Select if the target should be used in the calculation. * - X, Y, Z coordinate - float - [m] - The coordinates of the target's location. * - Name - str - [-] - Optional: The name of the target. The targets in the simulation are identified by their ID, name is only used for plotting. * - Category - str - [-] - Optional: The category of the target. This is a property of the specification supplier, but currently not used in the tool. * - Type - str - [-] - Optional: The type is used when adding vibration limits to the target, as these can be specified per type. To add the vibration limits use the following function :py:func:`~haskoning_atr_tools.vibration_contour_plot.target.target_functions.load_target_limits_from_file` to link limits based on the equipment type. .. code-block:: python project.load_target_limits_from_file( file_path=target_limits_excel_path, sheet_name='target_limits', limit_type='velocity') You can specify different limits for the different target types in the model. The name of the limit range is matched to the type names in the model. The limits are added to the target if these match. Currently, only velocity limits have been implemented. A template for the target inputs can be downloaded here (sheet for target_limits): :download:`Template inputs<_downloads/template_inputs.xlsx>` .. figure:: _static/excel_target_limits.png :alt: Target limits excel :align: center Example Excel for target limits inputs. This can be the same Excel as the one with the equipments, just specify the correct sheet-name. It is possible to provide a custom mapping for the data. **Step 3 - Perform simulation** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The simulation requires a mesh, which can be created with the :py:func:`~haskoning_atr_tools.vibration_contour_plot.mesh.generate_mesh.generate_constrained_mesh` function. This function requires the x- and y-range for the plot and the maximum dimension of the mesh-element area (influencing the precision vs performance). The function generates a 2D mesh. .. code-block:: python project.generate_constrained_mesh(x_range=(-100, 800), y_range=(-100, 800), mesh_area=100) The simulation also requires a material definition. Currently only one material can be used in the model. :download:`Template inputs<_downloads/template_inputs.xlsx>` .. figure:: _static/excel_materials.png :alt: Materials excel :align: center Example Excel for material inputs. Use function :py:func:`~haskoning_atr_tools.vibration_contour_plot.simulation.material_functions.create_materials_from_file` to load the Excel-file with the properties of the materials. This can be the same Excel as the one with the equipments, just specify the correct sheet-name. It is possible to provide a custom mapping for the data. .. code-block:: python materials = project.create_materials_from_file(file_path=material_excel_path, sheet_name='materials') The inputs in the Excel are described in the following table. .. list-table:: :class: center-second-third :widths: 25 10 10 50 :header-rows: 1 * - Input - Type - Unit - Description * - Name - str - [-] - The name of the material. * - Density - float - [kg/m3] - Density of the material in the simulation. * - Shear modulus - float - [GPa] - Shear modules of the material in the simulation. * - Poisson's ratio - float - [-] - Poisson's ratio of the material in the simulation. * - Quality factor - float - [-] - Quality factor of the material in the simulation. The mesh and material is combined in the simulation, together with the information on the targets and vibration sources defined in the previous steps. The simulation is created with the :py:func:`~haskoning_atr_tools.vibration_contour_plot.simulation.simulation_functions.create_vibration_simulation` function. .. code-block:: python vibration_simulation = project.create_vibration_simulation( name='vibration_simulation_1', material=materials['sandstone']) Before executing the analysis, the frequency data of the vibration sources should be generated. Execute the :py:func:`~haskoning_atr_tools.vibration_contour_plot.equipment.equipment_functions.create_frequency_domain_data_from_equipments` function to add the frequency data. You need to specify the sampling-rate, which influences the accuracy and performance of the analysis. .. code-block:: python project.create_frequency_domain_data_from_equipments(sampling_rate=1) Then the simulation can be executed with the :py:meth:`~haskoning_atr_tools.vibration_contour_plot.simulation.vibration_simulation.VibrationSimulation.calculate_level_per_node_per_source` method of VibrationSimulation class. Select what amplitude type you want the results in, in this example we use decibel for the vibration level. .. code-block:: python vibration_simulation.calculate_level_per_node_per_source(amplitude_type='decibel') **Step 4 - Assessment of the results** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Generate the spectra at the location of the targets in the simulation in one graph. You can select to generate the plot in velocity (m/s) or vibration-level (dB). The function :py:func:`~haskoning_atr_tools.vibration_contour_plot.plot.plot_functions.plot_f_spectrum_all_targets` can be used for these plots. .. code-block:: python project.plot_f_spectrum_all_targets(amplitude_type='velocity', log_scale_x=True) The user can select to add the vibration requirements and further customise the plot. .. figure:: _static/plot_vibration_level_spectra.png :alt: Spectra example :align: center Example plot of the vibration level spectra at all targets. The contour plots can be generated with the function :py:func:`~haskoning_atr_tools.vibration_contour_plot.plot.plot_functions.plot_contour`. Or the governing contour plot with :py:func:`~haskoning_atr_tools.vibration_contour_plot.plot.plot_functions.plot_governing_contour`. .. code-block:: python project.plot_governing_contour( vibration_simulation=vibration_simulation, amplitude_type='decibel', n_level=15) .. figure:: _static/plot_governing_contour.png :alt: Contour plot example :align: center :width: 80% Example plot of the governing contour plot. The contour plot can also be created per frequency, with the option to align the colour bar: .. code-block:: python project.plot_contour( vibration_simulation=vibration_simulation, amplitude_type='decibel', align_colour_bar=True, n_levels=15, at_frequencies=[10, 20, 40, 60]) .. figure:: _static/plot_contours.png :alt: Contour plot example :align: center Example plot of the contour plot at requested frequencies. Background information ====================== This section provides a brief theoretical overview of vibration simulation concepts to help you better understand the tool’s methods and capabilities. It also supports selecting the most suitable settings for your specific use case. .. toctree:: :maxdepth: 2 theoretical_background References ========== The following sections provide detailed documentation of the available classes, methods, and functions within the vibration contour plot tool. .. toctree:: :maxdepth: 1 code_references