Module contents

class OptiDamTool.Analysis[source]

Bases: object

Provide methods for analyzing simulation outputs and generating insights.

nondominated_solution_sorting(input_file: str, sorting_by: str, output_file: str) → DataFrame[source]

Sort non-dominated solutions produced by the OptiDamTool.SystemDesign class according to one of the available sorting methods: dam identifiers, Euclidean distance, or objective directions.

Parameters:

  • input_file (str) – Path to the input JSON file solutions_nondominated.json generated by OptiDamTool.SystemDesign.sediment_control_by_fixed_dams().

  • sorting_by (str) –

    Method used to sort the output DataFrame of non-dominated solutions.

    • dam_identifiers Sort the DataFrame by the d_<i> columns in ascending order.

    • metric_euclidean Sort the DataFrame by the column euclidean_metric(<ideal_solution>), which represents the Euclidean distance of normalized solutions to the ideal solution, in ascending order.

    • objective_directions Sort the DataFrame by the <obj>(<dir>) columns according to the specified objective directions (min for ascending and max for descending).

  • output_file (str) – Path to the JSON file where the sorted DataFrame will be saved.

Returns:

A sorted DataFrame.

Return type:

pandas.DataFrame

raster_features_retrieve(input_file: str, crs_code: int, output_file: str, target_driver: str = 'GTiff', scale: int | float = 1, offset: int | float = 0) → str[source]

Assign a default GTiff driver and a Coordinate Reference System (CRS) to the input raster generated from a WaTEM/SEDEM simulation using the default Idrisi raster format, which does not include CRS information. The function also applies a linear transformation to raster values \(x\) using the formula \(y = ax + b\), where \(a\) and \(b\) are the scale and offset input variables, respectively.

Parameters:

  • input_file (str) – Path to the input raster file.

  • crs_code (int) – EPSG code of the projected CRS to assign (e.g., 32638).

  • output_file (str) – Path to save the output raster file.

  • target_driver (str, optional) – GDAL-compatible name of the target driver. Default is ‘GTiff’.

  • scale (float, optional) – Scaling factor to apply to the raster values. Default is 1.

  • offset (float, optional) – Offset value to add to the scaled raster values. Default is 0.

Returns:

A message confirming that all geoprocessing steps are complete.

Return type:

str

sediment_delivery_to_stream_geojson(stream_file: str, sediment_file: str, geojson_file: str) → GeoDataFrame[source]

Generate a stream GeoJSON file containing detailed information for each segment, including sediment inflow values. The output GeoDataFrame includes all columns from the DataFrame produced by OptiDamTool.Analysis.sediment_delivery_to_stream_json(), along with two additional columns sed_ton and cumsed_ton, which represent sediment inflow to stream segments converted from kilograms to tons.

Parameters:
Returns:

A GeoDataFrame containing detailed information on stream segments.

Return type:

GeoDataFrame

sediment_delivery_to_stream_json(info_file: str, segsed_file: str, cumsed_file: str, json_file: str) → DataFrame[source]

Integrate sediment delivery data into stream segments using WaTEM/SEDEM outputs, with the extension Output per river segment = 1 enabled.

Parameters:

  • info_file (str) – Path to the input information TXT file stream_information.txt, produced by OptiDamTool.WatemSedem.dem_to_stream().

  • segsed_file (str) – Path to the input TXT file Total sediment segments.txt, generated by a WaTEM/SEDEM simulation. This file contains sediment inflow (in kilograms) to each stream segment from its own subbasin area.

  • cumsed_file (str) – Path to the input TXT file Cumulative sediment segments.txt, generated by a WaTEM/SEDEM simulation. This file contains sediment inflow (in kilograms) to each stream segment from all upstream segments.

  • json_file (str) – Path to the output JSON file to save the output DataFrame after integrating sediment delivery into stream segments.

Returns:

A DataFrame containing stream information with two additional columns. The sed_kg column represents the sediment delivery (in kilograms) to individual stream segments. The cumsed_kg column represents the cumulative sediment delivery (in kilograms), including contributions from all upstream segments.

Return type:

DataFrame

sediment_summary_dynamics_region(sediment_file: str, summary_file: str, output_file: str) → DataFrame[source]

Summarize total sediment values for the model region using outputs from a WaTEM/SEDEM simulation with the extension Only Routing = 0 disabled. The computed totals are used to derive insights on sediment dynamics across the region.

Parameters:

  • sediment_file (str) – Path to the input TXT file Total sediment.txt, generated by a WaTEM/SEDEM simulation.

  • summary_file (str) – Path to the input JSON file summary.json, produced by OptiDamTool.WatemSedem.dem_to_stream(). This file provides the total model region area in square meters.

  • output_file (str) – Path to the JSON file where the output DataFrame summarizing sediment dynamics will be saved.

Returns:

A DataFrame containing summary metrics on sediment dynamics for the model region.

Return type:

DataFrame

class OptiDamTool.Network[source]

Bases: object

Provide functionality to establish network-based connectivity and operations between dams.

connectivity_adjacent_downstream_dam(stream_file: str, dam_list: list[int], sort_dam: bool = False) → dict[int, int][source]

Generate adjacent downstream connectivity between dams based on the input stream network. Each dam is represented by a unique stream segment identifier.

Parameters:

  • stream_file (str) – Path to the input stream shapefile, generated by OptiDamTool.WatemSedem.dem_to_stream().

  • dam_list (list) – List of stream segment identifiers representing dam locations.

  • sort_dam (bool, optional) – If True, the dam identifiers in the output dictionary keys will be sorted in ascending order. Default is False.

Returns:

A dictionary with each key is a dam’s stream identifier, and the corresponding value is the stream identifier of the directly connected downstream dam. A value of -1 indicates that the dam has no downstream connectivity.

Return type:

dict

connectivity_adjacent_upstream_dam(stream_file: str, dam_list: list[int], sort_dam: bool = False) → dict[int, list[int]][source]

Compute adjacent upstream connectivity between dams based on the input stream network. Each dam is represented by a unique stream segment identifier.

Parameters:

  • stream_file (str) – Path to the input stream shapefile, generated by OptiDamTool.WatemSedem.dem_to_stream().

  • dam_list (list) – List of stream segment identifiers representing dam locations.

  • sort_dam (bool, optional) – If True, both the dam identifier keys and their corresponding value lists in the output dictionary will be sorted in ascending order. Default is False.

Returns:

A dictionary where each key is a dam’s stream identifier, and the corresponding value is a list of adjacent upstream dam identifiers. An empty list indicates no upstream connectivity.

Return type:

dict

controlled_drainage_area(stream_file: str, dam_list: list[int], sort_dam: bool = False) → dict[int, float][source]

Compute the controlled upstream drainage area for selected dams based on their locations within the input stream network. Each dam is represented by a unique stream segment identifier.

Parameters:

  • stream_file (str) – Path to the input stream shapefile, generated by OptiDamTool.WatemSedem.dem_to_stream().

  • info_file (str) – Path to the stream information text file stream_information.txt, generated by OptiDamTool.WatemSedem.dem_to_stream().

  • dam_list (list) – List of stream segment identifiers representing dam locations.

  • sort_dam (bool, optional) – If True, the dam identifiers in the output dictionary keys will be sorted in ascending order. Default is False.

Returns:

A dictionary where each key is a dam’s stream segment identifier, and the corresponding value is the effective upstream drainage area in square meters.

Return type:

dict

sediment_inflow_from_drainage_area(stream_file: str, dam_list: list[int], sort_dam: bool = False) → dict[int, float][source]

Compute the sediment inflows in kilograms for selected dams based on their local drainage areas within the input stream network. Each dam is identified by a unique stream segment identifier.

Parameters:

  • stream_file (str) – Path to the input stream GeoJSON file, generated by OptiDamTool.Analysis.sediment_delivery_to_stream_geojson().

  • dam_list (list) – List of stream segment identifiers representing dam locations.

  • sort_dam (bool, optional) – If True, the dam identifiers in the output dictionary keys will be sorted in ascending order. Default is False.

Returns:

A dictionary where each key is a dam’s stream segment identifier, and the corresponding value is the effective sediment inflow in kilograms.

Return type:

dict

stodym_plus(stream_file: str, storage_dict: dict[int, float], sediment_density: int | float, year_limit: int, trap_equation: bool = True, trap_threshold: int | float = 0.1, brown_d: int | float = 0.1, trap_constant: int | float | None = None, release_threshold: int | float = 0.95, config_validation: bool = True, folder_path: str | None = None) → dict[str, DataFrame][source]

Simulate the annual storage dynamics of a dam system influenced by sedimentation, and returns a dictionary containing dam lifespan, system-wide statistics, individual metrics, and simulation parameters.

The simulation runs for a user-defined number of years, unless all dams become inactive earlier. Sediment inflow to a dam is calculated as the sum of sediment yield from the dam’s controlled drainage area and the sediment outflow from upstream connected dams. The amount of sediment trapped by a dam is calculated as the product of the sediment inflow to the dam and its trap efficiency, which ranges from 0 to 1. At the end of each simulation year, dam storage capacities are updated using a mass balance approach based on the trapped sediment.

The simulation ends when either all individual dams become inactive or the entire dam system becomes inactive, whichever occurs first.

A dam is considered inactive if: - Its storage capacity becomes non-positive (<= 0). - Its sediment trap efficiency falls below or equals the threshold (<= trap_threshold).

The dam system is considered inactive if: - The maximum number of simulation years (year_limit) is reached. - The sediment release fraction of total stream input exceeds the threshold (> release_threshold).

Each dam in a system is uniquely identified by its stream segment identifier. When a dam becomes inactive, system connectivity, controlled drainage areas, and sediment inflows to the remaining dams are updated accordingly.

Warning

If a dam retains positive storage and the trap_threshold is not set appropriately, it may remain active indefinitely. Since trap efficiency is computed via OptiDamTool.Network.trap_efficiency_brown(), which depends on dam storage, using a very small threshold (e.g., 0.0001) may lead to unrealistic system behavior due to prolonged dam lifespan despite minimal sediment trapping. A recommended value is 0.1 based on Pal et al. (2018) and Pal and Galelli (2019). This value may be adjusted to suit user needs.

The simulation results are returned as a dictionary and can optionally be saved to the input directory as a set of JSON files. Each JSON file is named after the corresponding dictionary key and contains the related DataFrame.

A detailed description of the keys and their corresponding DataFrames is provided below.

  • dam_initial_storage: A DataFrame with the following columns:

    • dam_id: Stream segment identifier of the dam.

    • storage_m3: Initial storage capacity of the dam, in cubic meters.

    • storage_%: Initial storage of the dam as a percentage of the total storage across all dams.

    • cum_m3: Cumulative initial storage (up to this dam), in cubic meters, to give an idea of the total capacity.

  • dam_lifespan: A DataFrame with the following columns:

    • dam_id: Stream segment identifier of the dam.

    • life_year: Number of years the dam was active.

  • system_statistics: A DataFrame that stores system-wide statistics with the following columns:

    • start_year: Start of each simulation year, beginning from 1.

    • drainage_%: Percentage of the total controlled drainage area relative to the total stream drainage area, at the beginning of the simulation year.

    • storage_%: Percentage of total remaining storage across all dams relative to the initial total storage, at the beginning of the simulation year.

    • sedtrap_%: Percentage of total sediment trapped by all dams relative to the total sediment input across all stream segments, during the simulation year.

    • sedrelease_%: Percentage of sediment released by terminal dams and drainage areas not covered by the dam system, relative to the total sediment input across all stream segments, during the simulation year.

    • dam_removed: List of dams removed at the beginning of the year. An empty list implies all dams in the system remain active.

    • dam_active: List of active dams at the beginning of the year. An empty list in the final simulation year, if it occurs, indicates that all dams in the system became inactive before completing the user-defined number of simulation years.

    Note

    The sum of sediment trapping and release percentages for the dam system may not equal 100%. This is because these percentages are calculated relative to the total sediment input across all stream segments, using a fixed base value for consistency. In practice, the actual sediment inflow to the dams is greater than the total sediment input across all stream segments, due to additional contributions from sediment released by upstream dams. Furthermore, a dam’s sediment trapping efficiency depends on both its controlled drainage area and remaining storage capacity, making sediment dynamics within the system more complex. However, over time, the sum gradually converges to 100% as more dams become inactive, resulting in reduced sediment contributions from upstream dams.

  • dam_drainage_area: A DataFrame with columns start_year and dam identifiers. The cell values represent the annual controlled drainage area percentages for each dam, relative to the total stream drainage area at the beginning of the simulation year.

  • dam_remaining_storage: A DataFrame with columns start_year and dam identifiers. The cell values represent the annual remaining storage percentages, relative to each dam’s initial storage, at the beginning of the simulation year.

  • dam_trap_efficiency: A DataFrame with columns start_year and dam identifiers. The cell values represent the annual trap efficiency percentages at the beginning of the simulation year.

  • dam_trapped_sediment: A DataFrame with columns start_year and dam identifiers. The cell values represent the annual sediment trapping percentages, relative to the total sediment input across all stream segments, at the end of the simulation year.

    Note

    The values in dam_drainage_area, dam_remaining_storage, and dam_trap_efficiency are recorded at the beginning of each simulation year. This design ensures that the final state of each dam is captured just before its removal from the system, allowing users to understand the conditions that led to its inactivation.

Parameters:

  • stream_file (str) – Path to the input stream GeoJSON file, generated by OptiDamTool.Analysis.sediment_delivery_to_stream_geojson().

  • storage_dict (dict) – Dictionary mapping dam identifiers to initial storage capacities in cubic meters.

  • sediment_density (float) – Density of sediment in kilograms per cubic meter.

  • year_limit (int) – Maximum number of simulation years. Simulation stops earlier if all dams retire.

  • trap_equation (bool, optional) – If True (default), trap efficiency is calculated using the Brown (1943) formula. Further details can be found in Verstraeten and Poesen (2000).

  • trap_threshold (float, optional) – Minimum trap efficiency required to keep a dam active (default 0.1). Dams with efficiency below this value are treated as inactive.

  • brown_d (float, optional) –

    Empirical parameter used in the trap efficiency equation. It ranges from 0.046 to 1, with a mean value of 0.1, which is also the default. Refer to Verstraeten and Poesen (2000).

  • trap_constant (float, optional) – Fixed trap efficiency value applied when trap_equation=False. Must be greater than trap_threshold and less than 1. Default is None.

  • release_threshold (float, optional) – Maximum sediment release fraction threshold of the total stream sediment input to stop the simulation. The default is 0.95, meaning 95% of the total stream sediment input is leaving the study area. If the user does not want to consider this parameter in the simulation, set its value to 1.0.

  • config_validation (bool, optional) – If True (default), validates the configuration of input parameters. Users are advised not to modify this parameter. This option is provided to speed up computations in the OptiDamTool.SystemDesign class, where configuration checking is not required for every scenario generated by genetic algorithms.

  • folder_path (str, optional) – Path to the folder where JSON files will be saved. If None (default), no files are saved.

Returns:

A dictionary containing detailed information on dam lifespan, system-wide statistics, individual metrics, and simulation parameters.

Return type:

dict

stodym_plus_drainage_response(stream_file: str, flwdir_file: str, storage_dict: dict[int, float], sediment_density: int | float, year_limit: int, folder_path: str, trap_equation: bool = True, trap_threshold: int | float = 0.1, brown_d: int | float = 0.1, trap_constant: int | float | None = None, release_threshold: int | float = 0.95) → DataFrame[source]

Simulate the detailed annual storage dynamics of a dam system and saves the output to the specified input directory. Refer to OptiDamTool.Network.stodym_plus() for full implementation details.

Based on the output DataFrame system_statistics, which contains a start_year column (starting from 1), this method generates GeoDataFrames for dam location points and their controlled drainage polygons. These are saved as:

  • year_<start_year>_dam_location_point.geojson

  • year_<start_year>_dam_drainage_polygon.geojson

Files are created for each year where a dam becomes inactive, along with two additional GeoJSON files for start_year = 0, representing the initial condition.

Refer to OptiDamTool.WatemSedem.dam_controlled_drainage_polygons() for more details on GeoDataFrame generation.

In addition, a file all_potential_dam_location.geojson is created, which contains potential dam locations. Each point corresponds to a unique stream segment.

All GeoJSON files include the ws_id field to support cross-referencing with the stream network. The year_{start_year}_dam_drainage_polygon.geojson files also contain an area_% column, which represents the percentage of the total stream drainage area controlled by each dam.

Parameters:

  • stream_file (str) – Path to the input stream GeoJSON file, generated by OptiDamTool.Analysis.sediment_delivery_to_stream_geojson().

  • flwdir_file (str) – Path to the input flow direction raster file flowdir.tif, generated by OptiDamTool.WatemSedem.dem_to_stream().

  • storage_dict (dict) – Dictionary mapping dam identifiers to initial storage capacities in cubic meters.

  • sediment_density (float) – Density of sediment in kilograms per cubic meter.

  • year_limit (int) – Maximum number of simulation years. Simulation stops earlier if all dams retire.

  • folder_path (str) – Path to the folder where JSON and GeoJSON files will be saved.

  • trap_equation (bool, optional) –

    If True (default), trap efficiency is calculated using the Brown (1943) formula. Further details can be found in Verstraeten and Poesen (2000).

  • trap_threshold (float, optional) – Minimum trap efficiency required to keep a dam active (default 0.1). Dams with efficiency below this value are treated as inactive.

  • brown_d (float, optional) –

    Empirical parameter used in the trap efficiency equation. It ranges from 0.046 to 1, with a mean value of 0.1, which is also the default. Refer to Verstraeten and Poesen (2000).

  • trap_constant (float, optional) – Fixed trap efficiency value applied when trap_equation=False. Must be greater than trap_threshold and less than 1. Default is None.

  • release_threshold (float, optional) – Minimum sediment release fraction threshold of the total stream sediment input to stop the simulation. The default is 0.95, meaning 95% of the total stream sediment input is leaving the study area. If the user does not want to consider this parameter in the simulation, set its value to 1.0.

Returns:

A DataFrame with columns start_year, dam_removed, and dam_active. The start_year starts from 0 and helps trace the creation of corresponding GeoJSON files.

Return type:

DataFrame

trap_efficiency_brown(storage_dict: dict[int, float], area_dict: dict[int, float], brown_d: int | float = 0.1) → dict[int, float][source]

Compute the Trap Efficiency (TE) without percentage conversion of a dam using the Brown (1943) formula. Further details can be found in Verstraeten and Poesen (2000).

Parameters:

  • storage_dict (dict) – A dictionary where each key is a dam identifier, and the corresponding value is the dam’s storage capacity in cubic meters.

  • area_dict (dict) – A dictionary where each key is a dam identifier, and the corresponding value is the dam’s catchment area in square meters. The function internally converts the area from square meters to square kilometers.

  • brown_d (float, optional) – Empirical parameter used in the equation. It ranges from 0.046 to 1, with a mean value of 0.1, which is also the default.

Returns:

A dictionary where each key is a dam identifier, and the corresponding value is the computed TE.

Return type:

dict

upstream_metrics_summary(stream_file: str, dam_list: list[int], sort_dam: bool = False) → dict[str, dict[int, Any]][source]

Compute a summary of upstream metrics for selected dams based on their locations within the input stream network. Each dam is identified by a unique stream segment identifier.

The function returns a dictionary containing three sub-dictionaries, where each key corresponds to a dam’s stream identifier:

  • adjacent_upstream_dams: A dictionary where each value is a list of directly connected upstream dam identifiers. An empty list indicates no upstream connectivity.

  • controlled_drainage_m2: A dictionary mapping each dam to its effective upstream drainage area in square meters, based on upstream dam connections.

  • sediment_inflow_kg: A dictionary mapping each dam to its effective sediment inflow in kilograms, based on upstream dam connections.

Parameters:

  • stream_file (str) – Path to the input stream GeoJSON file, generated by OptiDamTool.Analysis.sediment_delivery_to_stream_geojson().

  • dam_list (list) – List of stream segment identifiers representing dam locations.

  • sort_dam (bool, optional) – If True, the dam identifiers in three sub-dictionaries keys will be sorted in ascending order. Default is False.

Returns:

A dictionary with three keys: adjacent_upstream_connections, controlled_drainage_m2, and sediment_inflow_kg. Each key maps to a sub-dictionary where the keys are dam segment identifiers and the values are the computed metrics.

Return type:

dict

class OptiDamTool.SystemDesign[source]

Bases: object

Provide functionality to optimize dam systems by evolutionary computing framework platypus-opt.

compute_curve_mean_deviation(df: DataFrame) → float[source]

Compute a scalar metric representing the maximum deviation of annual remaining storage percentage curves of dams from their mean curve.

The method processes the input DataFrame as follows:

  • Selects columns containing the remaining storage percentages of dams.

  • Replaces NaN and negative values with 0.

  • Normalizes percentages to the [0, 1] range by dividing by 100.

  • Computes the mean curve across all dams.

  • Calculates Euclidean distances between each normalized curve and the mean curve.

  • Returns the maximum of these normalized Euclidean distances.

Parameters:

df (DataFrame) – DataFrame corresponding to the dam_remaining_storage key from the output dictionary generated by OptiDamTool.Network.stodym_plus().

Returns:

Maximum normalized Euclidean distance between annual remaining storage percentage curves of dams and their mean curve. A smaller value indicates that dams follow more similar patterns relative to the mean remaining storage dynamics.

Return type:

float

compute_curve_pairwise_deviation(df: DataFrame) → float[source]

Compute a scalar metric representing the pairwise variability among annual remaining storage percentage curves of dams.

The method processes the input DataFrame as follows:

  • Selects the columns containing remaining storage percentages of dams.

  • Replaces NaN and negative values with 0.

  • Normalizes percentages to the [0, 1] range by dividing by 100.

  • Computes pairwise Euclidean distances between the normalized curves.

  • Returns the standard deviation of these pairwise distances.

Parameters:

df (DataFrame) – DataFrame corresponding to the dam_remaining_storage key from the output dictionary generated by OptiDamTool.Network.stodym_plus().

Returns:

Standard deviation of the normalized pairwise Euclidean distances between dam storage curves. A smaller value indicates that dams follow more similar patterns in their remaining storage dynamics.

Return type:

float

property mapping_constraint_operator: dict[str, str]

Provide a dictionary mapping optimization constraints to their corresponding operators. Each constraint is listed with its operator and an explanatory remark.

  • lb_lifespan

    • Operator: >=

    • Remark: Lower bound on dam lifespan, ensuring that each dam remains operates for at least the minimum required number of years.

  • ub_storage_sum

    • Operator: <=

    • Remark: Upper bound on the total storage volume across all dams, used to prevent unrealistic designs with excessively large reservoirs or prohibitively high deployment costs.

property mapping_objective_direction: dict[str, str]

Provide a dictionary mapping optimization objectives to their respective directions. Each objective is listed with its direction and an explanatory remark justifying the choice.

  • lifespan

    • Direction: Maximize

    • Remark: Extend the functional lifespan of dams. The objective is computed as the summation of logarithms of lifespans, with \(10^{-6}\) as a lower bound to avoid undefined behavior from computing \(\log(0)\). This ensures that dams with zero lifespans are penalized appropriately.

  • lifespan_std

    • Direction: Minimize

    • Remark: Reduce variability in dam lifespans so benefits are distributed more evenly across all dams. The objective is computed as the standard deviation of lifespans.

  • sediment_trapped_initial

    • Direction: Maximize

    • Remark: Retain more sediment within the watershed during the initial year, when trapping is most effective. This supports dam performance early in the system’s lifespan, before sedimentation reduces trapping capacity.

  • sediment_released_median

    • Direction: Minimize

    • Remark: Reduce the average sediment release from the median lifetime of the dam system onward to capture long-term effectiveness. For example, if the system has a 10–11 year lifespan, the average sediment release from year 6 to the end of operation is used as the metric.

  • storage_sum

    • Direction: Minimize

    • Remark: Promote cost-efficient deployment by reducing the total storage volume of the dam system.

  • curve_pairwise_deviation
  • curve_mean_deviation
scenario_stodym_plus(solution_file: str, count: int, stream_file: str, stodym_config: dict[str, Any]) → dict[str, DataFrame][source]

Retrieve detailed simulation outputs from OptiDamTool.Network.stodym_plus() for a specific solution scenario obtained via OptiDamTool.SystemDesign.sediment_control_by_fixed_dams().

Parameters:
Returns:

Dictionary produced by OptiDamTool.Network.stodym_plus(), containing detailed simulation results for the selected solution scenario.

Return type:

dict

scenario_stodym_plus_drainage_response(solution_file: str, count: int, stream_file: str, flwdir_file: str, folder_path: str, stodym_config: dict[str, Any]) → DataFrame[source]

Retrieve detailed simulation outputs from OptiDamTool.Network.stodym_plus_drainage_response() for a specific solution scenario obtained via OptiDamTool.SystemDesign.sediment_control_by_fixed_dams().

Parameters:
Returns:

Dataframe produced by OptiDamTool.Network.stodym_plus_drainage_response(), containing detailed information on the generated GeoJSON files.

Return type:

DataFrame

sediment_control_by_fixed_dams(dam_number: int, storage_bounds: tuple[int, int], storage_multiplier: int | float, stream_file: str, stodym_config: dict[str, Any], objectives: list[str], algorithm_name: str, algorithm_config: dict[str, Any], seeds: int, nfe: int, folder_path: str, constraints: dict[str, float] = {'lb_lifespan': 0}, processes: int | None = None) → DataFrame[source]

Optimize dam locations and storage volumes using a multi-objective evolutionary algorithm, based on annual sediment inflow to watershed drainage pathways.

This function uses built-in evolutionary algorithms from the platypus-opt Python package. Users can perform multiple experiments for the same problem, with each run starting from a different initial population.

The function returns a dictionary with two keys, where each value is a DataFrame. The DataFrames are also saved to the input directory as JSON files, with filenames corresponding to the dictionary keys.

  • solutions_nondominated

    DataFrame of non-dominated solutions extracted from merged feasible solutions across multiple experiments. Columns include:

    • count

      Sequential index (starting from 0) for solution numbering.

    • d_<i>

      Stream identifiers for dams (<i> ranges from 1 to dam_number).

    • sv_<i>

      Initial storage volume of dams in cubic meters (<i> ranges from 1 to dam_number).

    • ls_<i>

      Lifespan of dams in years (<i> ranges from 1 to dam_number).

    • <obj>(<dir>)

      Objective values, where <obj> is the objective name from the list of input objectives and <dir> is its direction (min or max).

    • <constr><op><val>

      Constraint values, where <constr> is the constraint name from the dictionary of input constraints, <op> is the operator, and <val> is the bound.

    • obj_normalize

      List of normalized objective values, computed as (obj_val - obj_lb) / (obj_ub - obj_lb), where obj_val is the objective value, and obj_lb and obj_ub are the lower and upper bounds of the objectives.

    • metric_euclidean(<solution_ideal>)

      Euclidean distance of normalized solutions to the ideal solution list <solution_ideal>.

  • computation_statistics

    DataFrame with two columns, feature and value. The feature column includes:

    • total_execution_time (s): Total execution time in seconds.

    • total_execution_timedelta: Total execution time in datetime.timedelta string format (HH:MM:SS).

    • CPU_number: Number of CPU cores used for computation (either processes or os.cpu_count()).

    • experiment_number: Number of experiments specified by the user.

    • batch_run_number: Number of batch runs across CPUs, defined as the ceiling division of the experiment number by the CPU count.

    • experiment_time (s): Total experiment time in seconds.

    • experiment_timedelta: Total experiment time in datetime.timedelta string format (HH:MM:SS).

    • average_experiment_time (s): Average execution time per experiment in seconds.

    • average_experiment_timedelta: Average execution time per experiment in datetime.timedelta string format (HH:MM:SS).

    • total_function_evaluations: Total function evaluations, calculated as the product of the number of experiments and the function evaluations per experiment, both specified by the user.

    • total_nondominated_solutions: Number of solutions in the solutions_nondominated DataFrame.

Parameters:

  • dam_number (int) – Number of dams to deploy in the watershed area.

  • storage_bounds (tuple[int, int]) – Tuple of two integers specifying the lower and upper bounds of storage volumes. Both values must be greater than 0.

  • storage_multiplier (float) – Multiplier applied to the values within the storage bounds to obtain the actual storage volumes in cubic meters. For example, if storage_bounds = (1, 5) and storage_multiplier = 1000, the resulting storage volumes for the dams will be [1000, 2000, 3000, 4000, 5000].

  • stream_file (str) – Path to the input stream GeoJSON file, generated by OptiDamTool.Analysis.sediment_delivery_to_stream_geojson().

  • stodym_config (dict) –

    Dictionary specifying input variable configurations for OptiDamTool.Network.stodym_plus(). Each key corresponds to the name of an input variable, and the value is the parameter supplied to the method.

    • Required keys: sediment_density and year_limit.

    • Optional keys: trap_equation, trap_threshold, brown_d, trap_constant, and release_threshold.

    Example

    # for dynamic sediment trapping efficiency of dams
stodym_config = {
    'sediment_density': 1300,
    'year_limit': 100,
    'trap_threshold': 0.05,
    'brown_d': 1,
    'release_threshold': 0.9
}

# for constant sediment trapping efficiency of dams
stodym_config = {
    'sediment_density': 1300,
    'year_limit': 100,
    'trap_equation': False,
    'trap_constant': 0.8,
    'release_threshold': 0.9
}

  • objectives (list) – List of valid objective names, which can be obtained from the keys of the output dictionary defined in the attribute OptiDamTool.SystemDesign.mapping_objective_direction.

  • algorithm_name (str) –

    Name of the evolutionary algorithm to use. Supported options:

    • PESA2: Pareto Envelope-based Selection Algorithm that divides the objective space into regions and maintains diversity by regulating density across those regions.

    • SPEA2: Strength Pareto Evolutionary Algorithm that assigns fitness based on dominance strength and incorporates density estimation for better selection pressure.

    • IBEA: Indicator-Based Evolutionary Algorithm that uses a Hypervolume indicator to guide the search toward well-distributed Pareto-optimal solutions.

    • MOEAD: Multi-Objective Evolutionary Algorithm with Decomposition, which transforms a multi-objective problem into multiple scalar subproblems and solves them cooperatively.

    • NSGAII: Classic Non-dominated Sorting Genetic Algorithm (NSGA-II) that ensures convergence toward the Pareto front while maintaining diversity using crowding distance.

    • NSGAIII: Extension of NSGA-II designed for many-objective problems, using a set of reference directions to maintain diversity across high-dimensional objective spaces.

    • EpsMOEA: ε-dominance Multi-Objective Evolutionary Algorithm that employs an ε-box archive to control archive size and promote solution diversity.

    • EpsNSGAII: Variant of NSGA-II that integrates ε-dominance into selection to maintain a bounded, diverse set of non-dominated solutions.

    Note

    • MOEAD and NSGAIII are particularly suited for many-objective optimization problems (more than three objectives). For problems with fewer objectives, EpsNSGAII is widely adopted.

    • The mapping of required keys to algorithms is as follows:

    {
    'population_size': ['EpsNSGAII', 'EpsMOEA', 'IBEA', 'MOEAD', 'NSGAII', 'PESA2', 'SPEA2'],
    'epsilons': ['EpsMOEA', 'EpsNSGAII'],
    'divisions_outer': ['NSGAIII']
}

    • The required key epsilons must be set between 0 and 1, consistent with the assumption that all objective values are normalized to the [0, 1] range.

    • For NSGAIII, the required key divisions_outer determines the number of reference directions and implicitly controls the population size. The population size is calculated as the combination C(O + D - 1, D), where O is the number of objectives and D is divisions_outer.

  • algorithm_config (dict) –

    Dictionary of algorithm parameters. Must include population_size along with other valid keyword arguments supported by the chosen algorithm.

    Example

    algorithm_config={
    'population_size': 10
}

  • seeds (int) – Number of independent experiments for the same problem, with each run starting from a different initial population.

  • nfe (int) – Maximum number of function evaluations per experiment. This parameter controls how many generations the algorithm will execute. For example, if nfe is set to 1000 and the population size is 100, the algorithm will run for at least 1000 // 100 = 10 generations. For best results, nfe should be a positive integer multiple of the population size,ensuring a more consistent and effective optimization process.

  • folder_path (str) – Path to the folder where the JSON files will be saved.

  • constraints (dict, optional) –

    Dictionary containing valid constraint names as keys and their corresponding values. The valid names can be obtained from the keys of the output dictionary defined in the attribute OptiDamTool.SystemDesign.mapping_constraint_operator. The default value is {'lb_lifespan': 0}, which is used to run the algorithm but has no effect on the optimization.

    Example

    constraints={
    'lb_lifespan': 1
}

  • processes (int, optional) – Number of logical CPUs to use for running seeds in parallel. Defaults to all available CPUs.

Returns:

Dictionary with two keys:

  • solutions_nondominated: DataFrame of non-dominated solutions.

  • computation_statistics: DataFrame of computation statistics.

Return type:

dict

class OptiDamTool.Visual[source]

Bases: object

Provides utilities for visualizing data.

dam_individual_features(json_file: str, figure_file: str, fig_width: int | float = 10, fig_height: int | float = 5, fig_title: str = '', colormap_name: str = 'coolwarm', dam_linewidth: int | float = 2, xaxis_lim: int | None = None, yaxis_lim: int | None = None, xtick_gap: int = 10, ytick_gap: int | float = 10, ytop_offset: int | float = 0, ybottom_offset: int | float = 0, legend_cols: int = 1, legend_fontsize: int = 12, tick_fontsize: int = 12, axis_fontsize: int = 15, title_fontsize: int = 15, gui_window: bool = True) → Figure[source]

Generate a figure illustrating the annual variability of key features for each dam in the system. The input data are produced by the methods OptiDamTool.Network.stodym_plus() and OptiDamTool.Network.stodym_plus_with_drainage_scenarios().

  • dam_drainage_area.json

    Percentage of the controlled drainage area for each dam, relative to the total stream drainage area, evaluated at the start of the simulation year.

  • dam_remaining_storage.json

    Remaining storage capacity as a percentage of the dam’s initial storage, evaluated at the start of the simulation year.

  • dam_trap_efficiency.json

    Trap efficiency expressed as a percentage, evaluated at the start of the simulation year.

  • dam_trapped_sediment.json

    Percentage of sediment trapped by the dam, relative to the total sediment input across all stream segments, evaluated at the end of the simulation year.

Parameters:

  • json_file (str) – Path to the JSON file containing the dam feature data.

  • figure_file (str) – Path to the output figure file.

  • fig_width (float, optional) – Width of the figure in inches. Default is 10.

  • fig_height (float, optional) – Height of the figure in inches. Default is 5.

  • fig_title (str, optional) – Title of the figure. Default is an empty string.

  • colormap_name (str, optional) – Name of the colormap used to generate colors for individual dams. Default is ‘coolwarm’.

  • dam_linewidth (float, optional) – Line width for plotting the storage variation of individual dams. Default is 2.

  • xaxis_lim (int, optional) – Upper limit of the x-axis. Default is None.

  • yaxis_lim (int, optional) – Upper limit of the x-axis. Default is None.

  • xtick_gap (int, optional) – Gap between two x-axis ticks. Default is 10.

  • ytick_gap (float, optional) – Gap between two y-axis ticks. Default is 10.

  • ytop_offset (float, optional) – Positive offset to increase the upper y-axis limit above 100, improving visibility when plot values are close to 100. Default is 0.

  • ybottom_offset (float, optional) – Negative offset to decrease the lower y-axis limit below 0, improving visibility when plot values are close to 0. Default is 0.

  • legend_cols (int, optional) – Number of columns to arrange legend items. Default is 1.

  • legend_fontsize (int, optional) – Font size of the legend. Default is 12.

  • tick_fontsize (int, optional) – Font size of the tick labels on both axes. Default is 12.

  • axis_fontsize (int, optional) – Font size of the axis labels. Default is 15.

  • title_fontsize (int, optional) – Font size of the figure title. Default is 15.

  • gui_window (bool, optional) – If True (default), open a graphical user interface window of the plot.

Returns:

A Figure object containing the annual sediment trapping percentage by each dam in the system.

Return type:

Figure

dam_location_in_stream(stream_file: str, dam_file: str, figure_file: str, fig_width: int | float = 6, fig_height: int | float = 6, fig_title: str = 'Dam locations with stream identifiers', stream_linewidth: int | float = 1, dam_marker: str = 'o', dam_markersize: int = 50, plot_damid: bool = True, damid_fontsize: int = 9, title_fontsize: int = 15, gui_window: bool = True) → Figure[source]

Generates a figure showing dam locations along the stream path, with an option to display the stream segment identifiers for each dam.

Parameters:

  • stream_file (str) –

    Path to the input stream vector file, created by one of:

  • dam_file (str) – Path to the input dam location vector file year_<start_year>_dam_location_point.geojson, created by OptiDamTool.Network.stodym_plus_with_drainage_scenarios().

  • figure_file (str) – Path to the output figure file.

  • fig_width (float, optional) – Width of the figure in inches. Default is 6.

  • fig_height (float, optional) – Height of the figure in inches. Default is 6.

  • fig_title (str, optional) – Title of the figure. Default is ‘Dam locations with identifiers’.

  • stream_linewidth (float, optional) – Line width for plotting the stream. Default is 1.

  • dam_marker (str, optional) – Marker style for dam points. Default is ‘o’.

  • dam_markersize (int, optional) – Marker size for dam points. Default is 50.

  • plot_damid (bool, optional) – If True (default), plot stream segment identifiers for dams.

  • damid_fontsize (int, optional) – Font size for stream segment identifier labels. Default is 9.

  • title_fontsize (int, optional) – Font size of the figure title. Default is 15.

  • gui_window (bool, optional) – If True (default), open a graphical user interface window for the plot.

Returns:

A Figure object containing the dam locations plotted on the stream path.

Return type:

Figure

objectives_parallel_coordinate(json_file: str, objs_rename: dict[str, str], figure_file: str, benchmark_solution: list[float] | None = None, benchmark_color: str = 'k', benchmark_linewidth: int | float = 3, select_solution: list[float] | None = None, select_color: str = 'red', select_linewidth: int | float = 3, fig_width: int | float = 10, fig_height: int | float = 5, fig_title: str = 'Parallel coordinate plot', colormap_name: str = 'Spectral', xtick_rotation: int = 0, tick_fontsize: int = 10, axis_fontsize: int = 12, title_fontsize: int = 15, gui_window: bool = True) → Figure[source]

Generate a parallel coordinate plot for Pareto front solutions. Optionally, benchmark and selected solutions can also be highlighted in the figure.

Parameters:

  • json_file (str) – Path to the JSON file containing Pareto front solutions generated by OptiDamTool.SystemDesign.sediment_control_by_fixed_dams().

  • objs_rename (dict) – Dictionary mapping objective names obtained from OptiDamTool.SystemDesign.mapping_objective_direction() to the labels displayed in the output figure. All keys must be present in the JSON file. Values may be identical to the keys if no renaming is required.

  • figure_file (str) – Path to the output figure file.

  • benchmark_solution (list, optional) – Benchmark solution values to display in the parallel coordinate plot. Default is None.

  • benchmark_color (str, optional) – Line color for the benchmark solution. Default is black.

  • benchmark_linewidth (float, optional) – Line width for the benchmark solution. Default is 3.

  • select_solution (list, optional) – Selected solution values to display in the parallel coordinate plot. Default is None.

  • select_color (str, optional) – Line color for the selected solution. Default is red.

  • select_linewidth (float, optional) – Line width for the selected solution. Default is 3.

  • fig_width (float, optional) – Width of the figure in inches. Default is 10.

  • fig_height (float, optional) – Height of the figure in inches. Default is 5.

  • fig_title (str, optional) – Title of the figure. Default is ‘Parallel coordinate plot’.

  • colormap_name (str, optional) –

    Name of the colormap used to plot Pareto front solutions. Default is ‘Spectral’.

  • tick_fontsize (int, optional) – Font size of the tick labels on both axes. Default is 10.

  • axis_fontsize (int, optional) – Font size of the axis labels. Default is 12.

  • title_fontsize (int, optional) – Font size of the figure title. Default is 15.

  • gui_window (bool, optional) – If True (default), open a graphical user interface window of the plot.

Returns:

A Figure object containing the parallel coordinate plot of the Pareto front solutions.

Return type:

Figure

objectives_tradeoff_2D(json_file: str, objs_rename: dict[str, str], figure_file: str, fig_rows: int, fig_cols: int, fig_width: int | float = 15, fig_height: int | float = 8, fig_title: str = 'Two-dimensional trade-off', tick_fontsize: int = 10, axis_fontsize: int = 12, title_fontsize: int = 15, gui_window: bool = True) → Figure[source]

Generate two-dimensional projections of Pareto front solutions for all combinations of the selected objectives. Additionally, print a dictionary whose keys are tuples of objective names and whose values contain information on the number of non-dominated solutions, along with their lower and upper bounds.

Parameters:

  • json_file (str) – Path to the JSON file containing Pareto front solutions generated by OptiDamTool.SystemDesign.sediment_control_by_fixed_dams().

  • objs_rename (dict) – Dictionary mapping objective names obtained from OptiDamTool.SystemDesign.mapping_objective_direction() to the labels displayed in the output figure. All keys must be present in the JSON file. Values may be identical to the keys if no renaming is required.

  • figure_file (str) – Path to the output figure file.

  • fig_rows (int) – Number of rows in the output plot.

  • fig_cols (int) – Number of columns in the output plot.

  • fig_width (float, optional) – Width of the figure in inches. Default is 15.

  • fig_height (float, optional) – Height of the figure in inches. Default is 8.

  • fig_title (str, optional) – Title of the figure. Default is ‘Two-dimensional trade-off’.

  • tick_fontsize (int, optional) – Font size of the tick labels on both axes. Default is 10.

  • axis_fontsize (int, optional) – Font size of the axis labels. Default is 12.

  • title_fontsize (int, optional) – Font size of the figure title. Default is 15.

  • gui_window (bool, optional) – If True (default), open a graphical user interface window of the plot.

Returns:

A Figure containing two-dimensional projections of the Pareto front solutions for all combinations of the selected objectives.

Return type:

Figure

sediment_inflow_to_stream(stream_file: str, figure_file: str, fig_width: int | float = 10, fig_height: int | float = 5, sed_title: str = 'Sediment inflow (%)', cumsed_title: str = 'Cumulative sediment inflow (%)', stream_linewidth: int | float = 1, sed_colormap: str = 'tab20', cumsed_colormap: str = 'Accent', sed_tickgap: int | float = 1, cumsed_tickgap: int = 20, tick_fontsize: int = 12, title_fontsize: int = 12, gui_window: bool = True) → Figure[source]

Generates a figure with two horizontally arranged plots:

  • Sediment inflow percentage to individual stream segments.

  • Cumulative sediment inflow percentage to each stream segment, including all upstream connected segments.

Both plots are normalized by the total sediment input across all stream segments.

Parameters:

  • stream_file (str) – Path to the input stream vector file, created by OptiDamTool.Analysis.sediment_delivery_to_stream_geojson()

  • figure_file (str) – Path to the output figure file.

  • fig_width (float, optional) – Width of the figure in inches. Default is 10.

  • fig_height (float, optional) – Height of the figure in inches. Default is 5.

  • sed_title (str, optional) – Title of the suplot for sediment inflow percentage. Default is ‘Sediment inflow (%)’.

  • cumsed_title (str, optional) – Title of the suplot for cumulative sediment inflow percentage. Default is ‘Cumulative sediment inflow (%)’.

  • stream_linewidth (float, optional) – Line width for plotting the stream. Default is 1.

  • sed_colormap (str, optional) –

    Name of the colormap used to generate colors for sediment percentage. Default is ‘tab20’.

  • sumsed_colormap (str, optional) – Name of the colormap used to generate colors for cumulative sediment percentage. Default is ‘winter’.

  • sed_tickgap (float, optional) – Gap between two y-axis ticks on the sediment inflow percentage colorbar. Default is 1.

  • cumsed_tickgap (int, optional) – Gap between two y-axis ticks on cumulative sediment inflow percentage colorbar. Default is 20.

  • tick_fontsize (int, optional) – Font size of the y-axis tick labels on both colorbars. Default is 12.

  • title_fontsize (int, optional) – Font size of the subplot titles. Default is 12.

  • gui_window (bool, optional) – If True (default), open a graphical user interface window for the plot.

Returns:

A Figure object containing plots of sediment inflow to the stream path.

Return type:

Figure

system_statistics(json_file: str, figure_file: str, fig_width: int | float = 10, fig_height: int | float = 5, fig_title: str = 'Dam system statistics', plot_storage: bool = True, plot_trap: bool = True, plot_release: bool = True, plot_drainage: bool = True, system_linewidth: int | float = 3, xaxis_lim: int | None = None, xtick_gap: int = 10, ytop_offset: int | float = 0, ybottom_offset: int | float = 0, legend_loc: str = 'best', legend_fontsize: int = 12, tick_fontsize: int = 12, axis_fontsize: int = 15, title_fontsize: int = 15, gui_window: bool = True) → Figure[source]

Generates a figure summarizing dam system statistics with annual percent changes for key metrics:

  • Total remaining storage across all dams, relative to the initial total storage at the start of each simulation year.

  • Total sediment trapped by all dams, relative to the total sediment input across all stream segments during the simulation year.

  • Sediment released by terminal dams and by drainage areas not covered by the dam system, relative to the total sediment input across all stream segments during the simulation year.

  • Total controlled drainage area across all dams, relative to the total stream drainage area at the start of each simulation year.

Parameters:

  • json_file (str) –

    Path to the input system_statistics.json file, created by one of the methods:

  • figure_file (str) – Path to the output figure file.

  • fig_width (float, optional) – Width of the figure in inches. Default is 10.

  • fig_height (float, optional) – Height of the figure in inches. Default is 5.

  • fig_title (str, optional) – Title of the figure. Default is ‘Dam system statistics’.

  • plot_storage (bool, optional) – If True (default), include the annual percent change in total remaining storage across all dams.

  • plot_trap (bool, optional) – If True (default), include the annual percent change in total sediment trapped by all dams.

  • plot_release (bool, optional) – If True (default), include the annual percent change in sediment released by terminal dams and by drainage areas not covered by the dam system.

  • plot_drainage (bool, optional) – If True (default), include the annual percent change in total controlled drainage area across all dams.

  • system_linewidth (float, optional) – Line width for plotting the system statistics. Default is 3.

  • xaxis_lim (int, optional) – Upper limit of the x-axis. Default is None.

  • xtick_gap (int, optional) – Gap between two x-axis ticks. Default is 10.

  • ytop_offset (float, optional) – Positive offset to increase the upper y-axis limit above 100, improving visibility when plot values are close to 100. Default is 0.

  • ybottom_offset (float, optional) – Negative offset to decrease the lower y-axis limit below 0, improving visibility when plot values are close to 0. Default is 0.

  • legend_loc (str, optional) – Location of the legend in the figure. Default is ‘best’.

  • legend_fontsize (int, optional) – Font size of the legend. Default is 12.

  • tick_fontsize (int, optional) – Font size of the tick labels on both axes. Default is 12.

  • axis_fontsize (int, optional) – Font size of the axis labels. Default is 15.

  • title_fontsize (int, optional) – Font size of the figure title. Default is 15.

  • gui_window (bool, optional) – If True (default), open a graphical user interface window of the plot.

Returns:

A Figure object containing the dam system statistics plots.

Note

Users can choose to plot all four metrics or only a subset of them by setting the corresponding boolean parameters to False.

Return type:

Figure

class OptiDamTool.WatemSedem[source]

Bases: object

Provides functionality to prepare the necessary inputs for simulating the WaTEM/SEDEM model.

dam_controlled_drainage_polygons(flwdir_file: str, location_file: str, dam_list: list[int], folder_path: str) → dict[str, GeoDataFrame][source]

Generates GeoJSON files of the selected dam locations and their corresponding effective upstream drainage area polygons, saved to the specified output directory. The output GeoJSON files include a common column, ws_id, for cross-referencing dam locations.

  • dam_location_point.geojson: Point shapefile of the selected dam locations.

  • dam_drainage_polygon.geojson: Polygon shapefile of the effective upstream drainage areas for the selected dams, with an area_m2 column representing the drainage area in square meters.

Parameters:

  • flwdir_file (str) – Path to the input flow direction raster file flowdir.tif, generated by OptiDamTool.WatemSedem.dem_to_stream().

  • location_file (str) – Path to the input point shapefile subbasin_drainage_points.shp containing all dam locations, generated by OptiDamTool.WatemSedem.dem_to_stream().

  • dam_list (list) – List of identifiers representing the selected dam locations.

  • folder_path (str) – Path to the directory where all output files will be saved.

Returns:

A dictionary with two keys: dam_location_point, a Point GeoDataFrame of dam locations, and dam_drainage_polygon, a Polygon GeoDataFrame of the corresponding drainage areas. Both GeoDataFrames include the ws_id for cross-referencing. The drainage area GeoDataFrame also includes an area_m2 column representing the drainage area in square meters.

Return type:

dict

dem_to_stream(dem_file: str, flwacc_percent: int | float, folder_path: str) → GeoDataFrame[source]

Generates all required input and supporting files for running the WaTEM/SEDEM model with the enabled extension river routing = 1.

This function processes a Digital Elevation Model (DEM) to derive stream networks, flow routing, and supporting shapefiles for analysis. It assumes the DEM covers a single watershed area and enforces flow convergence toward a single outlet at the lowest elevation point. The DEM must use a projected CRS with meter-based units.

Note

All valid DEM cells are converted to 1 to compute flow accumulation. Flow direction is forced toward the lowest pit to simulate a unified outlet.

The function generates the following files in the specified output directory:

  • stream_lines.tif: Raster of river segments.

  • stream_routing.tif: Raster of river routing.

  • stream_adjacent_downstream_connectivity.txt: Text file of adjacent downstream segments.

  • stream_all_upstream_connectivity.txt: Text file of upstream segment connectivity.

Additional raster and shapefiles (not required for WaTEM/SEDEM) are generated for detailed analysis. The shapefiles include a common column, ws_id, which cross-references each stream segment identifier with its drainage point and subbasin area.

  • flwdir.tif: Raster of flow direction.

  • stream_lines.shp: LineString shapefile with columns:

    • ds_id: Identifies of the adjacent downstream segment (-1 if no downstream connectivity).

    • isa_m2: Individual subbasin area of the segment (renamed area_m2 from subbasins.shp), in sqaure meters.

    • flwacc: Flow accumulation value fetched from subbasin_drainage_points.shp.

    • csa_m2: Cumulative subbasin area from upstream heads, in square meters.

  • subbasins.shp: Polygon shapefile contains a column area_m2 that represents the area of each subbasin in square meters.

  • subbasin_drainage_points.shp: Point shapefile contains a column flwacc that represents the flow accumulation at each drainage point. The flow accumulation values are calculated from a raster in which all valid DEM cells are converted to 1.

The following additional files are also generated:

  • stream_information.json: Table of all attributes from stream_lines.shp (excluding geometry), allowing stream analysis without directly opening the shapefile.

  • summary.json: Dictionary summarizing processing time and parameters used.

Warning

Some files are generated temporarily during the simulation and will be deleted at the end. Additionally, any generated files will overwrite existing files if they share the same name. It is strongly recommended to use an empty folder as the output directory to prevent accidental deletion or overwriting of important files.

Parameters:

  • dem_file (str) – Path to the input DEM file.

  • flwacc_percent (float) – A value between 0 and 100 representing the percentage of the maximum flow accumulation used to calculate the threshold for stream generation. The maximum flow accumulation corresponds to the total number of valid data cells. To generate streams based on a specific threshold cell count, calculate the equivalent percentage relative to the total number of valid cells.

  • folder_path (str) – Path to the directory where all output files will be saved.

Returns:

A GeoDataFrame containing information about the stream network.

Return type:

GeoDataFrame

land_cover_esri(lc_file: str, stream_file: str, folder_path: str, reclass_dict: dict[tuple[int, ...], int] | None = None) → str[source]

Processes a high-resolution, open-source Esri land cover raster of the model region for WaTEM/SEDEM simulation.

  • land_cover_percent_esri.csv: Contains the input Esri land cover raster values, along with cell counts, percentage counts, cumulative percentages, and class names.

  • land_cover_cropland_unsplit.tif: Reclassified Esri land cover raster using WaTEM/SEDEM land cover class values, with stream lines overlaid (using raster value -1). If the cropland class with Esri value 5 is present, it is not reclassified here due to its need in further processing.

  • land_cover_percent_watemsedem.csv: Contains the WaTEM/SEDEM land cover raster values, including counts, count percentages, cumulative percentages, and class names.

  • land_cover_extract_cropland.shp: Polygon shapefile of crop fields extracted from land_cover_cropland_unsplit.tif, with a c_id column representing polygon identifiers.

  • land_cover_cropland_split.tif: Raster created by overlaying crop fields onto land_cover_cropland_unsplit.tif.

The last two files, land_cover_extract_cropland.shp and land_cover_cropland_split.tif, are generated only if the cropland class (Esri value 5) is present in the input land cover raster.

Parameters:
Returns:

A message containing the number of agricultural fields detected in the output raster.

Return type:

str

property land_cover_mapping: dict[tuple[int, ...], int]

Dictionary mapping between Esri values and WaTEM/SEDEM values of land cover classes.

Warning

The default reclassification will be used in OptiDamTool.WatemSedem.land_cover_esri() if no custom input is provided and the raster contains Esri land cover classes. This mapping is specifically tailored for arid regions in the Kingdom of Saudi Arabia. If this mapping is not appropriate for the user’s model region, a custom reclassification dictionary must be supplied.

Esri Name

Esri Value

WaTEM/SEDEM Value

WaTEM/SEDEM Name

Water

1

-5

Open water

Trees

2

-3

Forest

Flooded vegetation

4

-4

Pasture

Crops

5

¹> 0

Agricultural fields

Built area

7

-2

Infrastructure

Bare ground

8

-4

Pasture

Snow/ice

9

-5

Open water

Rangeland

11

-4

Pasture

¹Internal processing is handled within the function. “NA” stands for Not Applicable.

land_management_factor(lc_file: str, stream_file: str, output_file: str, reclass_dict: dict[tuple[int, ...], int] | None = None) → list[float][source]

Generates a land management C-factor raster for the model region, suitable for WaTEM/SEDEM simulation.

Tip

The input stream shapefile will be overlaid onto the land cover raster using the value -1, as WaTEM/SEDEM designates this as the river class. If any non-river class already uses the value -1 in the input land cover raster, it is recommended to assign a different value to avoid conflicts.

Parameters:

  • lc_file (str) – Path to the input land cover raster file of the model region.

  • stream_file (str) – Path to the stream shapefile, produced by OptiDamTool.WatemSedem.dem_to_stream().

  • output_file (str) – Path to save the output raster file.

  • reclass_map (dict, optional) – Reclassification dictionary where each key is a tuple of land cover class values, and each corresponding value is a land management factor (between 0 and 1). If not provided, the default mapping from OptiDamTool.WatemSedem.land_management_mapping will be used, assuming the input raster contains Esri land cover classes.

Returns:

A list of land management factor values from the output raster, confirming successful reclassification.

Return type:

list

property land_management_mapping: dict[tuple[int, ...], float]

Dictionary mapping between land cover classes and their corresponding land management factor values.

Warning

The default reclassification will be used in OptiDamTool.WatemSedem.land_management_factor() if no custom input is provided and the raster contains Esri land cover classes. These reclassification values are taken from a global analysis of land management factors by Xiong et al. (2023). This mapping is specifically tailored for arid regions in the Kingdom of Saudi Arabia. If this mapping is not appropriate for the user’s model region, a custom reclassification dictionary must be supplied.

Esri Name

Esri Value

Management value

Water

1

0

Trees

2

0.013

Flooded vegetation

4

0.105

Crops

5

0.301

Built area

7

0.22

Bare ground

8

1

Rangeland

11

0.374
model_region_extension(dem_file: str, buffer_units: int, folder_path: str, select_values: list[float] | None = None, dtype: str = 'int16', nodata: int | float = -9999) → dict[str, float][source]

Generates a raster with a buffer area around the input Digital Elevation Model (DEM) raster. This raster serves as a mask to extend input rasters beyond the model region. Since WaTEM/SEDEM does not handle NoData values properly, at least two DEM pixels outside the model domain must contain valid data. For details, refer to the input DEM requirements.

The function generates the following files in the specified output directory:

  • region.tif: Constant raster with value 1 over the DEM region.

  • region.shp: Polygon shapefile of the DEM region.

  • region_buffer.tif: Raster file of the extended DEM region including the buffer area.

  • region_buffer.shp: Polygon shapefile of the extended DEM region including the buffer area.

All shapefiles contain a common column rst_val, used for cross-referencing. This column contains the corresponding values from the output raster files.

Tip

After generating region_buffer.shp, use this shapefile to clip the DEM, including the buffer area, from the extended DEM raster.

Warning

Generated files will overwrite any existing files with the same names. It is strongly recommended to use an empty folder as the output directory to prevent accidental overwriting or loss of existing data.

Parameters:

  • dem_file (str) – Path to the input DEM raster file.

  • buffer_units (int) – Buffer size, expressed in units of the DEM resolution. For example, if the DEM resolution is 10 meters and buffer_units is 50, the function applies a 500-meter buffer (10 × 50) around the DEM boundary.

  • folder_path (str) – Path to the directory where all output files will be saved.

  • select_values (list, optional) – A list of specific values from the rst_val column to include. If None, all values are used. This is useful for excluding small or negligible boundary polygons in region.shp after a trial run.

  • dtype (str, optional) – Data type of the output raster. Default is ‘int16’.

  • nodata (float, optional) – NoData value to assign to areas not covered by boundary polygons. Default is -9999.

Returns:

A dictionary containing information of actual and extended areas, including their difference.

Return type:

dict

raster_clipping_by_bounding_box(input_file: str, shape_file: str, output_file: str, buffer_length: int | float = 0, nodata: int | float = -9999, dtype: str | None = None) → Profile[source]

Clips a raster using a rectangular bounding box derived from the total bounds of an input shapefile. If necessary, the Coordinate Reference System (CRS) of the shapefile is automatically transformed to match the raster’s CRS. This function is useful for extracting specific regions from large rasters for focused analysis.

Parameters:

  • input_file (str) – Path to the input raster file.

  • shape_file (str) – Path to the input shapefile whose total bounds will be used to clip the raster.

  • output_file (str) – Path to the output raster file.

  • dtype (str, optional) – Data type of the output raster. Default is ‘int16’.

  • nodata (float, optional) – NoData value of the output raster. Default is -9999.

  • dtype – Data type of the output raster. If None, the data type of the input raster is retained.

Returns:

A profile containing metadata about the output raster.

Return type:

profile

raster_constant_extension(input_file: str, constant_value: float, region_file: str, output_file: str, fill_value: int | float = 0, dtype: str | None = None, nodata: int | float | None = None) → Profile[source]

Creates a constant raster by assigning a specified value to all valid pixels. The raster is further extended to exdented region file and NoData is replaced by a valid value. This is useful for preparing a constant raster, for example the erosion control factor, in an efficient way, often required for small regions when running WaTEM/SEDEM.

Note

If raster extension is not required, the same region.tif file must be used for both the input and region rasters.

Parameters:

  • input_file (str) – Path to the region raster named region.tif, produced by OptiDamTool.WatemSedem.model_region_extension().

  • constant_value (float) – The constant value to assign to all valid pixels in the output raster.

  • region_file (str) – Path to the extended region raster named region_buffer.tif, produced by OptiDamTool.WatemSedem.model_region_extension().

  • output_file (str) – Path to save the output raster file.

  • fill_value (float) – Value to assign to the extended areas and NoData region. Default is 0.

  • dtype (str, optional) – Data type of the output raster. If None, the data type of the region raster is retained.

  • nodata (float, optional) – NoData value to assign in the output raster. If None, the NoData value of the region raster is retained.

Returns:

A profile containing metadata about the output raster.

Return type:

profile

raster_driver_to_rst(file_dict: dict[str, str], folder_path: str) → list[str][source]

Converts raster files to the Idrisi raster format (RST), which is one of the two raster formats supported by WaTEM/SEDEM.

Parameters:

  • file_dict (dict) – A dictionary where each key is the desired output file name (without path or extension), and the corresponding value is the full path to the input raster file in a non-Idrisi format.

  • folder_path (str) – Path to the directory where all converted output files will be saved. For example, if ‘dem’ is a key in input file dictionary, the resulting file will be saved as ‘dem.rst’ in this folder.

Returns:

A list of successfully generated files with the .rst extension in the output directory.

Return type:

list

raster_extension(input_file: str, region_file: str, output_file: str, fill_value: int | float = 0, dtype: str | None = None, nodata: int | float | None = None) → Profile[source]

Extends the input raster to match the region file and replaces NoData values with a valid value. This is useful for preparing input data for WaTEM/SEDEM, which does not support NoData cells. For details, refer to the input requirements.

Parameters:

  • input_file (str) – Path to the input raster file.

  • region_file (str) – Path to the region raster including buffer area, region_buffer.tif, produced by OptiDamTool.WatemSedem.model_region_extension().

  • output_file (str) – Path to save the output raster file.

  • fill_value (float) – Value to assign to the extended areas and NoData region. Default is 0.

  • dtype (str, optional) – Data type of the output raster. If None, the data type of the input raster is retained.

  • nodata (float, optional) – NoData value to assign in the output raster. If None, the NoData value of the input raster is retained.

Returns:

A profile containing metadata about the output raster.

Return type:

profile

raster_reproject_clipping_rescaling(input_file: str, resampling_method: str, shape_file: str, mask_file: str, output_file: str, nodata: int | float | None = None) → Profile[source]

Reprojects a raster using the Coordinate Reference System (CRS) of the input shapefile, then clips the reprojected raster based on that shapefile. The provided mask raster, which shares the same extent as the shapefile, is used to rescale the resolution of the reprojected and clipped raster. This function is useful for performing focused analysis on rasters obtained via OptiDamTool.WatemSedem.raster_clipping_by_bounding_box().

Parameters:

  • input_file (str) – Path to the input raster file.

  • resampling_method (str) – Resampling method to apply during reprojection. The supported options are ‘nearest’, ‘bilinear’, and ‘cubic’.

  • shape_file (str) – Path to the shapefile named region.shp, generated by OptiDamTool.WatemSedem.model_region_extension(), used to clip the raster.

  • mask_file (str) – Path to the region raster named region.tif, produced by OptiDamTool.WatemSedem.model_region_extension(), used to rescale the resolution of the output raster.

  • output_file (str) – Path to save the output raster file.

  • nodata (float, optional) – The NoData value to assign in the output raster. If None, the NoData value from the input raster is retained.

Returns:

A profile containing metadata about the output raster.

Return type:

profile

rusle_kr(k_file: str, r_file: str, region_file: str, output_file: str, k_multiplier: int | float = 1) → Profile[source]

Generates a raster map by multiplying the soil erodibility (K) and rainfall erosivity (R) factor rasters. While WaTEM/SEDEM typically uses a raster for K and a single value for R in small regions, this function multiplies the K and R rasters when both vary spatially across a larger area. For more details, see the R-factor documentation.

Warning

WaTEM/SEDEM uses the units of R and K as [MJ·mm]/[ha·h·year] and [kg·h]/[MJ·mm], respectively. If the K raster values are in tons, they must be converted to kilograms using the k_multiplier. There is no need to convert hectares to square meters in the R values. All input rasters (K, R, and region) must have the same Coordinate Reference System (CRS), resolution, and cell alignment. For details, refer to the formulas and units.

Parameters:

  • k_file (str) – Path to the input raster file representing the soil erodibility factor (K).

  • r_file (str) – Path to the input raster file representing the rainfall erosivity factor (R).

  • region_file (str) – Path to the region raster named region.tif, produced by OptiDamTool.WatemSedem.model_region_extension(). Used for internal alignment and masking.

  • output_file (str) – Path to save the output raster file.

  • k_multiplier (float, optional) – Multiplier used to convert K values, e.g., from tons to kilograms. Default is 1, meaning no conversion is applied.

Returns:

A profile containing metadata about the output raster.

Return type:

profile