floodmodeller-api 0.5.1__py3-none-any.whl → 0.5.2__py3-none-any.whl

floodmodeller_api/units/conduits.py

@@ -1,6 +1,6 @@
 """
 Flood Modeller Python API
-Copyright (C) 2024 Jacobs U.K. Limited
+Copyright (C) 2025 Jacobs U.K. Limited
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
@@ -14,19 +14,21 @@ If you have any query about this program or this License, please contact us at s
 address: Jacobs UK Limited, Flood Modeller, Cottons Centre, Cottons Lane, London, SE1 2QG, United Kingdom.
 """
 
+import logging
+
 import pandas as pd
 
 from floodmodeller_api.validation import _validate_unit
 
 from ._base import Unit
-from .helpers import (
-    _to_float,
-    _to_int,
-    _to_str,
+from ._helpers import (
     join_10_char,
     join_n_char_ljust,
     split_10_char,
     split_n_char,
+    to_float,
+    to_int,
+    to_str,
 )
 
 
@@ -179,93 +181,94 @@ class CONDUIT(Unit):
 
     def _read(self, c_block):  # noqa: PLR0915
         """Function to read a given CONDUIT block and store data as class attributes"""
-        self._subtype = c_block[1].split(" ")[0].strip()
+        self._subtype = self._get_first_word(c_block[1])
         # Extends label line to be correct length before splitting to pick up blank labels
         labels = split_n_char(f"{c_block[2]:<{2*self._label_len}}", self._label_len)
         self.name = labels[0]
         self.spill = labels[1]
-        self.comment = c_block[0].replace("CONDUIT", "").strip()
+        self.comment = self._remove_unit_name(c_block[0])
 
         # Read CIRCULAR type unit
         if self._subtype == "CIRCULAR":
             # Read Params
-            self.dist_to_next = _to_float(split_10_char(c_block[3])[0])
+            self.dist_to_next = to_float(split_10_char(c_block[3])[0])
             self.friction_eq = c_block[4].strip()
             params = split_10_char(f"{c_block[5]:<80}")
-            self.invert = _to_float(params[0])
-            self.diameter = _to_float(params[1])
-            self.use_bottom_slot = _to_str(params[2], "GLOBAL")
-            self.bottom_slot_dist = _to_float(params[3])
-            self.bottom_slot_depth = _to_float(params[4])
-            self.use_top_slot = _to_str(params[5], "GLOBAL")
-            self.top_slot_dist = _to_float(params[6])
-            self.top_slot_depth = _to_float(params[7])
+            self.invert = to_float(params[0])
+            self.diameter = to_float(params[1])
+            self.use_bottom_slot = to_str(params[2], "GLOBAL")
+            self.bottom_slot_dist = to_float(params[3])
+            self.bottom_slot_depth = to_float(params[4])
+            self.use_top_slot = to_str(params[5], "GLOBAL")
+            self.top_slot_dist = to_float(params[6])
+            self.top_slot_depth = to_float(params[7])
             friction_params = split_10_char(f"{c_block[6]:<20}")
-            self.friction_below_axis = _to_float(friction_params[0])
-            self.friction_above_axis = _to_float(friction_params[1])
+            self.friction_below_axis = to_float(friction_params[0])
+            self.friction_above_axis = to_float(friction_params[1])
 
         elif self._subtype == "RECTANGULAR":
             # Read Params
-            self.dist_to_next = _to_float(split_10_char(c_block[3])[0])
+            self.dist_to_next = to_float(split_10_char(c_block[3])[0])
             self.friction_eq = c_block[4].strip()
             params = split_10_char(f"{c_block[5]:<90}")
-            self.invert = _to_float(params[0])
-            self.width = _to_float(params[1])
-            self.height = _to_float(params[2])
-            self.use_bottom_slot = _to_str(params[3], "GLOBAL")
-            self.bottom_slot_dist = _to_float(params[4])
-            self.bottom_slot_depth = _to_float(params[5])
-            self.use_top_slot = _to_str(params[6], "GLOBAL")
-            self.top_slot_dist = _to_float(params[7])
-            self.top_slot_depth = _to_float(params[8])
+            self.invert = to_float(params[0])
+            self.width = to_float(params[1])
+            self.height = to_float(params[2])
+            self.use_bottom_slot = to_str(params[3], "GLOBAL")
+            self.bottom_slot_dist = to_float(params[4])
+            self.bottom_slot_depth = to_float(params[5])
+            self.use_top_slot = to_str(params[6], "GLOBAL")
+            self.top_slot_dist = to_float(params[7])
+            self.top_slot_depth = to_float(params[8])
             friction_params = split_10_char(f"{c_block[6]:<30}")
-            self.friction_on_invert = _to_float(friction_params[0])
-            self.friction_on_walls = _to_float(friction_params[1])
-            self.friction_on_soffit = _to_float(friction_params[2])
+            self.friction_on_invert = to_float(friction_params[0])
+            self.friction_on_walls = to_float(friction_params[1])
+            self.friction_on_soffit = to_float(friction_params[2])
 
         elif self._subtype in ("SPRUNG", "SPRUNGARCH"):
-            self.dist_to_next = _to_float(split_10_char(c_block[3])[0])
-            self.equation = _to_str(c_block[4], "MANNING")
+            self.dist_to_next = to_float(split_10_char(c_block[3])[0])
+            self.equation = to_str(c_block[4], "MANNING")
             params = split_10_char(f"{c_block[5]:<100}")
-            self.elevation_invert = _to_float(params[0])
-            self.width = _to_float(params[1])
-            self.height_springing = _to_float(params[2])
-            self.height_crown = _to_float(params[3])
-            self.use_bottom_slot = _to_str(params[4], "GLOBAL")
-            self.bottom_slot_dist = _to_float(params[5])
-            self.bottom_slot_depth = _to_float(params[6])
-            self.use_top_slot = _to_str(params[7], "GLOBAL")
-            self.top_slot_dist = _to_float(params[8])
-            self.top_slot_depth = _to_float(params[9])
+            self.elevation_invert = to_float(params[0])
+            self.width = to_float(params[1])
+            self.height_springing = to_float(params[2])
+            self.height_crown = to_float(params[3])
+            self.use_bottom_slot = to_str(params[4], "GLOBAL")
+            self.bottom_slot_dist = to_float(params[5])
+            self.bottom_slot_depth = to_float(params[6])
+            self.use_top_slot = to_str(params[7], "GLOBAL")
+            self.top_slot_dist = to_float(params[8])
+            self.top_slot_depth = to_float(params[9])
             friction_params = split_10_char(f"{c_block[6]:<30}")
-            self.friction_on_invert = _to_float(friction_params[0])
-            self.friction_on_walls = _to_float(friction_params[1])
-            self.friction_on_soffit = _to_float(friction_params[2])
+            self.friction_on_invert = to_float(friction_params[0])
+            self.friction_on_walls = to_float(friction_params[1])
+            self.friction_on_soffit = to_float(friction_params[2])
 
         elif self._subtype == "SECTION":
-            self.dist_to_next = _to_float(split_10_char(c_block[3])[0])
-            end_index = 5 + _to_int(c_block[4])
+            self.dist_to_next = to_float(split_10_char(c_block[3])[0])
+            end_index = 5 + to_int(c_block[4])
             x = []
             y = []
             friction = []
             for i in range(5, end_index):
                 row_data = split_10_char(f"{c_block[i]:<30}")
-                x.append(_to_float(row_data[0]))
-                y.append(_to_float(row_data[1]))
-                friction.append(_to_float(row_data[2]))
+                x.append(to_float(row_data[0]))
+                y.append(to_float(row_data[1]))
+                friction.append(to_float(row_data[2]))
             self.coords = pd.DataFrame({"x": x, "y": y, "cw_friction": friction})
 
         else:
             # This else block is triggered for conduit subtypes which aren't yet supported, and just keeps the '_block' in it's raw state to write back.
-            print(
-                f'This Conduit sub-type: "{self._subtype}" is currently unsupported for reading/editing',
+            logging.warning(
+                "This Conduit sub-type: '%s' is currently unsupported for reading/editing",
+                self._subtype,
             )
             self._raw_block = c_block
 
     def _write(self):
         """Function to write a valid CONDUIT block"""
         _validate_unit(self)  # Function to check the params are valid for CONDUIT unit
-        header = "CONDUIT " + self.comment
+        header = self._create_header()
         labels = join_n_char_ljust(self._label_len, self.name, self.spill)
         c_block = [header, self._subtype, labels]
 

floodmodeller_api/units/connectors.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from floodmodeller_api.validation import _validate_unit
+
+from ._base import Unit
+from ._helpers import (
+    join_12_char_ljust,
+    read_lateral_data,
+    split_12_char,
+    to_int,
+    write_dataframe,
+)
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class JUNCTION(Unit):
+    """Class to hold and process JUNCTION unit type
+
+    Args:
+        comment (str, optional): Comment included in unit.
+        subtype (str, optional): Defines the type of junction unit (*Should not be changed*)
+        labels (str, optional): Unlimited number of labels, the first of which is the name.
+
+    Returns:
+        JUNCTION: Flood Modeller JUNCTION Unit class object"""
+
+    _unit = "JUNCTION"
+
+    def _read(self, block: list[str]) -> None:
+        self.comment = self._remove_unit_name(block[0])
+        self._subtype = self._get_first_word(block[1])
+        self.labels = split_12_char(block[2])
+
+        self.name = self.labels[0]
+
+    def _write(self) -> list[str]:
+        _validate_unit(self)
+        return [
+            self._create_header(),
+            self.subtype,  # type: ignore
+            join_12_char_ljust(*self.labels).rstrip(),
+        ]
+
+    def _create_from_blank(
+        self,
+        comment: str = "",
+        subtype: str = "OPEN",
+        labels: list[str] | None = None,
+    ) -> None:
+        self.comment = comment
+        self._subtype = subtype
+        self.labels = labels if labels is not None else []
+        self.name = self.labels[0]
+
+
+class LATERAL(Unit):
+    """Class to hold and process LATERAL unit type
+
+    Args:
+        name (str, optional): Unit name.
+        comment (str, optional): Comment included in unit.
+        subtype (str, optional): Defines the type of lateral unit (*Should not be changed*)
+        weight_factor (str, optional): Corresponding weight factors or user-defined area for
+            each receiving unit
+        data (pandas.DataFrame): Dataframe object containing all the reservoir section data.
+            Columns are ``'Node Label', 'Custom Weight Factor', 'Use Weight Factor'``
+
+    Returns:
+        LATERAL: Flood Modeller LATERAL Unit class object"""
+
+    _unit = "LATERAL"
+
+    def _read(self, block: list[str]) -> None:
+        self.comment = self._remove_unit_name(block[0])
+        self.name = block[1]
+        self.weight_factor = block[2]
+        self.no_units = to_int(block[3])
+        self.data = read_lateral_data(block[4:])
+        self.labels = list(self.data["Node Label"])
+
+    def _write(self) -> list[str]:
+        _validate_unit(self)
+        return [
+            self._create_header(),
+            self.name,  # type: ignore
+            self.weight_factor,
+            *write_dataframe(self.no_units, self.data, n=12),
+        ]
+
+    def _create_from_blank(
+        self,
+        name: str = "new_junction",
+        comment: str = "",
+        subtype: str = "OPEN",
+        weight_factor: str = "REACH",
+        data: pd.DataFrame | None = None,
+    ) -> None:
+        self.name = name
+        self.comment = comment
+        self._subtype = subtype
+        self.weight_factor = weight_factor
+
+        self.data = self._enforce_dataframe(
+            data,
+            ("Node Label", "Custom Weight Factor", "Use Weight Factor"),
+        )
+        self.no_units = len(self.data)
+        self.labels = list(self.data["Node Label"])

floodmodeller_api/units/controls.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from floodmodeller_api.validation import _validate_unit
+
+from ._base import Unit
+from ._helpers import (
+    join_10_char,
+    join_12_char_ljust,
+    read_reservoir_data,
+    split_10_char,
+    split_12_char,
+    to_float,
+    to_int,
+    write_dataframe,
+)
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class RESERVOIR(Unit):
+    """Class to hold and process RESERVOIR unit type
+
+    Args:
+        name (str, optional): Unit name.
+        comment (str, optional): Comment included in unit.
+        labels (str, optional): Unlimited number of labels - not including first label (name).
+        easting (float, optional): Easting coordinate of reservoir reference point (not used in computations).
+        northing (float, optional): Northing coordinate of reservoir reference point (not used in computations).
+        runoff_factor (float, optional): Rainfall runoff factor.
+        lateral_inflow_labels (list[str], optional): Lateral inflow labels (up to 4).
+        data (pandas.DataFrame): Dataframe object containing all the reservoir section data.
+            Columns are ``'Elevation','Plan Area'``
+
+    Returns:
+        RESERVOIR: Flood Modeller RESERVOIR Unit class object"""
+
+    _unit = "RESERVOIR"
+
+    def _read(self, block: list[str]) -> None:
+        self._revision, self.comment = self._get_revision_and_comment(block[0])
+
+        self.labels = split_12_char(block[1])
+        self.name = self.labels[0]
+
+        if self._revision == 1:
+            self.lateral_inflow_labels = split_12_char(block[2])
+            idx = 3
+
+            lines = split_10_char(f"{block[-1]:<30}")
+            self.easting = to_float(lines[0])
+            self.northing = to_float(lines[1])
+            self.runoff = to_float(lines[2])
+        else:
+            idx = 2
+
+        self.no_rows = to_int(block[idx])
+        start_idx = idx + 1
+        end_idx = start_idx + self.no_rows
+        self.data = read_reservoir_data(block[start_idx:end_idx])
+
+    def _write(self) -> list[str]:
+        _validate_unit(self)
+        rev1_a = (
+            [join_12_char_ljust(*self.lateral_inflow_labels).rstrip()]
+            if self._revision == 1
+            else []
+        )
+        rev1_b = (
+            [join_10_char(self.easting, self.northing, self.runoff)] if self._revision == 1 else []
+        )
+        return [
+            self._create_header(include_revision=self._revision is not None),
+            join_12_char_ljust(*self.labels).rstrip(),
+            *rev1_a,
+            *write_dataframe(self.no_rows, self.data),
+            *rev1_b,
+        ]
+
+    def _create_from_blank(  # noqa: PLR0913 (need that many)
+        self,
+        name: str = "new_reservoir",
+        comment: str = "",
+        subtype: str = "OPEN",
+        labels: list[str] | None = None,
+        easting: float = 0.0,
+        northing: float = 0.0,
+        runoff: float = 0.0,
+        lateral_inflow_labels: list[str] | None = None,
+        data: pd.DataFrame | None = None,
+    ) -> None:
+        self.easting = easting
+        self.northing = northing
+        self.runoff = runoff
+        self.name = name
+        self.comment = comment
+        self._subtype = subtype
+        self._revision = 1
+        self.labels = labels if labels is not None else []
+        self.lateral_inflow_labels = (
+            lateral_inflow_labels if lateral_inflow_labels is not None else []
+        )
+
+        self.data = self._enforce_dataframe(data, ("Elevation", "Plan Area"))
+        self.no_rows = len(self.data)

floodmodeller_api/units/iic.py

@@ -1,6 +1,6 @@
 """
 Flood Modeller Python API
-Copyright (C) 2024 Jacobs U.K. Limited
+Copyright (C) 2025 Jacobs U.K. Limited
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
@@ -18,7 +18,7 @@ import pandas as pd
 
 from ..diff import check_item_with_dataframe_equal
 from ..to_from_json import Jsonable
-from .helpers import join_10_char, split_10_char
+from ._helpers import join_10_char, split_10_char
 
 # Initial Conditions Class
 
@@ -65,15 +65,8 @@ class IIC(Jsonable):
                     float(z),
                 ],
             )
-        # AL is this storing the values as strings?
         self.data = pd.DataFrame(data_list, columns=header)
-        # JP Yes
-        # AL If it does, would it worth making it store the values instead?
-        # JP Yes I'll do that, only downside is that the updated values may not match notation
-        #   of original even if no changes. (i.e 2.0 -> 2.00 or 2. -> 2.00)
 
-    # AL Is this only to transform the table of data into a string-like array?
-    # JP Yes it just transforms the dataframe back into valid DAT format
     def _write(self):
         ic_block = [
             "INITIAL CONDITIONS",

floodmodeller_api/units/losses.py

@@ -1,6 +1,6 @@
 """
 Flood Modeller Python API
-Copyright (C) 2024 Jacobs U.K. Limited
+Copyright (C) 2025 Jacobs U.K. Limited
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
@@ -14,20 +14,21 @@ If you have any query about this program or this License, please contact us at s
 address: Jacobs UK Limited, Flood Modeller, Cottons Centre, Cottons Lane, London, SE1 2QG, United Kingdom.
 """
 
+import logging
+
 import pandas as pd
 
 from floodmodeller_api.validation import _validate_unit
 
 from ._base import Unit
-from .helpers import (
-    _to_data_list,
-    _to_float,
-    _to_int,
-    _to_str,
+from ._helpers import (
     join_10_char,
     join_n_char_ljust,
     split_10_char,
     split_n_char,
+    to_data_list,
+    to_float,
+    to_str,
 )
 
 
@@ -76,8 +77,8 @@ class CULVERT(Unit):
         """Function to read a given CULVERT block and store data as class attributes"""
 
         # Extract common attributes
-        self._subtype = block[1].split(" ")[0].strip()
-        self.comment = block[0].replace("CULVERT", "").strip()
+        self._subtype = self._get_first_word(block[1])
+        self.comment = self._remove_unit_name(block[0])
         labels = split_n_char(f"{block[2]:<{4*self._label_len}}", self._label_len)
         self.name = labels[0]
         self.ds_label = labels[1]
@@ -91,44 +92,43 @@ class CULVERT(Unit):
 
             # Read first set of general parameters
             params = split_10_char(f"{block[3]:<60}")
-            self.k = _to_float(params[0], 0.0)
-            self.m = _to_float(params[1], 0.0)
-            self.c = _to_float(params[2], 0.0)
-            self.y = _to_float(params[3], 0.0)
-            self.ki = _to_float(params[4], 0.0)
-            self.type_code = _to_str(params[5], "A")
+            self.k = to_float(params[0], 0.0)
+            self.m = to_float(params[1], 0.0)
+            self.c = to_float(params[2], 0.0)
+            self.y = to_float(params[3], 0.0)
+            self.ki = to_float(params[4], 0.0)
+            self.type_code = to_str(params[5], "A")
 
             # Read trash screen and remaining general parameters
             params1 = split_10_char(f"{block[4]:<70}")
-            self.screen_width = _to_float(params1[0], 0.0)
-            self.bar_proportion = _to_float(params1[1], 0.0)
-            self.debris_proportion = _to_float(params1[2], 0.0)
-            self.loss_coefficient = _to_float(params1[3], 0.0)
-            self.reverse_flow_mode = _to_str(params1[4], "CALCULATED", check_float=True)
-            self.headloss_type = _to_str(params1[5], "TOTAL")
-            self.max_screen_height = _to_float(params1[6], 0.0)
+            self.screen_width = to_float(params1[0], 0.0)
+            self.bar_proportion = to_float(params1[1], 0.0)
+            self.debris_proportion = to_float(params1[2], 0.0)
+            self.loss_coefficient = to_float(params1[3], 0.0)
+            self.reverse_flow_mode = to_str(params1[4], "CALCULATED", check_float=True)
+            self.headloss_type = to_str(params1[5], "TOTAL")
+            self.max_screen_height = to_float(params1[6], 0.0)
 
         elif self.subtype == "OUTLET":
             params = split_10_char(f"{block[3]:<30}")
-            self.loss_coefficient = _to_float(params[0], 1.0)
-            self.reverse_flow_mode = _to_str(params[1], "CALCULATED")
-            self.headloss_type = _to_str(params[2], "TOTAL")
+            self.loss_coefficient = to_float(params[0], 1.0)
+            self.reverse_flow_mode = to_str(params[1], "CALCULATED")
+            self.headloss_type = to_str(params[2], "TOTAL")
 
         else:
-            # This else block is triggered for culvert subtypes which aren't yet supported, and just keeps the '_block' in it's raw state to write back.
-            print(
-                f'This Culvert sub-type: "{self.subtype}" is currently unsupported for reading/editing',
+            # This else block is triggered for culvert subtypes which aren't yet supported, and just keeps the '_block' in its raw state to write back.
+            logging.warning(
+                "This Culvert sub-type: '%s' is currently unsupported for reading/editing",
+                self.subtype,
             )
             self._raw_block = block
 
-        # TODO: Create from blank.  Not supported currently as CULVERT has multiple subtypes
-
     def _write(self):
         """Function to write a valid CULVERT block"""
 
         _validate_unit(self)
 
-        header = "CULVERT " + self.comment
+        header = self._create_header()
         labels = join_n_char_ljust(
             self._label_len,
             self.name,
@@ -192,9 +192,7 @@ class BLOCKAGE(Unit):
         """Function to read a given BLOCKAGE block and store data as class attributes"""
 
         # Extract comment and revision number
-        b = block[0].replace("BLOCKAGE #revision#", " ").strip()
-        self._revision = _to_int(b[0], 1)
-        self.comment = b[1:].strip()
+        self._revision, self.comment = self._get_revision_and_comment(block[0])
 
         # Extract labels
         labels = split_n_char(f"{block[1]:<{5*self._label_len}}", self._label_len)
@@ -206,25 +204,27 @@ class BLOCKAGE(Unit):
 
         # Extract inlet and outlet loss coefficients
         params = split_10_char(f"{block[2]:<20}")
-        self.inlet_loss = _to_float(params[0], 1.5)
-        self.outlet_loss = _to_float(params[1], 1.0)
+        self.inlet_loss = to_float(params[0], 1.5)
+        self.outlet_loss = to_float(params[1], 1.0)
 
         # Extract blockage timeseries parameters
         params1 = split_10_char(f"{block[3]:<40}")
         self.nrows = int(params1[0])
-        self.timeoffset = _to_float(params1[1])
+        self.timeoffset = to_float(params1[1])
 
-        self.timeunit = _to_str(params1[2], "HOURS", check_float=True)
+        self.timeunit = to_str(params1[2], "HOURS", check_float=True)
         if self.timeunit == "DATE":
-            self.timeunit = "DATES"  # Parameter value updated to 'DATES' for consistency with other unit types.  'DATE' and 'DATES' both accepted for blockage unit ONLY
+            self.timeunit = "DATES"
+            # Parameter value updated to 'DATES' for consistency with other unit types.
+            # 'DATE' and 'DATES' both accepted for blockage unit ONLY
 
-        self.extendmethod = _to_str(params1[3], "NOEXTEND")
+        self.extendmethod = to_str(params1[3], "NOEXTEND")
 
         # Extract blockage to timeseries
         data_list = (
-            _to_data_list(block[4:], num_cols=2, date_col=0)
+            to_data_list(block[4:], num_cols=2, date_col=0)
             if self.timeunit == "DATES"
-            else _to_data_list(block[4:], num_cols=2)
+            else to_data_list(block[4:], num_cols=2)
         )  # Enforced two columns as Flood Modeller saves old parameters when using DATES (also to avoid extra 'HOURS' bug)
 
         self.data = pd.DataFrame(data_list, columns=["Time", "Blockage"])
@@ -241,7 +241,7 @@ class BLOCKAGE(Unit):
             msg = f"Parameter error with {self!r} - blockage percentage must be between 0 and 1"
             raise ValueError(msg)
 
-        header = f"BLOCKAGE #revision#{self._revision} {self.comment}"
+        header = self._create_header(include_revision=True)
         labels = join_n_char_ljust(
             self._label_len,
             self.name,