pynearshore 2.0.0
Nearshore wave propagation, currents, and sediment transport modeling
Requires Python: >=3.7
Keywords: coastal engineering, wave propagation, sediment transport, nearshore dynamics, wave breaking, Goda model, Battjes-Janssen, Bailard model, numerical methods, Runge-Kutta, oceanography

# PyNearshore

Python package for nearshore wave propagation, currents, and sediment transport modeling.

## Features

- Wave propagation with refraction, shoaling, and breaking
- Wave-induced nearshore currents
- Sediment transport (Bailard 1981 energetics model)
- Multiple breaking models (Goda, depth-limited)
- Energy dissipation (Battjes-Janssen, Thornton-Guza)
- Adaptive numerical solvers (RK4, RK45, DOP853)

## Installation

```bash
pip install pynearshore
```

Or from source:
```bash
git clone https://github.com/pavlishenku/pynearshore.git
cd pynearshore
pip install -e .
```

## Quick Start

```python
from pynearshore import CoastalWaveModel

# Create model
model = CoastalWaveModel()

# Define conditions
data = {
    'wave': {'H13': 2.0, 'PERIOD': 10.0, 'TETAH': 15.0},
    'water': {'NIVMAR': 0.0},
    'wind': {'W': 5.0, 'TETAW': 0.0},
    'sediment': {'ROS': 2650, 'WC': 0.04, 'PHI': 32, 'EPSB': 0.1, 'EPSS': 0.02},
    'numerical': {'CF': 0.01, 'PAS': 10.0, 'GAMMA': 0.78, 'LAMBDA': 43.0},
    'bathymetry': {
        'XZ': [2000, 1000, 500, 0],
        'Z': [20, 10, 5, 0],
    },
}

# Run simulation
params = model.load_data(data)
results = model.solve()

# Save results
model.save_results('results.csv')

# Print transport
print(f"Sediment transport: {results['total_transport_m3_per_s'] * 86400:.1f} m³/day")
```

## Physical Models

### Wave Transformation
- Linear wave theory with currents
- Snell's law refraction
- Shoaling on variable bathymetry
- Breaking: Goda (1970, 1985) or depth-limited

### Energy Dissipation
- Battjes & Janssen (1978) - Wave breaking
- Thornton & Guza (1983) - Probabilistic breaking
- Barailler - Gradual slopes

### Currents
- Orbital velocities (linear theory)
- Longshore currents (radiation stress)
- Wind stress (Wu 1982)
- Bottom friction
- Coriolis force

### Sediment Transport
- Bailard (1981) energetics model
- Bedload and suspended load
- Integration via Simpson's rule

## Requirements

- Python >= 3.7
- numpy >= 1.19.0
- scipy >= 1.5.0

## Testing

```bash
pytest tests/ -v
```

## Examples

See `examples/` directory:
- `example_basic_usage.py` - Simple simulation
- `example_solver_comparison.py` - Compare numerical solvers
- `test_complete_implementation.py` - Full validation

## Documentation

### Input Parameters

**Wave**:
- `H13`: Significant wave height (m)
- `PERIOD`: Peak wave period (s)
- `TETAH`: Incident angle (degrees)

**Bathymetry**:
- `XZ`: Cross-shore distances (m, decreasing)
- `Z`: Water depths (m, positive)

**Sediment**:
- `ROS`: Sediment density (kg/m³, ~2650 for sand)
- `WC`: Fall velocity (m/s, ~0.04 for fine sand)
- `PHI`: Friction angle (degrees, ~32 for sand)
- `EPSB`: Bedload efficiency (0.05-0.15)
- `EPSS`: Suspended load efficiency (0.01-0.03)

**Numerical**:
- `PAS`: Spatial step (m, 5-20)
- `GAMMA`: Breaking parameter (0.78 default)
- `CF`: Bottom friction (0.005-0.02)

### Output

Results dictionary contains:
- `rms_wave_height_m`: Wave heights
- `wave_angle_deg`: Wave angles
- `current_velocity_m_per_s`: Currents
- `water_elevation_m`: Setup/setdown
- `local_transport_m3_per_m_per_s`: Local sediment transport
- `total_transport_m3_per_s`: Total transport

## Citation

If you use this software, please cite:

```
Pavlishenku (2025). PyNearshore: A Python package for nearshore 
wave propagation and sediment transport modeling.
GitHub: https://github.com/pavlishenku/pynearshore
```

## Scientific References

- Battjes, J.A., & Janssen, J.P.F.M. (1978). Energy loss and set-up due to breaking of random waves.
- Goda, Y. (1970). A synthesis of breaker indices.
- Thornton, E.B., & Guza, R.T. (1983). Transformation of wave height distribution.
- Bailard, J.A. (1981). An energetics total load sediment transport model.
- Longuet-Higgins, M.S., & Stewart, R.W. (1964). Radiation stresses in water waves.
- Wu, J. (1982). Wind-stress coefficients over sea surface.

## License

MIT License - see LICENSE file

## Author

**Pavlishenku**  
Email: pavlishenku@gmail.com

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

## Support

- Issues: GitHub issue tracker
- Email: pavlishenku@gmail.com