rapid2 2.0.0b1__py3-none-any.whl

rapid2/__init__.py

@@ -0,0 +1,79 @@
+# *****************************************************************************
+# __init__.py
+# *****************************************************************************
+
+# Purpose:
+# This file used in Python to define packages and initialize their namespaces.
+# Author:
+# Cedric H. David, 2025-2025
+
+
+# *****************************************************************************
+# Initialization
+# *****************************************************************************
+
+# -----------------------------------------------------------------------------
+# Dynamic Package Versioning
+# -----------------------------------------------------------------------------
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("rapid2")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "unknown"
+
+# -----------------------------------------------------------------------------
+# Top-Level API Facade
+# -----------------------------------------------------------------------------
+from .core.chck_bas import chck_bas
+from .core.chck_cpl import chck_cpl
+from .core.make_0bi_tbl import make_0bi_tbl
+from .core.make_CCC_mat import make_CCC_mat
+from .core.make_Mus_mat import make_Mus_mat
+from .core.make_Net_mat import make_Net_mat
+from .core.make_Wdw_mat import make_Wdw_mat
+from .core.prep_Qex_ncf import prep_Qex_ncf
+from .core.prep_Qfi_ncf import prep_Qfi_ncf
+from .core.prep_Qou_ncf import prep_Qou_ncf
+from .core.prep_skl_ncf import prep_skl_ncf
+from .core.read_bas_vec import read_bas_vec
+from .core.read_con_vec import read_con_vec
+from .core.read_cpl_vec import read_cpl_vec
+from .core.read_crd_vec import read_crd_vec
+from .core.read_kpr_vec import read_kpr_vec
+from .core.read_nml_tbl import read_nml_tbl
+from .core.read_std_vec import read_std_vec
+from .core.read_xpr_vec import read_xpr_vec
+from .core.updt_Mus_Qou import updt_Mus_Qou
+
+# -----------------------------------------------------------------------------
+# Explicit Public Interface
+# -----------------------------------------------------------------------------
+__all__ = [
+    "__version__",
+    "chck_bas",
+    "chck_cpl",
+    "make_0bi_tbl",
+    "make_CCC_mat",
+    "make_Mus_mat",
+    "make_Net_mat",
+    "make_Wdw_mat",
+    "prep_Qex_ncf",
+    "prep_Qfi_ncf",
+    "prep_Qou_ncf",
+    "prep_skl_ncf",
+    "read_bas_vec",
+    "read_con_vec",
+    "read_cpl_vec",
+    "read_crd_vec",
+    "read_kpr_vec",
+    "read_nml_tbl",
+    "read_std_vec",
+    "read_xpr_vec",
+    "updt_Mus_Qou",
+]
+
+
+# *****************************************************************************
+# End
+# *****************************************************************************

rapid2/cli/_cmpncf.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+# *****************************************************************************
+# _cmpncf.py
+# *****************************************************************************
+
+# Author:
+# Cedric H. David, 2016-2026
+
+
+# *****************************************************************************
+# Import Python modules
+# *****************************************************************************
+import argparse
+import sys
+
+import netCDF4
+import numpy as np
+from numpy.ma import MaskedArray
+
+from rapid2 import (
+    __version__,
+    make_0bi_tbl,
+    read_std_vec,
+)
+
+
+# *****************************************************************************
+# Main
+# *****************************************************************************
+def main() -> None:
+
+    # -------------------------------------------------------------------------
+    # Initialize the argument parser and add valid arguments
+    # -------------------------------------------------------------------------
+    parser = argparse.ArgumentParser(
+        description=(
+            "Compare RAPID input/output netCDF files for numerical regression "
+            "testing."
+        ),
+        epilog=(
+            "examples:\n"
+            "  cmpncf "
+            "--previous "
+            "input/Tutorial/Qinit_GLDAS_2.1_VIC_2010-01_GOLD.nc4 "
+            "--now "
+            "input/Tutorial/Qinit_GLDAS_2.1_VIC_2010-01.nc4 "
+            "--relative_tolerance 1e-6 "
+            "--absolute_tolerance 1e-3\n"
+            "  cmpncf "
+            "--previous "
+            "input/Tutorial/Qext_GLDAS_2.1_VIC_2010-01_GOLD.nc4 "
+            "--now "
+            "input/Tutorial/Qext_GLDAS_2.1_VIC_2010-01.nc4 "
+            "--relative_tolerance 1e-6 "
+            "--absolute_tolerance 1e-3"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "--version", action="version", version=f"rapid2 {__version__}"
+    )
+
+    parser.add_argument(
+        "-prv",
+        "--previous",
+        dest="prv",
+        metavar="PREVIOUS",
+        type=str,
+        required=True,
+        help="specify the old netCDF file",
+    )
+
+    parser.add_argument(
+        "-now",
+        "--now",
+        dest="now",
+        metavar="NOW",
+        type=str,
+        required=True,
+        help="specify the new netCDF file",
+    )
+
+    parser.add_argument(
+        "-rtl",
+        "--relative_tolerance",
+        dest="rtl",
+        metavar="RELATIVE_TOLERANCE",
+        type=str,
+        required=False,
+        default="0",
+        help="specify the relative tolerance",
+    )
+
+    parser.add_argument(
+        "-atl",
+        "--absolute_tolerance",
+        dest="atl",
+        metavar="ABSOLUTE_TOLERANCE",
+        type=str,
+        required=False,
+        default="0",
+        help="specify the absolute tolerance",
+    )
+
+    # -------------------------------------------------------------------------
+    # Parse arguments and assign to variables
+    # -------------------------------------------------------------------------
+    args = parser.parse_args()
+
+    prv_ncf = args.prv
+    now_ncf = args.now
+    YS_rtl = args.rtl
+    YS_atl = args.atl
+
+    print(
+        f"Comparing {prv_ncf} "
+        f"with {now_ncf} "
+        f"relative tolerance {YS_rtl} "
+        f"absolute tolerance {YS_atl}"
+    )
+
+    ZS_rtl = np.float64(YS_rtl)
+    ZS_atl = np.float64(YS_atl)
+
+    # -------------------------------------------------------------------------
+    # Get metadata in netCDF files
+    # -------------------------------------------------------------------------
+    (
+        IV_riv_prv,
+        ZV_lon_prv,
+        ZV_lat_prv,
+        IV_tim_prv,
+        IM_tim_prv,
+    ) = read_std_vec(prv_ncf)
+
+    (
+        IV_riv_now,
+        ZV_lon_now,
+        ZV_lat_now,
+        IV_tim_now,
+        IM_tim_now,
+    ) = read_std_vec(now_ncf)
+
+    # -------------------------------------------------------------------------
+    # Compare dimension sizes
+    # -------------------------------------------------------------------------
+    if len(IV_riv_prv) == len(IV_riv_now):
+        IS_riv_tot = len(IV_riv_prv)
+        print(f"Common number of river reaches: {IS_riv_tot}")
+    else:
+        print(
+            f"ERROR - The number of river reaches differs: "
+            f"{len(IV_riv_prv)} <> {len(IV_riv_now)}"
+        )
+        sys.exit(1)
+
+    if len(IV_tim_prv) == len(IV_tim_now):
+        IS_tim = len(IV_tim_prv)
+        print(f"Common number of time steps   : {IS_tim}")
+    else:
+        print(
+            f"ERROR - The number of time steps differs: "
+            f"{len(IV_tim_prv)} <> {len(IV_tim_now)}"
+        )
+        sys.exit(1)
+
+    # -------------------------------------------------------------------------
+    # Compare rivid values
+    # -------------------------------------------------------------------------
+    if np.array_equal(IV_riv_prv, IV_riv_now):
+        print("The rivids and their sort are both the same")
+    else:
+        if np.array_equal(np.sort(IV_riv_prv), np.sort(IV_riv_now)):
+            print("WARNING - The rivids are the same, but sorted differently")
+            _, _, IV_0bi_prv = make_0bi_tbl(IV_riv_now, IV_riv_prv)
+        else:
+            print("ERROR - The rivids differ")
+            sys.exit(1)
+
+    # -------------------------------------------------------------------------
+    # Compare other metadata values
+    # -------------------------------------------------------------------------
+    if np.array_equal(ZV_lon_prv, ZV_lon_now):
+        print("The longitude values are the same")
+    else:
+        print("ERROR - The longitude values differ")
+        sys.exit(1)
+
+    if np.array_equal(ZV_lat_prv, ZV_lat_now):
+        print("The latitude values are the same")
+    else:
+        print("ERROR - The latitude values differ")
+        sys.exit(1)
+
+    if np.array_equal(IV_tim_prv, IV_tim_now):
+        print("The time values are the same")
+    else:
+        print("ERROR - The time values differ")
+        sys.exit(1)
+
+    if (IM_tim_prv is None) != (IM_tim_now is None):
+        print("ERROR - time_bnds present in only one file")
+        sys.exit(1)
+
+    if (IM_tim_prv is not None) and (IM_tim_now is not None):
+        if np.array_equal(IM_tim_prv, IM_tim_now):
+            print("The time_bnds values are the same")
+        else:
+            print("ERROR - The time_bnds values differ")
+            sys.exit(1)
+    else:
+        print("WARNING - time_bnds variable missing: skipping comparison")
+
+    # -------------------------------------------------------------------------
+    # Get main variable in netCDF files
+    # -------------------------------------------------------------------------
+    p = netCDF4.Dataset(prv_ncf, "r")
+    n = netCDF4.Dataset(now_ncf, "r")
+
+    if "Qext" in p.variables and "Qext" in n.variables:
+        YS_val_tmp = "Qext"
+    elif "Qout" in p.variables and "Qout" in n.variables:
+        YS_val_tmp = "Qout"
+    else:
+        print("ERROR - Neither Qext nor Qout is common variable")
+        sys.exit(1)
+    print(f"The main variable names are the same: {YS_val_tmp}")
+
+    # -------------------------------------------------------------------------
+    # Compute differences
+    # -------------------------------------------------------------------------
+    ZS_rdf_max = 0
+    ZS_adf_max = 0
+    BS_fll_prv = False
+    BS_fll_now = False
+
+    for JS_tim in range(IS_tim):
+        # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+        # Initializing
+        # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+        ZS_rdf = 0
+        ZS_adf = 0
+
+        # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+        # Getting values
+        # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+        ZV_val_prv = p.variables[YS_val_tmp][JS_tim, :]
+        ZV_val_now = n.variables[YS_val_tmp][JS_tim, :]
+        if "IV_0bi_prv" in locals():
+            ZV_val_now = ZV_val_now[IV_0bi_prv]
+
+        # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+        # Converting masked values to -9999
+        # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+        if isinstance(ZV_val_prv, MaskedArray) and np.any(ZV_val_prv.mask):
+            ZV_val_prv = ZV_val_prv.filled(fill_value=-9999)
+            BS_fll_prv = True
+        if isinstance(ZV_val_now, MaskedArray) and np.any(ZV_val_now.mask):
+            ZV_val_now = ZV_val_now.filled(fill_value=-9999)
+            BS_fll_now = True
+
+        # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+        # Comparing difference values
+        # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+        # Tried computations with regular Python lists but they are very slow.
+        # Also tried using map(operator.sub,V,W) or [x-y for x,y in zip(V,W)],
+        # but this still results in slow computations.
+        # The best performance seems to be with Numpy.
+        ZV_adf_tmp = np.absolute(ZV_val_prv - ZV_val_now)
+        ZS_adf_max = max(np.max(ZV_adf_tmp), ZS_adf_max)
+
+        ZS_rdf = np.sqrt(
+            np.sum(ZV_adf_tmp * ZV_adf_tmp) / np.sum(ZV_val_prv * ZV_val_prv)
+        )
+        ZS_rdf_max = max(ZS_rdf, ZS_rdf_max)
+
+    # ------------------------------------------------------------------------
+    # Print difference values and compare to tolerances
+    # ------------------------------------------------------------------------
+    if BS_fll_prv:
+        print(f"WARNING - masked values replaced by -9999 in {prv_ncf}")
+    if BS_fll_now:
+        print(f"WARNING - masked values replaced by -9999 in {now_ncf}")
+    if BS_fll_prv or BS_fll_now:
+        print("-------------------------------")
+
+    print("Max relative difference       :" + "{0:.2e}".format(ZS_rdf_max))
+    print("Max absolute difference       :" + "{0:.2e}".format(ZS_adf_max))
+    print("-------------------------------")
+
+    if ZS_rdf_max > ZS_rtl:
+        print("Unacceptable rel. difference!!!")
+        print("-------------------------------")
+        sys.exit(1)
+
+    if ZS_adf_max > ZS_atl:
+        print("Unacceptable abs. difference!!!")
+        print("-------------------------------")
+        sys.exit(1)
+
+    print("netCDF files similar!!!")
+    print("-------------------------------")
+
+
+# *****************************************************************************
+# If executed as a script
+# *****************************************************************************
+if __name__ == "__main__":
+    main()
+
+
+# *****************************************************************************
+# End
+# *****************************************************************************

rapid2/cli/_cpllsm.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+# *****************************************************************************
+# _cpllsm.py
+# *****************************************************************************
+
+# Author:
+# Cedric H. David, 2025-2025
+
+
+# *****************************************************************************
+# Import Python modules
+# *****************************************************************************
+import argparse
+import os.path
+import sys
+
+import netCDF4
+import numpy as np
+from tqdm import tqdm
+
+from rapid2 import (
+    __version__,
+    chck_cpl,
+    prep_Qex_ncf,
+    read_con_vec,
+    read_cpl_vec,
+    read_crd_vec,
+)
+
+
+# *****************************************************************************
+# Main
+# *****************************************************************************
+def main() -> None:
+
+    # -------------------------------------------------------------------------
+    # Initialize the argument parser and add valid arguments
+    # -------------------------------------------------------------------------
+    parser = argparse.ArgumentParser(
+        description=(
+            "Transform Land Surface Model data into RAPID external inflow "
+            "input."
+        ),
+        epilog=(
+            "examples:\n"
+            "  cpllsm "
+            "--land_surface_model "
+            "input/Tutorial/GLDAS_2.1_VIC_2010-01.nc4 "
+            "--connectivity "
+            "input/Tutorial/rapid_connect_pfaf_74.csv "
+            "--coordinates "
+            "input/Tutorial/coords_pfaf_74.csv "
+            "--coupling "
+            "input/Tutorial/rapid_coupling_pfaf_74_GLDAS.csv "
+            "--external_inflow "
+            "input/Tutorial/Qext_GLDAS_2.1_VIC_2010-01.nc4"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "--version", action="version", version=f"rapid2 {__version__}"
+    )
+
+    parser.add_argument(
+        "-lsm",
+        "--land_surface_model",
+        dest="lsm",
+        metavar="LAND_SURFACE_MODEL",
+        type=str,
+        required=True,
+        help="specify the LSM file",
+    )
+
+    parser.add_argument(
+        "-con",
+        "--connectivity",
+        dest="con",
+        metavar="CONNECTIVITY",
+        type=str,
+        required=True,
+        help="specify the connectivity file",
+    )
+
+    parser.add_argument(
+        "-crd",
+        "--coordinates",
+        dest="crd",
+        metavar="COORDINATES",
+        type=str,
+        required=True,
+        help="specify the coordinates",
+    )
+
+    parser.add_argument(
+        "-cpl",
+        "--coupling",
+        dest="cpl",
+        metavar="COUPLING",
+        type=str,
+        required=True,
+        help="specify the coupling file",
+    )
+
+    parser.add_argument(
+        "-Qex",
+        "--external_inflow",
+        dest="Qex",
+        metavar="EXTERNAL_INFLOW",
+        type=str,
+        required=True,
+        help="specify the file name",
+    )
+
+    # -------------------------------------------------------------------------
+    # Parse arguments and assign to variables
+    # -------------------------------------------------------------------------
+    args = parser.parse_args()
+
+    lsm_ncf = args.lsm
+    con_csv = args.con
+    crd_csv = args.crd
+    cpl_csv = args.cpl
+    Qex_ncf = args.Qex
+
+    print(
+        f"Transforming data from  {lsm_ncf} "
+        f"for {con_csv} "
+        f"with {crd_csv} "
+        f"and {cpl_csv} "
+        f"as {Qex_ncf}"
+    )
+
+    # -------------------------------------------------------------------------
+    # Skip if file already exists
+    # -------------------------------------------------------------------------
+    if os.path.exists(Qex_ncf):
+        print(f"WARNING - File already exists {Qex_ncf}. Exit without error")
+        sys.exit(0)
+
+    # -------------------------------------------------------------------------
+    # Check if files exist
+    # -------------------------------------------------------------------------
+    try:
+        with open(lsm_ncf):
+            pass
+    except IOError:
+        print(f"ERROR - Unable to open {lsm_ncf}")
+        sys.exit(1)
+
+    # -------------------------------------------------------------------------
+    # Read connectivity file
+    # -------------------------------------------------------------------------
+    print("- Read connectivity file")
+
+    IV_riv_tot, IV_dwn_tot = read_con_vec(con_csv)
+    IS_riv_tot = len(IV_riv_tot)
+    print(
+        "  . The number of river reaches in connectivity file is: "
+        f"{IS_riv_tot}"
+    )
+
+    # -------------------------------------------------------------------------
+    # Read coordinate file
+    # -------------------------------------------------------------------------
+    print("- Read coordinate file")
+
+    IV_riv_tmp, ZV_lon_tot, ZV_lat_tot = read_crd_vec(crd_csv)
+    np.testing.assert_array_equal(IV_riv_tot, IV_riv_tmp)
+    print("  . The river reaches are the same as in connectivity file")
+
+    # -------------------------------------------------------------------------
+    # Read coupling file
+    # -------------------------------------------------------------------------
+    print("- Read coupling file")
+
+    IV_riv_tmp, ZV_skm_tot, IV_1bi_tot, IV_1bj_tot = read_cpl_vec(cpl_csv)
+    np.testing.assert_array_equal(IV_riv_tot, IV_riv_tmp)
+    print("  . The river reaches are the same as in connectivity file")
+
+    # -------------------------------------------------------------------------
+    # Check consistency of coupling file
+    # -------------------------------------------------------------------------
+    print("- Check consisitency of coupling file")
+
+    chck_cpl(ZV_skm_tot, IV_1bi_tot, IV_1bj_tot)
+    print(" . OK")
+
+    # -------------------------------------------------------------------------
+    # Read LSM metadata
+    # -------------------------------------------------------------------------
+    print("- Read LSM metadata")
+
+    c = netCDF4.Dataset(lsm_ncf, "r")
+
+    IS_lon_lsm = len(c.dimensions["lon"])
+    print(f"  . The number of longitudes is: {IS_lon_lsm}")
+
+    IS_lat_lsm = len(c.dimensions["lat"])
+    print(f"  . The number of latitudes is: {IS_lat_lsm}")
+
+    IS_tim_all = len(c.dimensions["time"])
+    print(f"  . The number of time steps is: {IS_tim_all}")
+
+    if "Qs_acc" in c.variables:
+        if "_FillValue" in c.variables["Qs_acc"].ncattrs():
+            ZS_fll = c.variables["Qs_acc"]._FillValue
+            print(f"  . The fill value for Qs_acc is: {ZS_fll}")
+    else:
+        raise ValueError("Qs_acc variable missing")
+
+    if "Qsb_acc" in c.variables:
+        if "_FillValue" in c.variables["Qsb_acc"].ncattrs():
+            ZS_fll = c.variables["Qsb_acc"]._FillValue
+            print(f"  . The fill value for Qsb_acc is: {ZS_fll}")
+    else:
+        raise ValueError("Qsb_acc variable missing")
+
+    # -------------------------------------------------------------------------
+    # Create Qext file
+    # -------------------------------------------------------------------------
+    print("- Create Qext file")
+
+    prep_Qex_ncf(IV_riv_tot, ZV_lon_tot, ZV_lat_tot, Qex_ncf)
+
+    f = netCDF4.Dataset(Qex_ncf, "a")
+
+    # -------------------------------------------------------------------------
+    # Populate dynamic data
+    # -------------------------------------------------------------------------
+    print("- Populate dynamic data")
+
+    ZV_scl_tot = 1000 * ZV_skm_tot
+    # Scale by 1000: the multiplication of 0.001 m/mm and 1,000,000 m^2/km^2
+    # This directly converts an input flux of mm/s (or kg*m^-2*s-1) and an
+    # input area of km^2 into an output flow rate of m^3/s.
+
+    IV_0bi_tot = IV_1bi_tot - 1
+    IV_0bj_tot = IV_1bj_tot - 1
+    # Shift to 0-based indexing; entries becoming −1 have 0 area (chck_cpl.py).
+
+    for JS_tim_all in tqdm(range(IS_tim_all), desc="Processing LSM data"):
+        ZM_rsf_lsm = c.variables["Qs_acc"][JS_tim_all][:][:]
+        ZM_rsb_lsm = c.variables["Qsb_acc"][JS_tim_all][:][:]
+        # netCDF data are stored following: c.variables[var][time][lat][lon]
+        ZM_run_lsm = ZM_rsf_lsm + ZM_rsb_lsm
+        # ZM_run_lsm is of type 'np.ma.core.MaskedArray' or 'np.ndarray'
+        # We here assume that runoff data inputs are in kg/m^2/s.
+
+        ZV_Qex_tot = ZM_run_lsm[IV_0bj_tot, IV_0bi_tot]
+        # This uses the multidimensional list-of-locations indexing capability.
+        # All values at given i and j indices can be obtained by giving two
+        # lists of j and i indices.
+        ZV_Qex_tot = ZV_Qex_tot * ZV_scl_tot
+        # Result is now a true flow rate (m3/s) because input was a rate.
+
+        if isinstance(ZV_Qex_tot, np.ma.MaskedArray):
+            ZV_Qex_tot = np.where(ZV_Qex_tot.mask, 0, ZV_Qex_tot.data)
+        # Make sure the masked values are replaced by 0
+        f.variables["Qext"][JS_tim_all, :] = ZV_Qex_tot[:]
+        # netCDF data are stored following: f.variables[Qext][time][rivid]
+
+    f.variables["time"][:] = c.variables["time"][:]
+    f.variables["time_bnds"][:] = c.variables["time_bnds"][:]
+    # From the LSM netCDF file
+    c.close()
+
+
+# *****************************************************************************
+# If executed as a script
+# *****************************************************************************
+if __name__ == "__main__":
+    main()
+
+
+# *****************************************************************************
+# End
+# *****************************************************************************