nzahasan / tank-model

Python implementation of Tank Hydrological model by Sugawara and Funiyuki (1956)

Tank Hydrologic Model

Python implementation of Tank Hydrologic Model, a conceptual rainfall-runoff model proposed by Sugawara and Funiyuki (1956)

Installation

Tank-Model can be installed as a python package using the following commands

$ pip install https://github.com/nzahasan/tank-model/zipball/master

after successful installation tank_cmd.py should be available which can be used for setting up new project, optimizing the project and computation.

# get help text command line utility
$ tank_cmd.py --help

# get help text of subcommand
$ tank_cmd.py new-project --help

Setting up a new model:

New project can be created using the following command. This command creates a folder in working directory with a json formatted project definition inside it.

$ tank_cmd.py new-project project_name

A sample project definition looks like this

{
  "interval": 24.0,
  "basin": "sample_project.basin.json",
  "precipitation": "sample_project.pr.csv",
  "evapotranspiration": "sample_project.et.csv",
  "discharge": "sample_project.q.csv",
  "result": "sample_project.result.csv",
  "statistics": "sample_project.stats.json"
}

here interval is the time step of simulation in hours. The other attributes are file locations; precipitation, evapotranspiration and discharge are CSV files containing time-series data. These files should be formatted according to the file format mentioned here file-format-spec.md

precipitation & evapotranspiration serve as input data for the model simulation and resulting output is stored in the result file following the time-series CSV format mentioned earlier. Data in the discharge is used for model calibration. And performance matrices are stored in the statistics file.

Converting HEC-HMS basin to tank model basin

$ tank_cmd.py hms2tank -bf hechms_basin_file -of output_tank_basin_file_path

Computing tank model

$ tank_cmd.py compute -pf project_name.project.json

Automatic optimization of tank model

$ tank_cmd.py optimize -pf project_name.project.json

References:

1. Paik K., Kim J. H., Kim H. S., Lee D. R. (2005) A conceptual rainfall-runoff model considering seasonal variation.
2. Aguilar C., Polo M. J. (2011) Generating reference evapotranspiration surfaces from the Hargreaves equation at watershed scale.
3. Taib A. T. M., Tahir W., Ramli S., Mohtar I. S. A. (2022) Hydro-Meteorological Flood Forecasting Using Tank Model With Satellite-Based Rainfall Input For Kemaman River Catchment.
4. D. N. Moriasi, J. G. Arnold, M. W. Van Liew, R. L. Bingner, R. D. Harmel, T. L. Veith (2007) Model Evaluation Guidelines For Systematic Quantification Of Accuracy In Watershed Simulations.

tank-model's Issues

check when index name is not `Time`

tank-model/tank_core/io_helpers.py

Line 40 in acd4663

def write_ts_file(df:pd.DataFrame,file_path:str)->int:

Check if the provided datetimeindex is not timezone aware

check if precipitation and evapotranspiration index is same

Use time difference in seconds.

Return basin state variables

Return model state variables by default, possible use for error correction.

Cast to UTC time zone

tank-model/tank_core/io_helpers.py

Line 47 in d6b20c1

status = df.to_csv(

-- ref : https://stackoverflow.com/questions/48724902/python-datetime-use-strftime-with-a-timezone-aware-date

add node name here for directly reading from pandas dataframe?

tank-model/tank_core/tank_basin.py

Line 35 in d69f0be

t3_is:float, t3_soc:float) -> np.ndarray:

remove hardcoded time difference

tank-model/tank_core/computation_helpers.py

Line 247 in d6b20c1

result = compute_project(updated_basin,rainfall,evapotranspiration,24.0)

Check timedleta for minutes

This will allow us to hourly simulation

tank-model/tank_core/io_helpers.py

Line 35 in d6b20c1

raise Exception('Time difference is not equal, possible missing values')

Use tank-basin states to correct model prediction error

Return/store tank basin states for further state based error correction.

Reference:

• https://www.sciencedirect.com/science/article/pii/S0098300421003010

Define input data unit in project config file

Read rainfall/evapotranspiration unit form project config file.

Output result based on simulation start and end date defined in the project file

Also check in the process, that pr and et files contains right amount data if not warn and abort

Computation point specific automatic optimisation

If two computation/statistic point defined do automatic optimisation for each points upstream nodes, of any computation point is in upstream of another point, then the later point will consider nodes after the previous computation point.