Interactive Groundwater Gradient Calculator

A Python implementation of the US EPA ITRC groundwater gradient calculator, originally developed by Dr. Jim Weaver at the EPA's National Exposure Research Laboratory. This application converts the original JavaScript calculator into a modern Python web application with interactive 3D visualization.

Overview

This application calculates hydraulic gradient magnitude and flow direction by fitting a plane to groundwater head measurements from monitoring wells. It supports both confined and unconfined aquifers, handles unit conversions, and provides interactive 3D visualization of the data and calculated gradient.

Key Features

• Interactive Web Interface: Built with Dash/Plotly for real-time gradient calculation
• 3D Visualization: Interactive plots showing wells, fitted plane, and gradient vector
• Multiple Aquifer Types: Supports both confined and unconfined aquifer calculations
• Unit Flexibility: Handles both metric (meters) and imperial (feet) units
• Well Selection: Include/exclude specific wells from calculations via checkboxes
• Example Datasets: Two pre-loaded examples for testing and demonstration
• Real-time Updates: Calculations update automatically as data is modified

Project Structure

gradient_py/
├── app.py              # Dash web application
├── gradient.py         # Core gradient calculation class
├── requirements.txt    # Python dependencies
├── gradient4plus-ns_1.js  # Original EPA JavaScript implementation
└── README.md          # This file

Core Components

GradientCalculator Class (gradient.py)

The main calculation engine that:

• Fits a plane to 3D point data using least squares regression
• Calculates gradient magnitude and flow direction
• Handles unit conversions and aquifer type adjustments
• Provides standalone plotting capabilities
• Supports up to 30 monitoring wells

Dash Web Application (app.py)

Interactive web interface featuring:

• Editable data table for well coordinates and head values
• Real-time 3D plotting with Plotly
• Unit selection dropdowns
• Aquifer type selection
• Well inclusion/exclusion via row selection
• Pre-loaded example datasets
• Gradient results summary

Installation and Setup

Prerequisites

• Python 3.7 or higher
• pip package manager

Local Installation

1. Clone or download the repository:

   git clone <repository-url>
   cd gradient_py

2. Install dependencies:

   pip install -r requirements.txt

3. Run the application:

   python app.py

4. Open your browser to:

   http://127.0.0.1:8050
   

Alternative: Virtual Environment Setup

# Create virtual environment
python -m venv gradient_env

# Activate virtual environment
# Windows:
gradient_env\Scripts\activate
# Mac/Linux:
source gradient_env/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run application
python app.py

Usage

Web Application

1. Load Example Data: Click "Load Example 1" or "Load Example 2" to start with sample datasets
2. Edit Well Data: Modify coordinates and head values directly in the table
3. Select Wells: Use checkboxes to include/exclude specific wells from calculations
4. Configure Settings: Choose units (meters/feet) and aquifer type (confined/unconfined)
5. View Results: Gradient magnitude, direction, and fit quality are displayed automatically
6. 3D Visualization: Interact with the 3D plot to examine wells, fitted plane, and gradient vector

Standalone Usage

from gradient import GradientCalculator

# Example data
x = [100, 0, 100, 100, 0, 100]
y = [0, 100, 100, 0, 100, 100]
h = [20, 20, 19.75, 20, 20, 19.75]

# Calculate gradient
gc = GradientCalculator(x, y, h, head_unit='ft', dist_unit='ft', aquifer_type='confined')

# Display results
gc.summary()

# Show 3D plot
gc.plot()

Output Interpretation

• Gradient Magnitude: Unitless value representing the slope of the water table
• Flow Direction: Degrees from North (positive Y-axis) indicating steepest descent direction
• R²: Coefficient of determination showing how well the plane fits the data
• Head Range: Difference between highest and lowest head measurements

Example Datasets

Example 1 (ITRC Reference Dataset)

Based on the original EPA ITRC example from August 2005:

• 10 monitoring wells
• Large coordinate values (UTM-style)
• Produces gradient magnitude ≈ 0.0019
• Flow direction ≈ 37.78° from North

Example 2 (Synthetic Dynamic Dataset)

Simplified dataset showing clear gradient pattern:

• 8 monitoring wells
• Simple coordinate system (0-150 range)
• More pronounced gradient for demonstration

Deployment Options

Local Development

python app.py

Access at http://127.0.0.1:8050

Plotly Cloud Deployment

The application is configured for Plotly Cloud deployment with:

• server = app.server declaration in app.py
• Under 80 MiB total file size
• All dependencies in requirements.txt

To deploy to Plotly Cloud:

1. Create account at https://chart-studio.plotly.com/
2. Install Plotly CLI: pip install plotly
3. Configure credentials: plotly setup
4. Deploy: plotly deploy

Other Deployment Options

Heroku:

# Add Procfile
echo "web: python app.py" > Procfile
# Deploy via Heroku CLI

Docker:

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8050
CMD ["python", "app.py"]

AWS/Azure/GCP:

• Deploy as containerized application
• Use platform-specific Python hosting services

Technical Details

Calculation Method

The gradient calculation follows the EPA ITRC methodology:

1. Plane Fitting: Uses least squares regression to fit h = ax + by + c to the data
2. Gradient Calculation:
   • Magnitude: √(a² + b²)
   • Direction: arctan2(-a, -b) converted to degrees from North
3. Unit Handling: Converts to meters internally, preserves original units for display
4. Aquifer Type: For unconfined aquifers, uses h² instead of h in calculations

Coordinate System

• X-axis: Eastward (positive to the right)
• Y-axis: Northward (positive upward)
• Flow Direction: Measured clockwise from North (positive Y-axis)
• Gradient Vector: Points in direction of steepest descent (water flow direction)

Data Requirements

• Minimum: 3 wells required for plane fitting
• Maximum: 30 wells supported
• Coordinate Format: Any consistent coordinate system (UTM, State Plane, local grid)
• Head Values: Hydraulic head measurements in consistent units

Troubleshooting

Common Issues

1. "Insufficient Wells" Message: Ensure at least 3 wells are selected (checked) in the table
2. Poor R² Values: Check for data entry errors or wells that don't follow a planar trend
3. Unexpected Gradient Direction: Verify coordinate system and North direction
4. Unit Conversion Issues: Ensure consistent units within each measurement type

Performance Tips

• For large datasets, consider using a subset of representative wells
• Ensure good spatial distribution of wells for best plane fitting
• Remove obvious outliers that may skew the gradient calculation

References

• Original EPA ITRC implementation by Dr. Jim Weaver, EPA National Exposure Research Laboratory
• Available at: https://www3.epa.gov/ceampubl/learn2model/part-two/onsite/gradient4plus-ns.html
• ITRC Technical Guidelines for Groundwater Monitoring

License

This implementation is based on public domain EPA software and is provided for educational and research purposes.

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

Contact

For questions about the original methodology, refer to the EPA ITRC documentation. For issues with this Python implementation, please use the project's issue tracker.