pyelq 1.1.4__py3-none-any.whl → 1.2.0__py3-none-any.whl

pyelq/dispersion_model/gaussian_plume.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2024 Shell Global Solutions International B.V. All Rights Reserved.
+# SPDX-FileCopyrightText: 2026 Shell Global Solutions International B.V. All Rights Reserved.
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -10,37 +10,32 @@ The class for the Gaussian Plume dispersion model used in pyELQ.
 The Mathematics of Atmospheric Dispersion Modeling, John M. Stockie, DOI. 10.1137/10080991X
 
 """
+
 from copy import deepcopy
 from dataclasses import dataclass
-from typing import Callable, Union
+from typing import Union
 
 import numpy as np
 
-import pyelq.support_functions.spatio_temporal_interpolation as sti
 from pyelq.coordinate_system import ENU, LLA
+from pyelq.dispersion_model.dispersion_model import DispersionModel
 from pyelq.gas_species import GasSpecies
-from pyelq.meteorology import Meteorology, MeteorologyGroup
+from pyelq.meteorology.meteorology import Meteorology, MeteorologyGroup
 from pyelq.sensor.beam import Beam
 from pyelq.sensor.satellite import Satellite
 from pyelq.sensor.sensor import Sensor, SensorGroup
-from pyelq.source_map import SourceMap
 
 
 @dataclass
-class GaussianPlume:
+class GaussianPlume(DispersionModel):
     """Defines the Gaussian plume dispersion model class.
 
     Attributes:
-        source_map (Sourcemap): SourceMap object used for the dispersion model
         source_half_width (float): Source half width (radius) to be used in the Gaussian plume model (in meters)
-        minimum_contribution (float): All elements in the Gaussian plume coupling smaller than this number will be set
-            to 0. Helps to speed up matrix multiplications/matrix inverses, also helps with stability
 
     """
 
-    source_map: SourceMap
     source_half_width: float = 1
-    minimum_contribution: float = 0
 
     def compute_coupling(
         self,
@@ -120,7 +115,7 @@ class GaussianPlume:
         self,
         sensor_object: Sensor,
         meteorology: Meteorology,
-        gas_object: GasSpecies = None,
+        gas_object: Union[GasSpecies, None] = None,
         run_interpolation: bool = True,
     ) -> Union[list, np.ndarray]:
         """Wrapper function to compute the gaussian plume coupling for a single sensor.
@@ -186,7 +181,7 @@ class GaussianPlume:
             )
 
         if sensor_object.source_on is not None:
-            plume_coupling = plume_coupling * sensor_object.source_on[:, None]
+            plume_coupling = plume_coupling * np.where(sensor_object.source_on != 0, 1, 0)[:, None]
 
         return plume_coupling
 
@@ -255,150 +250,6 @@ class GaussianPlume:
 
         return plume_coupling
 
-    def calculate_gas_density(
-        self, meteorology: Meteorology, sensor_object: Sensor, gas_object: Union[GasSpecies, None]
-    ) -> np.ndarray:
-        """Helper function to calculate the gas density using ideal gas law.
-
-        https://en.wikipedia.org/wiki/Ideal_gas
-
-        When a gas object is passed as input we calculate the density according to that gas. We check if the
-        meteorology object has a temperature and/or pressure value and use those accordingly. Otherwise, we use Standard
-        Temperature and Pressure (STP).
-
-        We interpolate the temperature and pressure values to the source locations/times such that this is consistent
-        with the other calculations, i.e. we only do spatial interpolation when the sensor is a Satellite object
-        and temporal interpolation otherwise.
-
-        When no gas_object is passed in we just set the gas density value to 1.
-
-        Args:
-            meteorology (Meteorology): Meteorology object potentially containing temperature or pressure values
-            sensor_object (Sensor): Sensor object containing information about where to interpolate to
-            gas_object (Union[GasSpecies, None]): Gas species object which actually calculates the correct density
-
-        Returns:
-            gas_density (np.ndarray): Numpy array of shape [1 x nof_sources] (Satellite sensor)
-                or [nof_observations x 1] (otherwise) containing the gas density values to use
-
-        """
-        if not isinstance(gas_object, GasSpecies):
-            if isinstance(sensor_object, Satellite):
-                return np.ones((1, self.source_map.nof_sources))
-            return np.ones((sensor_object.nof_observations, 1))
-
-        temperature_interpolated = self.interpolate_meteorology(
-            meteorology=meteorology, variable_name="temperature", sensor_object=sensor_object
-        )
-        if temperature_interpolated is None:
-            temperature_interpolated = np.array([[273.15]])
-
-        pressure_interpolated = self.interpolate_meteorology(
-            meteorology=meteorology, variable_name="pressure", sensor_object=sensor_object
-        )
-        if pressure_interpolated is None:
-            pressure_interpolated = np.array([[101.325]])
-
-        gas_density = gas_object.gas_density(temperature=temperature_interpolated, pressure=pressure_interpolated)
-
-        return gas_density
-
-    def interpolate_all_meteorology(
-        self, sensor_object: Sensor, meteorology: Meteorology, gas_object: GasSpecies, run_interpolation: bool
-    ):
-        """Function which carries out interpolation of all meteorological information.
-
-        The flag run_interpolation determines whether the interpolation should be carried out. If this
-        is set to be False, the meteorological parameters are simply set to the values stored on the
-        meteorology object (i.e. we assume that the meteorology has already been interpolated). This
-        functionality is required to avoid wasted computation in the case of e.g. a reversible jump run.
-
-        Args:
-            sensor_object (Sensor): object containing locations/times onto which met information should
-                be interpolated.
-            meteorology (Meteorology): object containing meteorology information for interpolation.
-            gas_object (GasSpecies): object containing gas information.
-            run_interpolation (bool): logical indicating whether the meteorology information needs to be interpolated.
-
-        Returns:
-            gas_density (np.ndarray): numpy array of shape [n_data x 1] of gas densities.
-            u_interpolated (np.ndarray): numpy array of shape [n_data x 1] of northerly wind components.
-            v_interpolated (np.ndarray): numpy array of shape [n_data x 1] of easterly wind components.
-            wind_turbulence_horizontal (np.ndarray): numpy array of shape [n_data x 1] of horizontal turbulence
-                parameters.
-            wind_turbulence_vertical (np.ndarray): numpy array of shape [n_data x 1] of vertical turbulence
-                parameters.
-
-        """
-        if run_interpolation:
-            gas_density = self.calculate_gas_density(
-                meteorology=meteorology, sensor_object=sensor_object, gas_object=gas_object
-            )
-            u_interpolated = self.interpolate_meteorology(
-                meteorology=meteorology, variable_name="u_component", sensor_object=sensor_object
-            )
-            v_interpolated = self.interpolate_meteorology(
-                meteorology=meteorology, variable_name="v_component", sensor_object=sensor_object
-            )
-            wind_turbulence_horizontal = self.interpolate_meteorology(
-                meteorology=meteorology, variable_name="wind_turbulence_horizontal", sensor_object=sensor_object
-            )
-            wind_turbulence_vertical = self.interpolate_meteorology(
-                meteorology=meteorology, variable_name="wind_turbulence_vertical", sensor_object=sensor_object
-            )
-        else:
-            gas_density = gas_object.gas_density(temperature=meteorology.temperature, pressure=meteorology.pressure)
-            gas_density = gas_density.reshape((gas_density.size, 1))
-            u_interpolated = meteorology.u_component.reshape((meteorology.u_component.size, 1))
-            v_interpolated = meteorology.v_component.reshape((meteorology.v_component.size, 1))
-            wind_turbulence_horizontal = meteorology.wind_turbulence_horizontal.reshape(
-                (meteorology.wind_turbulence_horizontal.size, 1)
-            )
-            wind_turbulence_vertical = meteorology.wind_turbulence_vertical.reshape(
-                (meteorology.wind_turbulence_vertical.size, 1)
-            )
-
-        return gas_density, u_interpolated, v_interpolated, wind_turbulence_horizontal, wind_turbulence_vertical
-
-    def interpolate_meteorology(
-        self, meteorology: Meteorology, variable_name: str, sensor_object: Sensor
-    ) -> Union[np.ndarray, None]:
-        """Helper function to interpolate meteorology variables.
-
-        This function interpolates meteorological variables to times in Sensor or Sources in sourcemap. It also
-        calculates the wind speed and mathematical angle between the u- and v-components which in turn gets used in the
-        calculation of the Gaussian plume.
-
-        When the input sensor object is a Satellite type we use spatial interpolation using the interpolation method
-        from the coordinate system class as this takes care of the coordinate systems.
-        When the input sensor object is of another time we use temporal interpolation (assumption is spatial uniformity
-        for all observations over a small(er) area).
-
-        Args:
-            meteorology (Meteorology): Meteorology object containing u- and v-components of wind including their
-                spatial location
-            variable_name (str): String name of an attribute in the meteorology input object which needs to be
-                interpolated
-            sensor_object (Sensor): Sensor object containing information about where to interpolate to
-
-        Returns:
-            variable_interpolated (np.ndarray): Interpolated values
-
-        """
-        variable = getattr(meteorology, variable_name)
-        if variable is None:
-            return None
-
-        if isinstance(sensor_object, Satellite):
-            variable_interpolated = meteorology.location.interpolate(variable, self.source_map.location)
-            variable_interpolated = variable_interpolated.reshape(1, self.source_map.nof_sources)
-        else:
-            variable_interpolated = sti.interpolate(
-                time_in=meteorology.time, values_in=variable, time_out=sensor_object.time
-            )
-            variable_interpolated = variable_interpolated.reshape(sensor_object.nof_observations, 1)
-        return variable_interpolated
-
     def compute_coupling_satellite(
         self,
         sensor_object: Sensor,
@@ -559,38 +410,6 @@ class GaussianPlume:
 
         return plume_coupling
 
-    @staticmethod
-    def compute_coverage(
-        couplings: np.ndarray, threshold_function: Callable, coverage_threshold: float = 6, **kwargs
-    ) -> Union[np.ndarray, dict]:
-        """Returns a logical vector that indicates which sources in the couplings are, or are not, within the coverage.
-
-        The 'coverage' is the area inside which all sources are well covered by wind data. E.g. If wind exclusively
-        blows towards East, then all sources to the East of any sensor are 'invisible', and are not within the coverage.
-
-        Couplings are returned in hr/kg. Some threshold function defines the largest allowed coupling value. This is
-        used to calculate estimated emission rates in kg/hr. Any emissions which are greater than the value of
-        'coverage_threshold' are defined as not within the coverage.
-
-        Args:
-            couplings (np.ndarray): Array of coupling values. Dimensions: n_datapoints x n_sources.
-            threshold_function (Callable): Callable function which returns some single value that defines the
-                maximum or 'threshold' coupling. For example: np.quantile(., q=0.95)
-            coverage_threshold (float, optional): The threshold value of the estimated emission rate which is
-                considered to be within the coverage. Defaults to 6 kg/hr.
-            kwargs (dict, optional): Keyword arguments required for the threshold function.
-
-        Returns:
-            coverage (Union[np.ndarray, dict]): A logical array specifying which sources are within the coverage.
-
-        """
-        coupling_threshold = threshold_function(couplings, **kwargs)
-        no_warning_threshold = np.where(coupling_threshold <= 1e-100, 1, coupling_threshold)
-        no_warning_estimated_emission_rates = np.where(coupling_threshold <= 1e-100, np.inf, 1 / no_warning_threshold)
-        coverage = no_warning_estimated_emission_rates < coverage_threshold
-
-        return coverage
-
 
 def _create_enu_sensor_array(
     inclusion_idx: np.ndarray, sensor_object: Sensor, source_map_location_lla: LLA, current_source: int

pyelq/dispersion_model/site_layout.py

@@ -0,0 +1,97 @@
+# SPDX-FileCopyrightText: 2026 Shell Global Solutions International B.V. All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# -*- coding: utf-8 -*-
+"""Site layout module.
+
+This module defines the SiteLayout class, which represents the layout of a site, giving the option to include obstacles
+(e.g. buildings, tanks, equipment) as cylinders obstructing the flow field.
+
+"""
+
+from dataclasses import dataclass, field
+from typing import Union
+
+import numpy as np
+from scipy import spatial
+
+from pyelq.coordinate_system import ENU
+
+
+@dataclass
+class SiteLayout:
+    """Class for site layout defining cylindrical obstacles in the environment.
+
+    These are used with MeteorologyWindfield to calculate the wind field at each grid point with a potential flow
+    around the cylindrical obstacles.
+
+    Attributes:
+        cylinder_coordinates (Union[ENU, None]): The coordinates of the cylindrical obstacles in the site layout. The
+            east, north represent the the center of the cylinder and the up coordinate represents the cylinder height.
+        cylinder_radius (np.ndarray): The radius of the cylindrical obstacles in the site layout.
+        id_obstacles (np.ndarray): Boolean array indicating which grid points are within obstacle regions.
+        id_obstacles_index (np.ndarray): The indices of the grid points that are within obstacle regions.
+
+    """
+
+    cylinder_coordinates: Union[ENU, None]
+    cylinder_radius: np.ndarray
+
+    id_obstacles: np.ndarray = field(init=False)
+    id_obstacles_index: np.ndarray = field(init=False)
+
+    @property
+    def nof_cylinders(self) -> int:
+        """Int: Returns the number of cylinders in the site layout."""
+        if self.cylinder_coordinates is None:
+            return 0
+        return self.cylinder_coordinates.nof_observations
+
+    def find_index_obstacles(self, grid_coordinates: ENU):
+        """Find the indices of the grid_coordinates that are within the radius of the obstacles.
+
+        This method uses a KDTree to efficiently find the indices of the grid points that are within the radius of the
+        cylindrical obstacles. It also checks the height of the grid points against the height of the obstacles.
+        If the height of the grid point is greater than the height of the obstacle, it is not considered an obstacle.
+
+        Args:
+            grid_coordinates (ENU): The coordinates of the grid points to check.
+
+        """
+        if self.cylinder_coordinates is None or self.cylinder_coordinates.nof_observations == 0:
+            self.id_obstacles = np.zeros((grid_coordinates.nof_observations, 1), dtype=bool)
+            return
+
+        self.check_reference_coordinates(grid_coordinates)
+
+        grid_coordinates_array = grid_coordinates.to_array(dim=2)
+        tree = spatial.KDTree(grid_coordinates_array)
+        indices = tree.query_ball_point(x=self.cylinder_coordinates.to_array(dim=2), r=self.cylinder_radius.flatten())
+
+        if grid_coordinates.up is not None:
+
+            for i, height in enumerate(self.cylinder_coordinates.up):
+                indices[i] = np.array(indices[i])
+                if len(indices[i]) > 0:
+                    indices[i] = indices[i][grid_coordinates.up[indices[i]].flatten() <= height]
+        indices_conc = np.unique(np.concatenate(indices, axis=0)).astype(int)
+        self.id_obstacles_index = indices_conc
+        self.id_obstacles = np.zeros((grid_coordinates.nof_observations, 1), dtype=bool)
+        self.id_obstacles[[indices_conc]] = True
+
+    def check_reference_coordinates(self, grid_coordinates: ENU):
+        """Check if the reference coordinates of the grid and cylinder coordinates match.
+
+        Args:
+            grid_coordinates (ENU): The coordinates of the grid points to check.
+
+        Raises:
+            ValueError: If the reference coordinates do not match.
+        """
+        if grid_coordinates.ref_altitude != self.cylinder_coordinates.ref_altitude:
+            raise ValueError("Grid coordinates and cylinder coordinates must have the same reference altitude.")
+        if grid_coordinates.ref_longitude != self.cylinder_coordinates.ref_longitude:
+            raise ValueError("Grid coordinates and cylinder coordinates must have the same reference longitude.")
+        if grid_coordinates.ref_latitude != self.cylinder_coordinates.ref_latitude:
+            raise ValueError("Grid coordinates and cylinder coordinates must have the same reference latitude.")

pyelq/dlm.py

@@ -9,11 +9,12 @@ This module provides a class definition for the Dynamic Linear Models following
 'Bayesian Forecasting and Dynamic Models' (2nd ed), Springer New York, NY, Chapter 4, https://doi.org/10.1007/b98971
 
 """
+
 from dataclasses import dataclass, field
 from typing import Tuple, Union
 
 import numpy as np
-from scipy.stats import chi2
+from scipy.stats import chi2, multivariate_normal
 
 
 @dataclass
@@ -119,23 +120,18 @@ class DLM:
         mean_state_noise = np.zeros(self.nof_state_parameters)
         mean_observation_noise = np.zeros(self.nof_observables)
 
-        random_generator = np.random.default_rng(seed=None)
-
         for i in range(nof_timesteps):
             if i == 0:
-                state[:, [i]] = (
-                    self.g_matrix @ init_state
-                    + random_generator.multivariate_normal(mean_state_noise, self.w_matrix, size=1).T
-                )
+                state[:, [i]] = self.g_matrix @ init_state + multivariate_normal.rvs(
+                    mean=mean_state_noise, cov=self.w_matrix, size=1
+                ).reshape((-1, 1))
             else:
-                state[:, [i]] = (
-                    self.g_matrix @ state[:, [i - 1]]
-                    + random_generator.multivariate_normal(mean_state_noise, self.w_matrix, size=1).T
-                )
-            obs[:, [i]] = (
-                self.f_matrix.T @ state[:, [i]]
-                + random_generator.multivariate_normal(mean_observation_noise, self.v_matrix, size=1).T
-            )
+                state[:, [i]] = self.g_matrix @ state[:, [i - 1]] + multivariate_normal.rvs(
+                    mean=mean_state_noise, cov=self.w_matrix, size=1
+                ).reshape((-1, 1))
+            obs[:, [i]] = self.f_matrix.T @ state[:, [i]] + multivariate_normal.rvs(
+                mean=mean_observation_noise, cov=self.v_matrix, size=1
+            ).reshape((-1, 1))
 
         return state, obs
 

pyelq/gas_species.py

@@ -9,6 +9,7 @@ The superclass for the Gas species classes. It contains a few gas species with i
 calculate the density of the gas and do emission rate conversions from m^3/s to kg/hr and back
 
 """
+
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import Union

pyelq/meteorology/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2026 Shell Global Solutions International B.V. All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Data Access Module."""
+
+__all__ = ["meteorology", "meteorology_windfield"]