WaveletML: A Scalable and Extensible Wavelet Neural Network Framework

Overview

WaveletML is an open-source Python framework designed for building, training, and evaluating Wavelet Neural Networks (WNNs) tailored for supervised learning tasks such as regression and classification. Leveraging the power of PyTorch and the modularity of scikit-learn, WaveletML provides a unified, extensible, and scalable platform for researchers and practitioners to explore wavelet-based neural architectures.

Features

• Modular Wavelet Neural Network (WNN) architectures
• Support for multiple wavelet functions (e.g., Morlet, Mexican Hat)
• Support for multiple wavelet layers (e.g., Weighed Linear, Product, Summation, etc.)
• Gradient Descent-based training via Pytorch
• Metaheuristic Algorithm-based training via Mealpy
• scikit-learn-compatible API with BaseEstimator support
• Built-in support for both classification and regression tasks
• Customizable activation functions, training parameters, and loss functions
• Designed for scalability, enabling deployment on CPU or GPU environments.

Whether you're prototyping WNN-based models or conducting advanced experimental research, WaveletML aims to bridge the gap between theory and practical implementation in wavelet-based learning systems.

Model Types

• GdWnnClassifier: Wavelet-based classifier using gradient-based training
• GdWnnRegressor: Wavelet-based regressor using gradient-based training
• MhaWnnClassifier: Uses metaheuristics (e.g., PSO, GA) for training
• MhaWnnRegressor: Wavelet-based regressor with metaheuristic training

Installation

Install the latest version using pip:

bash pip install waveletml

After that, check the version to ensure successful installation:

```sh $ python

import waveletml waveletml.version ```

Quick Start

Classification

In this example, we will use Adam optimizer to train Wavelet Weighted Linear Neural Network (WNN) for a classification task.

```python from sklearn.datasets import load_iris from waveletml import Data, GdWnnClassifier

Load data object

X, y = loadiris(returnX_y=True) data = Data(X, y)

Split train and test

data.splittraintest(testsize=0.2, randomstate=2, inplace=True, shuffle=True) print(data.Xtrain.shape, data.Xtest.shape)

Scaling dataset

data.Xtrain, scalerX = data.scale(data.Xtrain, scalingmethods=("standard", "minmax")) data.Xtest = scalerX.transform(data.X_test)

data.ytrain, scalery = data.encodelabel(data.ytrain) data.ytest = scalery.transform(data.y_test)

print(type(data.Xtrain), type(data.ytrain))

Create model

model = GdWnnClassifier(sizehidden=10, waveletfn="morlet", actoutput=None, epochs=100, batchsize=16, optim="Adam", optimparams=None, validrate=0.1, seed=42, verbose=True, device=None)

Train the model

model.fit(X=data.Xtrain, y=data.ytrain)

Test the model

ypred = model.predict(data.Xtest) print(ypred) print(model.predictproba(data.X_test))

Calculate some metrics

print(model.evaluate(ytrue=data.ytest, ypred=ypred, list_metrics=["F2S", "CKS", "FBS", "PS", "RS", "NPV", "F1S"]))

Print model parameters

for k, v in model.network.named_parameters(): print(f"{k}: {v.shape}, {v.data}") ```

Regression

In this example, we will use Genetic Algorithm - GA to train Wavelet Summation Neural Network (WNN) for a regression task.

```python from sklearn.datasets import load_diabetes from waveletml import Data, MhaWnnRegressor, CustomWaveletSummationNetwork

Load data object

X, y = loaddiabetes(returnX_y=True) data = Data(X, y)

Split train and test

data.splittraintest(testsize=0.2, randomstate=2, inplace=True) print(data.Xtrain.shape, data.Xtest.shape)

Scaling dataset

data.Xtrain, scalerX = data.scale(data.Xtrain, scalingmethods=("standard", "minmax")) data.Xtest = scalerX.transform(data.X_test)

data.ytrain, scalery = data.scale(data.ytrain, scalingmethods=("standard", "minmax")) data.ytest = scalery.transform(data.y_test.reshape(-1, 1))

print(type(data.Xtrain), type(data.ytrain))

Create model

model = MhaWnnRegressor(sizehidden=10, waveletfn="morlet", actoutput=None, optim="BaseGA", optimparams={"epoch": 40, "popsize": 20}, objname="MSE", seed=42, verbose=True, wnntype=CustomWaveletSummationNetwork, lb=None, ub=None, mode='single', nworkers=None, termination=None)

Train the model

model.fit(data.Xtrain, data.ytrain)

Test the model

ypred = model.predict(data.Xtest) print(y_pred)

Calculate some metrics

print(model.evaluate(ytrue=data.ytest, ypred=ypred, list_metrics=["R2", "NSE", "MAPE", "NNSE"]))

Print model parameters

for k, v in model.network.named_parameters(): print(f"{k}: {v.shape}, {v.data}") ```

Please read the examples folder for more use cases.

Documentation

Documentation is available at: https://waveletml.readthedocs.io

You can build the documentation locally:

shell cd docs make html

Testing

You can run unit tests using:

shell pytest tests/

Contributing

We welcome contributions to WaveletML! If you have suggestions, improvements, or bug fixes, feel free to fork the repository, create a pull request, or open an issue.

License

This project is licensed under the GPLv3 License. See the LICENSE file for more details.

Citation Request

Please include these citations if you plan to use this library:

```bibtex @software{thieu20250525WaveletML, author = {Nguyen Van Thieu}, title = {WaveletML: A Scalable and Extensible Wavelet Neural Network Framework}, month = June, year = 2025, doi = {10.6084/m9.figshare.29095376}, url = {https://github.com/thieu1995/WaveletML} }

@article{van2023mealpy, title={MEALPY: An open-source library for latest meta-heuristic algorithms in Python}, author={Van Thieu, Nguyen and Mirjalili, Seyedali}, journal={Journal of Systems Architecture}, year={2023}, publisher={Elsevier}, doi={10.1016/j.sysarc.2023.102871} } ```

Official Links

• Official source code repo: https://github.com/thieu1995/WaveletML
• Official document: https://waveletml.readthedocs.io/
• Download releases: https://pypi.org/project/waveletml/
• Issue tracker: https://github.com/thieu1995/WaveletML/issues
• Notable changes log: https://github.com/thieu1995/WaveletML/blob/master/ChangeLog.md
• Official chat group: https://t.me/+fRVCJGuGJg1mNDg1

Developed by: Thieu @ 2025