floodmodeller-api 0.4.4.post1__py3-none-any.whl → 0.5.0.post1__py3-none-any.whl

floodmodeller_api/units/conveyance.py

@@ -1,31 +1,34 @@
 from __future__ import annotations
 
 from functools import lru_cache
+from typing import TYPE_CHECKING
 
 import numpy as np
 import pandas as pd
-from shapely import LineString, MultiLineString, Polygon, intersection
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
 
 MINIMUM_PERIMETER_THRESHOLD = 1e-8
 
 
 def calculate_cross_section_conveyance(
-    x: np.ndarray,
-    y: np.ndarray,
-    n: np.ndarray,
-    rpl: np.ndarray,
-    panel_markers: np.ndarray,
+    x: NDArray[np.float64],
+    y: NDArray[np.float64],
+    n: NDArray[np.float64],
+    rpl: NDArray[np.float64],
+    panel_markers: NDArray[np.float64],
 ) -> pd.Series:
     """
     Calculate the conveyance of a cross-section by summing the conveyance
     across all panels defined by panel markers.
 
     Args:
-        x (np.ndarray): The x-coordinates of the cross-section.
-        y (np.ndarray): The y-coordinates of the cross-section.
-        n (np.ndarray): Manning's n values for each segment.
-        rpl (np.ndarray): Relative Path Length values for each segment.
-        panel_markers (np.ndarray): Boolean array indicating the start of each panel.
+        x (NDArray[np.float64]): The x-coordinates of the cross-section.
+        y (NDArray[np.float64]): The y-coordinates of the cross-section.
+        n (NDArray[np.float64]): Manning's n values for each segment.
+        rpl (NDArray[np.float64]): Relative Path Length values for each segment.
+        panel_markers (NDArray[np.float64]): Boolean array indicating the start of each panel.
 
     Returns:
         pd.Series: A pandas Series containing the conveyance values indexed by water levels.
@@ -41,164 +44,117 @@ def calculate_cross_section_conveyance(
             result = calculate_cross_section_conveyance(x, y, n, rpl, panel_markers)
             print(result)
     """
-    # Create a set of water levels to calculate conveyance at,
-    # currently using 50mm minimum increments plus WLs at every data point
-    wls = insert_intermediate_wls(np.unique(y), threshold=0.05)
-
-    # Panel markers are forced true to the bounds to make the process work
-    panel_markers = np.array([True, *panel_markers[1:-1], True])
-    panel_indices = np.where(panel_markers)[0]
-    conveyance_by_panel = []
-    for panel_start, panel_end in zip(panel_indices[:-1], panel_indices[1:] + 1):
-        panel_x = x[panel_start:panel_end]
-        panel_y = y[panel_start:panel_end]
-        panel_n = n[panel_start:panel_end]
-        # RPL value is only valid for the start of a panel, and set to 1 if it's zero
-        panel_rpl = (
-            1.0
-            if (panel_start == 0 and not panel_markers[0]) or rpl[panel_start] == 0
-            else float(rpl[panel_start])
-        )
-        conveyance_by_panel.append(
-            calculate_conveyance_by_panel(panel_x, panel_y, panel_n, panel_rpl, wls),
-        )
-
-    # Sum conveyance across panels
-    conveyance_values = [sum(values) for values in zip(*conveyance_by_panel)]
-
-    return pd.Series(data=conveyance_values, index=wls)
-
-
-def calculate_conveyance_by_panel(
-    x: np.ndarray,
-    y: np.ndarray,
-    n: np.ndarray,
-    rpl: float,
-    wls: np.ndarray,
-) -> list[float]:
-    """
-    Calculate the conveyance for a single panel of a cross-section at specified water levels.
-
-    Args:
-        x (np.ndarray): The x-coordinates of the panel.
-        y (np.ndarray): The y-coordinates of the panel.
-        n (np.ndarray): Manning's n values for each segment in the panel.
-        rpl (float): Relative Path Length for each segment in the panel.
-        wls (np.ndarray): The water levels at which to calculate conveyance.
-
-    Returns:
-        list[float]: A list of conveyance values for each water level.
-    """
+    water_levels = insert_intermediate_wls(np.unique(y), threshold=0.05)
+    area, length, mannings = calculate_geometry(x, y, n, water_levels)
+    panel = panel_markers.cumsum()[:-1]
 
-    max_y = np.max(wls) + 1
-    min_y = np.min(wls) - 1
+    intersection = (y[:-2] < water_levels[:, np.newaxis]) & (y[1:-1] >= water_levels[:, np.newaxis])
+    section_markers = np.hstack([np.full((intersection.shape[0], 1), False), intersection])
+    section = section_markers.cumsum(axis=1)
 
-    # insert additional start/end points to represent the glass wall sides
-    x = np.array([x[0], *x, x[-1]])
-    y = np.array([max_y, *y, max_y])
-    n = np.array([0, *n, 0])
+    conveyance = np.zeros_like(water_levels)
 
-    # Define a polygon for the channel including artificial sides and top
-    channel_polygon = Polygon(zip(x, y))
-    start, end = x[0] - 0.1, x[-1] + 0.1  # Useful points enclosing the x bounds with small buffer
-
-    # Define linestring geometries representing glass walls, so they can be subtracted later
-    glass_walls = (
-        LineString(zip([x[0], x[1]], [y[0], y[1]])),  # left
-        LineString(zip([x[-2], x[-1]], [y[-2], y[-1]])),  # right
-    )
-
-    # Remove glass wall sections from coords
-    x, y, n = x[1:-1], y[1:-1], n[1:-1]
-
-    conveyance_values = []
-    for wl in wls:
-        if wl <= np.min(y):
-            # no channel capacity (essentially zero depth) so no need to calculate
-            conveyance_values.append(0.0)
+    for i in range(panel.max() + 1):
+        in_panel = panel == i
+        if not in_panel.any():
             continue
 
-        # Some geometries to represent the channel at a given water level
-        water_surface = Polygon(zip([start, start, end, end], [wl, min_y, min_y, wl]))
-        water_plane = intersection(channel_polygon, LineString(zip([start, end], [wl, wl])))
-        wetted_polygon = intersection(channel_polygon, water_surface)
+        rpl_panel = np.sqrt(rpl[:-1][in_panel][0])
+        rpl_panel = 1 if rpl_panel == 0 else rpl_panel
 
-        multiple_parts = wetted_polygon.geom_type in ["GeometryCollection", "MultiPolygon"]
-        parts = wetted_polygon.geoms if multiple_parts else [wetted_polygon]
+        for j in range(section.max() + 1):
+            in_section = section == j
+            in_panel_and_section = in_panel & in_section
+            if not in_panel_and_section.any():
+                continue
 
-        conveyance = 0.0
+            total_area = np.where(in_panel_and_section, area, 0).sum(axis=1)
+            total_length = np.where(in_panel_and_section, length, 0).sum(axis=1)
+            total_mannings = np.where(in_panel_and_section, mannings, 0).sum(axis=1)
 
-        # 'parts' here refers to when a water level results in 2 separate channel sections,
-        # e.g. where the cross section has a 'peak' part way through
-        for part in parts:
-            conveyance += calculate_conveyance_part(part, water_plane, glass_walls, x, n, rpl)
-        conveyance_values.append(conveyance)
+            with np.errstate(invalid="ignore"):
+                conveyance += np.where(
+                    total_length >= MINIMUM_PERIMETER_THRESHOLD,
+                    total_area ** (5 / 3) * total_length ** (1 / 3) / (total_mannings * rpl_panel),
+                    0,
+                )
 
-    return conveyance_values
+    return pd.Series(conveyance, index=water_levels)
 
 
-def calculate_conveyance_part(  # noqa: PLR0913
-    wetted_polygon: Polygon,
-    water_plane: LineString,
-    glass_walls: tuple[LineString, LineString],
-    x: np.ndarray,
-    n: np.ndarray,
-    rpl: float,
-) -> float:
+def calculate_geometry(
+    x: NDArray[np.float64],
+    y: NDArray[np.float64],
+    n: NDArray[np.float64],
+    water_levels: NDArray[np.float64],
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
     """
-    Calculate the conveyance for a part of the wetted area.
+    Calculate area, length, weighted mannings for piecewise linear curve (x, y) below water_level.
 
     Args:
-        wetted_polygon (Polygon): The polygon representing the wetted area.
-        water_plane (LineString): The line representing the water plane.
-        glass_wall_left (LineString): The left boundary of the channel.
-        glass_wall_right (LineString): The right boundary of the channel.
-        x (np.ndarray): 1D array of channel chainage
-        n (np.ndarray): 1D array of channel mannings
-        rpl (float): Relative path length of panel
+        x (NDArray[np.float64]): 1D array of x-coordinates.
+        y (NDArray[np.float64]): 1D array of y-coordinates.
+        n (NDArray[np.float64]): 1D array to integrate over the length.
+        water_levels (NDArray[np.float64]): The horizontal reference line.
 
     Returns:
-        float: The conveyance value for the wetted part.
+        NDArray[np.float64]: The area above the curve and under the reference line.
+        NDArray[np.float64]: The length of the curve under the reference line.
+        NDArray[np.float64]: Manning's n integrated along the curve under the reference line.
     """
-    water_plane_clip: LineString = intersection(water_plane, wetted_polygon)
-    glass_wall_left_clip: LineString = intersection(glass_walls[0], wetted_polygon)
-    glass_wall_right_clip: LineString = intersection(glass_walls[1], wetted_polygon)
-
-    # wetted perimeter should only account for actual section of channel, so we need to remove any
-    # length related to the water surface and any glass walls due to panel
-    perimeter_loss = (
-        water_plane_clip.length + glass_wall_left_clip.length + glass_wall_right_clip.length
+    h = water_levels[:, np.newaxis] - y
+
+    x1 = x[:-1]
+    x2 = x[1:]
+    h1 = h[:, :-1]
+    h2 = h[:, 1:]
+    n1 = n[:-1]
+
+    dx = x2 - x1
+
+    is_submerged = (h1 > 0) & (h2 > 0)
+    is_submerged_on_left = (h1 > 0) & (h2 <= 0)
+    is_submerged_on_right = (h1 <= 0) & (h2 > 0)
+    conditions = [is_submerged, is_submerged_on_left, is_submerged_on_right]
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        # needed for partially submerged sections
+        dx_left = dx * h1 / (h1 - h2)
+        dx_right = dx * h2 / (h2 - h1)
+
+    area = np.select(
+        conditions,
+        [
+            0.5 * dx * (h1 + h2),
+            0.5 * dx_left * h1,
+            0.5 * dx_right * h2,
+        ],
+        default=0,
     )
-
-    wetted_perimeter = wetted_polygon.boundary.length - perimeter_loss
-    if wetted_perimeter < MINIMUM_PERIMETER_THRESHOLD:
-        # Would occur if water level is above lowest point on section, but intersects a near-zero
-        # perimeter, e.g. touching the bottom of an elevated side channel
-        return 0.0
-
-    area = wetted_polygon.area
-
-    wetted_polyline: LineString = (
-        wetted_polygon.exterior.difference(water_plane_clip)
-        .difference(glass_wall_left_clip)
-        .difference(glass_wall_right_clip)
+    length = np.select(
+        conditions,
+        [
+            np.sqrt((h2 - h1) ** 2 + dx**2),
+            np.sqrt(h1**2 + dx_left**2),
+            np.sqrt(h2**2 + dx_right**2),
+        ],
+        default=0,
     )
-    weighted_mannings = calculate_weighted_mannings(x, n, rpl, wetted_polyline)
+    weighted_mannings = n1 * length
 
-    # apply conveyance equation
-    return (area ** (5 / 3) / wetted_perimeter ** (2 / 3)) * (wetted_perimeter / weighted_mannings)
+    return area, length, weighted_mannings
 
 
-def insert_intermediate_wls(arr: np.ndarray, threshold: float):
+def insert_intermediate_wls(arr: NDArray[np.float64], threshold: float) -> NDArray[np.float64]:
     """
     Insert intermediate water levels into an array based on a threshold.
 
     Args:
-        arr (np.ndarray): The array of original water levels.
+        arr (NDArray[np.float64]): The array of original water levels.
         threshold (float): The maximum allowed gap between water levels.
 
     Returns:
-        np.ndarray: The array with intermediate water levels inserted.
+        NDArray[np.float64]: The array with intermediate water levels inserted.
     """
     # Calculate gaps between consecutive elements
     gaps = np.diff(arr)
@@ -207,81 +163,16 @@ def insert_intermediate_wls(arr: np.ndarray, threshold: float):
     num_points = (gaps // threshold).astype(int)
 
     # Prepare lists to hold the new points and results
-    new_points = []
-
-    for i, start in enumerate(arr[:-1]):
-        end = arr[i + 1]
-        if num_points[i] > 0:
-            points = np.linspace(start, end, num_points[i] + 2)[1:-1]
-            new_points.extend(points)
-        new_points.append(end)
-
-    # Combine the original starting point with the new points
-    return np.array([arr[0]] + new_points)
-
-
-def calculate_weighted_mannings(
-    x: np.ndarray,
-    n: np.ndarray,
-    rpl: float,
-    wetted_polyline: LineString,
-) -> float:
-    """Calculate the weighted Manning's n value for a wetted polyline."""
-
-    # We want the polyline to be split into each individual segment
-    segments = line_to_segments(wetted_polyline)
-    weighted_mannings = 0
-    for segment in segments:
-        mannings_value = get_mannings_by_segment_x_coords(
-            x,
-            n,
-            segment.coords[0][0],
-            segment.coords[1][0],
-        )
-        weighted_mannings += mannings_value * segment.length * np.sqrt(rpl)
-
-    return weighted_mannings
-
-
-def line_to_segments(line: LineString | MultiLineString) -> list[LineString]:
-    """Convert a LineString or MultiLineString into a list of LineString segments."""
-    if isinstance(line, LineString):
-        segments = []
-        for start, end in zip(line.coords[:-1], line.coords[1:]):
-            points = sorted([start, end], key=lambda x: x[0])
-            segments.append(LineString(points))
-        return segments
-    if isinstance(line, MultiLineString):
-        segments = []
-        for linestring in line.geoms:
-            segments.extend(line_to_segments(linestring))
-        return segments
-    raise TypeError("Input must be a LineString or MultiLineString")
-
-
-def get_mannings_by_segment_x_coords(
-    x: np.ndarray,
-    n: np.ndarray,
-    start_x: float,
-    end_x: float,
-) -> float:
-    """Get the Manning's n or RPL value for a segment based on its start x-coordinate."""
-
-    # This method doesn't handle cases where we have multiple manning's values at a vertical section
-    # and will always just take the first at any verticle, but it is probably quite rare for this
-    # not to be the case
-    if start_x == end_x:
-        # Vertical segment take first x match
-        index = np.searchsorted(x, start_x) - (start_x not in x)
-    else:
-        # Otherwise non-vertical segment, take last match
-        index = np.searchsorted(x, start_x, side="right") - 1
-
-    return n[index]
+    new_points = [
+        np.linspace(start, end, num + 2, endpoint=False)
+        for start, end, num in zip(arr[:-1], arr[1:], num_points)
+    ]
+    end = np.array([arr[-1]])
+    return np.concatenate([*new_points, end])
 
 
 @lru_cache
-def calculate_cross_section_conveyance_chached(
+def calculate_cross_section_conveyance_cached(
     x: tuple[float],
     y: tuple[float],
     n: tuple[float],

floodmodeller_api/units/sections.py

@@ -19,7 +19,7 @@ import pandas as pd
 from floodmodeller_api.validation import _validate_unit
 
 from ._base import Unit
-from .conveyance import calculate_cross_section_conveyance_chached
+from .conveyance import calculate_cross_section_conveyance_cached
 from .helpers import (
     _to_float,
     _to_int,
@@ -51,12 +51,21 @@ class RIVER(Unit):
 
     Returns:
         RIVER: Flood Modeller RIVER Unit class object
-
-    Methods:
-        convert_to_muskingham: Not currently supported but planned for future release
     """
 
     _unit = "RIVER"
+    _required_columns = [
+        "X",
+        "Y",
+        "Mannings n",
+        "Panel",
+        "RPL",
+        "Marker",
+        "Easting",
+        "Northing",
+        "Deactivation",
+        "SP. Marker",
+    ]
 
     def _create_from_blank(  # noqa: PLR0913
         self,
@@ -88,29 +97,18 @@ class RIVER(Unit):
             "dist_to_next": dist_to_next,
             "slope": slope,
             "density": density,
-            "data": data,
         }.items():
             setattr(self, param, val)
 
-        self.data = (
+        self._data = (
             data
             if isinstance(data, pd.DataFrame)
             else pd.DataFrame(
                 [],
-                columns=[
-                    "X",
-                    "Y",
-                    "Mannings n",
-                    "Panel",
-                    "RPL",
-                    "Marker",
-                    "Easting",
-                    "Northing",
-                    "Deactivation",
-                    "SP. Marker",
-                ],
+                columns=self._required_columns,
             )
         )
+        self._active_data = None
 
     def _read(self, riv_block):
         """Function to read a given RIVER block and store data as class attributes."""
@@ -171,20 +169,9 @@ class RIVER(Unit):
                         sp_marker,
                     ],
                 )
-            self.data = pd.DataFrame(
+            self._data = pd.DataFrame(
                 data_list,
-                columns=[
-                    "X",
-                    "Y",
-                    "Mannings n",
-                    "Panel",
-                    "RPL",
-                    "Marker",
-                    "Easting",
-                    "Northing",
-                    "Deactivation",
-                    "SP. Marker",
-                ],
+                columns=self._required_columns,
             )
 
         else:
@@ -195,6 +182,8 @@ class RIVER(Unit):
             self._raw_block = riv_block
             self.name = riv_block[2][: self._label_len].strip()
 
+        self._active_data = None
+
     def _write(self):
         """Function to write a valid RIVER block"""
 
@@ -214,7 +203,7 @@ class RIVER(Unit):
             )
             # Manual so slope can have more sf
             params = f'{self.dist_to_next:>10.3f}{"":>10}{self.slope:>10.6f}{self.density:>10.3f}'
-            self.nrows = len(self.data)
+            self.nrows = len(self._data)
             riv_block = [header, self.subtype, labels, params, f"{str(self.nrows):>10}"]
 
             riv_data = []
@@ -230,7 +219,7 @@ class RIVER(Unit):
                 northing,
                 deactivation,
                 sp_marker,
-            ) in self.data.itertuples():
+            ) in self._data.itertuples():
                 row = join_10_char(x, y, n)
                 if panel:
                     row += "*"
@@ -245,6 +234,36 @@ class RIVER(Unit):
 
         return self._raw_block
 
+    @property
+    def data(self) -> pd.DataFrame:
+        """Data table for the river cross section.
+
+        Returns:
+            pd.DataFrame: Pandas dataframe for the cross section data with columns: 'X', 'Y',
+            'Mannings n', 'Panel', 'RPL', 'Marker', 'Easting', 'Northing', 'Deactivation',
+            'SP. Marker'
+        """
+        if self._active_data is None:
+            return self._data
+
+        # Replace the active section with the self._active_data df
+        left_bank_idx, right_bank_idx = self._get_left_right_active_index()
+        self._data = pd.concat(
+            [self._data[:left_bank_idx], self._active_data, self._data[right_bank_idx + 1 :]],
+        ).reset_index(drop=True)
+        self._active_data = None
+        return self._data
+
+    @data.setter
+    def data(self, new_df: pd.DataFrame) -> None:
+        if not isinstance(new_df, pd.DataFrame):
+            raise ValueError(
+                "The updated data table for a cross section must be a pandas DataFrame.",
+            )
+        if list(map(str.lower, new_df.columns)) != list(map(str.lower, self._required_columns)):
+            raise ValueError(f"The DataFrame must only contain columns: {self._required_columns}")
+        self._data = new_df
+
     @property
     def conveyance(self) -> pd.Series:
         """Calculate and return the conveyance curve of the cross-section.
@@ -257,14 +276,76 @@ class RIVER(Unit):
         Returns:
             pd.Series: A pandas Series containing the conveyance values indexed by water levels.
         """
-        return calculate_cross_section_conveyance_chached(
-            x=tuple(self.data.X.values),
-            y=tuple(self.data.Y.values),
-            n=tuple(self.data["Mannings n"].values),
-            rpl=tuple(self.data.RPL.values),
-            panel_markers=tuple(self.data.Panel.values),
+        return calculate_cross_section_conveyance_cached(
+            x=tuple(self._data.X.values),
+            y=tuple(self._data.Y.values),
+            n=tuple(self._data["Mannings n"].values),
+            rpl=tuple(self._data.RPL.values),
+            panel_markers=tuple(self._data.Panel.values),
         )
 
+    @property
+    def active_data(self) -> pd.DataFrame:
+        """Data table for active subset of the river cross section, defined by deactivation markers.
+
+        Returns:
+            pd.DataFrame: Pandas dataframe for the active cross section data with columns: 'X', 'Y',
+            'Mannings n', 'Panel', 'RPL', 'Marker', 'Easting', 'Northing', 'Deactivation',
+            'SP. Marker'
+
+        Example:
+            In this example we read in a river section that has deactivation markers
+
+            .. ipython:: python
+
+                from floodmodeller_api.units import RIVER
+                river_unit = RIVER(
+                    [
+                        "RIVER normal case",
+                        "SECTION",
+                        "SomeUnit",
+                        "     0.000            0.000100  1000.000",
+                        "        5",
+                        "     0.000        10     0.030     0.000                 0.0       0.0          ",
+                        "     1.000         9     0.030     0.000                 0.0       0.0      LEFT",
+                        "     2.000         5     0.030     0.000                 0.0       0.0          ",
+                        "     3.000         6     0.030     0.000                 0.0       0.0     RIGHT",
+                        "     4.000        10     0.030     0.000                 0.0       0.0          ",
+                    ]
+                )
+                river_unit.data
+                river_unit.active_data
+        """
+        if self._active_data is not None:
+            return self._active_data
+        left_bank_idx, right_bank_idx = self._get_left_right_active_index()
+        self._active_data = self._data.iloc[left_bank_idx : right_bank_idx + 1].copy()
+        return self._active_data
+
+    @active_data.setter
+    def active_data(self, new_df: pd.DataFrame) -> None:
+        if not isinstance(new_df, pd.DataFrame):
+            raise ValueError(
+                "The updated data table for a cross section must be a pandas DataFrame.",
+            )
+        if new_df.columns.to_list() != self._required_columns:
+            raise ValueError(f"The DataFrame must only contain columns: {self._required_columns}")
+
+        # Ensure activation markers are present
+        new_df = new_df.copy()
+        new_df.iloc[0, 8] = "LEFT"
+        new_df.iloc[-1, 8] = "RIGHT"
+        self._active_data = new_df
+
+    def _get_left_right_active_index(self) -> tuple[int, int]:
+        bank_data = self._data.Deactivation.to_list()
+        lb_flag = "LEFT" in bank_data
+        rb_flag = "RIGHT" in bank_data
+
+        left_bank_idx = (len(bank_data) - 1) - bank_data[::-1].index("LEFT") if lb_flag else 0
+        right_bank_idx = bank_data.index("RIGHT") if rb_flag else len(bank_data) - 1
+        return left_bank_idx, right_bank_idx
+
 
 class INTERPOLATE(Unit):
     """Class to hold and process INTERPOLATE unit type

floodmodeller_api/util.py

@@ -59,6 +59,7 @@ def read_file(filepath: str | Path) -> FMFile:
 
     """
     from . import DAT, IED, IEF, INP, LF1, LF2, XML2D, ZZN
+    from .hydrology_plus import HydrologyPlusExport
 
     suffix_to_class = {
         ".ief": IEF,
@@ -69,6 +70,7 @@ def read_file(filepath: str | Path) -> FMFile:
         ".inp": INP,
         ".lf1": LF1,
         ".lf2": LF2,
+        ".csv": HydrologyPlusExport,
     }
     filepath = Path(filepath)
     api_class = suffix_to_class.get(filepath.suffix.lower())

floodmodeller_api/version.py

@@ -1 +1 @@
-__version__ = "0.4.4.post1"
+__version__ = "0.5.0.post1"