flood-adapt 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

flood_adapt/objects/__init__.py

@@ -1,13 +1,23 @@
-from .benefits.benefits import Benefit
-from .events.event_factory import EventFactory
-from .events.event_set import EventSet
-from .events.events import Event
-from .events.historical import HistoricalEvent
-from .events.hurricane import HurricaneEvent
-from .events.synthetic import SyntheticEvent
-from .forcing.forcing_factory import ForcingFactory
-from .measures.measure_factory import MeasureFactory
-from .measures.measures import (
+from flood_adapt.objects.benefits.benefits import Benefit, CurrentSituationModel
+from flood_adapt.objects.events.event_factory import EventFactory
+from flood_adapt.objects.events.event_set import EventSet, SubEventModel
+from flood_adapt.objects.events.events import (
+    Event,
+    Mode,
+    Template,
+    TimeFrame,
+)
+from flood_adapt.objects.events.historical import HistoricalEvent
+from flood_adapt.objects.events.hurricane import HurricaneEvent
+from flood_adapt.objects.events.synthetic import SyntheticEvent
+from flood_adapt.objects.forcing.forcing import (
+    ForcingSource,
+    ForcingType,
+    IForcing,
+)
+from flood_adapt.objects.forcing.forcing_factory import ForcingFactory
+from flood_adapt.objects.measures.measure_factory import MeasureFactory
+from flood_adapt.objects.measures.measures import (
     Buyout,
     Elevate,
     FloodProof,
@@ -18,10 +28,14 @@ from .measures.measures import (
     Pump,
     SelectionType,
 )
-from .object_model import Object
-from .projections.projections import Projection
-from .scenarios.scenarios import Scenario
-from .strategies.strategies import Strategy
+from flood_adapt.objects.object_model import Object
+from flood_adapt.objects.projections.projections import (
+    PhysicalProjection,
+    Projection,
+    SocioEconomicChange,
+)
+from flood_adapt.objects.scenarios.scenarios import Scenario
+from flood_adapt.objects.strategies.strategies import Strategy
 
 __all__ = [
     # Object
@@ -31,29 +45,38 @@ __all__ = [
     "Measure",
     "MeasureType",
     "SelectionType",
-    "MeasureType",
     "Buyout",
     "Elevate",
     "FloodProof",
     "FloodWall",
     "GreenInfrastructure",
-    "MeasureType",
     "Pump",
     # Events
     "Event",
     "EventFactory",
-    "EventSet",
     "SyntheticEvent",
     "HistoricalEvent",
     "HurricaneEvent",
+    "TimeFrame",
+    "Mode",
+    "Template",
+    # EventSet
+    "EventSet",
+    "SubEventModel",
     # Forcing
     "ForcingFactory",
+    "IForcing",
+    "ForcingType",
+    "ForcingSource",
     # Projections
     "Projection",
+    "PhysicalProjection",
+    "SocioEconomicChange",
     # Strategies
     "Strategy",
     # Scenarios
     "Scenario",
     # Benefits
     "Benefit",
+    "CurrentSituationModel",
 ]

flood_adapt/objects/benefits/benefits.py

@@ -28,8 +28,8 @@ class Benefit(Object):
     ----------
     name: str
         The name of the benefit analysis.
-    description: str, default=""
-        The description of the benefit analysis.
+    description: str
+        The description of the benefit analysis. Defaults to "".
     strategy : str
         The name of the strategy. Should be a strategy saved in the database.
     event_set : str
@@ -44,10 +44,10 @@ class Benefit(Object):
         The name of the baseline strategy.
     discount_rate : float
         The discount rate for the analysis.
-    implementation_cost : Optional[float], default = None
-        The implementation cost of the strategy.
-    annual_maint_cost : Optional[float], default = None
-        The annual maintenance cost of the strategy.
+    implementation_cost : Optional[float]
+        The implementation cost of the strategy. Defaults to None.
+    annual_maint_cost : Optional[float]
+        The annual maintenance cost of the strategy. Defaults to None.
     """
 
     strategy: str

flood_adapt/objects/events/event_set.py

@@ -33,10 +33,10 @@ class EventSet(Object):
     ----------
     name : str
         The name of the event.
-    description : str, default=""
-        The description of the event.
-    mode : Mode, default=Mode.risk
-        The mode of the event.
+    description : str
+        The description of the event. Defaults to "".
+    mode : Mode
+        The mode of the event. Defaults to Mode.risk.
     sub_events : List[SubEventModel]
         The sub events of the event set.
     """

flood_adapt/objects/events/events.py

@@ -23,14 +23,27 @@ from flood_adapt.objects.object_model import Object
 
 
 class Mode(str, Enum):
-    """Class describing the accepted input for the variable mode in Event."""
+    """Class describing the accepted input for the variable mode in Event.
+
+    Attributes
+    ----------
+    single_event : The single event mode.
+    risk : The risk mode.
+    """
 
     single_event = "single_event"
     risk = "risk"
 
 
 class Template(str, Enum):
-    """Class describing the accepted input for the variable template in Event."""
+    """Class describing the accepted input for the variable template in Event.
+
+    Attributes
+    ----------
+    Synthetic : The synthetic template.
+    Hurricane : The hurricane template.
+    Historical : The historical template.
+    """
 
     Synthetic = "Synthetic"
     Hurricane = "Hurricane"
@@ -66,8 +79,8 @@ class Event(Object):
     ----------
     name : str
         The name of the event.
-    description : str, default=""
-        The description of the event.
+    description : str
+        The description of the event. Defaults to "".
     time : TimeFrame
         The time frame of the event.
     template : Template
@@ -200,7 +213,7 @@ class Event(Object):
                     f"Allowed sources are: {allowed_sources}"
                 )
 
-        if Settings().validate_allowed_forcings:
+        if Settings().validate_allowed_forcings and hasattr(self, "ALLOWED_FORCINGS"):
             # Validate forcings
             for _, concrete_forcings in self.forcings.items():
                 for concrete_forcing in concrete_forcings:

flood_adapt/objects/events/historical.py

@@ -5,6 +5,9 @@ from flood_adapt.objects.forcing.forcing import (
     ForcingSource,
     ForcingType,
 )
+from flood_adapt.objects.forcing.time_frame import TimeFrame
+
+__all__ = ["HistoricalEvent", "TimeFrame"]
 
 
 class HistoricalEvent(Event):
@@ -14,16 +17,16 @@ class HistoricalEvent(Event):
     ----------
     name : str
         The name of the event.
-    description : str, default=""
-        The description of the event.
+    description : str
+        The description of the event. Defaults to "".
     time : TimeFrame
         The time frame of the event.
-    template : Template, default=Template.Historical
-        The template of the event.
-    mode : Mode, default=Mode.single_event
-        The mode of the event.
-    rainfall_multiplier : float, default=1.0
-        The rainfall multiplier of the event.
+    template : Template
+        The template of the event. Defaults to Template.Historical.
+    mode : Mode
+        The mode of the event. Defaults to Mode.single_event.
+    rainfall_multiplier : float
+        The rainfall multiplier of the event. Defaults to 1.0.
     forcings : dict[ForcingType, list[IForcing]]
         The forcings of the event.
     """

flood_adapt/objects/events/hurricane.py

@@ -8,6 +8,9 @@ from flood_adapt.objects.forcing.forcing import (
     ForcingSource,
     ForcingType,
 )
+from flood_adapt.objects.forcing.time_frame import TimeFrame
+
+__all__ = ["HurricaneEvent", "TranslationModel", "TimeFrame"]
 
 
 class TranslationModel(BaseModel):
@@ -28,16 +31,16 @@ class HurricaneEvent(Event):
     ----------
     name : str
         The name of the event.
-    description : str, default=""
-        The description of the event.
+    description :
+        The description of the event. Defaults to "".
     time : TimeFrame
         The time frame of the event.
-    template : Template, default=Template.Hurricane
-        The template of the event.
-    mode : Mode, default=Mode.single_event
-        The mode of the event.
-    rainfall_multiplier : float, default=1.0
-        The rainfall multiplier of the event.
+    template : Template
+        The template of the event. Defaults to Template.Hurricane.
+    mode : Mode
+        The mode of the event. Defaults to Mode.single_event.
+    rainfall_multiplier : float
+        The rainfall multiplier of the event. Defaults to 1.0.
     forcings : dict[ForcingType, list[IForcing]]
         The forcings of the event.
     track_name : str

flood_adapt/objects/events/synthetic.py

@@ -2,9 +2,11 @@ from typing import ClassVar, List
 
 from flood_adapt.objects.events.events import (
     Event,
+    Template,
+)
+from flood_adapt.objects.forcing.forcing import (
     ForcingSource,
     ForcingType,
-    Template,
 )
 
 
@@ -15,12 +17,12 @@ class SyntheticEvent(Event):
     ----------
     time : TimeFrame
         The time frame of the event.
-    template : Template, default=Template.Synthetic
-        The template of the event.
-    mode : Mode, default=Mode.single_event
-        The mode of the event.
-    rainfall_multiplier : float, default=1.0
-        The rainfall multiplier of the event.
+    template : Template
+        The template of the event. Defaults to Template.Synthetic.
+    mode : Mode
+        The mode of the event. Defaults to Mode.single_event.
+    rainfall_multiplier : float
+        The rainfall multiplier of the event. Defaults to 1.0.
     forcings : dict[ForcingType, list[IForcing]]
         The forcings of the event.
     """

flood_adapt/objects/forcing/forcing.py

@@ -14,7 +14,15 @@ from flood_adapt.misc.log import FloodAdaptLogging
 
 ### ENUMS ###
 class ForcingType(str, Enum):
-    """Enum class for the different types of forcing parameters."""
+    """Enum class for the different types of forcing parameters.
+
+    Attributes
+    ----------
+    RAINFALL : The type of forcing parameter for rainfall.
+    WIND : The type of forcing parameter for wind.
+    DISCHARGE : The type of forcing parameter for discharge.
+    WATERLEVEL : The type of forcing parameter for water level.
+    """
 
     WIND = "WIND"
     RAINFALL = "RAINFALL"

flood_adapt/objects/forcing/plotting.py

@@ -39,6 +39,7 @@ from flood_adapt.objects.forcing.wind import (
     WindSynthetic,
 )
 
+# TODO remove from frontend
 UNPLOTTABLE_SOURCES = [ForcingSource.TRACK, ForcingSource.METEO, ForcingSource.MODEL]
 logger = FloodAdaptLogging.getLogger("Plotting")
 

flood_adapt/objects/forcing/tide_gauge.py

@@ -27,24 +27,24 @@ class TideGauge(BaseModel):
 
     Attributes
     ----------
-    name : Optional[int | str], default=None
-        Name of the tide gauge.
-    description : Optional[str], default=""
-        Description of the tide gauge.
+    name : Optional[int, str]
+        Name of the tide gauge. Default is None.
+    description : Optional[str]
+        Description of the tide gauge. Default is "".
     source : TideGaugeSource
         Source of the tide gauge data.
     reference : str
         Reference of the tide gauge data. Should be defined in site.sfincs.water_level
-    ID : Optional[int], default=None
-        ID of the tide gauge data.
-    file : Optional[Path], default=None
-        Only for file based tide gauges. Should be a path relative to the static folder.
-    lat : Optional[float], default=None
-        Latitude of the tide gauge data.
-    lon : Optional[float], default=None
-        Longitude of the tide gauge data.
-    units : us.UnitTypesLength, default=us.UnitTypesLength.meters
-        Units of the water levels in the downloaded file.
+    ID : Optional[int]
+        ID of the tide gauge data. Default is None.
+    file : Optional[Path]
+        Only for file based tide gauges. Should be a path relative to the static folder. Default is None.
+    lat : Optional[float]
+        Latitude of the tide gauge data. Default is None.
+    lon : Optional[float]
+        Longitude of the tide gauge data. Default is None.
+    units : us.UnitTypesLength
+        Units of the water levels in the downloaded file. Default is us.UnitTypesLength.meters.
 
     """
 

flood_adapt/objects/forcing/time_frame.py

@@ -12,6 +12,19 @@ REFERENCE_TIME = datetime(year=2021, month=1, day=1, hour=0, minute=0, second=0)
 
 
 class TimeFrame(BaseModel):
+    """
+    Class representing a time frame for a simulation.
+
+    Attributes
+    ----------
+    start_time : datetime
+        The start time of the simulation.
+    end_time : datetime
+        The end time of the simulation.
+    time_step : timedelta
+        The time step of the simulation. Default is calculated as 1/1000 of the duration.
+    """
+
     start_time: datetime = REFERENCE_TIME
     end_time: datetime = REFERENCE_TIME + timedelta(days=1)
 

flood_adapt/objects/forcing/timeseries.py

@@ -331,15 +331,21 @@ class BlockTimeseries(SyntheticTimeseries):
             end=(REFERENCE_TIME + self.end_time.to_timedelta()),
             freq=time_step,
         )
-        ts = np.zeros((len(tt),)) + self.peak_value.value
+        if self.peak_value:
+            height_value = self.peak_value.value
+        elif self.cumulative:
+            area = self.cumulative.value
+            base = self.duration.convert(
+                us.UnitTypesTime.hours
+            )  # always expect duration in hours
+            height_value = area / base
+
+        ts = np.zeros((len(tt),)) + height_value
         return ts
 
     @model_validator(mode="after")
     def validate_attrs(self):
-        if not self.peak_value:
-            raise ValueError(
-                f"{self.__class__.__name__} must have `peak_value` specified. {self.peak_value}"
-            )
+        # either peak_value or cumulative must be set, which is already checked in the parent class: `either_value_or_cumulative`
         return self
 
 
@@ -355,17 +361,26 @@ class TriangleTimeseries(SyntheticTimeseries):
             freq=time_step,
         )
         tt_seconds = (tt - REFERENCE_TIME).total_seconds()
+        peak_time = self.peak_time.to_timedelta().total_seconds()
+        start_time = self.start_time.to_timedelta().total_seconds()
+
+        if self.peak_value:
+            height_value = self.peak_value.value
+        elif self.cumulative:
+            area = self.cumulative.value
+            base = self.duration.convert(
+                us.UnitTypesTime.hours
+            )  # always expect duration in hours
+            height_value = (2 * area) / base
 
         ascending_slope = (
-            self.peak_value.value
+            height_value
             / (self.peak_time - self.start_time).to_timedelta().total_seconds()
         )
         descending_slope = (
-            -self.peak_value.value
+            -height_value
             / (self.end_time - self.peak_time).to_timedelta().total_seconds()
         )
-        peak_time = self.peak_time.to_timedelta().total_seconds()
-        start_time = self.start_time.to_timedelta().total_seconds()
 
         ts = np.piecewise(
             tt_seconds,
@@ -373,7 +388,7 @@ class TriangleTimeseries(SyntheticTimeseries):
             [
                 lambda x: np.maximum(ascending_slope * (x - start_time), 0),
                 lambda x: np.maximum(
-                    descending_slope * (x - peak_time) + self.peak_value.value, 0
+                    descending_slope * (x - peak_time) + height_value, 0
                 ),
                 0,
             ],
@@ -382,10 +397,7 @@ class TriangleTimeseries(SyntheticTimeseries):
 
     @model_validator(mode="after")
     def validate_attrs(self):
-        if not self.peak_value:
-            raise ValueError(
-                f"{self.__class__.__name__} must have `peak_value` specified. {self.peak_value}"
-            )
+        # either peak_value or cumulative must be set, which is already checked in the parent class: `either_value_or_cumulative`
         return self
 
 
@@ -549,4 +561,4 @@ class TimeseriesFactory:
 
     @staticmethod
     def from_object(obj: SyntheticTimeseries) -> SyntheticTimeseries:
-        return TimeseriesFactory.from_args(**obj.model_dump())
+        return TimeseriesFactory.from_args(**obj.model_dump(exclude_none=True))

flood_adapt/objects/measures/measures.py

@@ -21,6 +21,25 @@ class MeasureCategory(str, Enum):
 
 
 class MeasureType(str, Enum):
+    """Class describing the accepted input for the variable 'type' in Measure.
+
+    Each type of measure is associated with a category (hazard or impact) and can be used to determine the type of measure.
+
+    Attributes
+    ----------
+    floodwall : A floodwall measure.
+    thin_dam : A thin dam measure.
+    levee : A levee measure.
+    pump : A pump measure.
+    culvert : A culvert measure.
+    water_square : A water square measure.
+    greening : A greening measure.
+    total_storage : A total storage measure.
+    elevate_properties : An elevate properties measure.
+    buyout_properties : A buyout properties measure.
+    floodproof_properties : A floodproof properties measure.
+    """
+
     # Hazard measures
     floodwall = "floodwall"
     thin_dam = "thin_dam"  # For now, same functionality as floodwall TODO: Add thin dam functionality
@@ -70,7 +89,17 @@ class MeasureType(str, Enum):
 
 
 class SelectionType(str, Enum):
-    """Class describing the accepted input for the variable 'selection_type' in ImpactMeasure."""
+    """Class describing the accepted input for the variable 'selection_type' in Measures.
+
+    It is used to determine where to apply the measure to a model.
+
+    Attributes
+    ----------
+    aggregation_area : Use aggregation area as geometry for the measure.
+    polygon : Use polygon as geometry for the measure.
+    polyline : Use polyline as geometry for the measure.
+    all : Apply the measure to all geometries in the database.
+    """
 
     aggregation_area = "aggregation_area"
     polygon = "polygon"
@@ -267,7 +296,7 @@ class Buyout(ImpactMeasure):
         Name of the aggregation area.
     property_type : str
         Type of property. Should be "residential" or "commercial".
-    elevation : UnitfulLengthRefValue
+    elevation : us.UnitfulLengthRefValue
         Elevation of the properties.
 
     """
@@ -297,9 +326,8 @@ class FloodProof(ImpactMeasure):
         Name of the aggregation area.
     property_type : str
         Type of property. Should be "residential" or "commercial".
-    elevation : UnitfulLengthRefValue
+    elevation : us.UnitfulLengthRefValue
         Elevation of the properties.
-
     """
 
     type: MeasureType = MeasureType.floodproof_properties
@@ -316,11 +344,11 @@ class FloodWall(HazardMeasure):
         Name of the measure.
     description: str
         Description of the measure.
-    type : MeasureType, default MeasureType.floodwall
-        Type of measure. Should be "floodwall"
+    type : MeasureType
+        Type of measure. Should be "MeasureType.floodwall"
     selection_type : SelectionType
-        Type of selection. Should be "polygon" or "aggregation_area".
-    polygon_file : str, Optional
+        Type of selection. Should be "SelectionType.polygon" or "SelectionType.aggregation_area".
+    polygon_file : Optional[str]
         Path to a polygon file, either absolute or relative to the measure path.
     elevation : us.UnitfulLength
         Height of the floodwall.
@@ -462,11 +490,6 @@ class GreenInfrastructure(HazardMeasure):
         percent_area : float, optional
             Percentage area covered by green infrastructure [%], by default 100.0
 
-        Returns
-        -------
-        float
-
-
         Returns
         -------
         float
@@ -492,8 +515,8 @@ class GreenInfrastructure(HazardMeasure):
 
         Returns
         -------
-        floatd
-            Area [m2]
+        area : float
+            Area of the given polygon
         """
         # Determine local CRS
         crs = pyproj.CRS.from_string(site.sfincs.config.csname)

flood_adapt/objects/object_model.py

@@ -13,8 +13,8 @@ class Object(BaseModel):
     ----------
     name : str
         Name of the object.
-    description : str (optional)
-        Description of the object.
+    description : str
+        Description of the object. defaults to "".
     """
 
     name: str = Field(

flood_adapt/objects/projections/projections.py

@@ -14,14 +14,14 @@ class PhysicalProjection(BaseModel):
 
     Attributes
     ----------
-    sea_level_rise : us.UnitfulLength, default = us.UnitfulLength(0.0, us.UnitTypesLength.meters).
-        The sea level rise in meters.
-    subsidence : us.UnitfulLength, default = us.UnitfulLength(0.0, us.UnitTypesLength.meters).
-        The subsidence in meters.
-    rainfall_multiplier : float, default = 1.0.
-        The rainfall multiplier.
-    storm_frequency_increase : float, default = 0.0.
-        The storm frequency increase as a percentage.
+    sea_level_rise : us.UnitfulLength
+        The sea level rise in meters. Default=us.UnitfulLength(0.0, us.UnitTypesLength.meters).
+    subsidence : us.UnitfulLength
+        The subsidence in meters. Default=us.UnitfulLength(0.0, us.UnitTypesLength.meters).
+    rainfall_multiplier : float
+        The rainfall multiplier. Default = 1.0.
+    storm_frequency_increase : float
+        The storm frequency increase as a percentage. Default = 0.0.
     """
 
     sea_level_rise: us.UnitfulLength = us.UnitfulLength(
@@ -39,16 +39,16 @@ class SocioEconomicChange(BaseModel):
 
     Attributes
     ----------
-    population_growth_existing : float, default = 0.0.
-        The existing population growth rate.
-    economic_growth : float, default = 0.0.
-        The economic growth rate.
-    population_growth_new : float, default = 0.0.
-        The population growth rate for new developments.
-    new_development_elevation : us.UnitfulLengthRefValue, default = None.
-        The elevation of new developments.
-    new_development_shapefile : str, default = None.
-        The path to the shapefile of new developments.
+    population_growth_existing : float
+        The existing population growth rate. default=0.0
+    economic_growth : float
+        The economic growth rate. default=0.0.
+    population_growth_new : float
+        The population growth rate for new developments. default=0.0.
+    new_development_elevation : Optional[us.UnitfulLengthRefValue]
+        The elevation of new developments. default=None.
+    new_development_shapefile : Optional[str]
+        The path to the shapefile of new developments. default=None.
     """
 
     population_growth_existing: Optional[float] = 0.0

flood_adapt/objects/strategies/strategies.py

@@ -24,10 +24,31 @@ class Strategy(Object):
     _measure_objects: list[Measure] | None = None
 
     def initialize_measure_objects(self, measures: list[Measure]) -> None:
+        """Initialize the measure objects associated with this strategy.
+
+        Parameters
+        ----------
+        measures : list[Measure]
+            A list of measure objects to be associated with this strategy. Should be a list of measure objects that are saved in the database.
+        """
         self._measure_objects = measures
 
     def get_measures(self) -> list[Measure]:
-        """Get the measures paths and types."""
+        """Get the measures associated with this strategy.
+
+        Note that this method will return the measure objects, not just their names.
+        The measure objects are initialized using the `initialize_measure_objects` method.
+
+        Returns
+        -------
+        measures : list[Measure]
+            The list of measure objects associated with this strategy.
+
+        Raises
+        ------
+        ValueError
+            If the measure objects have not been initialized.
+        """
         # Get measure paths using a database structure
         if self._measure_objects is None:
             raise ValueError(

flood_adapt/workflows/benefit_runner.py

@@ -69,7 +69,7 @@ class BenefitRunner:
 
         Returns
         -------
-        bool
+        has_run : bool
             True if the analysis has already been run, else False
         """
         # Output files to check