Skip to content

JGCRI/superwell

Repository files navigation

superwell: A physics-based hydro-economic model for groundwater cost and supply assessment

The superwell model provides estimates of the global extractable volumes and unit-costs $(USD/km^3)$ of accessible groundwater production under user-specified extraction scenarios.
The structure of superwell is:

  • input driven
  • fast, flexible and robust
  • spatially and temporally flexible (covers grid to global and hourly to centennial scales)

Key model documentation & primary citation:
Niazi, H., Ferencz, S., Graham, N., Yoon, J., Wild, T., Hejazi, M., Watson, D., & Vernon, C. (2024; In-prep). Long-term Hydro-economic Assessment Tool for Evaluating Global Groundwater Cost and Supply: Superwell v1. Geoscientific Model Development.

Getting Started

superwell can be installed directly from its GitHub repository by simply cloning it. Run the following from command prompt or any terminal that supports git commands:

git clone https://github.com/JGCRI/superwell.git

Run superwell

Navigate to python/ and run superwell with deepening script to simulate using default settings and scenario assumptions. Installing python and key libraries is evidently a pre-requisite.

Adjust params.csv in inputs/ folder to fit your scenario design needs. The script will automatically populate results in outputs/ folder.

Conceptual Overview

superwell conceptual overview

Inputs

All inputs are in inputs/ folder. The superwell code requires two primary input files:

  • params.csv defining model settings and scenario assumptions
  • inputs.csv containing grided aquifer thickness, porosity, depth to water, permeability, grid area, WHY class, and grid area

and two supporting data files:

inputs/ folder also contains digitized, geo-processed shape files of aquifer properties that makes the contents of the inputs.csv file after processing.

Cite input data as:
Niazi, H., Watson, D., Hejazi, M., Yonkofski, C., Ferencz, S., Vernon, C., Graham, N., Wild, T., & Yoon, J. (2024). Global Geo-processed Data of Aquifer Properties by 0.5° Grid, Country and Water Basins. MSD-LIVE Data Repository. https://doi.org/10.57931/2307831
DOI

See documentation on inputs for more details.

Outputs

All outputs are written to outputs/ folder as .csv formats. A select-few key outputs include: extractable volumes, drawdown, number of wells, costs including capital, maintenance, pumping, and unit costs of groundwater production.

Cite output data as:
Niazi, H., Ferencz, S., Yoon, J., Graham, N., Wild, T., Hejazi, M., Watson, D., & Vernon, C. (2024). Globally Gridded Groundwater Extraction Volumes and Costs under Six Depletion and Ponded Depth Targets. MSD-LIVE Data Repository. https://doi.org/10.57931/2307832
DOI

See documentation on outputs for more details.

Structure

Folder structure of superwell is as follows:

Folder Description
inputs/ contains necessary input data files and scripts to generate them
python/ contains main superwell python scripts (e.g., superwell_deepening.py)
outputs/ default folder where results are saved
processing/ contains diagnostics and post-processing scripts, along with key figures
R/ contains .R script for the old version of the model
man/ package documentation of functions
tests/ test scripts to verify the correct functioning of the model's components

Key References

Several high-impact publications and data products have utilized superwell to inform groundwater unit costs to discover key interactions and dynamics within coupled human-Earth systems.

Papers

Model documentation

Contribute

Reach out to Hassan Niazi or Stephen Ferencz or open an issue in this repository for questions or suggestions.

Stay Super Well! 😎