floodmodeller-api 0.5.2.post1__py3-none-any.whl → 0.5.3__py3-none-any.whl

floodmodeller_api/test/test_fmfile.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+import pytest
+
+from floodmodeller_api import read_file
+
+
+@pytest.mark.parametrize(
+    "file",
+    ["BRIDGE.DAT", "network.dat", "Domain1_W.xml", "T5.ief", "network.ied"],
+)
+def test_crlf_line_endings(test_workspace: Path, tmp_path: Path, file: str):
+    obj = read_file(test_workspace / file)
+    new_path = tmp_path / file
+    obj.save(new_path)
+    with open(new_path, "rb") as f:
+        contents = f.readlines()
+
+    # Check all line endings except last
+    assert all(line.endswith(b"\r\n") for line in contents[:-1])

floodmodeller_api/test/test_logs_lf.py

@@ -11,28 +11,34 @@ from floodmodeller_api.logs import create_lf
 
 
 @pytest.fixture()
-def lf1_fp(test_workspace: Path) -> Path:
+def lf1_fp_simple(test_workspace: Path) -> Path:
     return Path(test_workspace, "ex3.lf1")
 
 
-def test_lf1_info_dict(lf1_fp: Path):
+@pytest.fixture()
+def lf1_fp_complex(test_workspace: Path) -> Path:
+    return Path(test_workspace, "lf_complex_ex.lf1")
+
+
+def test_lf1_info_dict(lf1_fp_simple: Path):
     """LF1: Check info dictionary"""
-    lf1 = LF1(lf1_fp)
+    lf1 = LF1(lf1_fp_simple)
     assert lf1.info["version"] == "5.0.0.7752"
     assert lf1.info["max_system_volume"] == 270549
     assert lf1.info["mass_balance_error"] == -0.03
     assert lf1.info["progress"] == 100
+    assert lf1.info["total_boundary_inflow"] == 5506290
 
 
-def test_lf1_report_progress(lf1_fp: Path):
+def test_lf1_report_progress(lf1_fp_simple: Path):
     """LF1: Check report_progress()"""
-    lf1 = LF1(lf1_fp)
+    lf1 = LF1(lf1_fp_simple)
     assert lf1.report_progress() == 100
 
 
-def test_lf1_to_dataframe(lf1_fp: Path):
+def test_lf1_to_dataframe(lf1_fp_simple: Path):
     """LF1: Check to_dataframe()"""
-    lf1 = LF1(lf1_fp)
+    lf1 = LF1(lf1_fp_simple)
     lf1_df = lf1.to_dataframe(variable="all")
 
     assert lf1_df.loc[lf1_df.index[0], "iter"] == 6
@@ -56,9 +62,9 @@ def test_lf1_to_dataframe(lf1_fp: Path):
         assert lf1_tuflow_df[col].isna().all()  # there is no tuflow in this lf1
 
 
-def test_lf1_from_ief(lf1_fp: Path, test_workspace: Path):
+def test_lf1_from_ief(lf1_fp_simple: Path, test_workspace: Path):
     """LF1: Check IEF.get_log()"""
-    lf1 = LF1(lf1_fp)
+    lf1 = LF1(lf1_fp_simple)
 
     ief_fp = Path(test_workspace, "ex3.ief")
     ief = IEF(ief_fp)
@@ -76,7 +82,7 @@ def test_log_file_unsupported(caplog):
     assert lf is None
     assert (
         caplog.text
-        == "WARNING  root:lf.py:325 No progress bar as log file must have suffix lf1 or lf2. Simulation will continue as usual.\n"
+        == "WARNING  root:lf.py:332 No progress bar as log file must have suffix lf1 or lf2. Simulation will continue as usual.\n"
     )
 
 
@@ -90,7 +96,7 @@ def test_log_file_timeout(caplog):
     assert lf is None
     assert (
         caplog.text
-        == "WARNING  root:lf.py:325 No progress bar as log file is expected but not detected. Simulation will continue as usual.\n"
+        == "WARNING  root:lf.py:332 No progress bar as log file is expected but not detected. Simulation will continue as usual.\n"
     )
 
 
@@ -106,7 +112,7 @@ def test_log_file_from_old_run(caplog):
     assert lf is None
     assert (
         caplog.text
-        == "WARNING  root:lf.py:325 No progress bar as log file is from previous run. Simulation will continue as usual.\n"
+        == "WARNING  root:lf.py:332 No progress bar as log file is from previous run. Simulation will continue as usual.\n"
     )
 
 
@@ -121,3 +127,42 @@ def test_log_file_found():
 
     assert lf is not None
     lf1.assert_called_once_with(lf_filepath)
+
+
+def test_lf1_info_dict_all_params_present(lf1_fp_complex: Path):
+    """LF1: Check info dictionary contains all params required"""
+    lf1 = LF1(lf1_fp_complex)
+    expected_keys = {
+        "version",
+        "number_of_1D_river_nodes",
+        "qtol",
+        "htol",
+        "start_time",
+        "end_time",
+        "ran_at",
+        "max_itr",
+        "min_itr",
+        "progress",
+        "EFT",
+        "ETR",
+        "simulation_time_elapsed",
+        "number_of_unconverged_timesteps",
+        "proportion_of_simulation_unconverged",
+        "mass_balance_calculated_every",
+        "initial_volume",
+        "final_volume",
+        "total_boundary_inflow",
+        "total_boundary_outflow",
+        "total_lat_link_inflow",
+        "total_lat_link_outflow",
+        "max_system_volume",
+        "max_volume_increase",
+        "max_boundary_inflow",
+        "max_boundary_outflow",
+        "net_volume_increase",
+        "net_inflow_volume",
+        "volume_discrepancy",
+        "mass_balance_error",
+        "mass_balance_error_2",
+    }
+    assert expected_keys == lf1.info.keys()

floodmodeller_api/test/test_unit.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import pytest
+
+from floodmodeller_api.units._base import Unit  # update this import path to match your repo
+
+
+class DummyUnit(Unit):
+    def __init__(self, unit_value: str):
+        self._unit = unit_value
+
+
+@pytest.mark.parametrize(
+    ("unit", "header", "expected_revision", "expected_comment"),
+    [
+        ("RESERVOIR", "RESERVOIR 45678 This is a comment", None, "45678 This is a comment"),
+        ("RESERVOIR", "RESERVOIR #revision#1 Mr Comment123", 1, "Mr Comment123"),
+        ("LATERAL", "LATERAL #revision#1", 1, ""),
+        ("RIVER", "RIVER look at this lovely RIVER", None, "look at this lovely RIVER"),
+    ],
+)
+def test_get_revision_and_comment(
+    unit: str,
+    header: str,
+    expected_revision: int | None,
+    expected_comment: str,
+):
+    dummy_unit = DummyUnit(unit)
+    revision, comment = dummy_unit._get_revision_and_comment(header)
+    assert revision == expected_revision
+    assert comment == expected_comment
+
+
+@pytest.mark.parametrize(
+    ("unit", "header", "remove_revision", "expected_result"),
+    [
+        ("RESERVOIR", "RESERVOIR 45678 This is a comment", True, "45678 This is a comment"),
+        ("RESERVOIR", "RESERVOIR #revision#1 Mr Comment123", True, "Mr Comment123"),
+        (
+            "LATERAL",
+            "LATERAL #revision#1 another #revision#1 tag",
+            True,
+            "another #revision#1 tag",
+        ),
+        (
+            "LATERAL",
+            "LATERAL #revision#1 another #revision#1 tag",
+            False,
+            "#revision#1 another #revision#1 tag",
+        ),
+        ("RIVER", "RIVER look at this lovely RIVER", False, "look at this lovely RIVER"),
+    ],
+)
+def test_remove_unit_name(unit: str, header: str, remove_revision: bool, expected_result: str):
+    dummy_unit = DummyUnit(unit)
+    result = dummy_unit._remove_unit_name(header, remove_revision=remove_revision)
+    assert result == expected_result

floodmodeller_api/units/__init__.py

@@ -12,6 +12,7 @@ from .structures import (
     BRIDGE,
     CRUMP,
     FLAT_V_WEIR,
+    FLOODPLAIN,
     ORIFICE,
     OUTFALL,
     RNWEIR,
@@ -30,6 +31,6 @@ TConnectors: TypeAlias = JUNCTION | LATERAL
 TControls: TypeAlias = RESERVOIR
 TLosses: TypeAlias = BLOCKAGE | CULVERT
 TStructures: TypeAlias = (
-    BRIDGE | CRUMP | FLAT_V_WEIR | ORIFICE | OUTFALL | RNWEIR | SLUICE | SPILL | WEIR
+    BRIDGE | CRUMP | FLAT_V_WEIR | ORIFICE | OUTFALL | RNWEIR | SLUICE | SPILL | WEIR | FLOODPLAIN
 )
 TUnsupported: TypeAlias = UNSUPPORTED

floodmodeller_api/units/_base.py

@@ -18,7 +18,9 @@ from __future__ import annotations
 
 """ Holds the base unit class for all FM Units """
 
+import contextlib
 import logging
+import re
 from itertools import chain
 from typing import Any
 
@@ -26,7 +28,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, join_n_char_ljust, split_10_char, to_float, to_int, to_str
+from ._helpers import join_10_char, join_n_char_ljust, split_10_char, to_float, to_str
 
 
 class Unit(Jsonable):
@@ -138,6 +140,10 @@ class Unit(Jsonable):
 
         result = True
         diff = []
+        # Reset data attributes before checking equivalent
+        with contextlib.suppress(AttributeError):
+            _ = self.data, other.data
+
         result, diff = check_item_with_dataframe_equal(
             self.__dict__,
             other.__dict__,
@@ -257,7 +263,7 @@ class Unit(Jsonable):
     def _remove_unit_name(self, line: str, *, remove_revision: bool = False) -> str:
         line = line.replace(self._unit, "", 1)
         if remove_revision:
-            line = line.replace("#revision#", "", 1)
+            line = re.sub(r"^\s*#revision#\d+\s*", "", line)
         return line.strip()
 
     def _create_header(self, *, include_revision: bool = False) -> str:
@@ -272,10 +278,16 @@ class Unit(Jsonable):
         return line.split(" ")[0].strip()
 
     def _get_revision_and_comment(self, line: str) -> tuple[int | None, str]:
-        line_without_name = self._remove_unit_name(line, remove_revision=True)
-        revision = to_int(line_without_name[0], None) if line_without_name != "" else None
-        comment = line_without_name[1:].strip()
-        return revision, comment
+        unit = re.escape(self._unit)
+        pattern = rf"^{unit}(?:\s+#revision#(\d+))?(?:\s+(.*))?$"
+
+        match = re.match(pattern, line.strip())
+        if not match:
+            return None, ""
+
+        revision_str, comment = match.groups()
+        revision = int(revision_str) if revision_str else None
+        return revision, comment or ""
 
     def _enforce_dataframe(self, data: Any, columns: tuple[str, ...]) -> pd.DataFrame:
         return data if isinstance(data, pd.DataFrame) else pd.DataFrame([], columns=columns)

floodmodeller_api/units/sections.py

@@ -112,7 +112,7 @@ class RIVER(Unit):
 
         self._subtype = riv_block[1].split(" ")[0].strip()
         # Extends label line to be correct length before splitting to pick up blank labels
-        labels = split_n_char(f"{riv_block[2]:<{7*self._label_len}}", self._label_len)
+        labels = split_n_char(f"{riv_block[2]:<{7 * self._label_len}}", self._label_len)
 
         # Only supporting 'SECTION' subtype for now
         if self.subtype == "SECTION":
@@ -203,7 +203,7 @@ class RIVER(Unit):
                 self.lat4,
             )
             # Manual so slope can have more sf
-            params = f'{self.dist_to_next:>10.3f}{"":>10}{self.slope:>10.6f}{self.density:>10.3f}'
+            params = f"{self.dist_to_next:>10.3f}{'':>10}{self.slope:>10.6f}{self.density:>10.3f}"
             self.nrows = len(self._data)
             riv_block = [header, self.subtype, labels, params, f"{self.nrows!s:>10}"]
 
@@ -373,7 +373,7 @@ class INTERPOLATE(Unit):
         """Function to read a given INTERPOLATE WEIR block and store data as class attributes"""
 
         # Extends label line to be correct length before splitting to pick up blank labels
-        labels = split_n_char(f"{block[1]:<{7*self._label_len}}", self._label_len)
+        labels = split_n_char(f"{block[1]:<{7 * self._label_len}}", self._label_len)
         self.name = labels[0]
         self.first_spill = labels[1]
         self.second_spill = labels[2]
@@ -468,7 +468,7 @@ class REPLICATE(Unit):
         """Function to read a given REPLICATE block and store data as class attributes"""
 
         # Extends label line to be correct length before splitting to pick up blank labels
-        labels = split_n_char(f"{block[1]:<{7*self._label_len}}", self._label_len)
+        labels = split_n_char(f"{block[1]:<{7 * self._label_len}}", self._label_len)
         self.name = labels[0]
         self.first_spill = labels[1]
         self.second_spill = labels[2]

floodmodeller_api/units/structures.py

@@ -1518,3 +1518,145 @@ class OUTFALL(Unit):
             "modular_limit": modular_limit,
         }.items():
             setattr(self, param, val)
+
+
+class FLOODPLAIN(Unit):
+    """Class to hold and process FLOODPLAIN unit type.
+
+    Args:
+        name (str, optional): FLOODPLAIN section name
+        comment (str, optional): Comment included in unit
+        ds_label (str, optional): Downstream node label
+        data (pandas.Dataframe, optional): Dataframe object containing all the floodplain section data as well as all other relevant data.
+            Columns are ``'X', 'Y', 'Mannings n', 'Easting', 'Northing'``
+        calibration_coefficient (float, optional): Weir coefficient (includes discharge, velocity and calibration coefficients, optional)
+        modular_limit (float, optional): Ratio of upstream and downstream heads when switching between free and drowned mode
+        upstream_separation (float, optional): Distance from centre of upstream cell to section (m)
+        downstream_separation (float, optional): Distance from section to centre of downstream cell (m)
+        force_friction_flow (bool, optional): Force friction flow for all segments
+        ds_area_constraint (float, optional): Minimum value of downstream area (relative to upstream area) when Manning's equation applies. Typical value 0.1.
+
+    Returns:
+        FLOODPLAIN: Flood Modeller FLOODPLAIN Unit class object
+    """
+
+    _unit = "FLOODPLAIN"
+    _required_columns = (
+        "X",
+        "Y",
+        "Mannings n",
+        "Easting",
+        "Northing",
+    )
+
+    def _read(self, fp_block):
+        """Function to read a given FLOODPLAIN block and store data as class attributes."""
+
+        self._subtype = self._get_first_word(fp_block[1])
+        # Extends label line to be correct length before splitting to pick up blank labels
+        labels = split_n_char(f"{fp_block[2]:<{7 * self._label_len}}", self._label_len)
+        self.name = labels[0]
+        self.ds_label = labels[1]
+        self.comment = self._remove_unit_name(fp_block[0])
+
+        params = split_10_char(f"{fp_block[3]:<60}")
+        self.calibration_coefficient = to_float(params[0])
+        self.modular_limit = to_float(params[1])
+        self.upstream_separation = to_float(params[2])
+        self.downstream_separation = to_float(params[3])
+        self.force_friction_flow = params[4].upper() == "FRICTION"
+        self.ds_area_constraint = to_float(params[5])
+
+        self.nrows = int(split_10_char(fp_block[4])[0])
+        data_list = []
+        for row in fp_block[5:]:
+            row_split = split_10_char(f"{row:<50}")
+            x = to_float(row_split[0])  # chainage
+            y = to_float(row_split[1])  # elevation
+            n = to_float(row_split[2])  # Mannings
+            easting = to_float(row_split[3])  # easting
+            northing = to_float(row_split[4])  # northing
+
+            data_list.append(
+                [
+                    x,
+                    y,
+                    n,
+                    easting,
+                    northing,
+                ],
+            )
+        self._data = pd.DataFrame(
+            data_list,
+            columns=self._required_columns,
+        )
+
+    def _write(self):
+        """Function to write a valid FLOODPLAIN block"""
+
+        # Function to check the params are valid for FLOODPLAIN SECTION unit
+        _validate_unit(self)
+        header = self._create_header()
+        labels = join_n_char_ljust(self._label_len, self.name, self.ds_label)
+        # Manual so slope can have more sf
+        params = join_10_char(
+            self.calibration_coefficient,
+            self.modular_limit,
+            self.upstream_separation,
+            self.downstream_separation,
+            "FRICTION" if self.force_friction_flow else "",
+            self.ds_area_constraint,
+        )
+        self.nrows = len(self._data)
+        return [header, self.subtype, labels, params, *write_dataframe(self.nrows, self._data)]
+
+    def _create_from_blank(  # noqa: PLR0913
+        self,
+        name="new_floodplain",
+        comment="",
+        ds_label="",
+        data=None,
+        calibration_coefficient=1.0,
+        modular_limit=0.8,
+        upstream_separation=0.0,
+        downstream_separation=0.0,
+        force_friction_flow=False,
+        ds_area_constraint=0.1,
+    ):
+        # Initiate new FLOODPLAIN (currently hardcoding this as default)
+        self._subtype = "SECTION"
+
+        for param, val in {
+            "name": name,
+            "comment": comment,
+            "ds_label": ds_label,
+            "calibration_coefficient": calibration_coefficient,
+            "modular_limit": modular_limit,
+            "upstream_separation": upstream_separation,
+            "downstream_separation": downstream_separation,
+            "force_friction_flow": force_friction_flow,
+            "ds_area_constraint": ds_area_constraint,
+        }.items():
+            setattr(self, param, val)
+
+        self._data = self._enforce_dataframe(data, self._required_columns)
+
+    @property
+    def data(self) -> pd.DataFrame:
+        """Data table for the FLOODPLAIN cross section.
+
+        Returns:
+            pd.DataFrame: Pandas dataframe for the cross section data with columns: 'X', 'Y',
+            'Mannings n','Easting', 'Northing'
+        """
+        return self._data
+
+    @data.setter
+    def data(self, new_df: pd.DataFrame) -> None:
+        if not isinstance(new_df, pd.DataFrame):
+            msg = "The updated data table for a floodplain section must be a pandas DataFrame."
+            raise TypeError(msg)
+        if list(map(str.lower, new_df.columns)) != list(map(str.lower, self._required_columns)):
+            msg = f"The DataFrame must only contain columns: {self._required_columns}"
+            raise ValueError(msg)
+        self._data = new_df

floodmodeller_api/units/units.py

@@ -56,6 +56,7 @@ SUPPORTED_UNIT_TYPES: dict[str, SupportedUnitTypes] = {
     "JUNCTION": {"group": "connectors", "has_subtype": True},
     "LATERAL": {"group": "connectors", "has_subtype": False},
     "RESERVOIR": {"group": "controls", "has_subtype": False},
+    "FLOODPLAIN": {"group": "structures", "has_subtype": True},
 }
 
 UNSUPPORTED_UNIT_TYPES: dict[str, UnsupportedUnitTypes] = {
@@ -65,7 +66,6 @@ UNSUPPORTED_UNIT_TYPES: dict[str, UnsupportedUnitTypes] = {
     "FEHBDY": {"group": "boundaries", "has_subtype": False},  # RAINFALL RUNOFF METHOD boundary
     "FLOOD RELIEF": {"group": None, "has_subtype": True},  # found in dat file
     "FLOOD RELIEF ARCH": {"group": "structures", "has_subtype": True},  # found in FM help
-    "FLOODPLAIN": {"group": None, "has_subtype": True},  # floodplain section culvert
     "FRQSIM": {"group": "boundaries", "has_subtype": False},  # flood FReQuency SIMulation
     "FSRBDY": {"group": "boundaries", "has_subtype": False},  # FEH Rainfall Runoff Method
     "FSSR16BDY": {"group": "boundaries", "has_subtype": False},  # FSSR16 Method

floodmodeller_api/validation/parameters.py

@@ -661,4 +661,20 @@ parameter_options = {
         "type": "list-string-length",
         "max_length": 12,
     },
+    "upstream_separation": {
+        "type": "type-match",
+        "options": (float, int),
+    },
+    "downstream_separation": {
+        "type": "type-match",
+        "options": (float, int),
+    },
+    "force_friction_flow": {
+        "type": "type-match",
+        "options": (bool),
+    },
+    "ds_area_constraint": {
+        "type": "type-match",
+        "options": (float, int),
+    },
 }

floodmodeller_api/version.py

@@ -1 +1 @@
-__version__ = "0.5.2.post1"
+__version__ = "0.5.3"

floodmodeller_api/xml2d.py

@@ -442,7 +442,7 @@ class XML2D(FMFile):
         # Update XML dict and tree
         self._read()
 
-    def save(self, filepath: str | Path | None):
+    def save(self, filepath: str | Path) -> None:
         """Saves the XML to the given location, if pointing to an existing file it will be overwritten.
         Once saved, the XML() class will continue working from the saved location, therefore any further calls to XML.update() will
         update in the latest saved location rather than the original source XML used to construct the class

{floodmodeller_api-0.5.2.post1.dist-info → floodmodeller_api-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: floodmodeller_api
-Version: 0.5.2.post1
+Version: 0.5.3
 Summary: Extends the functionality of Flood Modeller to python users
 Author: Jacobs
 Author-email: joe.pierce@jacobs.com
@@ -24,6 +24,7 @@ Dynamic: author-email
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: license
+Dynamic: license-file
 Dynamic: project-url
 Dynamic: requires-dist
 Dynamic: summary
@@ -60,7 +61,8 @@ You can install the floodmodeller_api package from PyPI with the following comma
 pip install floodmodeller-api
 ```
 
-Python 3.10 or greater is required.
+Flood Modeller API is regularly tested for all versions of python 3.10 onwards. Although it may work for older versions of python, we recommend using at least v3.10 and ideally the latest 
+stable release.
 
 Once you have installed floodmodeller_api to your python environment, you can import the package with: