floodmodeller-api 0.4.3__py3-none-any.whl → 0.4.4__py3-none-any.whl

floodmodeller_api/units/conveyance.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+import pandas as pd
+from shapely import LineString, MultiLineString, Polygon, intersection
+
+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,
+) -> 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.
+
+    Returns:
+        pd.Series: A pandas Series containing the conveyance values indexed by water levels.
+
+    Example:
+        .. code-block:: python
+
+            x = np.array([0, 1, 2, 3, 4])
+            y = np.array([1, 2, 1, 2, 1])
+            n = np.array([0.03, 0.03, 0.03, 0.03, 0.03])
+            rpl = np.array([1., 1., 1., 1., 1.])
+            panel_markers = np.array([True, False, True, False, True])
+            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.
+    """
+
+    max_y = np.max(wls) + 1
+    min_y = np.min(wls) - 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])
+
+    # 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)
+            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)
+
+        multiple_parts = wetted_polygon.geom_type in ["GeometryCollection", "MultiPolygon"]
+        parts = wetted_polygon.geoms if multiple_parts else [wetted_polygon]
+
+        conveyance = 0.0
+
+        # '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)
+
+    return conveyance_values
+
+
+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:
+    """
+    Calculate the conveyance for a part of the wetted area.
+
+    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
+
+    Returns:
+        float: The conveyance value for the wetted part.
+    """
+    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
+    )
+
+    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)
+    )
+    weighted_mannings = calculate_weighted_mannings(x, n, rpl, wetted_polyline)
+
+    # apply conveyance equation
+    return (area ** (5 / 3) / wetted_perimeter ** (2 / 3)) * (wetted_perimeter / weighted_mannings)
+
+
+def insert_intermediate_wls(arr: np.ndarray, threshold: float):
+    """
+    Insert intermediate water levels into an array based on a threshold.
+
+    Args:
+        arr (np.ndarray): 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.
+    """
+    # Calculate gaps between consecutive elements
+    gaps = np.diff(arr)
+
+    # Calculate the number of points needed for each gap
+    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]
+
+
+@lru_cache
+def calculate_cross_section_conveyance_chached(
+    x: tuple[float],
+    y: tuple[float],
+    n: tuple[float],
+    rpl: tuple[float],
+    panel_markers: tuple[float],
+) -> pd.Series:
+    """Dummy function to allow for caching of the conveyance function as numpy arrays are not
+    hashable
+    """
+
+    return calculate_cross_section_conveyance(
+        np.array(x),
+        np.array(y),
+        np.array(n),
+        np.array(rpl),
+        np.array(panel_markers),
+    )

floodmodeller_api/units/sections.py

@@ -19,6 +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 .helpers import (
     _to_float,
     _to_int,
@@ -244,6 +245,26 @@ class RIVER(Unit):
 
         return self._raw_block
 
+    @property
+    def conveyance(self) -> pd.Series:
+        """Calculate and return the conveyance curve of the cross-section.
+
+        Note:
+            This uses the same method as applied in Flood Modeller so will be able to pick out any
+            undesirable spikes in conveyance. The only difference compared with Flood Modeller may
+            be the number of sampled points.
+
+        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),
+        )
+
 
 class INTERPOLATE(Unit):
     """Class to hold and process INTERPOLATE unit type

floodmodeller_api/util.py

@@ -18,10 +18,15 @@ from __future__ import annotations
 
 import sys
 import webbrowser
+from functools import wraps
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from .version import __version__
+
 if TYPE_CHECKING:
+    from typing import Callable
+
     from ._base import FMFile
 
 
@@ -75,3 +80,40 @@ def read_file(filepath: str | Path) -> FMFile:
 
 def is_windows() -> bool:
     return sys.platform.startswith("win")
+
+
+def handle_exception(when: str) -> Callable:
+    """Decorator factory to wrap a method with exception handling."""
+
+    def decorator(method: Callable) -> Callable:
+        @wraps(method)
+        def wrapped_method(self: FMFile, *args, **kwargs):
+            try:
+                return method(self, *args, **kwargs)
+            except Exception as e:
+                self._handle_exception(e, when)
+
+        return wrapped_method
+
+    return decorator
+
+
+class FloodModellerAPIError(Exception):
+    """Custom exception class for Flood Modeller API errors."""
+
+    def __init__(self, original_exception, when, filetype, filepath) -> None:
+        tb = original_exception.__traceback__
+        while tb.tb_next is not None:
+            tb = tb.tb_next
+        line_no = tb.tb_lineno
+        tb_path = Path(tb.tb_frame.f_code.co_filename)
+        fname = "/".join(tb_path.parts[-2:])
+
+        message = (
+            "\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
+            f"\nAPI Error: Problem encountered when trying to {when} {filetype} file {filepath}."
+            f"\n\nDetails: {__version__}-{fname}-{line_no}"
+            f"\nMsg: {original_exception}"
+            "\n\nFor additional support, go to: https://github.com/People-Places-Solutions/floodmodeller-api"
+        )
+        super().__init__(message)

floodmodeller_api/version.py

@@ -1 +1 @@
-__version__ = "0.4.3"
+__version__ = "0.4.4"

floodmodeller_api/xml2d.py

@@ -16,7 +16,6 @@ address: Jacobs UK Limited, Flood Modeller, Cottons Centre, Cottons Lane, London
 
 from __future__ import annotations
 
-import datetime as dt
 import io
 import os
 import time
@@ -30,7 +29,8 @@ from tqdm import trange
 
 from floodmodeller_api._base import FMFile
 
-from .logs import error_2d_dict, lf_factory
+from .logs import LF2, create_lf, error_2d_dict
+from .util import handle_exception
 from .xml2d_template import xml2d_template
 
 
@@ -70,19 +70,16 @@ class XML2D(FMFile):
     OLD_FILE = 5
     GOOD_EXIT_CODE = 100
 
+    @handle_exception(when="read")
     def __init__(self, xml_filepath: str | Path | None = None, from_json: bool = False):
-        try:
-            if from_json:
-                return
-            if xml_filepath is not None:
-                FMFile.__init__(self, xml_filepath)
-                self._read()
-                self._log_path = self._filepath.with_suffix(".lf2")
-            else:
-                self._read(from_blank=True)
-
-        except Exception as e:
-            self._handle_exception(e, when="read")
+        if from_json:
+            return
+        if xml_filepath is not None:
+            FMFile.__init__(self, xml_filepath)
+            self._read()
+            self._log_path = self._filepath.with_suffix(".lf2")
+        else:
+            self._read(from_blank=True)
 
     def _read(self, from_blank=False):
         # Read xml data
@@ -387,26 +384,21 @@ class XML2D(FMFile):
                     except AttributeError:
                         self._data[attr] = None
 
+    @handle_exception(when="write")
     def _write(self) -> str:
-        orig_xml_tree = deepcopy(self._xmltree)
+        self._update_dict()
+        self._recursive_update_xml(self._data, self._raw_data, "ROOT")
+        self._recursive_remove_data_xml(self._data, self._xmltree.getroot())
+        etree.indent(self._xmltree, space="    ")
         try:
-            self._update_dict()
-            self._recursive_update_xml(self._data, self._raw_data, "ROOT")
-            self._recursive_remove_data_xml(self._data, self._xmltree.getroot())
-            etree.indent(self._xmltree, space="    ")
-            try:
-                self._validate()
-            except Exception:
-                self._recursive_reorder_xml()
-                self._validate()
-
-            self._raw_data = deepcopy(self._data)  # reset raw data to equal data
+            self._validate()
+        except Exception:
+            self._recursive_reorder_xml()
+            self._validate()
 
-            return f'<?xml version="1.0" standalone="yes"?>\n{etree.tostring(self._xmltree.getroot()).decode()}'
+        self._raw_data = deepcopy(self._data)  # reset raw data to equal data
 
-        except Exception as e:
-            self._xmltree = orig_xml_tree
-            self._handle_exception(e, when="write")
+        return f'<?xml version="1.0" standalone="yes"?>\n{etree.tostring(self._xmltree.getroot()).decode()}'
 
     def _get_multi_value_keys(self):
         self._multi_value_keys = []
@@ -460,6 +452,7 @@ class XML2D(FMFile):
         self._read()
         self._log_path = self._filepath.with_suffix(".lf2")
 
+    @handle_exception(when="simulate")
     def simulate(  # noqa: C901, PLR0912, PLR0913
         self,
         method: str = "WAIT",
@@ -508,78 +501,74 @@ class XML2D(FMFile):
         self.range_function = range_function
         self.range_settings = range_settings if range_settings else {}
 
-        try:
-            if self._filepath is None:
-                raise UserWarning(
-                    "xml2D must be saved to a specific filepath before simulate() can be called.",
-                )
-            if precision.upper() == "DEFAULT":
-                precision = "SINGLE"  # defaults to single precision
-                for _, domain in self.domains.items():
-                    if domain["run_data"].get("double_precision") == "required":
-                        precision = "DOUBLE"
-                        break
-
-            if enginespath == "":
-                # Default location
-                _enginespath = r"C:\Program Files\Flood Modeller\bin"
-            else:
-                _enginespath = enginespath
-                if not Path(_enginespath).exists():
-                    raise Exception(
-                        f"Flood Modeller non-default engine path not found! {str(_enginespath)}",
-                    )
-
-            # checking if all schemes used are fast, if so will use FAST.exe
-            # TODO: Add in option to choose to use or not to use if you can
-            is_fast = True
+        if self._filepath is None:
+            raise UserWarning(
+                "xml2D must be saved to a specific filepath before simulate() can be called.",
+            )
+        if precision.upper() == "DEFAULT":
+            precision = "SINGLE"  # defaults to single precision
             for _, domain in self.domains.items():
-                if domain["run_data"]["scheme"] != "FAST":
-                    is_fast = False
+                if domain["run_data"].get("double_precision") == "required":
+                    precision = "DOUBLE"
                     break
 
-            if is_fast is True:
-                isis2d_fp = str(Path(_enginespath, "FAST.exe"))
-            elif precision.upper() == "SINGLE":
-                isis2d_fp = str(Path(_enginespath, "ISIS2d.exe"))
-            else:
-                isis2d_fp = str(Path(_enginespath, "ISIS2d_DP.exe"))
+        if enginespath == "":
+            # Default location
+            _enginespath = r"C:\Program Files\Flood Modeller\bin"
+        else:
+            _enginespath = enginespath
+            if not Path(_enginespath).exists():
+                raise Exception(
+                    f"Flood Modeller non-default engine path not found! {str(_enginespath)}",
+                )
 
-            if not Path(isis2d_fp).exists():
-                raise Exception(f"Flood Modeller engine not found! Expected location: {isis2d_fp}")
+        # checking if all schemes used are fast, if so will use FAST.exe
+        # TODO: Add in option to choose to use or not to use if you can
+        is_fast = True
+        for _, domain in self.domains.items():
+            if domain["run_data"]["scheme"] != "FAST":
+                is_fast = False
+                break
+
+        if is_fast is True:
+            isis2d_fp = str(Path(_enginespath, "FAST.exe"))
+        elif precision.upper() == "SINGLE":
+            isis2d_fp = str(Path(_enginespath, "ISIS2d.exe"))
+        else:
+            isis2d_fp = str(Path(_enginespath, "ISIS2d_DP.exe"))
 
-            console_output = console_output.lower()
-            run_command = (
-                f'"{isis2d_fp}" {"-q" if console_output != "detailed" else ""} "{self._filepath}"'
-            )
-            stdout = DEVNULL if console_output == "simple" else None
+        if not Path(isis2d_fp).exists():
+            raise Exception(f"Flood Modeller engine not found! Expected location: {isis2d_fp}")
 
-            if method.upper() == "WAIT":
-                print("Executing simulation ... ")
-                # execute simulation
-                process = Popen(run_command, cwd=os.path.dirname(self._filepath), stdout=stdout)
+        console_output = console_output.lower()
+        run_command = (
+            f'"{isis2d_fp}" {"-q" if console_output != "detailed" else ""} "{self._filepath}"'
+        )
+        stdout = DEVNULL if console_output == "simple" else None
 
-                # progress bar based on log files:
-                if console_output == "simple":
-                    self._init_log_file()
-                    self._update_progress_bar(process)
+        if method.upper() == "WAIT":
+            print("Executing simulation ... ")
+            # execute simulation
+            process = Popen(run_command, cwd=os.path.dirname(self._filepath), stdout=stdout)
 
-                while process.poll() is None:
-                    # process is still running
-                    time.sleep(1)
+            # progress bar based on log files:
+            if console_output == "simple":
+                self._lf = create_lf(self._log_path, "lf2")
+                self._update_progress_bar(process)
 
-                exitcode = process.returncode
-                self._interpret_exit_code(exitcode, raise_on_failure)
+            while process.poll() is None:
+                # process is still running
+                time.sleep(1)
 
-            elif method.upper() == "RETURN_PROCESS":
-                print("Executing simulation ...")
-                # execute simulation
-                return Popen(run_command, cwd=os.path.dirname(self._filepath), stdout=stdout)
+            exitcode = process.returncode
+            self._interpret_exit_code(exitcode, raise_on_failure)
 
-            return None
+        elif method.upper() == "RETURN_PROCESS":
+            print("Executing simulation ...")
+            # execute simulation
+            return Popen(run_command, cwd=os.path.dirname(self._filepath), stdout=stdout)
 
-        except Exception as e:
-            self._handle_exception(e, when="simulate")
+        return None
 
     def get_log(self):
         """If log files for the simulation exist, this function returns them as a LF2 class object
@@ -590,52 +579,7 @@ class XML2D(FMFile):
         if not self._log_path.exists():
             raise FileNotFoundError("Log file (LF2) not found")
 
-        return lf_factory(self._log_path, "lf2", False)
-
-    def _init_log_file(self):
-        """Checks for a new log file, waiting for its creation if necessary"""
-        # wait for log file to exist
-        log_file_exists = False
-        max_time = time.time() + 10
-
-        while not log_file_exists:
-            time.sleep(0.1)
-            log_file_exists = self._log_path.is_file()
-
-            # timeout
-            if time.time() > max_time:
-                self._no_log_file("log file is expected but not detected")
-                self._lf = None
-                return
-
-        # wait for new log file
-        old_log_file = True
-        max_time = time.time() + 10
-
-        while old_log_file:
-            time.sleep(0.1)
-
-            # difference between now and when log file was last modified
-            last_modified_timestamp = self._log_path.stat().st_mtime
-            last_modified = dt.datetime.fromtimestamp(last_modified_timestamp)
-            time_diff_sec = (dt.datetime.now() - last_modified).total_seconds()
-
-            # it's old if it's over self.OLD_FILE seconds old (TODO: is this robust?)
-            old_log_file = time_diff_sec > self.OLD_FILE
-
-            # timeout
-            if time.time() > max_time:
-                self._no_log_file("log file is from previous run")
-                self._lf = None
-                return
-
-        # create LF instance
-        self._lf = lf_factory(self._log_path, "lf2", False)
-
-    def _no_log_file(self, reason):
-        """Warning that there will be no progress bar"""
-
-        print("No progress bar as " + reason + ". Simulation will continue as usual.")
+        return LF2(self._log_path)
 
     def _update_progress_bar(self, process: Popen):
         """Updates progress bar based on log file"""