| Name | EcoHydroModel JSON |
| Version |
0.1.0.post5
JSON |
| download |
| home_page | None |
| Summary | A framework built on PyTorch for eco-hydrological modeling |
| upload_time | 2025-09-04 00:08:06 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2025 Long Jiang
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
hydrology
ecohydro
modeling
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# EcoHydroModel
EcoHydroModel is a framework built on **PyTorch** and **PyTorch Geometric** for eco-hydrological modeling. It combines **process-based updaters** with **deep learning modules (GNN)** to support watershed DEM extraction, graph construction, state evolution simulation, visualization, and training.
The framework is particularly suited for **hydrological and biogeochemical processes** (e.g., soil water storage, evapotranspiration, nitrification) and parameter inversion, and can be extended to various **graph-structured process models**.
---
## ✨ Modules
- **Updaters**: Supports hydrological balance, nitrogen cycle, MLP approximation, and can be flexibly extended
- **DataManager**: Extract watershed from DEM, build directed graph, and manage forcings, states, and references in a unified way
- **Trainer**: Provides training, checkpointing, parameter constraints, and best parameter tracking
- **Visualizer**: Supports grid/graph visualization, similarity metrics (NSE/KGE), and time series comparison
👉 To customize your own updater, see [Updater Specification.md](docs/Updater_Specification.md)
---
## 📦 Installation
```bash
pip install ecohydromodel
```
---
## 🔑 Core Components
### 1. Updater Base Class
- Provides an `update` method to be implemented by subclasses
- Supports **parallel / layer / converge / max_depth** update modes
- Includes parameter management, graph aggregation, and iterative convergence utilities
### 2. DataManager
- `load_dem()`: Extract sub-basin from DEM and build graph structure
- `load_csv()` / `save_csv()`: Load/save states and reference data
- `coarse()`: Graph coarsening using graclus
- `chunk_data()`: Split time series into chunks for training
### 3. Trainer
- `train()`: Train model with options for target variables, checkpointing, and parameter constraints
- Automatically saves and restores best parameters
### 4. Visualizer
- `plot()`: Spatial visualization (grid or graph)
- `plot_similarity()`: NSE/KGE-based similarity visualization
- `plot_timeseries()`: Node-level time series comparison
### 5. Process Update Modules ([custom_updater.py](tests/custom_updater.py))
- **BucketUpdater**: Implements simple Bucket Model with Hamon (1961) evapotranspiration equations
- **NitriUpdater**: Implements [Del Grosso](docs/Nitrification_Module_Del_Grosso.md) / [Parton](docs/Nitrification_Module_Parton.md) nitrification equations
- **MLPUpdater**: Predicts nitrification rate using soil embedding and MLP
---
## 🚀 Example Usage ([example_basic.py](tests/example_basic.py))
This example demonstrates how to use **EcoHydroModel** for data loading, model setup, training, and visualization.
The workflow is divided into five parts: **Environment & Dependencies**, **Data Preparation**, **Model Construction**, **Training**, and **Evaluation & Visualization**.
---
### 1. Data Preparation
```python
data = DataManager(device)
dem = 'data/dem.asc'
data.load_dem(dem, outx=38, outy=54)
ref = {'storage': 'data/ref_storage.csv'}
data.load_csv(ref, target='ref', time_index=[1, 365])
forcing = {'RAIN': 'data/ref_RAIN.csv', 'TEMP': 'data/ref_TEMP.csv'}
data.load_csv(forcing, target='forcing', time_index=[1, 365])
state = {'storage': 'data/ref_storage_bucket.csv'}
data.load_csv(state, target='state', time_index=0)
```
- Initialize the `DataManager` to store and manage input/ref data.
- Load the DEM and resample to the specified grid size.
- Load reference data (`ref`), forcing data (`RAIN`, `TEMP`), and initial state.
- `time_index` can be used to specify a range or a single timestep (if omitted, all timesteps are used).
---
### 2. Model Construction
```python
bucket = BucketUpdater().to(device)
model = EcoHydroModel({'bucket': bucket}, device=device)
var = 'storage'
```
- Define a simple process module (`BucketUpdater`).
- Construct the `EcoHydroModel` with the module dictionary.
- Specify the target variable (`storage`) for training and evaluation.
---
### 3. Test Run
```python
model.eval()
with torch.no_grad():
out = model(data)
Visualizer.plot(out[var], pos=data.pos)
Visualizer.plot_similarity(out[var], data.ref[var], pos=data.pos)
Visualizer.plot_timeseries(out[var], data.ref[var], node_idx=0)
```
- Run the model with default setting in evaluation mode to generate predictions.
- Visualize spatial patterns, similarity with reference data, and node-level time series.
---
### 4. Training
```python
print("Start training...")
final_params = Trainer(model).train(
data, epochs=100, lr=1e-2, chunk_size=1, target_keys=[var]
)
print('Final params:', final_params)
```
- Train the model with the given dataset for 100 epochs.
- Use a simple trainer with learning rate `1e-2` and chunk size of 1.
- Print the final optimized parameters after training.
---
### 5. Evaluation & Visualization
```python
model.eval()
with torch.no_grad():
out = model(data)
Visualizer.plot(out[var], pos=data.pos)
Visualizer.plot_similarity(out[var], data.ref[var], pos=data.pos)
Visualizer.plot_timeseries(out[var], data.ref[var], node_idx=0)
```
- Evaluate the trained model.
- Generate the same set of visualizations as in the reference run, enabling a direct comparison between model predictions and reference data.
---
## 🔧 Advanced Usage ([example_full.py](tests/example_full.py))
This example shows **graph coarsening**, **multi-module wiring**, and **constrained parameter tuning**.
For a full step-by-step description, see the [detailed manual of example](docs/Full_example.md).
### Highlights
- Graph coarsening to switch between resolutions
- Multiple updaters (e.g., `NitriUpdater`, `MLPUpdater`)
- Parameter range constraints during training
- Targeted training on selected variables/time windows
Raw data
{
"_id": null,
"home_page": null,
"name": "EcoHydroModel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "hydrology, ecohydro, modeling",
"author": null,
"author_email": "Long Jiang <jlon@uw.edu>",
"download_url": "https://files.pythonhosted.org/packages/5d/cd/336d5329945982efeb61634d4e2a4551990ba862a4a94f24fff87a1eb454/ecohydromodel-0.1.0.post5.tar.gz",
"platform": null,
"description": "# EcoHydroModel\r\n\r\nEcoHydroModel is a framework built on **PyTorch** and **PyTorch Geometric** for eco-hydrological modeling. It combines **process-based updaters** with **deep learning modules (GNN)** to support watershed DEM extraction, graph construction, state evolution simulation, visualization, and training. \r\n\r\nThe framework is particularly suited for **hydrological and biogeochemical processes** (e.g., soil water storage, evapotranspiration, nitrification) and parameter inversion, and can be extended to various **graph-structured process models**.\r\n\r\n---\r\n\r\n## \u2728 Modules\r\n- **Updaters**: Supports hydrological balance, nitrogen cycle, MLP approximation, and can be flexibly extended \r\n- **DataManager**: Extract watershed from DEM, build directed graph, and manage forcings, states, and references in a unified way \r\n- **Trainer**: Provides training, checkpointing, parameter constraints, and best parameter tracking \r\n- **Visualizer**: Supports grid/graph visualization, similarity metrics (NSE/KGE), and time series comparison \r\n\r\n\ud83d\udc49 To customize your own updater, see [Updater Specification.md](docs/Updater_Specification.md)\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n```bash\r\npip install ecohydromodel\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udd11 Core Components\r\n\r\n### 1. Updater Base Class\r\n- Provides an `update` method to be implemented by subclasses \r\n- Supports **parallel / layer / converge / max_depth** update modes \r\n- Includes parameter management, graph aggregation, and iterative convergence utilities \r\n\r\n### 2. DataManager\r\n- `load_dem()`: Extract sub-basin from DEM and build graph structure \r\n- `load_csv()` / `save_csv()`: Load/save states and reference data \r\n- `coarse()`: Graph coarsening using graclus \r\n- `chunk_data()`: Split time series into chunks for training \r\n\r\n### 3. Trainer\r\n- `train()`: Train model with options for target variables, checkpointing, and parameter constraints \r\n- Automatically saves and restores best parameters \r\n\r\n### 4. Visualizer\r\n- `plot()`: Spatial visualization (grid or graph) \r\n- `plot_similarity()`: NSE/KGE-based similarity visualization \r\n- `plot_timeseries()`: Node-level time series comparison \r\n\r\n### 5. Process Update Modules ([custom_updater.py](tests/custom_updater.py))\r\n- **BucketUpdater**: Implements simple Bucket Model with Hamon (1961) evapotranspiration equations \r\n- **NitriUpdater**: Implements [Del Grosso](docs/Nitrification_Module_Del_Grosso.md) / [Parton](docs/Nitrification_Module_Parton.md) nitrification equations\r\n- **MLPUpdater**: Predicts nitrification rate using soil embedding and MLP \r\n\r\n---\r\n\r\n## \ud83d\ude80 Example Usage ([example_basic.py](tests/example_basic.py))\r\n\r\nThis example demonstrates how to use **EcoHydroModel** for data loading, model setup, training, and visualization. \r\nThe workflow is divided into five parts: **Environment & Dependencies**, **Data Preparation**, **Model Construction**, **Training**, and **Evaluation & Visualization**.\r\n\r\n---\r\n\r\n### 1. Data Preparation\r\n```python\r\ndata = DataManager(device)\r\ndem = 'data/dem.asc'\r\ndata.load_dem(dem, outx=38, outy=54)\r\n\r\nref = {'storage': 'data/ref_storage.csv'}\r\ndata.load_csv(ref, target='ref', time_index=[1, 365])\r\n\r\nforcing = {'RAIN': 'data/ref_RAIN.csv', 'TEMP': 'data/ref_TEMP.csv'}\r\ndata.load_csv(forcing, target='forcing', time_index=[1, 365])\r\n\r\nstate = {'storage': 'data/ref_storage_bucket.csv'}\r\ndata.load_csv(state, target='state', time_index=0)\r\n```\r\n- Initialize the `DataManager` to store and manage input/ref data. \r\n- Load the DEM and resample to the specified grid size. \r\n- Load reference data (`ref`), forcing data (`RAIN`, `TEMP`), and initial state. \r\n- `time_index` can be used to specify a range or a single timestep (if omitted, all timesteps are used). \r\n\r\n---\r\n\r\n### 2. Model Construction\r\n```python\r\nbucket = BucketUpdater().to(device)\r\nmodel = EcoHydroModel({'bucket': bucket}, device=device)\r\nvar = 'storage'\r\n```\r\n- Define a simple process module (`BucketUpdater`). \r\n- Construct the `EcoHydroModel` with the module dictionary. \r\n- Specify the target variable (`storage`) for training and evaluation. \r\n\r\n---\r\n\r\n### 3. Test Run\r\n```python\r\nmodel.eval()\r\nwith torch.no_grad():\r\n out = model(data)\r\n\r\nVisualizer.plot(out[var], pos=data.pos)\r\nVisualizer.plot_similarity(out[var], data.ref[var], pos=data.pos)\r\nVisualizer.plot_timeseries(out[var], data.ref[var], node_idx=0)\r\n```\r\n- Run the model with default setting in evaluation mode to generate predictions. \r\n- Visualize spatial patterns, similarity with reference data, and node-level time series. \r\n\r\n---\r\n\r\n### 4. Training\r\n```python\r\nprint(\"Start training...\")\r\nfinal_params = Trainer(model).train(\r\n data, epochs=100, lr=1e-2, chunk_size=1, target_keys=[var]\r\n)\r\nprint('Final params:', final_params)\r\n```\r\n- Train the model with the given dataset for 100 epochs. \r\n- Use a simple trainer with learning rate `1e-2` and chunk size of 1. \r\n- Print the final optimized parameters after training. \r\n\r\n---\r\n\r\n### 5. Evaluation & Visualization\r\n```python\r\nmodel.eval()\r\nwith torch.no_grad():\r\n out = model(data)\r\n\r\nVisualizer.plot(out[var], pos=data.pos)\r\nVisualizer.plot_similarity(out[var], data.ref[var], pos=data.pos)\r\nVisualizer.plot_timeseries(out[var], data.ref[var], node_idx=0)\r\n```\r\n- Evaluate the trained model. \r\n- Generate the same set of visualizations as in the reference run, enabling a direct comparison between model predictions and reference data. \r\n\r\n---\r\n\r\n## \ud83d\udd27 Advanced Usage ([example_full.py](tests/example_full.py))\r\n\r\nThis example shows **graph coarsening**, **multi-module wiring**, and **constrained parameter tuning**. \r\nFor a full step-by-step description, see the [detailed manual of example](docs/Full_example.md).\r\n\r\n### Highlights\r\n- Graph coarsening to switch between resolutions\r\n- Multiple updaters (e.g., `NitriUpdater`, `MLPUpdater`) \r\n- Parameter range constraints during training \r\n- Targeted training on selected variables/time windows \r\n\r\n",
"bugtrack_url": null,
"license": "MIT License\r\n \r\n Copyright (c) 2025 Long Jiang\r\n \r\n Permission is hereby granted, free of charge, to any person obtaining a copy\r\n of this software and associated documentation files (the \"Software\"), to deal\r\n in the Software without restriction, including without limitation the rights\r\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n copies of the Software, and to permit persons to whom the Software is\r\n furnished to do so, subject to the following conditions:\r\n \r\n The above copyright notice and this permission notice shall be included in all\r\n copies or substantial portions of the Software.\r\n \r\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n SOFTWARE.\r\n ",
"summary": "A framework built on PyTorch for eco-hydrological modeling",
"version": "0.1.0.post5",
"project_urls": null,
"split_keywords": [
"hydrology",
" ecohydro",
" modeling"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8c85a304d6119079704cc9163a828514367287043af861d98429576156af70ed",
"md5": "028cc3c2b749ed4be43ccb23eb6f484e",
"sha256": "75f0b210720dbcca3ab20d7d6e8d0d5c9d22027afad3e246347c3c6db5cb3fb2"
},
"downloads": -1,
"filename": "ecohydromodel-0.1.0.post5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "028cc3c2b749ed4be43ccb23eb6f484e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13930,
"upload_time": "2025-09-04T00:08:04",
"upload_time_iso_8601": "2025-09-04T00:08:04.605643Z",
"url": "https://files.pythonhosted.org/packages/8c/85/a304d6119079704cc9163a828514367287043af861d98429576156af70ed/ecohydromodel-0.1.0.post5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5dcd336d5329945982efeb61634d4e2a4551990ba862a4a94f24fff87a1eb454",
"md5": "130bfe0b9827e8019f0c617e4c98249f",
"sha256": "f2e0e8dc800789836c6c69ee5accb582fb807a040ecd2809cf05b3dc86b4e320"
},
"downloads": -1,
"filename": "ecohydromodel-0.1.0.post5.tar.gz",
"has_sig": false,
"md5_digest": "130bfe0b9827e8019f0c617e4c98249f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 14198589,
"upload_time": "2025-09-04T00:08:06",
"upload_time_iso_8601": "2025-09-04T00:08:06.960789Z",
"url": "https://files.pythonhosted.org/packages/5d/cd/336d5329945982efeb61634d4e2a4551990ba862a4a94f24fff87a1eb454/ecohydromodel-0.1.0.post5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 00:08:06",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ecohydromodel"
}
