| Name | hydreservoir JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | HydReservoir is a Python library for hydrological calculations related to reservoirs. |
| upload_time | 2024-12-11 10:02:25 |
| maintainer | None |
| docs_url | None |
| author | Duy Nguyen |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# HydReservoir
[](https://pypi.org/project/hydreservoir/)
[](https://pypi.org/project/hydreservoir/)
[](https://github.com/duynguyen02/hydreservoir)
## Overview
`HydReservoir` is a comprehensive Python library for advanced hydrological calculations and water reservoir management.
## Key Features
- Detailed water balance calculations
- Complex hydraulic system modeling
- Support for multiple hydraulic components:
- Pumps
- Box culverts
- Circular culverts
- Gated spillways
- Free spillways
- Unknown discharge sources
- Advanced reservoir regulation utilities
## Installation
Install HydReservoir quickly using pip:
```bash
pip install hydreservoir
```
## Getting Started
### 1. Water Balance Calculation
```python
import pandas as pd
from hydreservoir.water_balance.v2.hydraulic_component import BoxCulvert
from hydreservoir.water_balance.v2.hydraulic_component import CircularCulvert
from hydreservoir.water_balance.v2.hydraulic_component import CircularCulvertV2
from hydreservoir.water_balance.v2.hydraulic_component import FreeSpillway
from hydreservoir.water_balance.v2.hydraulic_component import Pump
from hydreservoir.water_balance.v2.hydraulic_component import Unknown
from hydreservoir.water_balance.v2.hydraulic_component import GatedSpillway
from hydreservoir.water_balance.v2.wb import WB
df = pd.read_csv('data.csv')
free_spillway = FreeSpillway(
'FS1', 109.3, 19.0
)
gated_spillway = GatedSpillway(
'GS1', 109.3, 19.0,
df['GatedA'].to_numpy(), free_spillway
)
circular_culvert = CircularCulvert(
'CC1', 102.5, 0.4, df['CircularA'].to_numpy(), free_spillway,
discharge_coefficient=0.9, contraction_coefficient=1.0
)
circular_culvert_v2 = CircularCulvertV2(
'CC2', 102.5, 0.4, df['CircularA'].to_numpy(), free_spillway,
discharge_coefficient=0.9, contraction_coefficient=1.0
)
box_culvert = BoxCulvert(
'BC1', 102.5, 0.4, df['BoxA'].to_numpy(), free_spillway
)
pump = Pump(
'P1', df['P'].to_numpy()
)
unknown = Unknown(
'U1', df['P'].to_numpy()
)
timeseries = pd.to_datetime(df['Timeseries'])
wb = WB(
timeseries.to_numpy(),
df['WaterLevel'].astype(float).to_numpy(),
df['Capacity'].astype(float).to_numpy(),
)
(wb.add_component(circular_culvert_v2).add_component(free_spillway)
.add_component(pump).add_component(box_culvert))
wb.calculate().to_csv('result.csv', index=False)
```
### Result DataFrame Columns
The water balance calculation returns a detailed DataFrame with the following columns:
| Column Name | Description | Unit | Example |
|--------------------------------------------------|----------------------------------------------------------------------|--------------------------------|--------------|
| `Timeseries` | Timestamp for the measurement | Datetime | `2022-01-01` |
| `WaterLevel` | Current water level in the reservoir | Meters (m) | `109.3` |
| `Capacity` | Reservoir capacity corresponding to the current water level | Cubic meters (10^6m³) | `2.53` |
| `Delta` | Change in water level since the previous measurement | Meters (m) | `0.0` |
| `Interval` | Time interval between consecutive measurements | Seconds | `86400` |
| `FreeSpillway.<Free Spillway ID>.<uuid>` | Flow rate through the free spillway with the specified ID | Cubic meters per second (m³/s) | `0.0` |
| `GatedSpillway.<Gated Spillway ID>.<uuid>` | Flow rate through a gated spillway port with the specified ID | Cubic meters per second (m³/s) | `0.0` |
| `CircularCulvert.<Circular Culvert ID>.<uuid>` | Flow rate through the circular culvert with the specified ID | Cubic meters per second (m³/s) | `4.046643` |
| `CircularCulvertV2.<Circular Culvert ID>.<uuid>` | Flow rate through the updated circular culvert with the specified ID | Cubic meters per second (m³/s) | `0.131839` |
| `BoxCulvert.<Box Culvert ID>.<uuid>` | Flow rate through the box culvert with the specified ID | Cubic meters per second (m³/s) | `0.573937` |
| `Pump.<Pump ID>.<uuid>` | Discharge rate for the pump with the specified ID | Cubic meters per second (m³/s) | `0.0` |
| `Unknown.<Unknown Source ID>.<uuid>` | Discharge rate for an unknown source with the specified ID | Cubic meters per second (m³/s) | `0.0` |
| `Inflow` | Total inflow into the reservoir | Cubic meters per second (m³/s) | `4.75242` |
| `Outflow` | Total outflow from all components | Cubic meters per second (m³/s) | `4.75242` |
### 2. Custom Hydraulic Components
```python
import numpy as np
from hydreservoir.water_balance.v2.hydraulic_component import BaseFreeSpillway, BaseGatedSpillway, BaseCircularCulvert,\
BaseBoxCulvert, SimpleDischarge
from hydreservoir.water_balance.v2.hydraulic_component.core import Core
class CustomFromScratch(Core):
def provide_discharge(self, water_level: np.ndarray[float], capacity: np.ndarray[float]) -> np.ndarray[float]:
return np.zeros(len(water_level))
class CustomFreeSpillway(BaseFreeSpillway):
def calculate_free_spillway_discharge(self, water_level: float, capacity: float) -> float:
m = self._spillway_discharge_coefficient
g = self._gravitational_acceleration
_B = self._dimension
_H = water_level - self._elevation
# do something ...
return 0
class CustomGatedSpillway(BaseGatedSpillway):
def calculate_gated_spillway_discharge(self, water_level: float, capacity: float, opening: float) -> float:
# access properties
# do something ...
return 0
class CustomCircularCulvert(BaseCircularCulvert):
def calculate_circular_culvert_discharge(self, water_level: float, capacity: float, opening: float) -> float:
# access properties
# do something ...
return 0
class CustomBoxCulvert(BaseBoxCulvert):
def calculate_box_culvert_discharge(self, water_level: float, capacity: float, opening: float) -> float:
# access properties
# do something ...
return 0
class CustomPump(SimpleDischarge):
def provide_discharge(
self, water_level: np.ndarray[float], capacity: np.ndarray[float]
) -> np.ndarray[float]:
return self._discharge
```
### 3. Reservoir Regulation Analysis
```python
from hydreservoir.regulation import regulation
from hydreservoir.regulation.dataset import Dataset as RDataset
# ... calculate init components for water balance
df = wb.calculate().to_csv('result.csv', index=False)
# Regulation analysis
P = 90.0
eps = 0.1
P_n = regulation.P_n(RDataset.from_wb_df_to_dataset(df), V_c=1.0, gt_10_years=True)
print(P_n - P <= eps)
```
### 3. Mapping Functions for Water Levels and Capacities
These functions allow efficient mapping between water levels and reservoir capacities, with optional support for nearest
neighbor interpolation.
`get_capacity`
Maps a single water level to its corresponding capacity using a provided mapping dictionary. Supports optional nearest
neighbor interpolation for unmatched values.
```python
from hydreservoir.utils import get_capacity
water_level_capacity_map = {0.0: 0.0, 1.0: 100.0, 2.0: 200.0}
capacity = get_capacity(1.5, water_level_capacity_map, nearest_mapping=True)
print(capacity) # Output: 100.0
```
`map_capacity`
Maps an array of water levels to their corresponding capacities using a provided mapping dictionary. Supports optional
nearest neighbor interpolation for unmatched values.
```python
from hydreservoir.utils import map_capacity
water_level_capacity_map = {0.0: 0.0, 1.0: 100.0, 2.0: 200.0}
water_levels = [0.5, 1.5, 2.0]
capacities = map_capacity(water_levels, water_level_capacity_map, nearest_mapping=True)
print(capacities) # Output: [0.0, 100.0, 200.0]
```
`get_water_level`
Maps a single capacity to its corresponding water level using a provided mapping dictionary. Supports optional nearest
neighbor interpolation for unmatched values.
```python
from hydreservoir.utils import get_water_level
capacity_water_level_map = {0.0: 0.0, 100.0: 1.0, 200.0: 2.0}
water_level = get_water_level(150.0, capacity_water_level_map, nearest_mapping=True)
print(water_level) # Output: 1.0
```
`map_water_level`
Maps an array of capacities to their corresponding water levels using a provided mapping dictionary. Supports optional
nearest neighbor interpolation for unmatched values.
```python
from hydreservoir.utils import map_water_level
capacity_water_level_map = {0.0: 0.0, 100.0: 1.0, 200.0: 2.0}
capacities = [50.0, 150.0, 200.0]
water_levels = map_water_level(capacities, capacity_water_level_map, nearest_mapping=True)
print(water_levels) # Output: [0.0, 1.0, 2.0]
```
## License
This library is released under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "hydreservoir",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Duy Nguyen",
"author_email": "duynguyen02.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cb/d4/f23f421a50bb992c2f176c507ac4fc24d6923fa4f31e0d2b61e87d81a2ed/hydreservoir-1.1.0.tar.gz",
"platform": null,
"description": "# HydReservoir\n\n[](https://pypi.org/project/hydreservoir/)\n[](https://pypi.org/project/hydreservoir/)\n[](https://github.com/duynguyen02/hydreservoir)\n\n## Overview\n\n`HydReservoir` is a comprehensive Python library for advanced hydrological calculations and water reservoir management.\n\n## Key Features\n\n- Detailed water balance calculations\n- Complex hydraulic system modeling\n- Support for multiple hydraulic components:\n - Pumps\n - Box culverts\n - Circular culverts\n - Gated spillways\n - Free spillways\n - Unknown discharge sources\n- Advanced reservoir regulation utilities\n\n## Installation\n\nInstall HydReservoir quickly using pip:\n\n```bash\npip install hydreservoir\n```\n\n## Getting Started\n\n### 1. Water Balance Calculation\n\n```python\nimport pandas as pd\n\nfrom hydreservoir.water_balance.v2.hydraulic_component import BoxCulvert\nfrom hydreservoir.water_balance.v2.hydraulic_component import CircularCulvert\nfrom hydreservoir.water_balance.v2.hydraulic_component import CircularCulvertV2\nfrom hydreservoir.water_balance.v2.hydraulic_component import FreeSpillway\nfrom hydreservoir.water_balance.v2.hydraulic_component import Pump\nfrom hydreservoir.water_balance.v2.hydraulic_component import Unknown\nfrom hydreservoir.water_balance.v2.hydraulic_component import GatedSpillway\nfrom hydreservoir.water_balance.v2.wb import WB\n\ndf = pd.read_csv('data.csv')\n\nfree_spillway = FreeSpillway(\n 'FS1', 109.3, 19.0\n)\n\ngated_spillway = GatedSpillway(\n 'GS1', 109.3, 19.0,\n df['GatedA'].to_numpy(), free_spillway\n)\n\ncircular_culvert = CircularCulvert(\n 'CC1', 102.5, 0.4, df['CircularA'].to_numpy(), free_spillway,\n discharge_coefficient=0.9, contraction_coefficient=1.0\n)\n\ncircular_culvert_v2 = CircularCulvertV2(\n 'CC2', 102.5, 0.4, df['CircularA'].to_numpy(), free_spillway,\n discharge_coefficient=0.9, contraction_coefficient=1.0\n)\n\nbox_culvert = BoxCulvert(\n 'BC1', 102.5, 0.4, df['BoxA'].to_numpy(), free_spillway\n)\n\npump = Pump(\n 'P1', df['P'].to_numpy()\n)\n\nunknown = Unknown(\n 'U1', df['P'].to_numpy()\n)\n\ntimeseries = pd.to_datetime(df['Timeseries'])\n\nwb = WB(\n timeseries.to_numpy(),\n df['WaterLevel'].astype(float).to_numpy(),\n df['Capacity'].astype(float).to_numpy(),\n)\n\n(wb.add_component(circular_culvert_v2).add_component(free_spillway)\n .add_component(pump).add_component(box_culvert))\n\nwb.calculate().to_csv('result.csv', index=False)\n```\n\n### Result DataFrame Columns\n\nThe water balance calculation returns a detailed DataFrame with the following columns:\n\n| Column Name | Description | Unit | Example |\n|--------------------------------------------------|----------------------------------------------------------------------|--------------------------------|--------------|\n| `Timeseries` | Timestamp for the measurement | Datetime | `2022-01-01` |\n| `WaterLevel` | Current water level in the reservoir | Meters (m) | `109.3` |\n| `Capacity` | Reservoir capacity corresponding to the current water level | Cubic meters (10^6m\u00b3) | `2.53` |\n| `Delta` | Change in water level since the previous measurement | Meters (m) | `0.0` |\n| `Interval` | Time interval between consecutive measurements | Seconds | `86400` |\n| `FreeSpillway.<Free Spillway ID>.<uuid>` | Flow rate through the free spillway with the specified ID | Cubic meters per second (m\u00b3/s) | `0.0` |\n| `GatedSpillway.<Gated Spillway ID>.<uuid>` | Flow rate through a gated spillway port with the specified ID | Cubic meters per second (m\u00b3/s) | `0.0` |\n| `CircularCulvert.<Circular Culvert ID>.<uuid>` | Flow rate through the circular culvert with the specified ID | Cubic meters per second (m\u00b3/s) | `4.046643` |\n| `CircularCulvertV2.<Circular Culvert ID>.<uuid>` | Flow rate through the updated circular culvert with the specified ID | Cubic meters per second (m\u00b3/s) | `0.131839` |\n| `BoxCulvert.<Box Culvert ID>.<uuid>` | Flow rate through the box culvert with the specified ID | Cubic meters per second (m\u00b3/s) | `0.573937` |\n| `Pump.<Pump ID>.<uuid>` | Discharge rate for the pump with the specified ID | Cubic meters per second (m\u00b3/s) | `0.0` |\n| `Unknown.<Unknown Source ID>.<uuid>` | Discharge rate for an unknown source with the specified ID | Cubic meters per second (m\u00b3/s) | `0.0` |\n| `Inflow` | Total inflow into the reservoir | Cubic meters per second (m\u00b3/s) | `4.75242` |\n| `Outflow` | Total outflow from all components | Cubic meters per second (m\u00b3/s) | `4.75242` |\n\n### 2. Custom Hydraulic Components\n\n```python\nimport numpy as np\n\nfrom hydreservoir.water_balance.v2.hydraulic_component import BaseFreeSpillway, BaseGatedSpillway, BaseCircularCulvert,\\\n BaseBoxCulvert, SimpleDischarge\nfrom hydreservoir.water_balance.v2.hydraulic_component.core import Core\n\n\nclass CustomFromScratch(Core):\n\n def provide_discharge(self, water_level: np.ndarray[float], capacity: np.ndarray[float]) -> np.ndarray[float]:\n return np.zeros(len(water_level))\n\n\nclass CustomFreeSpillway(BaseFreeSpillway):\n def calculate_free_spillway_discharge(self, water_level: float, capacity: float) -> float:\n m = self._spillway_discharge_coefficient\n g = self._gravitational_acceleration\n _B = self._dimension\n _H = water_level - self._elevation\n # do something ...\n return 0\n\n\nclass CustomGatedSpillway(BaseGatedSpillway):\n def calculate_gated_spillway_discharge(self, water_level: float, capacity: float, opening: float) -> float:\n # access properties\n # do something ...\n return 0\n\n\nclass CustomCircularCulvert(BaseCircularCulvert):\n def calculate_circular_culvert_discharge(self, water_level: float, capacity: float, opening: float) -> float:\n # access properties\n # do something ...\n return 0\n\n\nclass CustomBoxCulvert(BaseBoxCulvert):\n def calculate_box_culvert_discharge(self, water_level: float, capacity: float, opening: float) -> float:\n # access properties\n # do something ...\n return 0\n\n\nclass CustomPump(SimpleDischarge):\n def provide_discharge(\n self, water_level: np.ndarray[float], capacity: np.ndarray[float]\n ) -> np.ndarray[float]:\n return self._discharge\n\n```\n\n### 3. Reservoir Regulation Analysis\n\n```python\nfrom hydreservoir.regulation import regulation\nfrom hydreservoir.regulation.dataset import Dataset as RDataset\n\n# ... calculate init components for water balance\ndf = wb.calculate().to_csv('result.csv', index=False)\n\n# Regulation analysis\nP = 90.0\neps = 0.1\nP_n = regulation.P_n(RDataset.from_wb_df_to_dataset(df), V_c=1.0, gt_10_years=True)\n\nprint(P_n - P <= eps)\n```\n\n### 3. Mapping Functions for Water Levels and Capacities\n\nThese functions allow efficient mapping between water levels and reservoir capacities, with optional support for nearest\nneighbor interpolation.\n\n`get_capacity`\nMaps a single water level to its corresponding capacity using a provided mapping dictionary. Supports optional nearest\nneighbor interpolation for unmatched values.\n\n```python\nfrom hydreservoir.utils import get_capacity\n\nwater_level_capacity_map = {0.0: 0.0, 1.0: 100.0, 2.0: 200.0}\ncapacity = get_capacity(1.5, water_level_capacity_map, nearest_mapping=True)\nprint(capacity) # Output: 100.0\n```\n\n`map_capacity`\nMaps an array of water levels to their corresponding capacities using a provided mapping dictionary. Supports optional\nnearest neighbor interpolation for unmatched values.\n\n```python\nfrom hydreservoir.utils import map_capacity\n\nwater_level_capacity_map = {0.0: 0.0, 1.0: 100.0, 2.0: 200.0}\nwater_levels = [0.5, 1.5, 2.0]\ncapacities = map_capacity(water_levels, water_level_capacity_map, nearest_mapping=True)\nprint(capacities) # Output: [0.0, 100.0, 200.0]\n```\n\n`get_water_level`\nMaps a single capacity to its corresponding water level using a provided mapping dictionary. Supports optional nearest\nneighbor interpolation for unmatched values.\n\n```python\nfrom hydreservoir.utils import get_water_level\n\ncapacity_water_level_map = {0.0: 0.0, 100.0: 1.0, 200.0: 2.0}\nwater_level = get_water_level(150.0, capacity_water_level_map, nearest_mapping=True)\nprint(water_level) # Output: 1.0\n```\n\n`map_water_level`\nMaps an array of capacities to their corresponding water levels using a provided mapping dictionary. Supports optional\nnearest neighbor interpolation for unmatched values.\n\n```python\nfrom hydreservoir.utils import map_water_level\n\ncapacity_water_level_map = {0.0: 0.0, 100.0: 1.0, 200.0: 2.0}\ncapacities = [50.0, 150.0, 200.0]\nwater_levels = map_water_level(capacities, capacity_water_level_map, nearest_mapping=True)\nprint(water_levels) # Output: [0.0, 1.0, 2.0]\n```\n\n## License\n\nThis library is released under the MIT License.",
"bugtrack_url": null,
"license": "MIT",
"summary": "HydReservoir is a Python library for hydrological calculations related to reservoirs.",
"version": "1.1.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fe28ef811f5caae9407e94a99a7820569313d94ddaa1e410aac4851e3f4d86b6",
"md5": "3d2c09e4ef442cd18f4368f82d497cf8",
"sha256": "30596b73657e00e00dee5c5961ecce1fff1007ec47745e0e91aa3145d359dd60"
},
"downloads": -1,
"filename": "hydreservoir-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d2c09e4ef442cd18f4368f82d497cf8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 25592,
"upload_time": "2024-12-11T10:02:22",
"upload_time_iso_8601": "2024-12-11T10:02:22.568401Z",
"url": "https://files.pythonhosted.org/packages/fe/28/ef811f5caae9407e94a99a7820569313d94ddaa1e410aac4851e3f4d86b6/hydreservoir-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cbd4f23f421a50bb992c2f176c507ac4fc24d6923fa4f31e0d2b61e87d81a2ed",
"md5": "4123ca487ff976cd6d3b5e0203ed3265",
"sha256": "d20cf0ebeed707212ab10daa69d2c5fc86e743bc029c16e8c0a9549ec2f25fc3"
},
"downloads": -1,
"filename": "hydreservoir-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4123ca487ff976cd6d3b5e0203ed3265",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 16184,
"upload_time": "2024-12-11T10:02:25",
"upload_time_iso_8601": "2024-12-11T10:02:25.245777Z",
"url": "https://files.pythonhosted.org/packages/cb/d4/f23f421a50bb992c2f176c507ac4fc24d6923fa4f31e0d2b61e87d81a2ed/hydreservoir-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-11 10:02:25",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "hydreservoir"
}
