NILMTK is a research ecosystem for loading real energy datasets, resolving their meaning, implementing disaggregation models, and comparing them under frozen protocols.
Four repositories. Four distinct responsibilities.
+
Repositories
+
Which repository should I use?
-
Start with the question you are trying to answer. The packages work together, but each has one canonical job. This separation keeps data semantics, model code, and scientific claims reviewable.
+
Use core for data, metadata for shared meaning, contrib for models, and NILMbench for fixed protocols and published results.
01
-
Data layer
+
Data and metrics
NILMTK
- Load, convert, inspect, and score energy data.
-
Use core for dataset converters, buildings and meters, preprocessing, metrics, and classical baselines.
+ Use this for dataset and meter work.
+
Converters, buildings, meters, preprocessing, metrics, and classical baselines.
NILM Metadata supplies shared meaning across the entire path. Core turns physical files into consistent meters and windows. Contrib supplies models. NILMbench freezes the comparison and publishes only provenance-complete results.
Use Python 3.11 and uv. Pick the smallest installation that matches your job. The model install brings core and metadata with it.
+
Choose a tab and copy the commands. The model install includes core and metadata. Dataset files are downloaded separately.
@@ -256,15 +249,15 @@
A supported route, not another dated tutorial.
A
-
Bring licensed data
Datasets are not baked into packages or images. Download them from their official custodians, follow their licenses, and mount local NILMTK HDF5 conversions read-only.
+
Datasets are not included
Download data from its official custodian, follow its license, and convert or mount it locally.
B
-
Keep one general image
The contrib Dockerfile defines the common starting environment. Model contributions do not create a new container tag or image family.
+
One development Dockerfile
nilmtk-contrib provides the common environment. Do not create an image for every model.
C
-
Separate benchmark runtimes
NILMbench owns pinned CPU-smoke and CUDA-benchmark runtimes. Those images certify results; they are not per-algorithm development images.
+
Benchmark images are separate
NILMbench pins CPU-smoke and CUDA runtimes used to certify results.
@@ -273,10 +266,10 @@
A supported route, not another dated tutorial.
-
Cite precisely
-
Credit the layer your work relies on.
-
There is no single citation that describes every part of the current ecosystem. Cite the infrastructure paper for each layer you use, plus the original model and dataset papers.
One model contribution. One auditable route to rank.
+
Add a model
+
Add a model, then benchmark it.
-
Algorithm code and benchmark evidence move at different cadences. A model can merge once its implementation contract is sound. It enters the leaderboard only after the pinned benchmark matrix passes on real data.
+
Model code goes to nilmtk-contrib. Leaderboard evidence goes to NILMbench after the fixed real-data protocol passes.
01
Implement
Add the model to nilmtk-contrib using shared validation, windowing, checkpoint, and logging utilities.
One model contribution. One auditable route to rank.
-
New here?
-
Start with a reproducible failure.
-
Open an issue with the repository, exact command, operating system, Python version, dataset identity, and the smallest trace that reproduces the problem.
+
Help
+
Need help?
+
Open an issue with the exact command, operating system, Python version, dataset, and a small reproducer.