Add dynamic tools

Docs/Dynamic_Tutorial.rst

@@ -0,0 +1,257 @@
+Dynamic Maps - groovy scripts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Many publications have emerged showcasing the use of **NoiseModelling** to create dynamic maps (see `scientific production`_).
+
+.. _scientific production : https://noisemodelling.readthedocs.io/en/latest/Scientific_production.html
+
+If you'd like to achieve similar results but you feel a bit lost, this tutorial is here to help you navigate through the process.
+
+There are three main approaches to creating dynamic maps using NoiseModelling:
+
+1. **A road network with a single traffic flow**  
+   You have a road network and a single traffic flow associated with a specific time period (e.g., 24h). You want to compute dynamic indicators such as **L10**, **L90**, or the **number of events exceeding a threshold** or to get time series for the same time period.
+
+2. **A road network with traffic flows at regular intervals**  
+   You have a road network and traffic flow data available at regular intervals (e.g., hourly or every 15 minutes), and you want to generate a dynamic noise map every 15 min.
+
+3. **A road network with associated spatio-temporal data of moving sources**
+   You have spatio-temporal information about vehicles moving around a network (e.g., from traffic simulations such as Simuvya or SUMO; or from trajectories of drones). You want to compute **time-series data at each receiver** corresponding to the passage of these sources.
+
+A Word of Caution
+-----------------
+
+**Caution** : In all these cases, we assume that the **sound attenuation between the source and receiver remains constant throughout the calculation**. This is a strong approximation, and there are ways to account for variations, but this tutorial will not cover such specific cases.
+
+Dynamic mapping has its subtleties, and it's important to be aware of them to avoid errors. We recommend referring to the following documents for a better understanding of these concepts:
+
+- Can, A., & Aumond, P. (2018). Estimation of road traffic noise emissions: The influence of speed and acceleration. Transportation Research Part D: Transport and Environment, 58, 155-171.
+- Gozalo, G. R., Aumond, P., & Can, A. (2020). Variability in sound power levels: Implications for static and dynamic traffic models. Transportation Research Part D: Transport and Environment, 84, 102339.
+- Le Bescond, V., Can, A., Aumond, P., & Gastineau, P. (2021). Open-source modeling chain for the dynamic assessment of road traffic noise exposure. Transportation Research Part D: Transport and Environment, 94, 102793.
+
+This is an **advanced tutorial**, so you may need to open the Groovy scripts to see what’s under the hood. Assumptions are freely made, specific formats are expected, and so on. To understand the required data formats and check the expected structure of the input tables, please refer also to the example input tables and spatial layers!
+
+Study Cases
+---------------
+
+Case 1: A Road Network with a Single Traffic Flow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: groovy
+
+         // Import the road network (with predicted traffic flows) and buildings from an OSM file
+        new Import_OSM().exec(connection, [
+                "pathFile"      : TestImportExport.getResource("map.osm.gz").getPath(),
+                "targetSRID"    : 2154,
+                "ignoreGround"  : true,
+                "ignoreBuilding": false,
+                "ignoreRoads"   : false,
+                "removeTunnels" : true
+        ]);
+
+        // Create a receiver grid
+        new Regular_Grid().exec(connection,  ["buildingTableName": "BUILDINGS",
+                                              "sourcesTableName" : "ROADS",
+                                              "delta"            : 25])
+
+        // Set a height to the receivers at 1.5 m
+        new Set_Height().exec(connection,
+                [ "tableName":"RECEIVERS",
+                  "height": 1.5
+                ])
+
+        // From the network with traffic flow to individual trajectories with associated Lw using the Probabilistic method
+        // This method place randomly the vehicles on the network according to the traffic flow
+        new Flow_2_Noisy_Vehicles().exec(connection,
+                ["tableRoads": "ROADS",
+                 "method": "PROBA",
+                 "timestep": 1,
+                 "gridStep" : 10,
+                 "duration" : 60])
+
+        // From the network with traffic flow to individual trajectories with associated Lw using the Poisson method
+        // This method place the vehicles on the network according to the traffic flow following a poisson law
+        // It keeps a coherence in the time series of the noise level
+        new Flow_2_Noisy_Vehicles().exec(connection,
+                ["tableRoads": "ROADS",
+                 "method": "POISSON",
+                 "timestep": 1,
+                 "gridStep" : 10,
+                 "duration" : 60])
+
+        // Compute the attenuation noise level from the network sources (SOURCES_0DB) to the receivers
+        new Noise_level_from_source().exec(connection,
+                ["tableBuilding"   : "BUILDINGS",
+                 "tableSources"   : "SOURCES_0DB",
+                 "tableReceivers": "RECEIVERS",
+                 "maxError" : 0.0,
+                 "confMaxSrcDist" : 150,
+                 "confDiffHorizontal" : false,
+                 "confExportSourceId": true,
+                 "confSkipLday":true,
+                 "confSkipLevening":true,
+                 "confSkipLnight":true,
+                 "confSkipLden":true
+                ])
+
+        // Compute the noise level from the moving vehicles to the receivers
+        // the output table is called here LT_GEOM and contains the time series of the noise level at each receiver
+        new Noise_From_Attenuation_Matrix().exec(connection,
+                ["lwTable"   : "LW_DYNAMIC_GEOM",
+                 "attenuationTable"   : "LDAY_GEOM",
+                 "outputTable"   : "LT_GEOM"
+                ])
+
+        // This step is optional, it compute the LEQA, LEQ, L10, L50 and L90 at each receiver from the table LT_GEOM
+        new DynamicIndicators().exec(connection,
+                ["tableName"   : "LT_GEOM",
+                 "columnName"   : "LEQA"
+                ])
+
+
+Case 2: A Road Network with Traffic Flows at Regular Intervals
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This case is similar to the **MATSim** use case (`here <Matsim_Tutorial.rst>`_), but this tutorial generalizes the approach to fit other datasets.
+
+.. code-block:: groovy
+
+         // Import Buildings for your study area
+        new Import_File().exec(connection,
+                ["pathFile" :  TestDatabaseManager.getResource("Dynamic/Z_EXPORT_TEST_BUILDINGS.geojson").getPath() ,
+                 "inputSRID": "2154",
+                 "tableName": "buildings"])
+
+        // Import the road network
+        new Import_File().exec(connection,
+                ["pathFile" :TestDatabaseManager.getResource("Dynamic/Z_EXPORT_TEST_TRAFFIC.geojson").getPath() ,
+                 "inputSRID": "2154",
+                 "tableName": "ROADS"])
+
+        // Create a receiver grid
+        new Regular_Grid().exec(connection,  ["buildingTableName": "BUILDINGS",
+                                              "sourcesTableName" : "ROADS",
+                                              "delta"            : 25])
+
+        // Set a height to the receivers at 1.5 m
+        new Set_Height().exec(connection,
+                [ "tableName":"RECEIVERS",
+                  "height": 1.5
+                ])
+
+        // From the network with traffic flow to individual trajectories with associated Lw using the Probabilistic method
+        // This method place randomly the vehicles on the network according to the traffic flow
+        new Road_Emission_from_Traffic().exec(connection,
+                ["tableRoads": "ROADS",
+                "Mode" : "dynamic"])
+
+
+        // Compute the attenuation noise level from the network sources (SOURCES_0DB) to the receivers
+        new Noise_level_from_source().exec(connection,
+                ["tableBuilding"   : "BUILDINGS",
+                 "tableSources"   : "SOURCES_0DB",
+                 "tableReceivers": "RECEIVERS",
+                 "maxError" : 0.0,
+                 "confMaxSrcDist" : 150,
+                 "confDiffHorizontal" : false,
+                 "confExportSourceId": true,
+                 "confSkipLday":true,
+                 "confSkipLevening":true,
+                 "confSkipLnight":true,
+                 "confSkipLden":true
+                ])
+
+        // Compute the noise level from the moving vehicles to the receivers
+        // the output table is called here LT_GEOM and contains the noise level at each receiver for the whole timesteps
+        new Noise_From_Attenuation_Matrix().exec(connection,
+                ["lwTable"   : "LW_ROADS",
+                 "lwTable_sourceId" : "LINK_ID",
+                 "attenuationTable"   : "LDAY_GEOM",
+                 "outputTable"   : "LT_GEOM"
+                ])
+
+The toy dataset used in this example was kindly provide by Valentin Lebescond from Université Gustave Eiffel.
+
+Case 3: Spatio-Temporal Data of Moving Sources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: groovy
+
+        // Import Buildings for your study area
+        new Import_File().exec(connection,
+                ["pathFile" :  TestDatabaseManager.getResource("Dynamic/buildings_nm_ready_pop_heights.shp").getPath() ,
+                 "inputSRID": "32635",
+                 "tableName": "buildings"])
+
+        // Import the receivers (or generate your set of receivers using Regular_Grid script for example)
+        new Import_File().exec(connection,
+                ["pathFile" : TestDatabaseManager.getResource("Dynamic/receivers_python_method0_50m_pop.shp").getPath() ,
+                 "inputSRID": "32635",
+                 "tableName": "receivers"])
+
+        // Set the height of the receivers
+        new Set_Height().exec(connection,
+                [ "tableName":"RECEIVERS",
+                  "height": 1.5
+                ])
+
+        // Import the road network
+        new Import_File().exec(connection,
+                ["pathFile" :TestDatabaseManager.getResource("Dynamic/network_tartu_32635_.geojson").getPath() ,
+                 "inputSRID": "32635",
+                 "tableName": "network_tartu"])
+
+        // (optional) Add a primary key to the road network
+        new Add_Primary_Key().exec(connection,
+                ["pkName" :"PK",
+                 "tableName": "network_tartu"])
+
+        // Import the vehicles trajectories
+        new Import_File().exec(connection,
+                ["pathFile" : TestDatabaseManager.getResource("Dynamic/SUMO.geojson").getPath() ,
+                 "inputSRID": "32635",
+                 "tableName": "vehicle"])
+
+        // Create point sources from the network every 10 meters. This point source will be used to compute the noise attenuation level from them to each receiver.
+        // The created table will be named SOURCES_0DB
+        new Point_Source_0dB_From_Network().exec(connection,
+                ["tableRoads": "network_tartu",
+                 "gridStep" : 10
+                ])
+
+        // Compute the attenuation noise level from the network sources (SOURCES_0DB) to the receivers
+        new Noise_level_from_source().exec(connection,
+                ["tableBuilding"   : "BUILDINGS",
+                 "tableSources"   : "SOURCES_0DB",
+                 "tableReceivers": "RECEIVERS",
+                 "maxError" : 0.0,
+                 "confMaxSrcDist" : 150,
+                 "confDiffHorizontal" : false,
+                 "confExportSourceId": true,
+                 "confSkipLday":true,
+                 "confSkipLevening":true,
+                 "confSkipLnight":true,
+                 "confSkipLden":true
+                ])
+
+        // Create a table with the noise level from the vehicles and snap the vehicles to the discretized network
+        new Ind_Vehicles_2_Noisy_Vehicles().exec(connection,
+                ["tableVehicles": "vehicle",
+                "distance2snap" : 30,
+                "fileFormat" : "SUMO"])
+
+        // Compute the noise level from the moving vehicles to the receivers
+        // the output table is called here LT_GEOM and contains the time series of the noise level at each receiver
+        new Noise_From_Attenuation_Matrix().exec(connection,
+                ["lwTable"   : "LW_DYNAMIC_GEOM",
+                 "attenuationTable"   : "LDAY_GEOM",
+                 "outputTable"   : "LT_GEOM"
+                ])
+
+        // this step is optional, it compute the LEQA, LEQ, L10, L50 and L90 at each receiver from the table LT_GEOM
+        new DynamicIndicators().exec(connection,
+                ["tableName"   : "LT_GEOM",
+                 "columnName"   : "LEQA"
+                ])
+
+The toy dataset was kindly provide by Sacha Baclet from KTH (0000-0003-2114-8680).

Docs/Scientific_production.rst

@@ -8,14 +8,11 @@ Below is a non-exhaustive list of articles or presentations in which NoiseModell
 Standard Noise maps
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-BACLET S., VENKATARAMAN S., RUMPLER R., BILLSJÖ R., HORVATH J., ÖSTERLUND P. E., , `From strategic noise maps to receiver-centric noise exposure sensitivity mapping <https://www.sciencedirect.com/science/article/pii/S1361920921004089>`_, Transportation Research Part D: Transport and Environment, 2022, vol. 102 *(Noise mapping, Road traffic noise, Population exposure, Road network sensitivity)*
 
 GRAZIUSO G., FRANCAVILLA A. B., MANCINI S., GUARNACCIA C., `Open-source software tools for strategic noise mapping: a case study <https://iopscience.iop.org/article/10.1088/1742-6596/2162/1/012014>`_, Journal of Physics: Conference Series, 2022, vol. 2162, 012014
 
 AUMOND P., BOCHER E., ECOTIERE D., FORTIN N., GAUVREAU B., GUILLAUME G., PETIT G., `Improvement of city noise map production processes and sensitivity analysis to noise models inputs <http://www.sea-acustica.es/fileadmin/Madeira21/ID122.pdf>`_, Euronoise Conference Proceedings, 2021, p. 1128
 
-BACLET S., VENKATARAMAN S., RUMPLER R., `A methodology to assess the impact of driving noise from individual vehicles in an urban environment <http://axaco.s3.amazonaws.com/uploads/2021/06/07/MIHmJYsH/rev2021-032.pdf>`_, Resource Efficient Vehicles Conference, 2021.
-
 NOURMOHAMMADI Z., LILASATHAPORNKIT T., ASHFAQ M., et al., `Mapping Urban Environmental Performance with Emerging Data Sources: A Case of Urban Greenery and Traffic Noise in Sydney, Australia <https://www.mdpi.com/2071-1050/13/2/605>`_, Sustainability, 2021, vol. 13, n° 2, p. 605
 
 BAEZA J. L., SIEVERT J. L., LANDWEHR A., et al., `CityScope Platform for Real-Time Analysis and Decision-Support in Urban Design Competitions <https://www.igi-global.com/article/cityscope-platform-for-real-time-analysis-and-decision-support-in-urban-design-competitions/278826>`_, International Journal of E-Planning Research (IJEPR), 2021, vol. 10, n° 4, p. 1-17
@@ -28,6 +25,12 @@ AUMOND P., FORTIN N., CAN A., `Overview of the NoiseModelling open-source softwa
 Dynamic Noise maps
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+MONTENEGRO, A. L., MELLUSO, D., STASI, G., PANCI, A., BOLOGNESE, M., PALAZZUOLI, D., ... & LICITRA, G., `An open-source pipeline in noise modelling and noise exposure reduction in a port city.<https://www.researchgate.net/profile/Alexandra-Montenegro/publication/382072874_An_open-source_pipeline_in_noise_modelling_and_noise_exposure_reduction_in_a_port_city/links/668bdf59f3b61c4e2cb7e962/An-open-source-pipeline-in-noise-modelling-and-noise-exposure-reduction-in-a-port-city.pdf>`_, In Proceedings of the 30th International Congress on Sound and Vibration (ICSV30), 2024.
+
+BACLET S., VENKATARAMAN S., RUMPLER R., BILLSJÖ R., HORVATH J., ÖSTERLUND P. E., `From strategic noise maps to receiver-centric noise exposure sensitivity mapping <https://www.sciencedirect.com/science/article/pii/S1361920921004089>`_, Transportation Research Part D: Transport and Environment, 2022, vol. 102 *(Noise mapping, Road traffic noise, Population exposure, Road network sensitivity)*
+
+BACLET S., VENKATARAMAN S., RUMPLER R., `A methodology to assess the impact of driving noise from individual vehicles in an urban environment <http://axaco.s3.amazonaws.com/uploads/2021/06/07/MIHmJYsH/rev2021-032.pdf>`_, Resource Efficient Vehicles Conference, 2021.
+
 LE BESCOND V., CAN A., AUMOND P., GASTINEAU P., `Open-source modeling chain for the dynamic assessment of road traffic noise exposure <https://www.sciencedirect.com/science/article/pii/S1361920921000973>`_, Transportation Research Part D: Transport and Environment, 2021, vol. 94, 102793 (Watch a `short presentation <https://youtu.be/jNCG0qQrsrE>`_ on Youtube)
 
 CAN A., AUMOND P., BECARIE, C., LECLERCQ, L., `Dynamic approach for the study of the spatial impact of road traffic noise at peak hours <https://pub.dega-akustik.de/ICA2019/data/articles/000646.pdf>`_, Proceedings of the 23rd International Congress on Acoustics, Aachen, Allemagne, 09-13 September, 2019

Docs/index.rst

@@ -160,6 +160,7 @@ Fundings
     Noise_Map_From_OSM_Tutorial
     Noise_Map_From_Point_Source
     Matsim_Tutorial
+    Dynamic_Tutorial
     Get_Started_Script
     Tutorials_FAQ