WASSDDPM: Denoising Diffusion Probabilistic Models for scattered point cloud interpolation of sea waves elevation data

WASSDDPM is a Python tool for interpolating 3D point clouds of sea surface elevation data using Denoising Diffusion Probabilistic Models (DDPMs).

⚠️ NOTE: This repository contains research code that is still under active development and testing. It is provided primarily to support the reproducibility of the associated paper and may be subject to frequent changes.

⚙️ Installation

Clone the repository and install the required dependencies (we suggest doing so in a venv to install packages locally):

git clone https://github.com/fbergama/wassddpm.git
cd wassddpm
wget -P src/wassddpm/Conditional_DDIM/unet https://www.dais.unive.it/\~bergamasco/files/diffusion_pytorch_model.safetensors
python -m venv .venv
source .venv/bin/activate
pip install .

🚀 Usage

The program is controlled via a command-line interface with three main modes of operation: createdataset, ddpm, and kf.

General Syntax:

python -m wassddpm [action] [arguments] [options]

1. Data Preparation (createdataset)

Pre-processes a NetCDF file created by WASSfast for further processing by the DDPM model

python -m wassddpm createdataset [infile] [outfile]

infile: Path to the input NetCDF file (.nc).

outfile: Name of the output HDF5 file (.h5) to be created.

2. Diffusion Generation (ddpm)

Runs the Denoising Diffusion Probabilistic Model to generate surface reconstructions. This step produces multiple stochastic realizations to capture the underlying uncertainty.

python -m wassddpm ddpm [infile] [outfile]

infile: The HDF5 file generated in the previous step.

outfile: Directory path where temporary results (reconstructions) will be stored.

--do_plots: (Optional) specific flag to generate visualization plots during inference.

3. Kalman Filter Fusion (kf)

Fuses the generated realizations with the initial data using a Kalman Filter. This step utilizes the correlation between generation variance and error to weight the dispersion relation constraints.

python wassddpm.py kf [infile] [outfile] [netcdf_append] [--kalman_std FLOAT]

infile: The HDF5 file (from step 1).

outfile: The directory containing the DDPM results (from step 2).

netcdf_append: The NetCDF file created by WASSfast (from step 1). Old variable Z will be renamed to Z_wassfast, and the result surfaces are written into the variable Z

--kalman_std: (Optional) Standard deviation for the Kalman Filter (Default: 0.04).

📊 Workflow Example

Here is a complete example of the processing pipeline:

1. Download a test NetCDF file generated with WASSfast

mkdir data
wget -P data https://www.dais.unive.it/\~bergamasco/files/gridded_WASSFAST_short.nc

2. Pre-process

python -m wassddpm createdataset data/gridded_WASSFAST_short.nc data/preprocessed.h5

3. Run the diffusion model to generate surfaces

mkdir data/interpolated
python -m wassddpm ddpm data/preprocessed.h5 data/interpolated

4. Fuse results using Kalman Filtering

mkdir plots
python -m wassddpm kf data/preprocessed.h5 data/interpolated data/gridded_WASSFAST_short.nc --kalman_std 0.04 --do_plots

Images are generated in the plots directory. The file data/gridded_WASSFAST_short.nc is modified so that the variable Z contains the surfaces generated by the tool.

📄 License

WASSDDPM: Denoising Diffusion Probabilistic Models for scattered point cloud
          interpolation of sea waves elevation data
Copyright (C) 2026 Ca' Foscari University of Venice
                                                                                
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
                                                                                
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
                                                                                
You should have received a copy of the GNU General Public License along
with this program. If not, see <https://www.gnu.org/licenses/>.