# GoldSim-MODFLOW Interface

**Educational groundwater modeling with GSPy and FloPy**

This package provides a clean interface for coupling GoldSim with MODFLOW using GSPy (GoldSim's Python interface) and FloPy (Python MODFLOW package). It features a Tutorial 2 style confined aquifer setup that produces clear, predictable groundwater responses to pumping.

## Quick Start

1. **Install Python dependencies**: `pip install -r requirements.txt`
2. **Test the interface**: `python goldsim_interface.py`
3. **Set up GoldSim External Element** (see QUICK_START.md for details)

## What's Included

### Core Files
- `goldsim_interface.py` - Main GoldSim entry point
- `responsive_interface.py` - Core MODFLOW interface
- `gspy_modflow.json` - GSPy configuration
- `mf2005.exe` - MODFLOW executable
- `requirements.txt` - Python dependencies

### Folders
- `examples/` - Example scripts and demonstrations
- `development/` - Development files and prototypes
- `docs/` - Documentation and blog posts

## Model Overview

### Grid and Domain
- **Grid Size**: 21×21 cells (441 total cells)
- **Cell Size**: 100m × 100m (2.1km × 2.1km total domain)
- **Layers**: 1 confined aquifer layer (50m thick)
- **Boundaries**: Constant head (40m) on all edges (like surrounding lakes/rivers)
- **Active Cells**: 19×19 = 361 interior cells

### Well and Monitoring Configuration
- **Well Location**: Typically at (3,4) in northwest quadrant
- **Northwest Monitor (4,6)**: ~280m from well - maximum response
- **Center Monitor (10,10)**: ~850m from well - moderate response
- **Southeast Monitor (13,13)**: ~1270m from well - minimum response

### Temporal Setup
- **Simulation Period**: 30 days per GoldSim call
- **Time Steps**: 30 daily time steps within each month
- **State Persistence**: Groundwater levels carry forward between months within each simulation
- **Simulation Detection**: Automatically resets for new GoldSim scenarios (>10 second gap)

### Model Grid Layout
```
     0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20
 0   C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  ← Constant head (40m)
 1   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
 2   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
 3   C  .  .  .  W  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C  ← W = Well (3,4)
 4   C  .  .  .  .  .  M  .  .  .  .  .  .  .  .  .  .  .  .  .  C  ← M = NW monitor (4,6)
 5   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
 6   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
 7   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
 8   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
 9   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
10   C  .  .  .  .  .  .  .  .  .  M  .  .  .  .  .  .  .  .  .  C  ← M = Center monitor (10,10)
11   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
12   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
13   C  .  .  .  .  .  .  .  .  .  .  .  .  M  .  .  .  .  .  .  C  ← M = SE monitor (13,13)
14   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
15   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
16   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
17   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
18   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
19   C  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  C
20   C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  C  ← Constant head (40m)
```

**Legend:** C = Constant head boundary (40m), . = Active aquifer cells, W = Pumping well, M = Monitoring points

## GoldSim Interface Configuration

### Required Inputs (6 parameters)

| Input # | Parameter      | Type   | Units  | Typical Range | Description                                    |
| ------- | -------------- | ------ | ------ | ------------- | ---------------------------------------------- |
| 1       | `pumping_rate` | Scalar | m³/day | 0-3000        | Well pumping rate (positive = pumping out)    |
| 2       | `recharge_rate`| Scalar | m³/day | 0-10000       | Total recharge volume (usually 0 for demos)   |
| 3       | `well_row`     | Scalar | -      | 1-19          | Well row location (3 for northwest quadrant)  |
| 4       | `well_col`     | Scalar | -      | 1-19          | Well column location (4 for northwest quadrant)|
| 5       | `hydraulic_k`  | Scalar | m/day  | 5-20          | Hydraulic conductivity (10 = Tutorial 2 style)|
| 6       | `specific_yield`| Scalar| -      | 0.1-0.3       | Ignored for confined aquifer                   |

### Outputs

| Output | Parameter        | Type   | Units | Description                                    |
| ------ | ---------------- | ------ | ----- | ---------------------------------------------- |
| 1      | `northwest_head` | Scalar | m     | Head at northwest monitoring point (4,6)      |
| 2      | `center_head`    | Scalar | m     | Head at center monitoring point (10,10)       |
| 3      | `southeast_head` | Scalar | m     | Head at southeast monitoring point (13,13)    |

## Expected Results (Tutorial 2 Style)

### Typical Drawdown Response
- **No pumping**: 40.00m everywhere
- **500 m³/day**: 0.64m drawdown at well, 0.07m at NW monitor, 0.15m at SE monitor
- **1000 m³/day**: 1.27m drawdown at well, 0.13m at NW monitor, 0.30m at SE monitor
- **2000 m³/day**: 2.54m drawdown at well, 0.26m at NW monitor, 0.59m at SE monitor

### Key Features
- **Linear response**: Drawdown proportional to pumping rate
- **Radial pattern**: Symmetric drawdown around well
- **Monthly persistence**: Each month builds on previous results
- **Automatic reset**: Fresh start for new GoldSim scenarios

## Dependencies and Related Work

This implementation relies on:
- **FloPy**: A Python package for creating, running, and post-processing MODFLOW models, developed and maintained by the USGS
- **GSPy**: GoldSim's Python interface for communication between GoldSim and Python functions. See the [GSPy project](https://github.com/GoldSim/GSPy) for detailed setup and requirements.

For comprehensive applications, refer to GoldSim's [Dynamic Coupling framework](https://support.goldsim.com/hc/en-us/articles/216179218-Dynamic-Coupling-of-GoldSim-and-MODFLOW-MT3D).

## Files

### Dependencies
```
Python 3.14 (required for GSPy)
flopy>=3.3.6
numpy>=1.21.0
```

### Auto-generated Files
- `responsive_state.pkl` - Persistent state (auto-generated)
- `responsive.*` - MODFLOW input/output files (auto-generated)

## Technical Notes

- **Aquifer Type**: Confined (constant thickness)
- **Boundary Conditions**: Constant head (40m) on all edges
- **Solver**: PCG (Preconditioned Conjugate Gradient)
- **Coordinate System**: (0,0) = northwest corner
- **Units**: All heads in meters, rates in m³/day
- **Time Convention**: 30-day months

---

*This interface provides clean, predictable groundwater responses perfect for demonstrating pumping effects in GoldSim models.*