HydTANK
Python implementation of the Tank Hydrological model by Sugawara and Funiyuki (1956), based on the original code from tank-model by nzahasan.
Installation
pip install hydtank
Getting Started
1. Prepare the Dataset
The dataset must include the following columns: Date, Precipitation, Evapotranspiration, and Discharge. Additionally, ensure that:
- The time intervals between dates are consistent (e.g., 24 hours) for accurate model performance.
Example dataset:
| Date | Discharge | Precipitation | Evapotranspiration |
|---|---|---|---|
| 10/9/2016 | 0.25694 | 0 | 2.79 |
| 10/10/2016 | 0.25812 | 0 | 3.46 |
| 10/11/2016 | 0.30983 | 0 | 3.65 |
| 10/12/2016 | 0.31422 | 0 | 3.46 |
| 10/13/2016 | 0.30866 | 0 | 5.64 |
| 10/14/2016 | 0.30868 | 0 | 3.24 |
| 10/15/2016 | 0.31299 | 0 | 3.41 |
| ... | ... | ... | ... |
2. Prepare the HEC-HMS Basin File
In addition to the dataset, ensure you have the required HEC-HMS basin file. This file contains the hydrological and geographical configuration needed for the TANK model.
3. Initialize the Model
3.1 Directly from a dataset file and a basin file:
from hydtank import build_hydtank
with open('data.csv') as file1, open('NuiLe_GiaUi.basin') as file2:
tank = build_hydtank(
dataset_content=file1.read(),
basin_content=file2.read(),
interval=24.0,
start=None,
end=None
)
3.2 From a Dataset and a basin file:
import pandas as pd
from hydtank import build_hydtank_from_dataset, Dataset, TIME_SERIES, PRECIPITATION, EVAPOTRANSPIRATION, DISCHARGE
df = pd.read_csv('data.csv')
_dataset = Dataset(
time_series=df[TIME_SERIES].tolist(),
precipitation=df[PRECIPITATION].tolist(),
evapotranspiration=df[EVAPOTRANSPIRATION].tolist(),
discharge=df[DISCHARGE].tolist(),
)
tank = build_hydtank_from_dataset(
basin_content=open('NuiLe_GiaUi.basin').read(),
_dataset=_dataset,
interval=24.0,
start=None,
end=None
)
3.3 From an existing model:
from hydtank import build_hydtank, HydTANK
with open('data.csv') as file1, open('NuiLe_GiaUi.basin') as file2:
tank = build_hydtank(
file1.read(),
file2.read()
)
# Avoid using the original model directly!
# Always make a copy before creating a new model
tank_copy = tank.copy()
tank2 = HydTANK(
tank_copy.dataset,
tank_copy.basin_defs,
tank_copy.root_node,
tank_copy.interval,
tank_copy.start,
tank_copy.end
)
4. Retrieve BasinDef Information by Name
from hydtank.bsd_junction import Junction
from hydtank.bsd_reach import Reach
from hydtank.bsd_sink import Sink
from hydtank.bsd_subbasin import Subbasin
...
try:
nui_le: Subbasin = tank.get_basin_def_by_name('NuiLe')
giaui_local: Subbasin = tank.get_basin_def_by_name('GiaUi_Local')
reach1: Reach = tank.get_basin_def_by_name('Reach1')
junction1: Junction = tank.get_basin_def_by_name('Junction1')
sink: Sink = tank.get_basin_def_by_name('Sink1')
except ValueError:
# BasinDef not found
pass
5. Plotting
tank.plot_basin_network().save('GiaUi_NuiLe_Basin_Network.png')
tank.plot_headwater_q().save('GiaUi_NuiLe_Headwater.png')
tank.plot_q().save('GiaUi_NuiLe_Qsim.png')
tank.plot_subbasin(nui_le).save('GiaUi_NuiLe_NuiLe_Subbasin.png')
tank.plot_subbasin(giaui_local).save('GiaUi_NuiLe_GiaUiLocal_Subbasin.png')
6. Reconfigure Parameters for a BasinDef
from hydtank.parameters import SubbasinParameters, ReachParameters
...
params = reach1.parameters.copy()
params.k = 0.9235288521736096
tank.reconfig_parameters(reach1.name, params)
tank.reconfig_parameters(reach1.name, ReachParameters())
tank.reconfig_parameters(nui_le.name, SubbasinParameters())
7. Auto-Optimize Parameters for Subbasin and Reach
7.1 Optimize Specific Subbasin and Reach
tank.optimize([nui_le, reach1, giaui_local])
7.2 Optimize All
Note: This process can take significant time as it involves optimizing parameters for all Subbasin and Reach
elements in the model.
tank.optimize_all()
8. Export Calculation Results as a pandas.DataFrame
r_df = tank.to_dataframe()
9. Set a New Dataset
df = pd.read_csv('new_data.csv')
_dataset = Dataset(
time_series=df[TIME_SERIES].tolist(),
precipitation=df[PRECIPITATION].tolist(),
evapotranspiration=df[EVAPOTRANSPIRATION].tolist(),
discharge=df[DISCHARGE].tolist(),
)
tank.reset_dataset(_dataset, interval=24.0)
10. Configure Time Range
from datetime import datetime
...
tank.set_timeseries_range(start=datetime(...), end=datetime(...))
License
This library is released under the MIT License.
Contact
For any questions or issues, please open an issue on GitHub or email us at duynguyen02.dev@gmail.com.
Metadata
Release files for hydtank 1.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hydtank-1.1.1.tar.gz | 14.1 kB | Without provenance | Details for hydtank-1.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hydtank-1.1.1-py3-none-any.whl | Python 3 | none | any | Details for hydtank-1.1.1-py3-none-any.whl |
Total release size: 30.4 kB
Release files / hydtank-1.1.1.tar.gz
| Download URL | hydtank-1.1.1.tar.gz |
|---|---|
| Size | 14.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d9864141f2c762b9bc1230946d61dfb3089f4dfa5f47d2f4ccf17dc57184b157
|
|
BLAKE2b-256 checksum How to use checksums |
c60287277c8237fb27118544917ebac0d2ec1841c24e57745e159035e36d459c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.4 CPython/3.12.3 Linux/6.8.0-50-generic
|
Release files / hydtank-1.1.1-py3-none-any.whl
| Download URL | hydtank-1.1.1-py3-none-any.whl |
|---|---|
| Size | 16.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6db682399b1077f5c3677e8529de01aac225bd9244dcf1e23a15a0e498c3a7c1
|
|
BLAKE2b-256 checksum How to use checksums |
bf3a2ad456f4105f9fb270d78d346002945cee02233fabe2ecbc5cd4c8af5401
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.4 CPython/3.12.3 Linux/6.8.0-50-generic
|
Security for hydtank 1.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.