VdE_NILM

Research toolkit for NILM (Non-Intrusive Load Monitoring)

A modular toolbox to prototype and compare energy disaggregation models.

Description

VdE_NILM is a modular framework for research and experimentation in electrical consumption disaggregation (NILM). It provides utilities for time-series preprocessing, data generators, model implementations (TensorFlow and PyTorch), training engines and evaluation scripts.

Key features

• Support for PyTorch and TensorFlow models
• Data generators for training/validation (src/data_generator)
• Preprocessing pipeline (src/preprocessing.py)
• Reusable training and evaluation modules (src/trainers)
• Evaluation tools and metrics (src/metrics.py)

Quick start

Recommended: Python 3.10+ and a virtual environment.

• Activate the included virtual environment:

source nilm-venv/bin/activate

• Or create a new environment:

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip

• Install dependencies (if requirements.txt exists):

pip install -r requirements.txt

If no requirements.txt is provided, install at least: numpy, pandas, scipy, scikit-learn, matplotlib, tqdm. For training install torch and/or tensorflow depending on the chosen backend.

Repository structure

• src/ : main source code
  • src/main.py : main entry script (examples and experiments)
  • src/preprocessing.py : signal preprocessing functions
  • src/training_testing.py : training / testing scripts
  • src/metrics.py : evaluation metrics and helpers
  • src/utils.py : miscellaneous utilities
  • src/convert_vde.py : converters (VdE-specific formats)
  • src/data_generator/ : data generators (TF / PyTorch)
  • src/models/ : model implementations (PyTorch / TF)
  • src/trainers/ : trainer classes for different backends

Usage examples

Training and evaluation scripts are mainly located in src/.

• Run a quick training example:

source nilm-venv/bin/activate
python src/training_testing.py

• Inspect routines and adapt experiments:
  • src/main.py
  • src/training_testing.py
  • src/models/tf_models.py
  • src/models/pytorch_models.py

Data

The project does not enforce a specific dataset. Adapt paths and converters via src/convert_vde.py or use the generators in src/data_generator/. Document the origin and preprocessing steps for datasets used in your experiments.

Training & evaluation

• Use trainer classes in src/trainers/ to separate training logic from experiment orchestration.
• Metrics are defined in src/metrics.py and serve as a baseline for model comparison.

Contributing

Contributions are welcome: open issues for bugs or improvement proposals, or add new model/generator implementations. Please:

• Open an issue describing your goal
• Create a branch named feat/<description> or fix/<description>
• Submit a pull request with a clear description of changes

License

See LICENSE.md at the repository root for usage and redistribution terms.

Contact

For questions, open an issue or contact the repository author.

Technologies

The project primarily uses the following technologies:

• Python: recommended version 3.10+
• NumPy / Pandas / SciPy: data processing and manipulation
• scikit-learn: utilities and classic metrics
• Matplotlib: visualization
• PyTorch: PyTorch backend — models and training (src/models/pytorch_models.py)
• TensorFlow / Keras: TensorFlow backend — models and training (src/models/tf_models.py)
• Jupyter: notebooks for exploration
• virtualenv / venv: virtual environment management (included nilm-venv)
• GPU (optional): CUDA/cuDNN for accelerated training if available

Models included

The repository includes implementations of two model families adapted for NILM, provided in both PyTorch and TensorFlow: src/models/pytorch_models.py and src/models/tf_models.py.

• Seq2Point (PyTorchSeq2Point, TFSeq2Point):

  • Convolutional 1D stacks that take a time-window and predict the device power at the center of the window (sequence-to-point approach).
  • Designed for single-channel input (aggregate power) and a scalar output per window.

• 1D UNet adapted for NILM (PyTorchUNetNilm, TFUNetNilm):

  • 1D encoder-decoder (U-Net) with upsampling / transpose-conv blocks to reconstruct fine temporal features.
  • Can be configured to estimate multi-output targets (e.g., multiple appliances) or produce temporal maps depending on configuration.

Implementation notes

• PyTorch and TensorFlow implementations follow the same conceptual structure: encoding blocks, decoding blocks (UpLayer / TFUpLayer) and a final fully-connected head.
• Seq2Point modules are deep convolutional networks followed by dense layers to output a single prediction per window.
• Weights use adapted initialization schemes (Xavier / Kaiming) — see initialization functions in src/models/pytorch_models.py.

📃 License

MIT License — see LICENSE.md.

🤝 Acknowledgments

This project was developed within the context of academic collaboration with Université Libre de Bruxelles (ULB).

📧 Contact

👤 Brice Petit

📧 brice[dot]petit[at]ulb[dot]be

📍 IRIDIA, ULB — Brussels, Belgium