RepD3D – Representative‐period Detection & Delft3D Boundary‑data Toolbox

RepD3D is a Windows‑first graphical user interface (GUI) and open‑source Python library that helps coastal and estuarine modelers

• identify statistically representative simulation periods from long‑term wind records using the algorithm of Soares et al., 2024.
• extract space‑ and time‑varying boundary conditions (water level, waves, wind & pressure) from public hindcast data sets, and
• write fully‑formatted Delft3D‑4 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 all‑class or selective‑class representative periods with user‑defined window length.	Output rank list .txt, interactive wind‑rose viewer
Extract all	Generation of water‑level (.bct) and wave (.bcw) files, plus updated .mdw and CSV of boundary coordinates.	.bct, .bcw, updated .mdw, *_locations.csv
Bct / Bcw year‑overlap	Build multi‑year time‑series for water level or waves.	.bct / .bcw
SLR adjuster	Add gradual or constant sea‑level rise to existing .bct.	new .bct
Wind‑field generator	Convert COSMO‑REA6 (10 m U & V, surface P) to Delft3D wind/pressure grids on a user grid.	.amu, .amv, .amp, xwind.wnd, ywind.wnd

---

Quick start (GUI)

1. Download the latest RepD3D.exe from the releases page and place it in your project folder.
2. Double‑click to launch. A splash screen will appear followed by the main menu.
3. Browse to a working directory and select the desired sub‑module.
4. Follow on‑screen prompts to choose grids, boundaries, NetCDF files and parameters.
5. Output files are written to the working directory (all times in UTC).

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

---

Install from source (CLI)

# 1. Clone the repo
$ git clone https://github.com/capt-clay10/RepD3D.git
$ cd RepD3D

# 2. Create environment (Python ≥3.9)
$ conda create -n repd3d python=3.9
$ conda activate repd3d

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

# 4. Run command‑line interface
$ python main.py

Python dependencies

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

Some packages (cfgrib, ecCodes) require C‑libraries. On Windows we recommend the conda‑forge channel.

---

Required data sets

Data set	Coverage	Used for	Source
EasyGSH‑DB 1000 m	German North Sea, 1996‑2016	Water level & wave forcing	https://mdi-de.baw.de/easygsh/
COSMO‑REA6 hourly 2D	Europe, 1995‑2019	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/        # 10 m wind  GRIB           (U_*.grb, V_*.grb)

---

Typical workflow

1. Design grids & boundaries in Delft3D‑RGFGRID / 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 time‑series 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:

• EasyGSH‑DB (Hagen et al., 2020)

• COSMO‑REA6 (Bollmeyer et al., 2015)

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

• Citations for using EasyGSH data : 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

  • 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/climate_environment/REA/COSMO_REA6/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 high‐resolution regional reanalysis for the European CORDEX domain. Q.J.R. Meteorol. Soc. 141, 1–15. https://doi.org/10.1002/qj.2486

  • Please read the source document to understand how COSMO-REA6 datasets are generated. https://opendata.dwd.de/climate_environment/REA/COSMO_REA6/help_COSMO_REA6/
    • COSMO data is provided on a rotated pole, which is currently corrected in the algorithm to true north
    • COSMO data U_10m, V_10m 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.

Road‑map: Support additional hindcast products (TriwaWaTT, ERA5), automatic download helpers, and native Linux GUI.

---

License

This project is released under the MIT License – see LICENSE.

---

Contact

Clayton C. Soares – [email protected]
Christian Winter
Arne Knies

Always validate numerical‑model results yourself! RepD3D provides no guarantees for suitability for any specific purpose.