iso_1996 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58b7aaecfa7460bb341e22d3fdd31cbf0c0463c7dd757324f24d61cabf955051
+  data.tar.gz: e01c3447842cd52d511ac7205cbc9f3191ac2cece2249c2bcbc6ceef6aa60e48
+SHA512:
+  metadata.gz: d3623c9060b7b78c180325fea3150a92b63ab903c5ae516553a5d3cffa49613879511a7bd63e4e513d60ab1766d0e30a189775e272a2b0e8a06d7898a12623cb
+  data.tar.gz: 44fd1b43650fbb939d30bd15f21e846035867147a3493b30a1ac702e6a96093c986d8b5b523328497d6d2744c609b7f4f361b22cd9df054169b16c216847dd6b

data/README.md

@@ -0,0 +1,43 @@
+
+# ISO 1996 - Acoustics — Description, measurement and assessment of environmental noise Ruby gem.
+
+[![Gem Version](https://badge.fury.io/rb/iso_1996.svg)](https://badge.fury.io/rb/iso_1996)
+[![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue)](https://rubydoc.info/gems/iso_1996)
+
+Ruby implementation of ISO 1996 - Acoustics — Description, measurement and assessment of environmental noise.
+
+## Features
+
+- Complete implementation of all three parts of ISO 1996
+- Fully documented with RDoc comments
+- Comprehensive test suite
+- MIT licensed
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'iso_1996'
+```
+
+Or install directly:
+
+```bash
+gem install iso_1996
+```
+
+## Documentation
+Full documentation available at:
+https://rubydoc.info/gems/iso_1996
+
+## Contributing
+Bug reports and pull requests are welcome on GitHub at:
+https://github.com/yourusername/iso_1996
+
+## License
+The gem is available as open source under the terms of the MIT License.
+
+## Author
+Maciej Ciemborowicz
+July 11, 2025

data/lib/iso_1996/basic.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ISO_1996
+
+  ##
+  # == ISO 1996-1:2003 Basic Quantities and Assessment Procedures
+  #
+  # Module implementing calculations defined in ISO 1996-1:2003:
+  # "Acoustics - Description, measurement and assessment of environmental noise - 
+  # Part 1: Basic quantities and assessment procedures"
+  #
+  # Author:: Maciej Ciemborowicz
+  # Date:: July 11, 2025
+  #
+  module Basic
+    ##
+    # Constants defined in ISO 1996-1:2003 standard
+    module Constants
+      ##
+      # Reference sound pressure (p₀) as defined in Section 3.1
+      # Value: 20 μPa (20e-6 Pa)
+      REFERENCE_SOUND_PRESSURE = 20e-6 # Pa
+
+      ##
+      # Reference time (t₀) for sound exposure level as defined in Section 3.9
+      # Value: 1 second
+      REFERENCE_TIME = 1.0 # s
+    end
+    include Constants
+
+    ##
+    # Calculate sound pressure level (L_p) as defined in Section 3.2
+    #
+    # L_p = 10 * log10(p² / p₀²) dB
+    #
+    # @param p [Float] Root-mean-square sound pressure (Pa)
+    # @return [Float] Sound pressure level in dB
+    #
+    # Example:
+    #   Basic.sound_pressure_level(0.1) # => 74.0 dB
+    #
+    def self.sound_pressure_level(p)
+      10 * Math.log10((p ** 2) / (Constants::REFERENCE_SOUND_PRESSURE ** 2))
+    end
+
+    ##
+    # Calculate A-weighted sound pressure level (L_A) as defined in Section 3.2
+    #
+    # L_A = 10 * log10( (1/T) * ∫(p_A²(t)/p₀²) dt ) dB
+    #
+    # @param p_a [Float] A-weighted sound pressure (Pa)
+    # @param measurement_time [Float] Measurement time interval (seconds)
+    # @return [Float] A-weighted sound pressure level in dB
+    #
+    def self.a_weighted_sound_pressure_level(p_a, measurement_time: 1.0)
+      10 * Math.log10((1.0 / measurement_time) * (p_a ** 2) / (Constants::REFERENCE_SOUND_PRESSURE ** 2))
+    end
+
+    ##
+    # Calculate sound exposure level (L_AE) as defined in Section 3.9
+    #
+    # L_AE = 10 * log10( (1/t₀) * ∫(p_A²(t)/p₀²) dt ) dB
+    #
+    # @param p_a [Float] A-weighted sound pressure (Pa)
+    # @return [Float] Sound exposure level in dB
+    #
+    def self.sound_exposure_level(p_a)
+      10 * Math.log10((1.0 / Constants::REFERENCE_TIME) * (p_a ** 2) / (Constants::REFERENCE_SOUND_PRESSURE ** 2))
+    end
+
+    ##
+    # Calculate equivalent continuous sound level (L_Aeq,T) as defined in Section 3.7
+    #
+    # L_Aeq,T = 10 * log10( (1/T) * Σ(10^(0.1*L_i)) ) dB
+    #
+    # @param levels [Array<Float>] Array of sound pressure levels (dB)
+    # @param measurement_time [Float] Total measurement time (seconds)
+    # @return [Float] Equivalent continuous sound level in dB
+    #
+    # Example:
+    #   levels = [65.0, 67.0, 63.0]
+    #   Basic.equivalent_continuous_sound_level(levels, 3.0) # => ~65.1 dB
+    #
+    def self.equivalent_continuous_sound_level(levels, measurement_time)
+      raise ArgumentError, "Measurement time must be positive" if measurement_time <= 0
+      
+      return -Float::INFINITY if levels.empty?
+
+      energy_sum = levels.sum { |l| 10 ** (l / 10.0) }
+      10 * Math.log10(energy_sum / measurement_time)
+    end
+
+    ##
+    # Calculate C-weighted peak sound pressure level (L_Cpeak) as defined in Section 3.10
+    #
+    # L_Cpeak = 20 * log10(p_Cmax / p₀) dB
+    #
+    # @param p_c_max [Float] Maximum C-weighted sound pressure (Pa)
+    # @return [Float] C-weighted peak sound pressure level in dB
+    #
+    def self.peak_sound_pressure_level(p_c_max)
+      20 * Math.log10(p_c_max / Constants::REFERENCE_SOUND_PRESSURE)
+    end
+  end
+end

data/lib/iso_1996/environmental_noise.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module ISO_1996
+
+  ##
+  # == ISO 1996-2:2007 Determination of Sound Pressure Levels
+  #
+  # Module implementing calculations defined in ISO 1996-2:2007:
+  # "Acoustics - Description, measurement and assessment of environmental noise - 
+  # Part 2: Determination of sound pressure levels"
+  #
+  # Author:: Maciej Ciemborowicz
+  # Date:: July 11, 2025
+  #
+  module EnvironmentalNoise
+    ##
+    # Constants defined in ISO 1996-2:2007 standard
+    module Constants
+      ##
+      # Minimum level difference for background correction (ΔL_min) as defined in Section 6.3
+      # Value: 3 dB
+      MIN_BACKGROUND_LEVEL_DIFFERENCE = 3.0 # dB
+
+      ##
+      # Threshold for background correction (ΔL_threshold) as defined in Section 6.3
+      # Value: 10 dB
+      BACKGROUND_CORRECTION_THRESHOLD = 10.0 # dB
+    end
+    include Constants
+
+    ##
+    # Calculate background noise correction (K₁) as defined in Section 6.3 and Annex D
+    #
+    # K₁ = -10 * log10(1 - 10^(-0.1 * ΔL)) dB
+    # where ΔL = L_total - L_background
+    #
+    # @param l_total [Float] Total sound pressure level (dB)
+    # @param l_background [Float] Background sound pressure level (dB)
+    # @return [Float] Background noise correction in dB
+    # @raise [ArgumentError] if ΔL ≤ 3 dB (measurement uncertain)
+    #
+    # Example:
+    #   EnvironmentalNoise.background_noise_correction(65, 60) # => 1.7 dB
+    #
+    def self.background_noise_correction(l_total, l_background)
+      delta_l = l_total - l_background
+
+      if delta_l <= Constants::MIN_BACKGROUND_LEVEL_DIFFERENCE
+        raise ArgumentError, "Measurement uncertain: ΔL ≤ #{Constants::MIN_BACKGROUND_LEVEL_DIFFERENCE} dB"
+      elsif delta_l >= Constants::BACKGROUND_CORRECTION_THRESHOLD
+        0.0
+      else
+        -10 * Math.log10(1 - 10 ** (-0.1 * delta_l))
+      end
+    end
+
+    ##
+    # Calculate atmospheric absorption correction (A_atm) as defined in Section 7.3 and Annex A
+    #
+    # A_atm = α * d dB
+    #
+    # @param attenuation_coefficient [Float] Atmospheric attenuation coefficient (dB/m)
+    # @param propagation_distance [Float] Sound propagation distance (m)
+    # @return [Float] Atmospheric absorption correction in dB
+    #
+    def self.atmospheric_absorption_correction(attenuation_coefficient, propagation_distance)
+      attenuation_coefficient * propagation_distance
+    end
+
+    ##
+    # Calculate combined measurement uncertainty as defined in Section 9
+    #
+    # u_total = √(Σ(u_i²)) dB
+    #
+    # @param uncertainty_components [Array<Float>] Array of uncertainty components (dB)
+    # @return [Float] Combined measurement uncertainty in dB
+    #
+    # Example:
+    #   EnvironmentalNoise.measurement_uncertainty([0.5, 1.0, 0.7]) # => 1.28 dB
+    #
+    def self.measurement_uncertainty(uncertainty_components)
+      Math.sqrt(uncertainty_components.sum { |c| c ** 2 })
+    end
+  end
+end

data/lib/iso_1996/noise_limits.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module ISO_1996
+
+  ##
+  # == ISO 1996-3:1987 Application to Noise Limits
+  #
+  # Module implementing calculations defined in ISO 1996-3:1987:
+  # "Acoustics - Description, measurement and assessment of environmental noise - 
+  # Part 3: Application to noise limits"
+  #
+  # Author:: Maciej Ciemborowicz
+  # Date:: July 11, 2025
+  #
+  module NoiseLimits
+    ##
+    # Constants defined in ISO 1996-3:1987 standard
+    module Constants
+      ##
+      # Impulse correction threshold (L_Cpeak,min) as defined in Section 7.2
+      # Value: 130 dB
+      IMPULSE_CORRECTION_THRESHOLD = 130.0 # dB
+
+      ##
+      # Standard 24-hour period as defined in Annex A
+      # Value: 24 hours
+      STANDARD_24H_PERIOD = 24.0 # hours
+    end
+    include Constants
+
+    ##
+    # Determine tonal adjustment factor (K_T) as defined in Section 6 and Table 1
+    #
+    # @param delta_l [Float] Difference between tone level and background level (dB)
+    # @return [Float] Tonal adjustment factor in dB
+    #
+    # According to Table 1:
+    #   ΔL ≥ 15 dB → 6 dB
+    #   10 ≤ ΔL ≤ 14 dB → 4-6 dB (default 5 dB)
+    #   5 ≤ ΔL ≤ 9 dB → 0-3 dB (default 2 dB)
+    #   ΔL < 5 dB → 0 dB
+    #
+    def self.tonal_adjustment_factor(delta_l)
+      case delta_l
+      when 15..Float::INFINITY then 6.0
+      when 10..14 then 5.0
+      when 5..9  then 2.0
+      else 0.0
+      end
+    end
+
+    ##
+    # Determine impulsive adjustment factor (K_I) as defined in Section 7.2
+    #
+    # @param l_cpeak [Float] C-weighted peak sound pressure level (dB)
+    # @param is_highly_annoying [Boolean] Whether noise is subjectively assessed as highly annoying
+    # @return [Float] Impulsive adjustment factor in dB
+    #
+    # According to version:
+    #   K_I = 6 dB if L_Cpeak ≥ 130 dB OR noise is highly annoying
+    #   K_I = 0 dB otherwise
+    #
+    def self.impulsive_adjustment_factor(l_cpeak, is_highly_annoying: false)
+      (l_cpeak >= Constants::IMPULSE_CORRECTION_THRESHOLD || is_highly_annoying) ? 6.0 : 0.0
+    end
+
+    ##
+    # Calculate assessment level (L_r) as defined in Section 8
+    #
+    # L_r = L_AeqT + K_T + K_I dB
+    #
+    # @param l_aeq_t [Float] Equivalent continuous A-weighted sound pressure level (dB)
+    # @param k_t [Float] Tonal adjustment factor (dB)
+    # @param k_i [Float] Impulsive adjustment factor (dB)
+    # @return [Float] Assessment level in dB
+    #
+    def self.assessment_level(l_aeq_t, k_t, k_i)
+      l_aeq_t + k_t + k_i
+    end
+
+    ##
+    # Evaluate compliance with noise limits as defined in Section 9
+    #
+    # @param l_r [Float] Assessment level (dB)
+    # @param noise_limit [Float] Noise limit value (dB)
+    # @param measurement_uncertainty [Float] Measurement uncertainty (dB)
+    # @return [Boolean] True if limit is exceeded (L_r > L_lim + uncertainty)
+    #
+    def self.compliance_evaluation(l_r, noise_limit, measurement_uncertainty)
+      l_r > noise_limit + measurement_uncertainty
+    end
+
+    ##
+    # Convert sound levels between time periods as defined in Annex A
+    #
+    # L_total = 10 * log10( [Σ(t_i * 10^(0.1*L_i)] / T_total ) dB
+    #
+    # @param period_levels [Array<Hash>] Array of hashes with :level (dB) and :duration (hours)
+    # @param total_period [Float] Total time period for normalization (hours)
+    # @return [Float] Equivalent sound level for total period in dB
+    #
+    # Example:
+    #   periods = [
+    #     {level: 65.0, duration: 16}, # Day
+    #     {level: 55.0, duration: 8}   # Night
+    #   ]
+    #   NoiseLimits.time_period_conversion(periods) # => ~62.1 dB
+    #
+    def self.time_period_conversion(period_levels, total_period: Constants::STANDARD_24H_PERIOD)
+      energy_sum = period_levels.sum { |period| period[:duration] * (10 ** (period[:level] / 10.0)) }
+      10 * Math.log10(energy_sum / total_period)
+    end
+  end
+end

data/lib/iso_1996.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+##
+# = ISO 1996 - Acoustics - Description, measurement and assessment of environmental noise
+#
+# Ruby implementation of ISO 1996 - Acoustics - Description, measurement and assessment of environmental noise.
+# Includes all three parts:
+# - ISO 1996-1:2003: Basic quantities and assessment procedures
+# - ISO 1996-2:2007: Determination of sound pressure levels
+# - ISO 1996-3:1987: Application to noise limits
+#
+# Author:: Maciej Ciemborowicz
+# Date:: July 11, 2025
+# Version:: 1.0.0
+# License:: MIT
+#
+# == Usage
+#   require 'iso_1996'
+#   
+#   # Basic calculations
+#   level = ISO_1996::Basic.sound_pressure_level(0.1)
+#   
+#   # Environmental noise corrections
+#   correction = ISO_1996::EnvironmentalNoise.background_noise_correction(65, 60)
+#   
+#   # Noise limits assessment
+#   assessment = ISO_1996::NoiseLimits.assessment_level(65, 2, 3)
+#
+# @see https://www.iso.org/standard/28633.html ISO 1996-1:2003
+# @see https://www.iso.org/standard/23776.html ISO 1996-2:2007
+# @see https://www.iso.org/standard/6750.html ISO 1996-3:1987
+
+require_relative 'iso_1996/basic'
+require_relative 'iso_1996/environmental_noise'
+require_relative 'iso_1996/noise_limits'
+
+module ISO_1996
+  ##
+  # Current version of the gem
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: iso_1996
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Maciej Ciemborowicz
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-07-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+- !ruby/object:Gem::Dependency
+  name: github-pages
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '228'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '228'
+description: |2
+      Ruby implementation of ISO 1996 - Acoustics — Description, measurement and assessment of environmental noise.
+      Includes all three parts:
+      - ISO 1996-1:2003: Basic quantities and assessment procedures
+      - ISO 1996-2:2007: Determination of sound pressure levels
+      - ISO 1996-3:1987: Application to noise limits
+email:
+- maciej.ciemborowicz@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/iso_1996.rb
+- lib/iso_1996/basic.rb
+- lib/iso_1996/environmental_noise.rb
+- lib/iso_1996/noise_limits.rb
+homepage: https://github.com/ciembor/iso_1996
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://ciembor.github.io/iso_1996
+  source_code_uri: https://github.com/ciembor/iso_1996
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Implementation of ISO 1996 - Acoustics — Description, measurement and assessment
+  of environmental noise
+test_files: []