flood-adapt 0.3.0__py3-none-any.whl

flood_adapt/config/gui.py

@@ -0,0 +1,224 @@
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, Field
+from tomli import load as load_toml
+
+from flood_adapt.config.fiat import DamageType
+from flood_adapt.objects.forcing import unit_system as us
+
+
+class MapboxLayersModel(BaseModel):
+    """The configuration of the mapbox layers in the gui.
+
+    Attributes
+    ----------
+    buildings_min_zoom_level : int
+        The minimum zoom level for the buildings layer.
+    flood_map_depth_min : float
+        The minimum depth for the flood map layer.
+    flood_map_zbmax : float
+        The maximum depth for the flood map layer.
+    flood_map_bins : list[float]
+        The bins for the flood map layer.
+    flood_map_colors : list[str]
+        The colors for the flood map layer.
+    aggregation_dmg_bins : list[float]
+        The bins for the aggregation damage layer.
+    aggregation_dmg_colors : list[str]
+        The colors for the aggregation damage layer.
+    footprints_dmg_type : DamageType
+        The type of damage for the footprints layer.
+    footprints_dmg_bins : list[float]
+        The bins for the footprints layer.
+    footprints_dmg_colors : list[str]
+        The colors for the footprints layer.
+    svi_bins : Optional[list[float]]
+        The bins for the SVI layer.
+    svi_colors : Optional[list[str]]
+        The colors for the SVI layer.
+    benefits_bins : list[float]
+        The bins for the benefits layer.
+    benefits_colors : list[str]
+        The colors for the benefits layer.
+    benefits_threshold : Optional[float], default=None
+        The threshold for the benefits layer.
+    damage_decimals : Optional[int], default=0
+        The number of decimals for the damage layer.
+
+    """
+
+    buildings_min_zoom_level: int = 13
+    flood_map_depth_min: float
+    flood_map_zbmax: float
+    flood_map_bins: list[float]
+    flood_map_colors: list[str]
+    aggregation_dmg_bins: list[float]
+    aggregation_dmg_colors: list[str]
+    footprints_dmg_type: DamageType = DamageType.absolute
+    footprints_dmg_bins: list[float]
+    footprints_dmg_colors: list[str]
+    svi_bins: Optional[list[float]] = Field(default_factory=list)
+    svi_colors: Optional[list[str]] = Field(default_factory=list)
+    benefits_bins: list[float]
+    benefits_colors: list[str]
+    benefits_threshold: Optional[float] = None
+    damage_decimals: Optional[int] = 0
+
+
+class VisualizationLayersModel(BaseModel):
+    """The configuration of the layers you might want to visualize in the gui.
+
+    Attributes
+    ----------
+    default_bin_number : int
+        The default number of bins for the visualization layers.
+    default_colors : list[str]
+        The default colors for the visualization layers.
+    layer_names : list[str]
+        The names of the layers to visualize.
+    layer_long_names : list[str]
+        The long names of the layers to visualize.
+    layer_paths : list[str]
+        The paths to the layers to visualize.
+    field_names : list[str]
+        The field names of the layers to visualize.
+    bins : Optional[list[list[float]]]
+        The bins for the layers to visualize.
+    colors : Optional[list[list[str]]]
+        The colors for the layers to visualize.
+    """
+
+    # TODO add check for default_bin_number and default_colors to have the same length
+    default_bin_number: int
+    default_colors: list[str]
+    layer_names: list[str] = Field(default_factory=list)
+    layer_long_names: list[str] = Field(default_factory=list)
+    layer_paths: list[str] = Field(default_factory=list)
+    field_names: list[str] = Field(default_factory=list)
+    bins: Optional[list[list[float]]] = Field(default_factory=list)
+    colors: Optional[list[list[str]]] = Field(default_factory=list)
+
+
+class GuiUnitModel(BaseModel):
+    """The unit system used in the GUI.
+
+    Attributes
+    ----------
+    default_length_units : us.UnitTypesLength
+        The length units used in the GUI.
+    default_distance_units : us.UnitTypesLength
+        The distance units used in the GUI.
+    default_area_units : us.UnitTypesArea
+        The area units used in the GUI.
+    default_volume_units : us.UnitTypesVolume
+        The volume units used in the GUI.
+    default_velocity_units : us.UnitTypesVelocity
+        The velocity units used in the GUI.
+    default_direction_units : us.UnitTypesDirection
+        The direction units used in the GUI.
+    default_discharge_units : us.UnitTypesDischarge
+        The discharge units used in the GUI.
+    default_intensity_units : us.UnitTypesIntensity
+        The intensity units used in the GUI.
+    default_cumulative_units : us.UnitTypesLength
+        The cumulative units used in the GUI.
+    """
+
+    default_length_units: us.UnitTypesLength
+    default_distance_units: us.UnitTypesLength
+    default_area_units: us.UnitTypesArea
+    default_volume_units: us.UnitTypesVolume
+    default_velocity_units: us.UnitTypesVelocity
+    default_direction_units: us.UnitTypesDirection
+    default_discharge_units: us.UnitTypesDischarge
+    default_intensity_units: us.UnitTypesIntensity
+    default_cumulative_units: us.UnitTypesLength
+
+    @staticmethod
+    def imperial() -> "GuiUnitModel":
+        return GuiUnitModel(
+            default_length_units=us.UnitTypesLength.feet,
+            default_distance_units=us.UnitTypesLength.miles,
+            default_area_units=us.UnitTypesArea.sf,
+            default_volume_units=us.UnitTypesVolume.cf,
+            default_velocity_units=us.UnitTypesVelocity.mph,
+            default_direction_units=us.UnitTypesDirection.degrees,
+            default_discharge_units=us.UnitTypesDischarge.cfs,
+            default_intensity_units=us.UnitTypesIntensity.inch_hr,
+            default_cumulative_units=us.UnitTypesLength.inch,
+        )
+
+    @staticmethod
+    def metric() -> "GuiUnitModel":
+        return GuiUnitModel(
+            default_length_units=us.UnitTypesLength.meters,
+            default_distance_units=us.UnitTypesLength.meters,
+            default_area_units=us.UnitTypesArea.m2,
+            default_volume_units=us.UnitTypesVolume.m3,
+            default_velocity_units=us.UnitTypesVelocity.mps,
+            default_direction_units=us.UnitTypesDirection.degrees,
+            default_discharge_units=us.UnitTypesDischarge.cms,
+            default_intensity_units=us.UnitTypesIntensity.mm_hr,
+            default_cumulative_units=us.UnitTypesLength.millimeters,
+        )
+
+
+class SyntheticTideModel(BaseModel):
+    """Configuration for the synthetic tide.
+
+    Parameters
+    ----------
+    harmonic_amplitude : us.UnitfulLength
+        The amplitude of the tide harmonic relative to the datum.
+    datum : str
+        The datum to which the harmonic amplitude is relative.
+        Should be a datum defined in `site.sfincs.waterlevels.datums`
+    """
+
+    harmonic_amplitude: us.UnitfulLength
+    datum: str
+
+
+class PlottingModel(BaseModel):
+    """
+    The configuration of the plotting in the gui.
+
+    Attributes
+    ----------
+    excluded_datums : list[str]
+        A list of datums that will be excluded from the forcing plot in event windows.
+    synthetic_tide : SyntheticTideModel
+        The configuration of the synthetic tide.
+    """
+
+    synthetic_tide: SyntheticTideModel
+    excluded_datums: list[str] = Field(default_factory=list)
+
+
+class GuiModel(BaseModel):
+    """The accepted input for the variable gui in Site.
+
+    Attributes
+    ----------
+    units : GuiUnitModel
+        The unit system used in the GUI.
+    mapbox_layers : MapboxLayersModel
+        The configuration of the mapbox layers in the GUI.
+    visualization_layers : VisualizationLayersModel
+        The configuration of the visualization layers in the GUI.
+    plotting : PlottingModel
+        The configuration for creating hazard forcing plots.
+    """
+
+    units: GuiUnitModel
+    mapbox_layers: MapboxLayersModel
+    visualization_layers: VisualizationLayersModel
+    plotting: PlottingModel
+
+    @staticmethod
+    def read_toml(path: Path) -> "GuiModel":
+        with open(path, mode="rb") as fp:
+            toml_contents = load_toml(fp)
+
+        return GuiModel(**toml_contents)

flood_adapt/config/sfincs.py

@@ -0,0 +1,336 @@
+import math
+from enum import Enum
+from pathlib import Path
+from typing import Optional, Union
+
+from pydantic import AfterValidator, BaseModel, Field, model_validator
+from tomli import load as load_toml
+from typing_extensions import Annotated
+
+from flood_adapt.objects.forcing import unit_system as us
+from flood_adapt.objects.forcing.tide_gauge import TideGauge
+from flood_adapt.objects.forcing.timeseries import Scstype
+
+
+def ensure_ascii(s: str):
+    assert s.isascii()
+    return s
+
+
+AsciiStr = Annotated[str, AfterValidator(ensure_ascii)]
+
+
+class Cstype(str, Enum):
+    """The accepted input for the variable cstype in Site."""
+
+    projected = "projected"
+    spherical = "spherical"
+
+
+class SCSModel(BaseModel):
+    """Class describing the accepted input for the variable scs.
+
+    Includes the file with the non-dimensional SCS rainfall curves in the site folder and the SCS rainfall curve type.
+
+    Attributes
+    ----------
+    file : str
+        The path to the SCS rainfall curves file.
+    type : Scstype
+        The type of the SCS rainfall curve.
+    """
+
+    file: str
+    type: Scstype
+
+
+class RiverModel(BaseModel):
+    """Model that describes the accepted input for the variable river in Site.
+
+    Attributes
+    ----------
+    name : str
+        The name of the river.
+    description : Optional[str], default=None
+        description of the river.
+    mean_discharge : us.UnitfulDischarge
+        The mean discharge of the river.
+    x_coordinate : float
+        The x coordinate of the river.
+    y_coordinate : float
+        The y coordinate of the river.
+    """
+
+    name: str
+    description: Optional[str] = None
+    mean_discharge: us.UnitfulDischarge
+    x_coordinate: float
+    y_coordinate: float
+
+
+class ObsPointModel(BaseModel):
+    """The accepted input for the variable obs_point in Site.
+
+    obs_points is used to define output locations in the hazard model, which will be plotted in the user interface.
+
+    Attributes
+    ----------
+    name : Union[int, AsciiStr]
+        The name of the observation point.
+    description : Optional[str], default=""
+        The description of the observation point.
+    ID : Optional[int], default=None
+        The ID of the observation point.
+    file : Optional[str], default=None
+        The path to the observation point data file.
+    """
+
+    name: Union[int, AsciiStr]
+    description: Optional[str] = ""
+    ID: Optional[int] = (
+        None  # if the observation station is also a tide gauge, this ID should be the same as for obs_station
+    )
+    file: Optional[str] = None  # for locally stored data
+    lat: float
+    lon: float
+
+
+class FloodFrequencyModel(BaseModel):
+    """The accepted input for the variable flood_frequency in Site."""
+
+    flooding_threshold: us.UnitfulLength
+
+
+class DemModel(BaseModel):
+    """The accepted input for the variable dem in Site.
+
+    Attributes
+    ----------
+    filename : str
+        The path to the digital elevation model file.
+    units : us.UnitTypesLength
+        The units of the digital elevation model file.
+    """
+
+    filename: str
+    units: us.UnitTypesLength
+
+
+class FloodmapType(str, Enum):
+    """The accepted input for the variable floodmap in Site."""
+
+    water_level = "water_level"
+    water_depth = "water_depth"
+
+
+class DatumModel(BaseModel):
+    """
+    The accepted input for the variable datums in WaterlevelReferenceModel.
+
+    Attributes
+    ----------
+    name : str
+        The name of the vertical reference model.
+    height : us.UnitfulLength
+        The height of the vertical reference model relative to the main reference.
+    """
+
+    name: str
+    height: us.UnitfulLength
+
+
+class WaterlevelReferenceModel(BaseModel):
+    """The accepted input for the variable water_level in Site.
+
+    Waterlevels timeseries are calculated from user input, assumed to be relative to the `reference` vertical reference model.
+
+    For plotting in the GUI, the `reference` vertical reference model is used as the main zero-reference, all values are relative to this.
+    All other vertical reference models are plotted as dashed lines.
+
+    Attributes
+    ----------
+    reference : str
+        The name of the vertical reference model that is used as the main zero-reference.
+    datums : list[DatumModel]
+        The vertical reference models that are used to calculate the waterlevels timeseries.
+        The datums are used to calculate the waterlevels timeseries, which are relative to the `reference` vertical reference model.
+    """
+
+    reference: str
+    datums: list[DatumModel] = Field(default_factory=list)
+
+    def get_datum(self, name: str) -> DatumModel:
+        for datum in self.datums:
+            if datum.name == name:
+                return datum
+        raise ValueError(f"Could not find datum with name {name}")
+
+    @model_validator(mode="after")
+    def main_reference_should_be_in_datums_and_eq_zero(self):
+        if self.reference not in [datum.name for datum in self.datums]:
+            raise ValueError(f"Reference {self.reference} not in {self.datums}")
+        if not math.isclose(
+            self.get_datum(self.reference).height.value, 0, abs_tol=1e-6
+        ):
+            raise ValueError(f"Reference {self.reference} height is not zero")
+        return self
+
+    @model_validator(mode="after")
+    def all_datums_should_have_unique_names(self):
+        datum_names = [datum.name for datum in self.datums]
+        if len(set(datum_names)) != len(datum_names):
+            raise ValueError(f"Duplicate datum names found: {datum_names}")
+        return self
+
+
+class CycloneTrackDatabaseModel(BaseModel):
+    """The accepted input for the variable cyclone_track_database in Site.
+
+    Attributes
+    ----------
+    file : str
+        The path to the cyclone track database file.
+    """
+
+    file: str
+
+
+class SlrScenariosModel(BaseModel):
+    """The accepted input for the variable slr_scenarios.
+
+    Attributes
+    ----------
+    file : str
+        The path to the sea level rise scenarios file.
+    relative_to_year : int
+        The year to which the sea level rise scenarios are relative.
+    """
+
+    file: str
+    relative_to_year: int
+
+
+class FloodModel(BaseModel):
+    """The accepted input for the variable overland_model and offshore_model in Site.
+
+    Attributes
+    ----------
+    name : str
+        The name of the directory in `static/templates/<directory>` that contains the template model files.
+    reference : str
+        The name of the vertical reference model that is used as the reference datum. Should be defined in water_level.datums.
+    vertical_offset : Optional[us.UnitfulLength], default = None
+        The vertical offset of the vertical reference model relative to the main reference.
+        Given that the height of the vertical reference model is often determined by external sources,
+        this vertical offset can be used to correct systematic over-/underestimation of a vertical reference model.
+    """
+
+    name: str
+    reference: str
+
+    # this used to be water_level_offset from events
+    vertical_offset: Optional[us.UnitfulLength] = None
+
+
+class SfincsConfigModel(BaseModel):
+    """The expected variables and data types of attributes of the SfincsConfig class.
+
+    Attributes
+    ----------
+    csname : str
+        The name of the CS model.
+    cstype : Cstype
+        Cstype of the CS model. must be either "projected" or "spherical".
+    version : Optional[str], default = None
+        The version of the CS model. If None, the version is not specified.
+    offshore_model : Optional[FloodModel], default = None
+        The offshore model. If None, the offshore model is not specified.
+    overland_model : FloodModel
+        The overland model. This is the main model used for the simulation.
+    floodmap_units : us.UnitTypesLength
+        The units used for the output floodmap. Sfincs always produces in metric units, this is used to convert the floodmap to the correct units.
+    save_simulation : Optional[bool], default = False
+        Whether to keep or delete the simulation files after the simulation is finished and all output files are created.
+        If True, the simulation files are kept. If False, the simulation files are deleted.
+    """
+
+    csname: str
+    cstype: Cstype
+    version: Optional[str] = None
+    offshore_model: Optional[FloodModel] = None
+    overland_model: FloodModel
+    floodmap_units: us.UnitTypesLength
+    save_simulation: Optional[bool] = False
+
+
+class SfincsModel(BaseModel):
+    """The expected variables and data types of attributes of the Sfincs class.
+
+    Attributes
+    ----------
+    config : SfincsConfigModel
+        The configuration of the Sfincs model.
+    water_level : WaterlevelReferenceModel
+        The collection of all datums and the main reference datum.
+    dem : DemModel
+        The digital elevation model.
+    flood_frequency : FloodFrequencyModel, default = FloodFrequencyModel()
+        The flood frequency model.
+    slr : SlrScenariosModel
+        Specification of the sea level rise scenarios.
+    cyclone_track_database : CycloneTrackDatabaseModel, optional, default = None
+        The cyclone track database model.
+    scs : SCSModel, optional, default = None
+        The SCS model.
+    tide_gauge : TideGauge, optional, default = None
+        The tide gauge model.
+    river : list[RiverModel], optional, default = None
+        The river model.
+    obs_point : list[ObsPointModel], optional, default = None
+        The observation point model.
+    """
+
+    config: SfincsConfigModel
+    water_level: WaterlevelReferenceModel
+    cyclone_track_database: Optional[CycloneTrackDatabaseModel] = None
+    slr_scenarios: Optional[SlrScenariosModel] = None
+    scs: Optional[SCSModel] = None  # optional for the US to use SCS rainfall curves
+    dem: DemModel
+
+    flood_frequency: FloodFrequencyModel = FloodFrequencyModel(
+        flooding_threshold=us.UnitfulLength(value=0.0, units=us.UnitTypesLength.meters)
+    )  # TODO we dont actually use this anywhere?
+
+    tide_gauge: Optional[TideGauge] = None
+    river: Optional[list[RiverModel]] = None
+    obs_point: Optional[list[ObsPointModel]] = None
+
+    @staticmethod
+    def read_toml(path: Path) -> "SfincsModel":
+        with open(path, mode="rb") as fp:
+            toml_contents = load_toml(fp)
+
+        return SfincsModel(**toml_contents)
+
+    @model_validator(mode="after")
+    def ensure_references_exist(self):
+        datum_names = [d.name for d in self.water_level.datums]
+
+        if self.config.overland_model.reference not in datum_names:
+            raise ValueError(
+                f"Could not find reference `{self.config.overland_model.reference}` in available datums: {datum_names}."
+            )
+
+        if self.config.offshore_model is not None:
+            if self.config.offshore_model.reference not in datum_names:
+                raise ValueError(
+                    f"Could not find reference `{self.config.offshore_model.reference}` in available datums: {datum_names}."
+                )
+
+        if self.tide_gauge is not None:
+            if self.tide_gauge.reference not in datum_names:
+                raise ValueError(
+                    f"Could not find reference `{self.tide_gauge.reference}` in available datums: {datum_names}."
+                )
+
+        return self

flood_adapt/config/site.py

@@ -0,0 +1,124 @@
+import os
+from pathlib import Path
+from typing import Literal, Union
+
+import tomli
+import tomli_w
+from pydantic import BaseModel, Field
+
+from flood_adapt.config.fiat import FiatModel
+from flood_adapt.config.gui import GuiModel
+from flood_adapt.config.sfincs import SfincsModel
+
+
+class StandardObjectModel(BaseModel):
+    """The accepted input for the variable standard_object in Site."""
+
+    events: list[str] = Field(default_factory=list)
+    projections: list[str] = Field(default_factory=list)
+    strategies: list[str] = Field(default_factory=list)
+
+
+class Site(BaseModel):
+    """The expected variables and data types of attributes of the Site class.
+
+    Attributes
+    ----------
+    name : str
+        Name of the site.
+    description : str, default=""
+        Description of the site.
+    lat : float
+        Latitude of the site.
+    lon : float
+        Longitude of the site.
+    standard_objects : StandardObjectModel, default=StandardObjectModel()
+        Standard objects of the site.
+    gui : GuiModel
+        GUI model of the site.
+    sfincs : SfincsModel
+        SFincs model of the site.
+    fiat : FiatModel
+        Fiat model of the site.
+    """
+
+    name: str
+    description: str = ""
+    lat: float
+    lon: float
+    standard_objects: StandardObjectModel = StandardObjectModel()
+
+    gui: GuiModel
+    sfincs: SfincsModel
+    fiat: FiatModel
+
+    def save(
+        self,
+        filepath: Union[str, os.PathLike],
+        sfincs: str = "sfincs.toml",
+        fiat: str = "fiat.toml",
+        gui: str = "gui.toml",
+    ) -> None:
+        """Write toml file from model object."""
+        parent_folder = Path(filepath).parent
+        config_dict = {
+            "name": self.name,
+            "description": self.description,
+            "lat": self.lat,
+            "lon": self.lon,
+            "components": {},
+        }
+
+        if self.sfincs is not None:
+            config_dict["components"]["sfincs"] = sfincs
+            with open(parent_folder / sfincs, "wb") as f:
+                tomli_w.dump(self.sfincs.model_dump(exclude_none=True), f)
+
+        if self.fiat is not None:
+            config_dict["components"]["fiat"] = fiat
+            with open(parent_folder / fiat, "wb") as f:
+                tomli_w.dump(self.fiat.model_dump(exclude_none=True), f)
+
+        if self.gui is not None:
+            config_dict["components"]["gui"] = gui
+            with open(parent_folder / gui, "wb") as f:
+                tomli_w.dump(self.gui.model_dump(exclude_none=True), f)
+
+        with open(filepath, "wb") as f:
+            tomli_w.dump(config_dict, f)
+
+    @staticmethod
+    def load_file(filepath: Union[str, os.PathLike]) -> "Site":
+        """Create Site from toml file."""
+        return SiteBuilder.load_file(Path(filepath))
+
+
+class SiteBuilder(BaseModel):
+    """Pydantic model that reads the site configuration file and builds the site model.
+
+    Note that the components are not required, as the site may not have all of them.
+    Second, note that the components are assumed to be the file names of the component configs, located in the same directory as the site configuration file.
+    """
+
+    name: str
+    description: str = ""
+    lat: float
+    lon: float
+    components: dict[Literal["sfincs", "fiat", "gui"], str]
+
+    @staticmethod
+    def load_file(file_path: Path) -> "Site":
+        with open(file_path, "rb") as f:
+            model_dict = tomli.load(f)
+
+        toml_dir = file_path.parent
+        if (sfincs_config := model_dict["components"].get("sfincs")) is not None:
+            model_dict["sfincs"] = SfincsModel.read_toml(toml_dir / sfincs_config)
+
+        if (gui_config := model_dict["components"].get("gui")) is not None:
+            model_dict["gui"] = GuiModel.read_toml(toml_dir / gui_config)
+
+        if (fiat_config := model_dict["components"].get("fiat")) is not None:
+            model_dict["fiat"] = FiatModel.read_toml(toml_dir / fiat_config)
+
+        return Site(**model_dict)