tjwb 2.0.0

Python library used to calculate reservoir water balance.

tjwb

tjwb is a Python library designed for water balance management in reservoirs. The library provides methods to calculate inflow and outflow speeds of various components, such as pumps, box culverts, and valve overflows, based on water level and configuration.

Installation

To install the library, use pip:

pip install tjwb

Usage

Basic Example

import pandas as pd
from tjwb import (calculate, RequiredColumnsName, WaterLevelCapacityMappingColumnsName, PumpConfig, ValveOverflowConfig,
                  BoxCulvertConfig)

# Prepare your data
df = pd.DataFrame({
    'Datetime': ['2024-08-28 10:00:00', '2024-08-28 10:05:00'],
    'Water Level': [5.0, 5.5],
    'Pump.Pump-1': [1.0, 1.5],
    'BoxCulvert.BoxCulvert-1': [0.5, 0.7],
    'ValveOverflow.ValveOverflow-1': [0.3, 0.4],
    'ValveOverflow.ValveOverflow-2': [0.3, 0.4],
    'ValveOverflow.ValveOverflow-3': [0.3, 0.4],
})

water_level_capacity_mapping_df = pd.DataFrame({
    'Water Level': [5.0, 5.5],
    'Capacity': [1000, 1500]
})

# Define component configurations
pump_configs = [PumpConfig(column_name_prefix='Pump')]
box_culvert_configs = [BoxCulvertConfig(column_name_prefix='BoxCulvert', elevation=2.0, height=1.0)]
valve_overflow_configs = [ValveOverflowConfig(column_name_prefix='ValveOverflow', elevation=1.5, height=0.5)]

# Calculate results
result = calculate(
    _df=df,
    _water_level_capacity_mapping_df=water_level_capacity_mapping_df,
    water_level_capacity_mapping_columns_name=WaterLevelCapacityMappingColumnsName(),
    required_columns_name=RequiredColumnsName(),
    pump_configs=pump_configs,
    box_culvert_configs=box_culvert_configs,
    valve_overflow_configs=valve_overflow_configs
)

# Convert results to DataFrame
result_df = result.to_dataframe()
print(result_df)

Main Classes and Functions

• calculate: The main function for calculating the inflow and outflow speeds based on the given configurations.
• TJWBResult: Holds the calculated results, including inflow speed, outflow speed, and outflow speeds for each component.
• RequiredColumnsName: Configuration for the required column names in the input DataFrame.
• WaterLevelCapacityMappingColumnsName: Configuration for the column names in the water level-capacity mapping DataFrame.
• Component Configurations:
  • PumpConfig
  • BoxCulvertConfig
  • ValveOverflowConfig

Error Handling

The tjwb library includes various validation steps to ensure that the inputs are correct. Below are the common scenarios where errors might be raised:

• Invalid DataFrame Structure:

  • If the main DataFrame (_df) or the Water Level Capacity Mapping DataFrame (_water_level_capacity_mapping_df) contains missing required columns, a ValueError will be raised.
  • If the Water Level Capacity Mapping DataFrame contains non-numeric data in the water_level or capacity columns, a TypeError will be raised.
  • If any required column in the main DataFrame contains null values, a ValueError will be raised.
  • If the Datetime column cannot be converted to a valid datetime format, a ValueError will be raised.

• Component Configuration Errors:

  • If the column_name_prefix of any component contains the character '.', a ValueError will be raised, as this character is not allowed in column name prefixes.
  • If there are duplicate column_name_prefix values among the configured components, a ValueError will be raised.
  • If a column referenced in the component configuration does not exist or is not of numeric type, a TypeError will be raised.

• Invalid Water Level to Capacity Mapping:

  • If there is a mismatch between the water levels in the main DataFrame and the Water Level Capacity Mapping DataFrame, such that no valid capacity can be mapped, a ValueError will be raised.

• Calculation Errors:

  • If the calculated inflow or outflow speeds result in negative or NaN values, the library automatically converts these to zero using internal validation functions.

License

This library is released under the MIT License.

Contact

If you have any questions or issues, please open an issue on GitHub or email us at [e-mail].