A Scalable Deep Learning Framework for Wave-Based Inverse Problems

Production-ready • Multi-GPU DDP • Memory-Efficient • Plug-and-Play

Getting Started • Documentation • Examples • Discussions • Citation

---

Plug in your model, load your data, and let WaveDL do the heavy lifting 💪

WaveDL is a deep learning framework built for wave-based inverse problems — from ultrasonic NDE and geophysics to biomedical tissue characterization. It provides a robust, scalable training pipeline for mapping multi-dimensional data (1D/2D/3D) to physical quantities.

Input: Waveforms, spectrograms, B-scans, dispersion curves, ... ↓ Output: Material properties, defect dimensions, damage locations, ... 

The framework handles the engineering challenges of large-scale deep learning — big datasets, distributed training, and HPC deployment — so you can focus on the science, not the infrastructure.

Built for researchers who need:

• 📊 Multi-target regression with reproducibility and fair benchmarking
• 🚀 Seamless multi-GPU training on HPC clusters
• 💾 Memory-efficient handling of large-scale datasets
• 🔧 Easy integration of custom model architectures

@register_model("my_net") class MyNet(BaseModel): ...

pip install -r requirements.txt

The run_training.sh wrapper automatically configures the environment for HPC systems:

# Make executable (first time only) chmod +x run_training.sh # Basic training (auto-detects available GPUs) ./run_training.sh --model <model_name> --data_path <train_data> --batch_size <number> --output_dir <output_folder> # Detailed configuration ./run_training.sh --model <model_name> --data_path <train_data> --batch_size <number> \ --lr <number> --epochs <number> --patience <number> --compile --output_dir <output_folder>

# Local - auto-detects GPUs accelerate launch train.py --model <model_name> --data_path <train_data> --batch_size <number> --output_dir <output_folder> # Resume training (automatic - just re-run with same output_dir) # Manual resume from specific checkpoint: accelerate launch train.py --model <model_name> --data_path <train_data> --resume <checkpoint_folder> --output_dir <output_folder> # Force fresh start (ignores existing checkpoints) accelerate launch train.py --model <model_name> --data_path <train_data> --output_dir <output_folder> --fresh # List available models python train.py --list_models

After training, use test.py to evaluate your model on test data:

# Basic inference python test.py --checkpoint <checkpoint_folder> --data_path <test_data> # With visualization, CSV export, and multiple file formats python test.py --checkpoint <checkpoint_folder> --data_path <test_data> \ --plot --plot_format png pdf --save_predictions --output_dir <output_folder> # With custom parameter names python test.py --checkpoint <checkpoint_folder> --data_path <test_data> \ --param_names '$p_1$' '$p_2$' '$p_3$' --plot # Export model to ONNX for deployment (LabVIEW, MATLAB, C++, etc.) python test.py --checkpoint <checkpoint_folder> --data_path <test_data> \ --export onnx --export_path <output_file.onnx>

Output:

• Console: R², Pearson correlation, MAE per parameter
• CSV (with --save_predictions): True, predicted, error, and absolute error for all parameters
• Plots (with --plot): 10 publication-quality plots (scatter, histogram, residuals, Bland-Altman, Q-Q, correlation, relative error, CDF, index plot, box plot)
• Format (with --plot_format): Supported formats: png (default), pdf (vector), svg (vector), eps (LaTeX), tiff, jpg, ps

WaveDL/ ├── train.py # Training entry point ├── test.py # Testing & inference script ├── run_training.sh # HPC helper script (recommended) ├── requirements.txt # Python dependencies ├── pytest.ini # Pytest (unit test) configuration ├── CONTRIBUTING.md # Contribution guidelines ├── CODE_OF_CONDUCT.md # Community standards ├── CITATION.cff # Citation metadata │ ├── models/ │ ├── __init__.py # Model exports │ ├── registry.py # Model factory (@register_model) │ ├── base.py # Abstract base class │ ├── cnn.py # Baseline CNN architecture │ ├── resnet.py # ResNet-18/34/50 (1D/2D/3D) │ ├── efficientnet.py # EfficientNet-B0/B1/B2 (2D, pretrained) │ ├── vit.py # Vision Transformer (1D/2D) │ ├── convnext.py # ConvNeXt (1D/2D/3D) │ ├── densenet.py # DenseNet-121/169 (1D/2D/3D) │ ├── unet.py # U-Net / U-Net Regression (1D/2D/3D) │ └── _template.py # Template for new models │ ├── utils/ │ ├── __init__.py # Utility exports │ ├── data.py # Memory-mapped data pipeline │ ├── metrics.py # R², Pearson, visualization │ ├── distributed.py # DDP synchronization utils │ ├── losses.py # Loss function factory │ ├── optimizers.py # Optimizer factory │ ├── schedulers.py # LR scheduler factory │ ├── cross_validation.py # K-fold cross-validation │ └── config.py # YAML configuration support │ ├── configs/ # YAML config template (all options documented) ├── examples/ # Ready-to-run example with pre-trained model └── unit_tests/ # Pytest test suite (420 tests) 

# Using run_training.sh ./run_training.sh --model cnn --batch_size 256 --lr 5e-4 --compile # Using accelerate launch directly accelerate launch train.py --model cnn --batch_size 256 --lr 5e-4 --compile

# Use Huber loss for noisy NDE data accelerate launch train.py --model cnn --loss huber --huber_delta 0.5 # Weighted MSE: prioritize thickness (first target) accelerate launch train.py --model cnn --loss weighted_mse --loss_weights "2.0,1.0,1.0"

# SGD with Nesterov momentum (often better generalization) accelerate launch train.py --model cnn --optimizer sgd --lr 0.01 --momentum 0.9 --nesterov # RAdam for more stable training accelerate launch train.py --model cnn --optimizer radam --lr 1e-3

# Cosine annealing for 1000 epochs accelerate launch train.py --model cnn --scheduler cosine --epochs 1000 --min_lr 1e-7 # OneCycleLR for super-convergence accelerate launch train.py --model cnn --scheduler onecycle --lr 1e-2 --epochs 50 # MultiStep with custom milestones accelerate launch train.py --model cnn --scheduler multistep --milestones "100,200,300"

# 5-fold cross-validation (works with both methods!) ./run_training.sh --model cnn --cv 5 --data_path train_data.npz # OR accelerate launch train.py --model cnn --cv 5 --data_path train_data.npz # Stratified CV (recommended for unbalanced data) ./run_training.sh --model cnn --cv 5 --cv_stratify --loss huber --epochs 100 # Full configuration ./run_training.sh --model cnn --cv 5 --cv_stratify \ --loss huber --optimizer adamw --scheduler cosine \ --output_dir ./cv_results

# Use a config file accelerate launch train.py --config configs/config.yaml --data_path train.npz # Override specific values from config accelerate launch train.py --config configs/config.yaml --lr 5e-4 --epochs 500

# Model & Training model: cnn batch_size: 128 lr: 0.001 epochs: 1000 patience: 20 # Loss, Optimizer, Scheduler loss: mse optimizer: adamw scheduler: plateau # Cross-Validation (0 = disabled) cv: 0 # Performance precision: bf16 compile: false seed: 2025

WaveDL supports multiple data formats for training and inference:

The framework automatically detects file format and data dimensionality (1D, 2D, or 3D) — you only need to provide the appropriate model architecture.

save('data.mat', 'input_train', 'output_train', '-v7.3')

import numpy as np X = np.array(images, dtype=np.float32) # (N, H, W) y = np.array(labels, dtype=np.float32) # (N, T) np.savez('train_data.npz', input_train=X, output_train=y)

import numpy as np from PIL import Image from pathlib import Path import pandas as pd # Load images images = [np.array(Image.open(f).convert('L'), dtype=np.float32) for f in sorted(Path("images/").glob("*.png"))] X = np.stack(images) # Load labels y = pd.read_csv("labels.csv").values.astype(np.float32) np.savez('train_data.npz', input_train=X, output_train=y)

import numpy as np from scipy.io import loadmat data = loadmat('simulation_data.mat') X = data['spectrograms'].astype(np.float32) # Adjust key y = data['parameters'].astype(np.float32) # Transpose if needed: (H, W, N) → (N, H, W) if X.ndim == 3 and X.shape[2] < X.shape[0]: X = np.transpose(X, (2, 0, 1)) np.savez('train_data.npz', input_train=X, output_train=y)

import numpy as np X = np.random.randn(1000, 256, 256).astype(np.float32) y = np.random.randn(1000, 5).astype(np.float32) np.savez('test_data.npz', input_train=X, output_train=y)

import numpy as np data = np.load('train_data.npz') assert data['input_train'].ndim == 3, "Input must be 3D: (N, H, W)" assert data['output_train'].ndim == 2, "Output must be 2D: (N, T)" assert len(data['input_train']) == len(data['output_train']), "Sample mismatch" print(f"✓ Input: {data['input_train'].shape} {data['input_train'].dtype}") print(f"✓ Output: {data['output_train'].shape} {data['output_train'].dtype}")

The examples/ folder contains a complete, ready-to-run example for material characterization of isotropic plates. The pre-trained CNN predicts three physical parameters from Lamb wave dispersion curves:

Try it yourself:

# Run inference on the example data python test.py --checkpoint ./examples/elastic_cnn_example/best_checkpoint \ --data_path ./examples/elastic_cnn_example/Test_data_100.mat \ --plot --save_predictions --output_dir ./examples/elastic_cnn_example/test_results # Export to ONNX (already included as model.onnx) python test.py --checkpoint ./examples/elastic_cnn_example/best_checkpoint \ --data_path ./examples/elastic_cnn_example/Test_data_100.mat \ --export onnx --export_path ./examples/elastic_cnn_example/model.onnx

What's Included:

Training Progress:

Training and validation loss over 162 epochs with learning rate schedule

Inference Results:

Figure 1: Predictions vs ground truth for all three elastic parameters

Figure 2: Distribution of prediction errors showing near-zero mean bias

Figure 3: Residuals vs predicted values (no heteroscedasticity detected)

Figure 4: Bland-Altman analysis with ±1.96 SD limits of agreement

Figure 5: Q-Q plots confirming normally distributed prediction errors

Figure 6: Error correlation matrix between parameters

Figure 7: Relative error (%) vs true value for each parameter

Figure 8: Cumulative error distribution — 95% of predictions within indicated bounds

Figure 9: True vs predicted values by sample index

Figure 10: Error distribution summary (median, quartiles, outliers)

Beyond the material characterization example above, the WaveDL pipeline can be adapted for a wide range of wave-based inverse problems across multiple domains:

If you use WaveDL in your research, please cite:

@software{le2025wavedl, author = {Le, Ductho}, title = {{WaveDL}: A Scalable Deep Learning Framework for Wave-Based Inverse Problems}, year = {2025}, publisher = {Zenodo}, doi = {10.5281/zenodo.18012338}, url = {https://doi.org/10.5281/zenodo.18012338} }

Or in APA format:

Le, D. (2025). WaveDL: A Scalable Deep Learning Framework for Wave-Based Inverse Problems. Zenodo. https://doi.org/10.5281/zenodo.18012338

Ductho Le would like to acknowledge NSERC and Alberta Innovates for supporting his study and research by means of a research assistantship and a graduate doctoral fellowship.

This research was enabled in part by support provided by Compute Ontario, Calcul Québec, and the Digital Research Alliance of Canada.