flood-adapt 0.3.0__py3-none-any.whl

flood_adapt/objects/forcing/forcing.py

@@ -0,0 +1,142 @@
+import logging
+import os
+from abc import ABC, abstractmethod
+from enum import Enum
+from pathlib import Path
+from typing import Any, ClassVar, List, Type
+
+import tomli
+from pydantic import BaseModel, field_serializer
+
+from flood_adapt.config.sfincs import RiverModel
+from flood_adapt.misc.log import FloodAdaptLogging
+
+
+### ENUMS ###
+class ForcingType(str, Enum):
+    """Enum class for the different types of forcing parameters."""
+
+    WIND = "WIND"
+    RAINFALL = "RAINFALL"
+    DISCHARGE = "DISCHARGE"
+    WATERLEVEL = "WATERLEVEL"
+
+
+class ForcingSource(str, Enum):
+    """Enum class for the different sources of forcing parameters."""
+
+    MODEL = "MODEL"  # 'our' hindcast/ sfincs offshore model
+    TRACK = "TRACK"  # 'our' hindcast/ sfincs offshore model + (shifted) hurricane
+    CSV = "CSV"  # user provided csv file
+    NETCDF = "NETCDF"  # user provided netcdf file
+
+    SYNTHETIC = "SYNTHETIC"  # synthetic data
+    CONSTANT = "CONSTANT"  # synthetic data
+
+    GAUGED = "GAUGED"  # data downloaded from a gauge
+    METEO = "METEO"  # external hindcast data
+
+    NONE = "NONE"  # no forcing data
+
+
+class IForcing(BaseModel, ABC):
+    """BaseModel describing the expected variables and data types for forcing parameters of hazard model."""
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    type: ForcingType
+    source: ForcingSource
+    logger: ClassVar[logging.Logger] = FloodAdaptLogging.getLogger("Forcing")
+
+    @classmethod
+    def load_file(cls, path: Path):
+        with open(path, mode="rb") as fp:
+            toml_data = tomli.load(fp)
+        return cls.load_dict(toml_data)
+
+    @classmethod
+    def load_dict(cls, attrs):
+        return cls.model_validate(attrs)
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        """Override the default model_dump to include class variables `type` and `source`."""
+        data = super().model_dump(**kwargs)
+        data.update({"type": self.type, "source": self.source})
+        return data
+
+    def save_additional(self, output_dir: Path | str | os.PathLike) -> None:
+        """Save additional data of the forcing."""
+        return
+
+    @field_serializer("path", check_fields=False)
+    @classmethod
+    def serialize_path(cls, value: Path) -> str:
+        """Serialize filepath-like fields by saving only the filename. It is assumed that the file will be saved in the same directory."""
+        return value.name
+
+
+class IDischarge(IForcing):
+    type: ForcingType = ForcingType.DISCHARGE
+    river: RiverModel
+
+
+class IRainfall(IForcing):
+    type: ForcingType = ForcingType.RAINFALL
+
+
+class IWind(IForcing):
+    type: ForcingType = ForcingType.WIND
+
+
+class IWaterlevel(IForcing):
+    type: ForcingType = ForcingType.WATERLEVEL
+
+
+class IForcingFactory:
+    @classmethod
+    @abstractmethod
+    def load_file(cls, toml_file: Path) -> IForcing:
+        """Create a forcing object from a TOML file."""
+        ...
+
+    @classmethod
+    @abstractmethod
+    def load_dict(cls, attrs: dict[str, Any] | IForcing) -> IForcing:
+        """Create a forcing object from a dictionary of attributes."""
+        ...
+
+    @classmethod
+    @abstractmethod
+    def read_forcing(
+        cls,
+        filepath: Path,
+    ) -> tuple[Type[IForcing], ForcingType, ForcingSource]:
+        """Extract forcing class, type and source from a TOML file."""
+        ...
+
+    @classmethod
+    @abstractmethod
+    def get_forcing_class(
+        cls, type: ForcingType, source: ForcingSource
+    ) -> Type[IForcing]:
+        """Get the forcing class corresponding to the type and source."""
+        ...
+
+    @classmethod
+    @abstractmethod
+    def list_forcing_types(cls) -> List[ForcingType]:
+        """List all available forcing types."""
+        ...
+
+    @classmethod
+    @abstractmethod
+    def list_forcing_classes(cls) -> List[Type[IForcing]]:
+        """List all available forcing classes."""
+        ...
+
+    @classmethod
+    @abstractmethod
+    def list_forcing_types_and_sources(cls) -> List[tuple[ForcingType, ForcingSource]]:
+        """List all available combinations of forcing types and sources."""
+        ...

flood_adapt/objects/forcing/forcing_factory.py

@@ -0,0 +1,182 @@
+from pathlib import Path
+from typing import Any, List, Type
+
+import tomli
+
+from flood_adapt.objects.forcing.discharge import (
+    DischargeConstant,
+    DischargeCSV,
+    DischargeSynthetic,
+)
+from flood_adapt.objects.forcing.forcing import (
+    ForcingSource,
+    ForcingType,
+    IForcing,
+    IForcingFactory,
+)
+from flood_adapt.objects.forcing.rainfall import (
+    RainfallConstant,
+    RainfallCSV,
+    RainfallMeteo,
+    RainfallNetCDF,
+    RainfallSynthetic,
+    RainfallTrack,
+)
+from flood_adapt.objects.forcing.waterlevels import (
+    WaterlevelCSV,
+    WaterlevelGauged,
+    WaterlevelModel,
+    WaterlevelSynthetic,
+)
+from flood_adapt.objects.forcing.wind import (
+    WindConstant,
+    WindCSV,
+    WindMeteo,
+    WindNetCDF,
+    WindSynthetic,
+    WindTrack,
+)
+
+__all__ = [
+    "ForcingFactory",
+    "ForcingSource",
+    "ForcingType",
+    "IForcing",
+    "IForcingFactory",
+    "WindConstant",
+    "WindCSV",
+    "WindMeteo",
+    "WindSynthetic",
+    "WindTrack",
+    "WaterlevelCSV",
+    "WaterlevelGauged",
+    "WaterlevelModel",
+    "WaterlevelSynthetic",
+    "RainfallConstant",
+    "RainfallCSV",
+    "RainfallMeteo",
+    "RainfallSynthetic",
+    "RainfallTrack",
+    "DischargeConstant",
+    "DischargeCSV",
+    "DischargeSynthetic",
+]
+
+
+class ForcingFactory(IForcingFactory):
+    """Factory class for creating forcings."""
+
+    WATERLEVELS: dict[ForcingSource, Type[IForcing]] = {
+        ForcingSource.MODEL: WaterlevelModel,
+        ForcingSource.CSV: WaterlevelCSV,
+        ForcingSource.SYNTHETIC: WaterlevelSynthetic,
+        ForcingSource.GAUGED: WaterlevelGauged,
+    }
+
+    WIND: dict[ForcingSource, Type[IForcing]] = {
+        ForcingSource.METEO: WindMeteo,
+        ForcingSource.TRACK: WindTrack,
+        ForcingSource.CSV: WindCSV,
+        ForcingSource.SYNTHETIC: WindSynthetic,
+        ForcingSource.CONSTANT: WindConstant,
+        ForcingSource.NETCDF: WindNetCDF,
+    }
+
+    RAINFALL: dict[ForcingSource, Type[IForcing]] = {
+        ForcingSource.METEO: RainfallMeteo,
+        ForcingSource.TRACK: RainfallTrack,
+        ForcingSource.CSV: RainfallCSV,
+        ForcingSource.SYNTHETIC: RainfallSynthetic,
+        ForcingSource.CONSTANT: RainfallConstant,
+        ForcingSource.NETCDF: RainfallNetCDF,
+    }
+
+    DISCHARGE: dict[ForcingSource, Type[IForcing]] = {
+        ForcingSource.CSV: DischargeCSV,
+        ForcingSource.SYNTHETIC: DischargeSynthetic,
+        ForcingSource.CONSTANT: DischargeConstant,
+    }
+
+    FORCINGTYPES: dict[ForcingType, dict[ForcingSource, Type[IForcing]]] = {
+        ForcingType.WATERLEVEL: WATERLEVELS,
+        ForcingType.RAINFALL: RAINFALL,
+        ForcingType.WIND: WIND,
+        ForcingType.DISCHARGE: DISCHARGE,
+    }
+
+    @classmethod
+    def read_forcing(
+        cls,
+        filepath: Path,
+    ) -> tuple[Type[IForcing], ForcingType, ForcingSource]:
+        """Extract forcing type and source from a TOML file."""
+        with open(filepath, mode="rb") as fp:
+            toml_data = tomli.load(fp)
+        type = toml_data.get("type")
+        source = toml_data.get("source")
+
+        if type is None or source is None:
+            raise ValueError(
+                f"Forcing type {type} or source {source} not found in {filepath}"
+            )
+        forcing_cls = cls.get_forcing_class(ForcingType(type), ForcingSource(source))
+        return forcing_cls, ForcingType(type), ForcingSource(source)
+
+    @classmethod
+    def get_forcing_class(
+        cls, type: ForcingType, source: ForcingSource
+    ) -> Type[IForcing]:
+        """Get the forcing class corresponding to the type and source."""
+        if (sources := cls.FORCINGTYPES.get(type)) is None:
+            raise ValueError(f"Invalid forcing type: {type}")
+
+        if (forcing_cls := sources.get(source)) is None:
+            raise ValueError(
+                f"Invalid forcing source: {source} for forcing type: {type}"
+            )
+        return forcing_cls
+
+    @classmethod
+    def load_file(cls, toml_file: Path) -> IForcing:
+        """Create a forcing object from a TOML file."""
+        with open(toml_file, mode="rb") as fp:
+            toml_data = tomli.load(fp)
+        return cls.load_dict(toml_data)
+
+    @classmethod
+    def load_dict(cls, attrs: dict[str, Any] | IForcing) -> IForcing:
+        """Create a forcing object from a dictionary of attributes."""
+        if isinstance(attrs, IForcing):
+            return attrs
+        type = attrs.get("type")
+        source = attrs.get("source")
+        if type is None or source is None:
+            raise ValueError(
+                f"Forcing type {type} or source {source} not found in attributes."
+            )
+        return cls.get_forcing_class(
+            ForcingType(type), ForcingSource(source)
+        ).model_validate(attrs)
+
+    @classmethod
+    def list_forcings(cls) -> List[Type[IForcing]]:
+        """List all available forcing classes."""
+        forcing_classes = set()
+        for source_map in cls.FORCINGTYPES.values():
+            for forcing in source_map.values():
+                if forcing is not None:
+                    forcing_classes.add(forcing)
+        return list(forcing_classes)
+
+    @classmethod
+    def list_forcing_types_and_sources(cls) -> List[tuple[ForcingType, ForcingSource]]:
+        """List all available forcing classes using a tuple of ForcingType and ForcingSource."""
+        # TODO remove this when the backend supports all forcings
+        ONLY_BACKEND_FORCINGS = {(ForcingType.WIND, ForcingSource.SYNTHETIC)}
+        combinations = set()
+        for type, source_map in cls.FORCINGTYPES.items():
+            for source in source_map.keys():
+                if (type, source) in ONLY_BACKEND_FORCINGS:
+                    continue
+                combinations.add((type, source))
+        return list(combinations)

flood_adapt/objects/forcing/meteo_handler.py

@@ -0,0 +1,93 @@
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import cht_meteo
+import numpy as np
+import xarray as xr
+from cht_meteo.dataset import MeteoDataset
+
+from flood_adapt.config.config import Settings
+from flood_adapt.config.site import Site
+from flood_adapt.objects.forcing.time_frame import TimeFrame
+
+
+class MeteoHandler:
+    def __init__(self, dir: Optional[Path] = None, site: Optional[Site] = None) -> None:
+        self.dir: Path = dir or Settings().database_path / "static" / "meteo"
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.site: Site = site or Site.load_file(
+            Settings().database_path / "static" / "config" / "site.toml"
+        )
+        # Create GFS dataset
+        self.dataset = cht_meteo.dataset(
+            name="gfs_anl_0p50",
+            source="gfs_analysis_0p50",
+            path=self.dir,
+            lon_range=(self.site.lon - 10, self.site.lon + 10),
+            lat_range=(self.site.lat - 10, self.site.lat + 10),
+        )
+        # quick fix for sites near the 0 degree longitude -> shift the meteo download area either east or west of the 0 degree longitude
+        # TODO implement a good solution to this in cht_meteo
+        self.dataset.lon_range = self._shift_grid_to_positive_lon(self.dataset)
+
+    def download(self, time: TimeFrame):
+        # Download and collect data
+        time_range = self.get_time_range(time)
+
+        self.dataset.download(time_range=time_range)
+
+    def read(self, time: TimeFrame) -> xr.Dataset:
+        self.download(time)
+        time_range = self.get_time_range(time)
+        ds = self.dataset.collect(time_range=time_range)
+
+        if ds is None:
+            raise FileNotFoundError(
+                f"No meteo files found in meteo directory {self.dir}"
+            )
+
+        ds.raster.set_crs(4326)
+
+        # Rename the variables to match what hydromt-sfincs expects
+        ds = ds.rename(
+            {
+                "barometric_pressure": "press_msl",
+                "precipitation": "precip",
+                "wind_u": "wind10_u",
+                "wind_v": "wind10_v",
+            }
+        )
+
+        # Convert the longitude to -180 to 180 to match hydromt-sfincs
+        if ds["lon"].min() > 180:
+            ds["lon"] = ds["lon"] - 360
+
+        return ds
+
+    @staticmethod
+    def get_time_range(time: TimeFrame) -> tuple:
+        t0 = time.start_time
+        t1 = time.end_time
+        if not isinstance(t0, datetime):
+            t0 = datetime.strptime(t0, "%Y%m%d %H%M%S")
+        if not isinstance(t1, datetime):
+            t1 = datetime.strptime(t1, "%Y%m%d %H%M%S")
+        time_range = (t0, t1)
+        return time_range
+
+    @staticmethod
+    def _shift_grid_to_positive_lon(grid: MeteoDataset):
+        """Shift the grid to positive longitudes if the grid crosses the 0 degree longitude."""
+        if np.prod(grid.lon_range) < 0:
+            if np.abs(grid.lon_range[0]) > np.abs(grid.lon_range[1]):
+                grid.lon_range = [
+                    grid.lon_range[0] - grid.lon_range[1] - 1,
+                    -1,
+                ]
+            else:
+                grid.lon_range = [
+                    1,
+                    grid.lon_range[1] - grid.lon_range[0] + 1,
+                ]
+        return grid.lon_range

flood_adapt/objects/forcing/netcdf.py

@@ -0,0 +1,40 @@
+import numpy as np
+import pandas as pd
+import xarray as xr
+
+
+@staticmethod
+def validate_netcdf_forcing(
+    ds: xr.Dataset, required_vars: tuple[str, ...], required_coords: tuple[str, ...]
+) -> xr.Dataset:
+    """Validate a forcing dataset by checking for required variables and coordinates."""
+    # Check variables
+    _required_vars = set(required_vars)
+    if not _required_vars.issubset(ds.data_vars):
+        missing_vars = _required_vars - set(ds.data_vars)
+        raise ValueError(
+            f"Missing required variables for netcdf forcing: {missing_vars}"
+        )
+
+    # Check coordinates
+    _required_coords = set(required_coords)
+    if not _required_coords.issubset(ds.coords):
+        missing_coords = _required_coords - set(ds.coords)
+        raise ValueError(
+            f"Missing required coordinates for netcdf forcing: {missing_coords}"
+        )
+
+    # Check time step
+    ts = pd.to_timedelta(np.diff(ds.time).mean())
+    if ts < pd.to_timedelta("1H"):
+        raise ValueError(
+            f"SFINCS NetCDF forcing time step cannot be less than 1 hour: {ts}"
+        )
+
+    for var in ds.data_vars:
+        # Check order of dimensions
+        if ds[var].dims != required_coords:
+            raise ValueError(
+                f"Order of dimensions for variable {var} must be {required_coords}"
+            )
+    return ds