https://github.com/csiro/cmextremes-xb2xbg
Python script to convert XBeach parameter files for use with XBeach-GPU. It can also be used to generate default XBeach-GPU parameters.
https://github.com/csiro/cmextremes-xb2xbg
Last synced: 5 months ago
JSON representation
Python script to convert XBeach parameter files for use with XBeach-GPU. It can also be used to generate default XBeach-GPU parameters.
- Host: GitHub
- URL: https://github.com/csiro/cmextremes-xb2xbg
- Owner: csiro
- License: mit
- Created: 2025-06-19T03:31:53.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-06-24T05:42:30.000Z (12 months ago)
- Last Synced: 2025-09-04T19:08:40.586Z (9 months ago)
- Language: Python
- Homepage:
- Size: 79.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
### Overview
Python script to convert XBeach parameter files for use with XBeach-GPU. It can also be used to generate default XBeach-GPU parameters.
Cyprien Bosserelle is the creator of XBeach-GPU which is available in [GitHub](https://github.com/CyprienBosserelle/xbeach_gpu). See also the main [XBeach-GPU](https://cyprienbosserelle.github.io/xbeach_gpu) page for more information.
An ordinary (non-"reuse") JONSWAP file listed in an XBeach parameters file will also be converted. A directional spread coefficient can be specified to be used in the converted JONSWAP file. Any bathymetry file with `.z` suffix will be replaced with `.dep`. In addition, sea-level and wind boundary files will also be copied to the specified output location.
Requires Python 3.7 or higher.
#### Usage
python3 xb2xbg.py -h
usage: xb2xbg.py [-h] [--xb-params-path XB_PARAMS_PATH] [--xb-file-root XB_FILE_ROOT] [--xbg-output-dir XBG_OUTPUT_DIR]
[--xbg-user-manual XBG_USER_MANUAL] [--directional-spread-coefficient DIRECTIONAL_SPREAD_COEFFICIENT]
[--peak-enhancement-factor PEAK_ENHANCEMENT_FACTOR] [--gen-doc] [--gen-defaults] [--verbose]
[--use-all-known-output-variables]
Convert XB params file for use with XBG.
optional arguments:
-h, --help show this help message and exit
--xb-params-path XB_PARAMS_PATH, -b XB_PARAMS_PATH
XB params input file path
--xb-file-root XB_FILE_ROOT, -r XB_FILE_ROOT
XB input file (e.g. bcfile) root. We allow XB parameter file location and input file locations to
vary; if specified, will apply to all input files within XB parameters file
--xbg-output-dir XBG_OUTPUT_DIR, -p XBG_OUTPUT_DIR
XBG params output file directory
--xbg-user-manual XBG_USER_MANUAL, -m XBG_USER_MANUAL
XBG user manual HTML input file path or URL
--directional-spread-coefficient DIRECTIONAL_SPREAD_COEFFICIENT, -s DIRECTIONAL_SPREAD_COEFFICIENT
Directional spread coefficient (default: 400)
--peak-enhancement-factor PEAK_ENHANCEMENT_FACTOR, -e PEAK_ENHANCEMENT_FACTOR
Peak enhancement factor (default: 3.3)
--gen-doc, -g Generate documentation strings along with parameters
--gen-defaults, -d Generate all XBG default parameters (this argument overrides --xb-params)
--verbose, -v Verbose output mode
--use-all-known-output-variables, -u
Allow all known XBG output variables to be used, irrespective of uncertainty of relationship to XB
#### Example Invocations
# convert XB parameters, generating XBG_params.txt
python xb2xbg.py --xb-params-path=data/example-XBeach-params.txt
# as above, but with verbose output
python xb2xbg.py --xb-params-path=data/example-XBeach-params.txt --verbose
# also add docs per parameter and output variable where they exist
python xb2xbg.py --xb-params-path=data/example-XBeach-params.txt --verbose --gen-doc
# XB input files will have "data" prepended to path found in XB parameters file
# and XBG files (e.g. XBG parameters, jonswap) will go into the `xbg` directory
python xb2xbg.py --xb-params-path=data/example-XBeach-params.txt --xb-file-root=data --xbg-output-dir=xbg
# default XBG parameters will be generated instead of those values that would normally
# be converted from XB
python xb2xbg.py --xb-params-path=data/example-XBeach-params.txt --gen-defaults
# directional spread coefficient for use in jonswap file conversion; defaults to 400
python xb2xbg.py --xb-params-path=data/example-XBeach-params.txt --directional-spread-coefficient=300
# peak enhancement factor for use in jonswap file conversion; defaults to 3.3
python3 xb2xbg.py --xb-params-path=data/example-XBeach-params.txt --peak-enhancement-factor=4.2
# any output variables in XBG where there is some uncertainty re: relationship to XB
# will be generated anyway; use with caution
python xb2xbg.py --xb-params-path=data/example-XBeach-params.txt --verbose --use-all-known-output-variables
# explicit reference to XBG user manual HTML
python xb2xbg.py --xb-params-path=data/example-XBeach-params.txt --xbg-user-manual=https://raw.githubusercontent.com/CyprienBosserelle/xbeach_gpu/gh-pages/Manual.html
#### Run Unit Tests (optional)
Requires `pytest` library.
pytest -v
or, if output from library warnings is too noisy (Python/library version dependent)
pytest -v --disable-warnings
#### Possible Future Work
* handle TSnode and TSOfile parameters and XBeach equivalents (see npoints, npointvar, tintp)
* refinement/addition of output variable and parameter documentation
* when JONSWAP file detected, instead of giving `wavebndtype` check warning, just set it
* --no-empty-values: don't include parameters with no value in output
* --doc-line-wrap (default to None); generated doc strings currently wrapped at or before column 60
* change wavebndtype=4 advisory in presence of JONSWAP file to setting that value