diff --git a/docs/_quarto.yml b/docs/_quarto.yml index ea36bd59b..593e12392 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -65,10 +65,6 @@ quartodoc: desc: The Model class represents an entire Ribasim model. contents: - Model - - Model.write - - Model.from_toml - - Model.plot - - title: Network desc: The Node and Edge GeoPackage layers define the network layout. contents: @@ -78,10 +74,13 @@ quartodoc: desc: Available node types to model different situations. contents: - Basin - - TabulatedRatingCurve - - LinearResistance - FractionalFlow + - LevelBoundary - LevelControl + - LinearResistance + - ManningResistance + - Pump + - TabulatedRatingCurve - title: Utility functions desc: Collection of utility functions. contents: diff --git a/python/ribasim/ribasim/basin.py b/python/ribasim/ribasim/basin.py index bbe00800d..5f1b3b259 100644 --- a/python/ribasim/ribasim/basin.py +++ b/python/ribasim/ribasim/basin.py @@ -46,46 +46,14 @@ class Basin(InputMixin, BaseModel): Parameters ---------- - profile: pandas.DataFrame - - A tabulation with the columns: - - * node_id - * storage - * area - * water level - - static: pandas.DataFrame, optional - - Static forcing with columns: - - * node_id - * potential evaporation - * precipitation - * groundwater drainage - * groundwater infiltration - * urban runoff - - forcing: pandas.DataFrame, optional - - Time varying forcing with columns: - - * node_id - * time - * potential evaporation - * precipitation - * groundwater drainage - * groundwater infiltration - * urban runoff - - state: pandas.DataFrame, optional - - Initial state with columns: - - * node_id - * storage - * concentration - + profile : pandas.DataFrame + Table describing the geometry. + static : pandas.DataFrame, optional + Table describing the constant fluxes. + forcing : pandas.DataFrame, optional + Table describing the time-varying fluxes. + state : pandas.DataFrame, optional + Table describing the initial condition. """ _input_type = "Basin" diff --git a/python/ribasim/ribasim/edge.py b/python/ribasim/ribasim/edge.py index 5c9312b48..8996905b9 100644 --- a/python/ribasim/ribasim/edge.py +++ b/python/ribasim/ribasim/edge.py @@ -30,14 +30,8 @@ class Edge(InputMixin, BaseModel): Parameters ---------- - static: pandas.DataFrame - - With columns: - - * from_node_id - * to_node_id - * geometry - + static : pandas.DataFrame + Table describing the flow connections. """ _input_type = "Edge" @@ -59,8 +53,8 @@ def write(self, directory: FilePath, modelname: str) -> None: Parameters ---------- - directory: FilePath - modelname: str + directory : FilePath + modelname : str """ self.sort() directory = Path(directory) diff --git a/python/ribasim/ribasim/fractional_flow.py b/python/ribasim/ribasim/fractional_flow.py index 42ec5cdb2..751af745c 100644 --- a/python/ribasim/ribasim/fractional_flow.py +++ b/python/ribasim/ribasim/fractional_flow.py @@ -18,26 +18,12 @@ class Config: class FractionalFlow(InputMixin, BaseModel): """ - Receives a fraction of the flow. The fractions must sum to 1.0 for a - furcation. + Receives a fraction of the flow. The fractions must sum to 1.0 for a furcation. Parameters ---------- - static: pandas.DataFrame - - With columns: - - * node_id - * fraction - - forcing: pandas.DataFrame, optional - - With columns: - - * node_id - * time - * fraction - + static : pandas.DataFrame + Table with the constant flow fractions. """ _input_type = "FractionalFlow" diff --git a/python/ribasim/ribasim/input_base.py b/python/ribasim/ribasim/input_base.py index 695913dee..b1a694681 100644 --- a/python/ribasim/ribasim/input_base.py +++ b/python/ribasim/ribasim/input_base.py @@ -78,8 +78,10 @@ def write(self, directory: FilePath, modelname: str) -> None: Parameters ---------- - directory: FilePath - modelname: str + directory : FilePath + Path to the directory where to write the files. + modelname : str + Name of the model, used as a file name. """ self.sort() directory = Path(directory) @@ -128,8 +130,8 @@ def from_geopackage(cls: Type[T], path: FilePath) -> T: Parameters ---------- - path: Path - Path to the GeoPackage + path : Path + Path to the GeoPackage. Returns ------- @@ -150,7 +152,7 @@ def from_config(cls: Type[T], config: Dict[str, Any]) -> T: Parameters ---------- - config: Dict[str, Any] + config : Dict[str, Any] Returns ------- diff --git a/python/ribasim/ribasim/level_boundary.py b/python/ribasim/ribasim/level_boundary.py index d722ee3e1..ca1cbb413 100644 --- a/python/ribasim/ribasim/level_boundary.py +++ b/python/ribasim/ribasim/level_boundary.py @@ -19,12 +19,8 @@ class LevelBoundary(InputMixin, BaseModel): Parameters ---------- - static: pandas.DataFrame - - With columns: - - * node_id - * level + static : pandas.DataFrame + Table with the constant water levels. """ _input_type = "LevelBoundary" diff --git a/python/ribasim/ribasim/level_control.py b/python/ribasim/ribasim/level_control.py index 94928bacd..0a0e1caa1 100644 --- a/python/ribasim/ribasim/level_control.py +++ b/python/ribasim/ribasim/level_control.py @@ -22,14 +22,8 @@ class LevelControl(InputMixin, BaseModel): Parameters ---------- - static: pandas.DataFrame - - With columns: - - * node_id - * target_level - * resistance - + static : pandas.DataFrame + Table with the constant target levels and resistances. """ _input_type = "LevelControl" diff --git a/python/ribasim/ribasim/linear_resistance.py b/python/ribasim/ribasim/linear_resistance.py index 6fc52258f..31d899e58 100644 --- a/python/ribasim/ribasim/linear_resistance.py +++ b/python/ribasim/ribasim/linear_resistance.py @@ -23,13 +23,8 @@ class LinearResistance(InputMixin, BaseModel): Parameters ---------- - static: pd.DataFrame - - With columns: - - * node_id - * resistance - + static : pd.DataFrame + Table with the constant resistances. """ _input_type = "LinearResistance" diff --git a/python/ribasim/ribasim/manning_resistance.py b/python/ribasim/ribasim/manning_resistance.py index b713e412f..1db7ed8b8 100644 --- a/python/ribasim/ribasim/manning_resistance.py +++ b/python/ribasim/ribasim/manning_resistance.py @@ -23,16 +23,8 @@ class ManningResistance(InputMixin, BaseModel): Parameters ---------- - static: pd.DataFrame - - With columns: - - * node_id - * length - * manning_n - * profile_width - * profile_slope - + static : pd.DataFrame + Table with the constant Manning parameters. """ _input_type = "ManningResistance" diff --git a/python/ribasim/ribasim/model.py b/python/ribasim/ribasim/model.py index 63ab0d626..ce606acbc 100644 --- a/python/ribasim/ribasim/model.py +++ b/python/ribasim/ribasim/model.py @@ -49,23 +49,41 @@ class Solver(BaseModel): class Model(BaseModel): """ + A full Ribasim model schematisation with all input. + Ribasim model containing the location of the nodes, the edges between the nodes, and the node parametrization. Parameters ---------- - modelname: str - node: Node - edge: Edge - basin: Basin - fractional_flow: Optional[FractionalFlow] - level_control: Optional[LevelControl] - level_boundary: Optional[LevelBoundary] + modelname : str + Model name, used in TOML and GeoPackage file name. + node : Node + The ID, type and geometry of each node. + edge : Edge + How the nodes are connected. + basin : Basin + The waterbodies. + fractional_flow : Optional[FractionalFlow] + Split flows into fractions. + level_control : Optional[LevelControl] + Control the water level with a resistance. + level_boundary : Optional[LevelBoundary] + Boundary condition specifying the water level. linear_resistance: Optional[LinearResistance] - tabulated_rating_curve: Optional[TabulatedRatingCurve] - starttime: Union[str, datetime.datetime] - endtime: Union[str, datetime.datetime] - solver: Optional[Solver] + Linear flow resistance. + manning_resistance : Optional[ManningResistance] + Flow resistance based on the Manning formula. + tabulated_rating_curve : Optional[TabulatedRatingCurve] + Tabulated rating curve describing flow based on the upstream water level. + pump : Optional[Pump] + Prescribed flow rate from one basin to the other. + starttime : Union[str, datetime.datetime] + Starting time of the simulation. + endtime : Union[str, datetime.datetime] + End time of the simulation. + solver : Optional[Solver] + Solver settings. """ modelname: str @@ -161,12 +179,12 @@ def from_toml(path: FilePath) -> "Model": Parameters ---------- - path: FilePath + path : FilePath Path to the configuration TOML file. Returns ------- - model: Model + model : Model """ path = Path(path) with open(path, "rb") as f: @@ -189,12 +207,12 @@ def plot(self, ax=None) -> Any: Parameters ---------- - ax: matplotlib.pyplot.Artist, optional - axes on which to draw the plot + ax : matplotlib.pyplot.Artist, optional + Axes on which to draw the plot. Returns ------- - ax: matplotlib.pyplot.Artist + ax : matplotlib.pyplot.Artist """ if ax is None: _, ax = plt.subplots() diff --git a/python/ribasim/ribasim/node.py b/python/ribasim/ribasim/node.py index a6d3b998c..73ef8ee1a 100644 --- a/python/ribasim/ribasim/node.py +++ b/python/ribasim/ribasim/node.py @@ -40,13 +40,8 @@ class Node(InputMixin, BaseModel): Parameters ---------- - static: geopandas.GeoDataFrame - - With columns: - - * type - * geometry - + static : geopandas.GeoDataFrame + Table with node ID, type and geometry. """ _input_type = "Node" @@ -72,8 +67,8 @@ def write(self, directory: FilePath, modelname: str) -> None: Parameters ---------- - directory: FilePath - modelname: str + directory : FilePath + modelname : str """ self.sort() directory = Path(directory) @@ -106,7 +101,7 @@ def plot(self, **kwargs) -> Any: Parameters ---------- - **kwargs: optional + **kwargs : optional Keyword arguments forwarded to GeoDataFrame.plot. Returns diff --git a/python/ribasim/ribasim/pump.py b/python/ribasim/ribasim/pump.py index a3ed85e2a..eac4db5ae 100644 --- a/python/ribasim/ribasim/pump.py +++ b/python/ribasim/ribasim/pump.py @@ -26,13 +26,8 @@ class Pump(InputMixin, BaseModel): Parameters ---------- - static: pd.DataFrame - - With columns: - - * node_id - * flow_rate - + static : pd.DataFrame + Table with constant flow rates. """ _input_type = "Pump" diff --git a/python/ribasim/ribasim/tabulated_rating_curve.py b/python/ribasim/ribasim/tabulated_rating_curve.py index 313dc52d5..688e69007 100644 --- a/python/ribasim/ribasim/tabulated_rating_curve.py +++ b/python/ribasim/ribasim/tabulated_rating_curve.py @@ -33,22 +33,10 @@ class TabulatedRatingCurve(InputMixin, BaseModel): Parameters ---------- - static: pd.DataFrame - - Tabulation with columns: - - * node_id - * level - * discharge - - time: pandas.DataFrame, optional - - Time varying rating curves with columns: - - * node_id - * time - * level - * discharge + static : pd.DataFrame + Table with constant rating curves. + time : pandas.DataFrame, optional + Table with time-varying rating curves. """ _input_type = "TabulatedRatingCurve" diff --git a/python/ribasim/ribasim/utils.py b/python/ribasim/ribasim/utils.py index 22a5b28f1..e1f6152d6 100644 --- a/python/ribasim/ribasim/utils.py +++ b/python/ribasim/ribasim/utils.py @@ -14,15 +14,15 @@ def geometry_from_connectivity( Parameters ---------- - node: Ribasim.Node - from_id: Sequence[int] + node : Ribasim.Node + from_id : Sequence[int] First node of every edge. - to_id: Sequence[int] + to_id : Sequence[int] Second node of every edge. Returns ------- - edge_geometry: np.ndarray + edge_geometry : np.ndarray Array of shapely LineStrings. """ geometry = node.static["geometry"] @@ -46,14 +46,14 @@ def connectivity_from_geometry( Parameters ---------- - node: Node - lines: np.ndarray + node : Node + lines : np.ndarray Array of shapely linestrings. Returns ------- - from_node_id: np.ndarray of int - to_node_id: np.ndarray of int + from_node_id : np.ndarray of int + to_node_id : np.ndarray of int """ node_index = node.static.index node_xy = shapely.get_coordinates(node.static.geometry.values)