Skip to content

RepD3D v1.0.0

Choose a tag to compare

View all tags
@capt-clay10 capt-clay10 released this 14 Oct 08:29
· 19 commits to main since this release
v1.0.0
4c53a4a

RepD3D v1.0.0 – first stable release

RepD3D is a Windows graphical toolbox, also available as open-source Python code, for coastal and estuarine modellers. It (1) identifies wind-based representative periods for numerical modelling studies and (2) extracts the boundary conditions for such periods from public hindcast datasets and writes them as ready-to-use Delft3D-4 input files. v1.0.0 is the software release that accompanies the MethodsX article RepD3D: A tool for representative period identification and associated boundary condition extraction (Soares, Knies and Winter, 2025, https://doi.org/10.1016/j.mex.2024.103109).

What is in this release

  • RepD3D.exe – stand-alone 64-bit Windows executable (Tkinter GUI packaged with PyInstaller, about 430 MB). No Python installation is required.
  • source_code/ – the pure-Python implementation (Python 3.9 or later). gui_generator.py provides the GUI and main.py a text-menu command-line interface; both expose the same eight modules.
  • Tutorial_files/ – a worked example with input files and expected output files for every module, plus a complete Delft3D-4 FLOW and WAVE example model (example_model/) that uses the generated files.
  • CITATION.cff and the MIT LICENSE.

Modules

  1. Identify representative period. Implements the unfiltered-reduction algorithm of Soares et al. (2024) on a long-term wind record (CSV with date as YYYYMMDDHH, speed, dir). Wind data are binned into 16 directional sectors and 12 Beaufort speed classes (0–11). All-class correlation scores candidate windows against the full reference period; selective-class correlation restricts the comparison to user-chosen sectors and speed classes, so that periods representative of specific conditions (for example storms from N to NNW at Beaufort 6–11) can be found. Candidate windows of one or more user-defined lengths (pandas offset strings such as 10MS, 12MS) are scanned across a user-defined period. Output is a ranked CSV of candidate periods and an interactive wind-rose viewer that compares each candidate with the reference period, including an overlap heat map.
  2. Extract all files. Reads a Delft3D-4 FLOW set-up (.mdf, .grd, .bnd) and WAVE set-up (.mdw, .grd, .bnd) together with EasyGSH-DB water-level and wave NetCDF files and writes, for the simulation period defined in the .mdf, the water-level time-series file (.bct), the wave time-series file (.bcw), an updated .mdw with the boundary section filled in, and a CSV with the coordinates of all boundary support points. Values are obtained by bilinear interpolation of the 1 km EasyGSH grid to both ends of every open boundary, with gap filling where the hindcast has missing values. Grid coordinates may be Cartesian (UTM zone 32N) or spherical. Selectable output time steps are 20, 40, 60 and 80 min for water level and 20 to 120 min for waves. Waves are written as significant wave height, peak period, mean direction (nautical "from" convention, derived from the x/y components) and directional spreading.
  3. Bct file overlapping over years. Builds a multi-year water-level .bct from several annual EasyGSH files.
  4. Bcw file overlapping over years. Builds a multi-year wave .bcw from several annual EasyGSH files.
  5. Boundary location CSV file. Writes the geographic coordinates of the boundary support points of any .grd/.bnd pair, for use outside RepD3D.
  6. Boundary location and mdw file. As module 5, and additionally writes the updated .mdw for the WAVE model.
  7. Add sea level change to .bct files. Adds a user-defined water-level change to an existing .bct, either as a constant offset or as a gradual (linear) increase over the file duration, and writes a new .bct.
  8. Generate ST-varying wind field files – COSMO. Converts COSMO-REA6 hourly 2D GRIB fields (10 m U and V wind, surface pressure) into Delft3D space- and time-varying meteo files on a user-supplied Delft3D grid (.mat v7 export): .amu, .amv, .amp and the uniform xwind.wnd/ywind.wnd files. The COSMO rotated-pole grid is rotated to true north before interpolation.

All output times are in UTC.

Supported input datasets

Running from source

Python 3.9 or later with: cfgrib and ecCodes, xarray, netCDF4 and h5netcdf, dask, numpy, pandas, scipy, scikit-learn, matplotlib, seaborn, windrose, tqdm, utm, pyproj, ttkbootstrap and Pillow. On Windows the conda-forge channel is recommended for cfgrib and ecCodes. Run python main.py for the command-line menu or python gui_generator.py for the GUI.

Known limitations in v1.0.0

  • Wave file reference date. The .bcw writer sets the reference time to the start date of the extraction and starts the time column at 0 min. If the reference date of your WAVE model differs from the extraction start, the .bcw must be adjusted by hand. A fix that takes the model reference date as input was committed to main on 2026-04-18 (commit 85f9864) and is not part of this tag or of the executable.
  • Extract all files expects the simulation period to lie within one annual EasyGSH file. For periods that span a year boundary use modules 3 and 4.
  • Only EasyGSH-DB and COSMO-REA6 are supported as data sources.
  • Boundary names in the .bnd files are expected in the form Name_1 (FLOW) and Name1 (WAVE).
  • Cartesian grids are assumed to be in UTM zone 32N.
  • The GUI can appear unresponsive while the interpolation loops run; progress is streamed to the processing window.
  • The executable is Windows only. The source code is platform independent but has only been tested on Windows.

Changes on main after the v1.0.0 tag

These commits are in the repository but not in the v1.0.0 source archive or executable:

  • 2025-04-25 – tutorial wind_input.csv shortened to 1975-01-01 to 2018-11-28 (previously ran to the end of 2021).
  • 2025-05-02 and 2025-10-01 – README rewritten (feature table, quick start, dataset table, road map).
  • 2026-04-18 (85f9864) – .bcw and multi-year .bcw writers take the model reference date and start offset; the GUI gains a Model reference date field; graphical abstract added.

Checksum

File Size (bytes) SHA-256
RepD3D.exe 435256124 8D03871ADAB3990268BA9EF5CB3573C2F823713E4279D3799050CF28C3813B76

How to cite

Software and method:

  • Soares, C. C., Knies, A., Winter, C. (2025). RepD3D: A tool for representative period identification and associated boundary condition extraction. MethodsX 14, 103109. https://doi.org/10.1016/j.mex.2024.103109
  • Soares, C. C., Galiforni-Silva, F., Winter, C. (2024). Representative residual transport pathways in a mixed-energy open tidal system. Journal of Sea Research 201, 102530. https://doi.org/10.1016/j.seares.2024.102530

Please also acknowledge the underlying datasets:

  • Hagen, R., Plüß, A., Schrage, N., Dreier, N. (2020). EasyGSH-DB: Themengebiet – synoptische Hydrodynamik. Bundesanstalt für Wasserbau. https://doi.org/10.48437/02.2020.K2.7000.0004
  • Bollmeyer, C., Keller, J. D., Ohlwein, C., Wahl, S., Crewell, S., Friederichs, P., Hense, A., Keune, J., Kneifel, S., Pscheidt, I., Redl, S., Steinke, S. (2015). Towards a high-resolution regional reanalysis for the European CORDEX domain. Q. J. R. Meteorol. Soc. 141, 1–15. https://doi.org/10.1002/qj.2486

Authors and licence

Clayton Cyril Soares (ORCID 0000-0001-6780-2305), Arne Knies and Christian Winter, Institute of Geosciences, Kiel University. Released under the MIT License. Contact: clayton.soares@ifg.uni-kiel.de

RepD3D provides no guarantee of suitability for any specific purpose. Always validate numerical-model results yourself.

Assets 3
Loading