Skip to main content

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

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

# 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

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.

Metadata

Release files for xbgears 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xbgears 0.3.0
File Size Uploaded Provenance Actions
xbgears-0.3.0.tar.gz 39.1 kB With provenance Details for xbgears-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xbgears 0.3.0
File Interpreter ABI Platform Actions
xbgears-0.3.0-py3-none-any.whl Python 3 none any Details for xbgears-0.3.0-py3-none-any.whl

Total release size: 82.2 kB

Release files / xbgears-0.3.0.tar.gz

Download URL xbgears-0.3.0.tar.gz
Size 39.1 kB
Tags Source
SHA-256 checksum
How to use checksums
176e5c86efcfba130ca901ce15a854d4b607f744212d4a5a7db85a0123e98b30
BLAKE2b-256 checksum
How to use checksums
a8131b34ffdb9cb24f33a0dde60ecb673875b3def30ff9403c2b3ef1bafdc6ee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / xbgears-0.3.0-py3-none-any.whl

Download URL xbgears-0.3.0-py3-none-any.whl
Size 43.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3693e84fbfa390a6b717d5f15700540adcc35f0a3b71fe4439f978500efd2796
BLAKE2b-256 checksum
How to use checksums
10967c958c7e46e1b694bccc91f6fb0ef7c10e13259113b771a3dd149944853c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for xbgears 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xbgears-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page