Metadata-Version: 2.4
Name: xbgears
Version: 0.3.0
Summary: A collection of tools for XBeach: grid <-> XYZ conversion, params.txt generation and run cleanup
Author-email: aaronchh <aaronhsu219@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/AaronOET/xbgears
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Provides-Extra: xlsx
Requires-Dist: pandas; extra == "xlsx"
Requires-Dist: openpyxl; extra == "xlsx"
Dynamic: license-file

# XBGEARS

A collection of Python tools for XBeach: converting between XBeach grid files (x.grd / y.grd / *.dep) and simple XYZ point files, building params.txt files and cleaning run output.

## Installation

```bash
pip install xbgears

# optional: load / save xbgen parameter sets as .xlsx
pip install xbgears[xlsx]
```

## Features

- **xb2xyz**: Convert XBeach x.grd / y.grd / *.dep grid files into a *.xyz point file
- **xyz2xb**: Convert a *.xyz point file back into x.grd / y.grd / bed.dep files
- **xb2yz**: Convert a 1D XBeach x.grd / *.dep profile into a two-column *.yz file
- **yz2xb**: Convert a two-column *.yz profile file back into 1D x.grd / bed.dep files
- **xbgen**: Build, check and write XBeach params.txt files (tkinter GUI or command line)
- **xbclr**: Remove files generated by an XBeach run (output, logs, *.bcf, ...), dry run by default

## Usage

### Command-line

```bash
# List all available commands
xbgears-info

# Convert XBeach grid files to a *.xyz point file
xb2xyz --dep bed.dep --xgrd x.grd --ygrd y.grd --out 001.xyz

# Convert a *.xyz point file back to XBeach grid files
xyz2xb --xyz 001.xyz --outdir XBGRID

# Convert a 1D XBeach profile to a two-column *.yz file
xb2yz --dep bed.dep --xgrd x.grd --out bathy.yz

# Convert a *.yz profile back to 1D XBeach grid files
yz2xb --yz bathy.yz --outdir XBGRID

# params.txt builder: GUI (optionally with an existing params.txt loaded)
xbgen
xbgen params.txt

# params.txt builder without GUI: check, or write params.txt + run.bat
xbgen params.txt --check
xbgen --write --outdir run1 --bat --exe "C:\XBeach\xbeach.exe"

# Clean files generated by an XBeach run (dry run first, then --yes)
xbclr
xbclr --yes
xbclr D:/runs -r --move-to _old_run --yes
```

### Python API

```python
from xbgears import xb2xyz, xyz2xb, xb2yz, yz2xb

# Convert XBeach grid files to a *.xyz point file (written to XYZ/001.xyz)
xb2xyz.xb_to_xyz(dep="bed.dep", xgrd="x.grd", ygrd="y.grd", out="001.xyz")

# Convert a *.xyz point file back to XBeach grid files (written to XBGRID/)
xyz2xb.xyz_to_xb(xyz="001.xyz", outdir="XBGRID")

# Convert a 1D XBeach profile to a *.yz file (written to YZ/bathy.yz)
xb2yz.xb_to_yz(dep="bed.dep", xgrd="x.grd", out="bathy.yz")

# Convert a *.yz profile back to 1D XBeach grid files (written to XBGRID/)
yz2xb.yz_to_xb(yz="bathy.yz", outdir="XBGRID")

# Build a params.txt from an existing one (or xbgen.load() for the built-in defaults)
from xbgears import xbgen
data = xbgen.load("params.txt")
xbgen.validate(data)                       # prints warnings, returns their number
xbgen.write_params(data, outdir="run1", bat=True)

# List / remove generated run files
from xbgears import xbclr
xbclr.clean_outputs("run1")               # dry run, returns [(folder, file, reason)]
xbclr.clean_outputs("run1", yes=True)
```

## Notes

- `xb2xyz` reads `xori`/`yori` from `params.txt` in the working directory (if present) and adds them to the x/y coordinates; grid rotation (`alfa`) is not applied.
- `xb2xyz` writes its output to the `XYZ/` directory by default; `xyz2xb` writes its output to the `XBGRID/` directory by default.
- `xb2yz` writes its output to the `YZ/` directory by default; `yz2xb` writes to `XBGRID/` and requires strictly increasing x values. Both use 3-decimal (`%.3f`) formatting.
- `xbgen` knows every params.txt keyword of the XBeach manual tables (plus `D15`/`D50`/`D90`/`sedcal`/`ucrcal`), one GUI tab per topic. Checked keywords are written as `key = value`; unchecked ones are left out, or written as `%key = value` comments with *Write disabled lines as %comments* / `--write-disabled`. Keywords in a loaded params.txt that are not in the manual go to the `other` tab.
- `xbgen` checks values against the manual ranges/options and common dependencies (`vardx`/`xfile`/`yfile`, nx/ny vs the grid files, `wbctype`/`bcfile`, `instat` + `wbctype`, output intervals vs run length, ...). `--write` refuses to write on warnings or over existing files unless `--force` is given.
- XBeach always reads `params.txt` from the working folder; for another `--name`, the generated `run_<name>.bat` first copies `<name>.txt` to `params.txt`.
- `xbclr` only cleans folders that contain a `params.txt` and never removes `params.txt` or any file it references (including the files listed in a FILELIST `bcfile`). Generated `*.bcf` files are kept with `wbctype = reuse` (or `--keep-bc`), and `hotstart*.dat` with `hotstart = 1`. Sub-folders are only cleaned with `-r`.
