Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

NILM

Non-Intrusive Load Monitoring is the process of estimating the energy consumed by individual appliances given just a whole-house power meter reading.
https://github.com/nilmtk/nilmtk

Category: Consumption
Sub Category: Buildings and Heating

Keywords

algorithms disaggregation energy energy-disaggregation forecasting ipython-notebook nilm nilm-algorithms nilmtk python

Last synced: about 19 hours ago
JSON representation

Repository metadata

Non-Intrusive Load Monitoring Toolkit (nilmtk)

README.md

NILMTK core

NILMTK is the data and evaluation layer of the open-source ecosystem for
non-intrusive load monitoring (NILM). It converts and loads energy datasets,
represents buildings and meters, prepares time windows, computes statistics and
metrics, and provides classical reference algorithms.

Use this repository when your work is about data, meters, preprocessing, or
metrics. For maintained neural models or reproducible benchmark claims, use
the companion repositories below.

Ecosystem repositories

Research task Repository
Dataset conversion, meter access, preprocessing, and metrics NILMTK core — this repository
Appliance taxonomy, synonyms, meter relationships, and dataset schema NILM Metadata
Disaggregation model implementation and testing nilmtk-contrib
Fixed T1/T2/T3 evaluation and published result bundles NILMbench

The NILMTK ecosystem guide explains how these
layers fit together, which Docker route to use, and which papers to cite.

Supported installation

NILMTK core supports Python 3.11 and newer. Use Python 3.11 for an end-to-end
environment shared with nilmtk-contrib and NILMbench.

Install uv, then create
an isolated environment:

uv venv --python 3.11
source .venv/bin/activate
uv pip install "nilmtk @ git+https://github.com/nilmtk/nilmtk.git"
python -c "import nilmtk; print(nilmtk.__version__)"

On Windows PowerShell, activate the environment with
.venv\Scripts\Activate.ps1.

To use the DEDDIAG converter, install the optional extra:

uv pip install "nilmtk[deddiag] @ git+https://github.com/nilmtk/nilmtk.git"

Do not combine these instructions with old Python 3.6, Anaconda-channel, or
setup.py develop tutorials. Those routes describe earlier releases and are
not the supported installation for the current repository.

Verify the command-line converter

nilmtk-convert --help
nilmtk-convert list
# Example after downloading REDD:
nilmtk-convert redd /path/to/low_freq /path/to/redd.h5

Dataset-specific converter arguments and source links live under
nilmtk/dataset_converters.

Docker ownership

NILMTK core is a Python library and does not publish a separate official core
image. This is intentional:

  • use the single nilmtk-contrib Dockerfile
    for a general environment containing core, metadata, and model code;
  • use NILMbench for pinned CPU-smoke and
    CUDA-benchmark runtimes that certify leaderboard results;
  • do not create an image for each algorithm.

Keeping container ownership in those two places prevents four repositories from
shipping drifting copies of the same environment.

Data

NILMTK does not redistribute REDD, UK-DALE, REFIT, or other licensed datasets.
Download data from its official custodian, comply with its license, and convert
it locally. A converted HDF5 dataset can then be opened with:

from nilmtk import DataSet

dataset = DataSet("redd.h5")
print(dataset.metadata)
print(dataset.buildings)

NILM Metadata is installed with core and supplies the canonical appliance
taxonomy, synonyms, and meter relationships used while loading datasets.

What core provides

  • converters for public energy datasets;
  • lazy access to buildings, meters, appliances, and time frames;
  • resampling, alignment, preprocessing, and data-quality statistics;
  • standard NILM accuracy and energy metrics;
  • the rapid experimentation API used by nilmtk-contrib;
  • classical reference disaggregators and baseline utilities.

Detailed API reference is published at
nilmtk.github.io/nilmtk/master.
The repository manual and notebooks live under docs/manual.

Development

git clone https://github.com/nilmtk/nilmtk.git
cd nilmtk
uv sync --extra dev
uv run pytest tests

Before opening a pull request, run the narrow test for your change, the current
package gate, and the documentation contract:

uv run pytest tests
uv run python scripts/check_docs.py
uv build

The historical core regression tests live under nilmtk/tests and
nilmtk/stats/tests. Run the affected files explicitly when changing those
modules; work to bring those fixtures into the default gate is tracked
separately.

Changes to dataset semantics belong in NILM Metadata. New model architectures
belong in nilmtk-contrib. Benchmark task definitions and published result
bundles belong in NILMbench.

Citation

If you use core dataset conversion, meter abstractions, preprocessing, or
metrics, cite the NILMTK paper:

@inproceedings{batra2014nilmtk,
  title     = {NILMTK: An Open Source Toolkit for Non-intrusive Load Monitoring},
  author    = {Batra, Nipun and Kelly, Jack and Parson, Oliver and Dutta, Haimonti
               and Knottenbelt, William and Rogers, Alex and Singh, Amarjeet
               and Srivastava, Mani},
  booktitle = {Proceedings of the 5th ACM International Conference on Future
               Energy Systems},
  year      = {2014},
  pages     = {265--276},
  doi       = {10.1145/2602044.2602051}
}

Also cite the NILM Metadata paper
when relying on its schema or taxonomy, the
nilmtk-contrib paper when using its
model suite, and the NILMBench2026 paper
when using its protocols, runner, or leaderboard results. Always cite the
original model and dataset papers as well.

Help and license

Search existing issues before opening
a report. Include the exact command, operating system, Python version, dataset
identity, and a minimal reproducer.

NILMTK is released under the Apache License 2.0.

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: 2 days ago

Total Commits: 1,730
Total Committers: 57
Avg Commits per committer: 30.351
Development Distribution Score (DDS): 0.492

Commits in past year: 14
Committers in past year: 2
Avg Commits per committer in past year: 7.0
Development Distribution Score (DDS) in past year: 0.429

Name Email Commits
Jack Kelly j****t@x****k 878
nipunreddevil n****l@g****m 450
Paulo Meira 1****a 123
Oliver Parson o****6@e****k 36
Oliver Parson o****n@g****m 28
Rishi Baijal r****4@i****n 24
josemao j****a@d****s 24
ayushp20.com a****0@g****l 11
beckel b****l@i****h 10
Mridul Malpotra m****a@g****m 10
Raktim Malakar r****5@g****m 10
Guillaume Levasseur p****l@p****t 10
Dhru Harsh Darshakbhai 2****7@i****n 9
Han Wu w****s@g****m 8
magusverma m****1@i****n 7
Oliver Parson o****n@b****k 6
Rajat r****2@g****m 6
oliver parson o****n@d****k 5
Oliver Parson o****p@e****k 5
enfuego27826 a****9@g****m 5
prince7003 1****3 5
Batra Nipun n****a@N****l 4
Oliver Parson u****r@E****l 4
Andrea Monacchi a****i@s****t 3
Batra Nipun n****a@d****U 3
Andrea a****i@g****m 3
unknown r****0@g****m 3
Florian Kalinke f****a@g****m 3
Hetvi Shastri h****9@g****m 3
Joulo u****r@d****k 2
and 27 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 3 days ago

Total issues: 877
Total pull requests: 158
Average time to close issues: 9 months
Average time to close pull requests: about 1 month
Total issue authors: 250
Total pull request authors: 53
Average comments per issue: 4.41
Average comments per pull request: 1.44
Merged pull request: 102
Bot issues: 0
Bot pull requests: 0

Past year issues: 3
Past year pull requests: 15
Past year average time to close issues: about 6 hours
Past year average time to close pull requests: 3 days
Past year issue authors: 3
Past year pull request authors: 3
Past year average comments per issue: 0.0
Past year average comments per pull request: 0.47
Past year merged pull request: 11
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/nilmtk/nilmtk

Top Issue Authors

  • JackKelly (177)
  • nipunbatra (140)
  • gjwo (25)
  • PMeira (21)
  • sanketvijaydesai (18)
  • walidsliti (16)
  • RishiBaijal (12)
  • suni9915 (11)
  • nekovolta (10)
  • deploy15 (9)
  • oliparson (9)
  • GautierAppert (9)
  • haderazzini (9)
  • DilanAgkoc (8)
  • bundit786 (8)

Top Pull Request Authors

  • prince7003 (20)
  • ayushp20 (14)
  • rajat-tech-002 (12)
  • nipunbatra (10)
  • wuhanstudio (9)
  • beckel (8)
  • enfuego27826 (8)
  • pilillo (6)
  • raktim2015 (6)
  • levaphenyl (5)
  • klemenjak (3)
  • PMeira (3)
  • camilomarino (3)
  • Rithwikksvr (3)
  • hetvishastri (3)

Top Issue Labels

  • DataStore and format conversion (93)
  • enhancement (84)
  • question (57)
  • bug (55)
  • design (48)
  • Building (34)
  • outdated (34)
  • documentation (32)
  • NILM algorithm (30)
  • Statistics and correlations (29)
  • refactoring (25)
  • Testing (17)
  • pre-processing (17)
  • Installation (15)
  • HMM (12)
  • Performance (11)
  • support (10)
  • Combinatorial Optimization (8)
  • NILM metrics (8)
  • simplify (6)
  • invalid (5)
  • needs more info (5)
  • duplicate (4)
  • Good as first PR (3)
  • Review (2)
  • offtopic (2)
  • discussion (2)
  • RE-API (2)
  • in progress (2)
  • planning (1)

Top Pull Request Labels

  • DataStore and format conversion (3)
  • enhancement (1)
  • bug (1)

Package metadata

proxy.golang.org: github.com/nilmtk/nilmtk

  • Homepage:
  • Documentation: https://pkg.go.dev/github.com/nilmtk/nilmtk#section-documentation
  • Licenses: apache-2.0
  • Latest release: v0.1.1 (published about 12 years ago)
  • Last Synced: 2026-08-15T15:02:56.820Z (2 days ago)
  • Versions: 2
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent packages count: 5.395%
    • Average: 5.576%
    • Dependent repos count: 5.758%

Dependencies

Dockerfile docker
  • python 3.11-slim build
.github/workflows/docs-checks.yml actions
  • actions/checkout v6 composite
  • actions/setup-python v6 composite
  • astral-sh/setup-uv v6 composite
pyproject.toml pypi
  • h5py >=3.9.0
  • hmmlearn >=0.3.0
  • ipython >=8.7.0
  • matplotlib >=3.7.0
  • networkx >=3.0
  • nilm-metadata @ git+https://github.com/nilmtk/nilm_metadata.git@59c9990de4836d77c0dcd807bd4293e39e0cc314
  • nose *
  • numpy >=1.24.0
  • pandas >=2.0.0
  • pyyaml >=6.0
  • scikit-learn >=1.3.0
  • scipy >=1.11.0
  • tables >=3.8.0
  • tqdm >=4.65.0

Score: -Infinity