plans 1.1.0.post1.dev0__py3-none-any.whl

plans/config.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Copyright (C) 2025 The Project Authors
+# See pyproject.toml for authors/maintainers.
+# See LICENSE for license details.
+"""
+{Short module description (1-3 sentences)}
+todo docstring
+
+Features
+--------
+todo docstring
+
+* {feature 1}
+* {feature 2}
+* {feature 3}
+* {etc}
+
+Overview
+--------
+todo docstring
+{Overview description}
+
+Examples
+--------
+todo docstring
+{Examples in rST}
+
+Print a message
+
+.. code-block:: python
+
+    # print message
+    print("Hello world!")
+    # [Output] >> 'Hello world!'
+
+
+"""
+# IMPORTS
+# ***********************************************************************
+# import modules from other libs
+
+# Native imports
+# =======================================================================
+from pathlib import Path
+
+# ... {develop}
+
+# External imports
+# =======================================================================
+import pandas as pd
+
+# ... {develop}
+
+# Project-level imports
+# =======================================================================
+# import {module}
+# ... {develop}
+
+
+# CONSTANTS
+# ***********************************************************************
+# define constants in uppercase
+
+DATA_DIR = Path(__file__).parent / "data"
+FILE_FIELDS = DATA_DIR / "fields.csv"
+FILE_FILES = DATA_DIR / "files.csv"
+# ... {develop}
+
+
+# FUNCTIONS
+# ***********************************************************************
+def parse_files():
+    df = pd.read_csv(FILE_FILES, sep=";")
+    df["ext"] = df["structure"].apply(lambda x: ".tif" if "raster" in x else ".csv")
+    df["file_name"] = df["name"] + df["ext"]
+    return df
+
+
+def parse_fields():
+    return pd.read_csv(FILE_FIELDS, sep=";")
+
+
+# CLASSES
+# ***********************************************************************
+
+
+# ... {develop}
+
+# CLASSES -- Module-level
+# =======================================================================
+# ... {develop}
+
+
+# SCRIPT
+# ***********************************************************************
+# standalone behaviour as a script
+if __name__ == "__main__":
+
+    # Script section
+    # ===================================================================
+    print("Hello world!")
+    # ... {develop}

plans/data/.gitkeep

@@ -0,0 +1,2 @@
+# This file ensures that Git tracks this otherwise-empty directory.
+# Safe to delete once the directory has real content.

plans/data/fields.csv

@@ -0,0 +1,61 @@
+name;description;units;dtype;category;tex;system;subsystem;project_info;parameters_info;climate_series;qobs_series;lulc_attributes;soils_attributes;dist_area_hist;simulation_series;lulc_series;climate_series_lulc_{scenario}
+field;Field or attribute name;unitless;str;;;;;x;x;;;;;;;;
+value;Set value of field;unitless;misc;;;;;x;x;;;;;;;;
+id;Identification number;unitless;uint16;;;;;;;;;x;x;;;;
+name;Name;unitless;str;;;;;h;;;;x;x;;;x;
+alias;Alias;unitless;str;;;;;h;;;;x;x;;;;
+color;Color;unitless;str;;;;;;;;;x;x;;;;
+source;Source for reference;unitless;str;;;;;h;;;;;;;;;
+description;Brief description;unitless;str;;;;;h;;;;;;;;;
+folder_base;(optional) System path to base / parent folder of project;unitless;str;;;;;h;;;;;;;;;
+datetime;Date-time label;unitless;str;variable;t;time;;;;x;x;;;;x;x;x
+ppt;Precipitation;mm/{dt};float32;variable;P;flow;input;;;x;;;;;x;;x
+pet;Potential Evapotranspiration;mm/{dt};float32;variable;E_{\text{pot}};flow;output;;;x;;;;;x;;x
+dt;Simulation time step;min;float32;parameter;\Delta t;time;;;h;;;;;;;;
+c0;Canopy storage initial conditions;mm;float32;initial condition;C_{0};storage;canopy;;h;;;;;;;;
+s0;Surface storage initial conditions;mm;float32;initial condition;S_{0};storage;surface;;h;;;;;;;;
+v0;Vadose zone initial conditions;mm;float32;initial condition;V_{0};storage;vadose zone;;h;;;;;;;;
+g0;Phreatic zone initial conditions;mm;float32;initial condition;G_{0};storage;phreatic zone;;h;;;;;;;;
+ck;Canopy residence time;d;float32;parameter;C_{k};storage;canopy;;h;;;w;;;;;
+ca;Activation level for canopy flow;mm;float32;parameter;C_{a};storage;canopy;;h;;;w;;;;;
+sk;Surface residence time;d;float32;parameter;S_{k};storage;surface;;h;;;w;;;;;
+soa;Activation level for overland flow;mm;float32;parameter;S_{o, a};storage;surface;;h;;;w;;;;;
+soc;Fragmentation level for overland flow;mm;float32;parameter;S_{o, c};storage;surface;;h;;;w;;;;;
+sua;Activation level for subsurface flow;mm;float32;parameter;S_{u, a};storage;surface;;h;;;w;;;;;
+suc;Fragmentation level for subsurface flow;mm;float32;parameter;S_{u, c};storage;surface;;h;;;w;;;;;
+sux;Subsurface storage capacity;mm;float32;parameter;\hat{S_{u}};storage;surface;;h;;;w;;;;;
+kv;Soil hydraulic conductivity;mm/d;float32;parameter;K_{V};flow;vadose zone;;h;;;;w;;;;
+gk;Phreatic zone residence time;d;float32;parameter;G_{k};storage;phreatic zone;;h;;;;w;;;;
+gx;Phreatic zone storage capacity;mm;float32;parameter;\hat{G};storage;phreatic zone;;h;;;;w;;;;
+dea;Deficit activation level for ET (root zone);mm;float32;parameter;D_{e, a};flow;phreatic zone;;h;;;w;;;;;
+gex;ET capacity of capilar zone;mm;float32;parameter;\hat{G_{e}};storage;vadose zone;;h;;;;w;;;;
+kq;Channel water celerity;m/d;float32;parameter;K_{Q};flow;channels;;h;;;;;;;;
+qobs;Streamflow observed at basin outlet;mm/{dt};float32;variable;Q_{\text{obs}};flow;channels;;;;x;;;;x;;
+distance;Distance to basin outlet;m;float32;boundary condition;X;flow;channels;;;;;;;x;;;
+f_area;Area fraction of basin;unitless;float32;boundary condition;A;flow;channels;;;;;;;x;;;
+lower;Lower bound value of field;misc;float32;;;;;;x;;;;;;;;
+upper;Upper bound value of field;misc;float32;;;;;;x;;;;;;;;
+hw;Weight for HAND in TSI superposition;unitless;float32;parameter;H_{w};storage;phreatic zone;;h;;;;;;;;
+hx;HAND upper threshold in TSI superposition;m;float32;parameter;\hat{H};storage;phreatic zone;;h;;;;;;;;
+et;Evapotranspiration flow (ET);mm/{dt};float32;variable;E;flow;output;;;;;;;;x;;
+ec;Canopy evaporation flow;mm/{dt};float32;variable;E_{c};flow;output;;;;;;;;x;;
+es;Surface evaporation flow;mm/{dt};float32;variable;E_{s};flow;output;;;;;;;;x;;
+eg;Phreatic zone transpiration flow;mm/{dt};float32;variable;E_{g};flow;output;;;;;;;;x;;
+c;Canopy storage level;mm;float32;variable;C;storage;canopy;;;;;;;;x;;
+s;Surface storage level;mm;float32;variable;S;storage;surface;;;;;;;;x;;
+v;Vadose zone storage level;mm;float32;variable;V;storage;vadose zone;;;;;;;;x;;
+g;Phreatic zone level;mm;float32;variable;G;storage;phreatic zone;;;;;;;;x;;
+psf;Canopy stem flow;mm/{dt};float32;variable;P_{sf};flow;canopy;;;;;;;;x;;
+ptf;Canopy spill flow (throughfall);mm/{dt};float32;variable;P_{tf};flow;canopy;;;;;;;;x;;
+ps;Surface effective precipitation (psf + ptf);mm/{dt};float32;variable;P_{s};flow;surface;;;;;;;;x;;
+qo;Overland flow (runoff);mm/{dt};float32;variable;Q_{o};flow;surface;;;;;;;;x;;
+qu;Underland flow (subsurface flow);mm/{dt};float32;variable;Q_{u};flow;surface;;;;;;;;x;;
+qh;Hillslope flow (qo + qu);mm/{dt};float32;variable;Q_{h};flow;surface;;;;;;;;x;;
+qc;Channel flow at basin outlet (routed qh);mm/{dt};float32;variable;Q_{c};flow;channels;;;;;;;;x;;
+qb;Groundwater base flow;mm/{dt};float32;variable;Q_{b};flow;phreatic zone;;;;;;;;x;;
+qn;Infiltration flow (drainage to mineral soil);mm/{dt};float32;variable;Q_{n};flow;surface;;;;;;;;x;;
+qv;Recharge flow (percolation to phreatic zone);mm/{dt};float32;variable;Q_{v};flow;vadose zone;;;;;;;;x;;
+d;Soil saturation deficit (gx - g);mm;float32;variable;D;storage;phreatic zone;;;;;;;;x;;
+dv;Vadose zone saturation deficit (d - v);mm;float32;variable;D_{v};storage;vadose zone;;;;;;;;x;;
+q;Streamflow or discharge at basin outlet;mm/{dt};float32;variable;Q;flow;output;;;;;;;;x;;
+id_lulc_raster;Identification number for land use map;unitless;uint16;;;;;;;;;;;;;x;x

plans/data/files.csv

@@ -0,0 +1,26 @@
+workflow;structure;title;name;folder;dtype;units
+input - optional;raster;Digital Elevation Model;dem;{project}/data/topo;float32;m
+input - required;raster;Height Above Nearest Drainage;hand;{project}/data/topo;float32;m
+input - required;raster;Topographic Wetness Index;twi;{project}/data/topo;float32;index
+intermediate;raster;Topographic Saturation Index;tsi;{project}/data/topo;uint8;index
+input - required;quali raster;Local Drain Direction;ldd;{project}/data/topo;uint8;id
+input - required;quali raster;Soils Map;soils;{project}/data/soils;uint8;id
+input - optional;raster;Slope;slope;{project}/data/topo;float32;degrees
+input - optional;raster;Hill Shade;hillshade;{project}/data/topo;uint8;unitless
+input - optional;raster;Flow Accumulation;flowacc;{project}/data/topo;float32;m^2
+input - required;attribute table;Soils Attributes;soils_attributes;{project}/data/soils;;
+input - required;attribute table;Land Use Attributes;lulc_attributes;{project}/data/lulc/{scenario};;
+input - required;time series;Climate Series;climate_series;{project}/data/climate/{scenario};;
+intermediate;raster;Distance To Outlet;dto;{project}/data/topo;float32;m
+input - optional;time series;Streamflow Series;qobs_series;{project}/data/basins/{basin};;
+input - required;raster;Basin Area;basin;{project}/data/basins/{basin};uint8;unitless
+intermediate;table;Distance vs Area Histogram;dist_area_hist;{project}/data/basins/{basin};;
+input - optional;raster;Upslope Area;uparea;{project}/data/topo;float32;m^2
+input - required;info table;Parameters Info;parameters_info;{project}/data;;
+input - required;info table;Project Info;project_info;{project}/data;;
+input - required;time quali raster;Land Use Map;lulc_{date};{project}/data/lulc/{scenario};uint8;id
+output;time series;Simulation Series;simulation_series;{project}/outputs/{id};;
+intermediate;time raster;Land Use Parameter Map;lulc_{date}_{parameter};{project}/data/lulc/{scenario}/parameters;float32;misc
+intermediate;raster;Soils Parameter Map;soils_{parameter};{project}/data/soils/parameters;float32;misc
+intermediate;time series;Climate and Land Use Series;climate_series_lulc_{scenario};{project}/data/climate/{scenario};;
+intermediate;time series;Land Use Series;lulc_series;{project}/data/lulc/{scenario};;

plans/data/tools.csv

@@ -0,0 +1,2 @@
+name;type;flag;required;default;help
+NULL;str;folder;1;none;output folder file path

plans/datasets/__init__.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Copyright (C) 2025 The Project Authors
+# See pyproject.toml for authors/maintainers.
+# See LICENSE for license details.
+"""
+{Short package description (1-3 sentences)}
+todo docstring
+
+Features
+--------
+todo docstring
+
+* ``core`` module provides Lorem ipsum dolor sit amet.
+* ``chrono`` module provides Lorem ipsum dolor sit amet.
+* ``spatial`` module provides Lorem ipsum dolor sit amet.
+
+Overview
+--------
+todo docstring
+{Overview description}
+
+Examples
+--------
+todo docstring
+{Examples in rST}
+
+Print a message
+
+.. code-block:: python
+
+    # print message
+    print("Hello world!")
+    # [Output] >> 'Hello world!'
+
+"""
+# EXPOSE MODULES FROM PACKAGE
+# ***********************************************************************
+# todo [docstring]
+from .core import *
+from .spatial import *
+from .chrono import *