# 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
Raw data
{
"_id": null,
"home_page": "https://github.com/pavlishenku/pynearshore",
"name": "pynearshore",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "coastal engineering, wave propagation, sediment transport, nearshore dynamics, wave breaking, Goda model, Battjes-Janssen, Bailard model, numerical methods, Runge-Kutta, oceanography",
"author": "Pavlishenku",
"author_email": "pavlishenku@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/05/af/da1556be25429d40e10580d0b0b070cf48482439140b0330398cb5d7b0af/pynearshore-2.0.0.tar.gz",
"platform": null,
"description": "# PyNearshore\r\n\r\nPython package for nearshore wave propagation, currents, and sediment transport modeling.\r\n\r\n## Features\r\n\r\n- Wave propagation with refraction, shoaling, and breaking\r\n- Wave-induced nearshore currents\r\n- Sediment transport (Bailard 1981 energetics model)\r\n- Multiple breaking models (Goda, depth-limited)\r\n- Energy dissipation (Battjes-Janssen, Thornton-Guza)\r\n- Adaptive numerical solvers (RK4, RK45, DOP853)\r\n\r\n## Installation\r\n\r\n```bash\r\npip install pynearshore\r\n```\r\n\r\nOr from source:\r\n```bash\r\ngit clone https://github.com/pavlishenku/pynearshore.git\r\ncd pynearshore\r\npip install -e .\r\n```\r\n\r\n## Quick Start\r\n\r\n```python\r\nfrom pynearshore import CoastalWaveModel\r\n\r\n# Create model\r\nmodel = CoastalWaveModel()\r\n\r\n# Define conditions\r\ndata = {\r\n 'wave': {'H13': 2.0, 'PERIOD': 10.0, 'TETAH': 15.0},\r\n 'water': {'NIVMAR': 0.0},\r\n 'wind': {'W': 5.0, 'TETAW': 0.0},\r\n 'sediment': {'ROS': 2650, 'WC': 0.04, 'PHI': 32, 'EPSB': 0.1, 'EPSS': 0.02},\r\n 'numerical': {'CF': 0.01, 'PAS': 10.0, 'GAMMA': 0.78, 'LAMBDA': 43.0},\r\n 'bathymetry': {\r\n 'XZ': [2000, 1000, 500, 0],\r\n 'Z': [20, 10, 5, 0],\r\n },\r\n}\r\n\r\n# Run simulation\r\nparams = model.load_data(data)\r\nresults = model.solve()\r\n\r\n# Save results\r\nmodel.save_results('results.csv')\r\n\r\n# Print transport\r\nprint(f\"Sediment transport: {results['total_transport_m3_per_s'] * 86400:.1f} m\u00b3/day\")\r\n```\r\n\r\n## Physical Models\r\n\r\n### Wave Transformation\r\n- Linear wave theory with currents\r\n- Snell's law refraction\r\n- Shoaling on variable bathymetry\r\n- Breaking: Goda (1970, 1985) or depth-limited\r\n\r\n### Energy Dissipation\r\n- Battjes & Janssen (1978) - Wave breaking\r\n- Thornton & Guza (1983) - Probabilistic breaking\r\n- Barailler - Gradual slopes\r\n\r\n### Currents\r\n- Orbital velocities (linear theory)\r\n- Longshore currents (radiation stress)\r\n- Wind stress (Wu 1982)\r\n- Bottom friction\r\n- Coriolis force\r\n\r\n### Sediment Transport\r\n- Bailard (1981) energetics model\r\n- Bedload and suspended load\r\n- Integration via Simpson's rule\r\n\r\n## Requirements\r\n\r\n- Python >= 3.7\r\n- numpy >= 1.19.0\r\n- scipy >= 1.5.0\r\n\r\n## Testing\r\n\r\n```bash\r\npytest tests/ -v\r\n```\r\n\r\n## Examples\r\n\r\nSee `examples/` directory:\r\n- `example_basic_usage.py` - Simple simulation\r\n- `example_solver_comparison.py` - Compare numerical solvers\r\n- `test_complete_implementation.py` - Full validation\r\n\r\n## Documentation\r\n\r\n### Input Parameters\r\n\r\n**Wave**:\r\n- `H13`: Significant wave height (m)\r\n- `PERIOD`: Peak wave period (s)\r\n- `TETAH`: Incident angle (degrees)\r\n\r\n**Bathymetry**:\r\n- `XZ`: Cross-shore distances (m, decreasing)\r\n- `Z`: Water depths (m, positive)\r\n\r\n**Sediment**:\r\n- `ROS`: Sediment density (kg/m\u00b3, ~2650 for sand)\r\n- `WC`: Fall velocity (m/s, ~0.04 for fine sand)\r\n- `PHI`: Friction angle (degrees, ~32 for sand)\r\n- `EPSB`: Bedload efficiency (0.05-0.15)\r\n- `EPSS`: Suspended load efficiency (0.01-0.03)\r\n\r\n**Numerical**:\r\n- `PAS`: Spatial step (m, 5-20)\r\n- `GAMMA`: Breaking parameter (0.78 default)\r\n- `CF`: Bottom friction (0.005-0.02)\r\n\r\n### Output\r\n\r\nResults dictionary contains:\r\n- `rms_wave_height_m`: Wave heights\r\n- `wave_angle_deg`: Wave angles\r\n- `current_velocity_m_per_s`: Currents\r\n- `water_elevation_m`: Setup/setdown\r\n- `local_transport_m3_per_m_per_s`: Local sediment transport\r\n- `total_transport_m3_per_s`: Total transport\r\n\r\n## Citation\r\n\r\nIf you use this software, please cite:\r\n\r\n```\r\nPavlishenku (2025). PyNearshore: A Python package for nearshore \r\nwave propagation and sediment transport modeling.\r\nGitHub: https://github.com/pavlishenku/pynearshore\r\n```\r\n\r\n## Scientific References\r\n\r\n- Battjes, J.A., & Janssen, J.P.F.M. (1978). Energy loss and set-up due to breaking of random waves.\r\n- Goda, Y. (1970). A synthesis of breaker indices.\r\n- Thornton, E.B., & Guza, R.T. (1983). Transformation of wave height distribution.\r\n- Bailard, J.A. (1981). An energetics total load sediment transport model.\r\n- Longuet-Higgins, M.S., & Stewart, R.W. (1964). Radiation stresses in water waves.\r\n- Wu, J. (1982). Wind-stress coefficients over sea surface.\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file\r\n\r\n## Author\r\n\r\n**Pavlishenku** \r\nEmail: pavlishenku@gmail.com\r\n\r\n## Contributing\r\n\r\nContributions welcome! Please:\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Add tests for new features\r\n4. Submit a pull request\r\n\r\n## Support\r\n\r\n- Issues: GitHub issue tracker\r\n- Email: pavlishenku@gmail.com\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Nearshore wave propagation, currents, and sediment transport modeling",
"version": "2.0.0",
"project_urls": {
"Bug Reports": "https://github.com/pavlishenku/pynearshore/issues",
"Homepage": "https://github.com/pavlishenku/pynearshore",
"Source": "https://github.com/pavlishenku/pynearshore"
},
"split_keywords": [
"coastal engineering",
" wave propagation",
" sediment transport",
" nearshore dynamics",
" wave breaking",
" goda model",
" battjes-janssen",
" bailard model",
" numerical methods",
" runge-kutta",
" oceanography"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ccc90a7ae41b1ea07a90a031f8171e85cd94adee823ac97bf60b35cc82986588",
"md5": "730d6dbe0c5ee03619d39fb5c1fb4b88",
"sha256": "29d0720189bdf06d27123ca1a6fb597d8fbe984455976cd6f1dca454dfa979f8"
},
"downloads": -1,
"filename": "pynearshore-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "730d6dbe0c5ee03619d39fb5c1fb4b88",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 50585,
"upload_time": "2025-10-24T21:27:15",
"upload_time_iso_8601": "2025-10-24T21:27:15.980785Z",
"url": "https://files.pythonhosted.org/packages/cc/c9/0a7ae41b1ea07a90a031f8171e85cd94adee823ac97bf60b35cc82986588/pynearshore-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "05afda1556be25429d40e10580d0b0b070cf48482439140b0330398cb5d7b0af",
"md5": "13b6900152f482141d16e67e03c7c7a7",
"sha256": "a4d6b2fe6f9121a1c8843e07f26348b8182858ff3dadf2038b6cbcabf629ba7b"
},
"downloads": -1,
"filename": "pynearshore-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "13b6900152f482141d16e67e03c7c7a7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 44545,
"upload_time": "2025-10-24T21:27:17",
"upload_time_iso_8601": "2025-10-24T21:27:17.656686Z",
"url": "https://files.pythonhosted.org/packages/05/af/da1556be25429d40e10580d0b0b070cf48482439140b0330398cb5d7b0af/pynearshore-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 21:27:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pavlishenku",
"github_project": "pynearshore",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.19.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.5.0"
]
]
}
],
"lcname": "pynearshore"
}
JSON
