RepD3D Representativeperiod Detection & Delft3D Boundarydata Toolbox

RepD3D is a Windowsfirst graphical user interface (GUI) and opensource Python library that helps coastal and estuarine modelers

• identify statistically representative simulation periods from longterm wind records using the algorithm of Soaresetal.,2024.
• extract space and timevarying boundary conditions (water level, waves, wind & pressure) from public hindcast data sets, and
• write fullyformatted Delft3D4 input files (.bct, .bcw, .amu/.amv/.amp, .wnd).

The toolbox is packaged as a portable RepD3D.exe as well as pure Python code (main.py) that runs on any platform with the required libraries.

Key features

| Module | Purpose | Output files | |--------|---------|--------------| | RPI | Identify allclass or selectiveclass representative periods with userdefined window length. | Output rank list.txt, interactive windrose viewer | | Extractall | Generation of waterlevel (.bct) and wave (.bcw) files, plus updated .mdw and CSV of boundary coordinates. | .bct, .bcw, updated .mdw, *_locations.csv | | Bct / Bcw yearoverlap | Build multiyear timeseries for water level or waves. | .bct / .bcw | | SLR adjuster | Add gradual or constant sealevel rise to existing .bct. | new .bct | | Windfield generator | Convert COSMOREA6(10m U&V, surfaceP) to Delft3D wind/pressure grids on a user grid. | .amu, .amv, .amp, xwind.wnd, ywind.wnd |

Quick start (GUI)

1. Download the latestRepD3D.exe from the releases page and place it in your project folder.
2. Doubleclickto launch. A splash screen will appear followed by the main menu.
3. Browse to a working directory and select the desired submodule.
4. Follow onscreen prompts to choose grids, boundaries, NetCDF files and parameters.
5. Output files are written to the working directory (all times inUTC).

Tip: The GUI may appear unresponsive while heavy interpolation loops are running; a progress console at the bottom streams realtime log output.

Install from source (CLI)

```bash

1. Clone the repo

$ git clone https://github.com/capt-clay10/RepD3D.git $ cd RepD3D

2. Create environment (Python3.9)

$ conda create -n repd3d python=3.9 $ conda activate repd3d

3. Install dependencies

$ pip install -r requirements.txt # see list below

4. Run commandline interface

$ python main.py ```

Python dependencies

ast cfgrib dask ecCodes h5py h5netcdf matplotlib numpy pandas pyproj scikitlearn scipy tqdm utm xarray windrose ttkbootstrap pillow

Some packages (cfgrib, ecCodes) require Clibraries. On Windows we recommend the condaforge channel.

Required data sets

| Data set | Coverage | Used for | Source | |----------|----------|----------|--------| | EasyGSHDB 1000m | German North Sea, 19962016 | Water level & wave forcing | https://mdi-de.baw.de/easygsh/ | | COSMOREA6 hourly2D | Europe, 19952019 | Wind (U,V) & surface pressure | https://opendata.dwd.de/climate_environment/REA/COSMO_REA6/hourly/2D/ |

Download files of interest into the working directory following the folder scheme below:

Working directory/ YYYY_1000m_wave_2D.nc YYYY_1000m_waterlevel_2D COSMO_YYYY/ PS/ # surface pressure GRIB (PS.*.grb) UV/ # 10m wind GRIB (U_*.grb, V_*.grb)

Typical workflow

1. Design grids & boundaries in Delft3DRGFGRID / FLOW / WAVE; save .grd, .bnd, .mdf, .mdw.
2. Run RPI to choose an unfiltered, reduced representative period matching your study goals.
3. Use Extract modules to build boundary timeseries for that period.
4. (Optional)Add SLR or generate COSMO wind fields.
5. Launch Delft3D, reference the generated files, and simulate!

Screenshots

| Screenshot | |------------| | Main menu
|

| Representative-period viewer
|

| EasyGSH extractor
|

| COSMO wind extractor
|

Citation

If you use RepD3D in your research, please cite the following:

``` @article{Soares2025, title = {RepD3D: A tool for representative period identification and associated boundary condition extraction}, journal = {MethodsX}, volume = {14}, pages = {103109}, year = {2025}, author = {C. C. Soares and A.Knies and C.Winter}, doi = {10.1016/j.mex.2024.103109} }

• Citation for using Representative period algorithm (source paper): 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
• Citation for using the RepD3D tool box (source paper): 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

```

Please also acknowledge the underlying data sets:

• EasyGSHDB(Hagenetal.,2020)
  

• COSMOREA6(Bollmeyeretal.,2015)

• Source of easygsh data https://mdi-de.baw.de/easygsh/EasyViewersyn.html#home

• Citations for using EasyGSH data : Hagen, R., Pl, A., Schrage, N., Dreier, N. (2020): EasyGSH-DB: Themengebiet - synoptische Hydrodynamik. Bundesanstalt fr Wasserbau. https://doi.org/10.48437/02.2020.K2.7000.0004

  • Please read the source document to understand how EasyGSH datasets are generated. Here are some quick points.
  • The data provided are the results of a numerical simulation gridded over 1km and provided every 20 minutes.
  • The numerical modelling approach used to generate the data utilizes annually updated bathymetry, tidal dynamics simulated by the Untrim2 modelling system, using tidal constituents at the open boundaries (corrected for external surge), waves computed using a combination of the model UnK (Schneggenburger et al., 2000) and SWAN for near-shore physical processes. This code does not extract SWAN-generated data

• Source for COSMO-REA6 data https://opendata.dwd.de/climateenvironment/REA/COSMOREA6/hourly/2D/

• Citations for using COMSO : 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 highresolution regional reanalysis for the European CORDEX domain. Q.J.R. Meteorol. Soc. 141, 115. https://doi.org/10.1002/qj.2486

  • Please read the source document to understand how COSMO-REA6 datasets are generated. https://opendata.dwd.de/climateenvironment/REA/COSMOREA6/helpCOSMOREA6/
  • COSMO data is provided on a rotated pole, which is currently corrected in the algorithm to true north
  • COSMO data U10m, V10m and PS is used in this toolbox

  * Additionally a Delft3D grid of 6X6 km, extracted as .mat (v7) is required

Contributing

Bug reports, feature requests and pull requests are welcome! Please open an issue first to discuss your ideas.

Roadmap: Support additional hindcast products (TriwaWaTT, ERA5), automatic download helpers, and native LinuxGUI.

License

This project is released under the MIT License see LICENSE.

Contact

ClaytonC.Soares clayton.soares@ifg.uni-kiel.de
ChristianWinter
ArneKnies

Always validate numericalmodel results yourself! RepD3D provides no guarantees for suitability for any specific purpose.