## <img src='https://abrain.one/img/lemur-nn-icon-64x64.png' width='32px'/> Neural Network Dataset
<a href='https://pypi.python.org/pypi/nn-dataset'><img src='https://img.shields.io/pypi/v/nn-dataset.svg'/></a>
LEMUR - Learning, Evaluation, and Modeling for Unified Research
<img src='https://abrain.one/img/lemur-nn-whit.jpg' width='25%'/>
The original version of the <a href='https://github.com/ABrain-One/nn-dataset'>LEMUR dataset</a> was created by <strong>Arash Torabi Goodarzi, Roman Kochnev</strong> and <strong>Zofia Antonina Bentyn</strong> at the Computer Vision Laboratory, University of Würzburg, Germany.
<h3>Overview 📖</h3>
The primary goal of NN Dataset project is to provide flexibility for dynamically combining various deep learing tasks, datasets, metrics, and neural network models. It is designed to facilitate the verification of neural network performance under various combinations of training hyperparameters and data transformation algorithms, by automatically generating performance statistics. It is primarily developed to support the <a href="https://github.com/ABrain-One/nn-gen">NN Gen</a> project.
## Installation or Update of NN Dataset
Remove old version of the LEMUR Dataset and its database:
```bash
source .venv/bin/activate
pip uninstall nn-dataset -y
rm -rf db
```
Installing the stable version:
```bash
source .venv/bin/activate
pip install nn-dataset --upgrade --extra-index-url https://download.pytorch.org/whl/cu124
```
Installing from GitHub to get the most recent code and statistics updates:
```bash
source .venv/bin/activate
pip install git+https://github.com/ABrain-One/nn-dataset --upgrade --force --extra-index-url https://download.pytorch.org/whl/cu124
```
Adding functionality to export data to Excel files and generate plots for <a href='https://github.com/ABrain-One/nn-stat'>analyzing neural network performance</a>:
```bash
source .venv/bin/activate
pip install nn-stat --upgrade --extra-index-url https://download.pytorch.org/whl/cu124
```
## Environment for NN Dataset Contributors
### Pip package manager
Create a virtual environment, activate it, and run the following command to install all the project dependencies:
```bash
source .venv/bin/activate
pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu124
```
### Docker
All versions of this project are compatible with <a href='https://hub.docker.com/r/abrainone/ai-linux' target='_blank'>AI Linux</a> and can be run inside a Docker image:
```bash
docker run -v /a/mm:. abrainone/ai-linux bash -c "PYTHONPATH=/a/mm python -m ab.nn.train"
```
## Usage
Standard use cases:
1. Add a new neural network model into the `ab/nn/nn` directory.
2. Run the automated training process for this model (e.g., a new ComplexNet training pipeline configuration):
```bash
source .venv/bin/activate
python -m ab.nn.train -c img-classification_cifar-10_acc_ComplexNet
```
or for all image segmentation models using a fixed range of training parameters and transformer:
```bash
source .venv/bin/activate
python run.py -c img-segmentation -f echo --min_learning_rate 1e-4 -l 1e-2 --min_momentum 0.8 -m 0.99 --min_batch_binary_power 2 -b 6
```
To reproduce the previous result, set the minimum and maximum to the same desired values:
```bash
source .venv/bin/activate
python run.py -c img-classification_cifar-10_acc_AlexNet --min_learning_rate 0.0061 -l 0.0061 --min_momentum 0.7549 -m 0.7549 --min_batch_binary_power 2 -b 2 -f norm_299
```
To view supported flags:
```bash
source .venv/bin/activate
python run.py -h
```
## Contribution
To contribute a new neural network (NN) model to the NN Dataset, please ensure the following criteria are met:
1. The code for each model is provided in a respective ".py" file within the <strong>/ab/nn/nn</strong> directory, and the file is named after the name of the model's structure.
2. The main class for each model is named <strong>Net</strong>.
3. The constructor of the <strong>Net</strong> class takes the following parameters:
- <strong>in_shape</strong> (tuple): The shape of the first tensor from the dataset iterator. For images it is structured as `(batch, channel, height, width)`.
- <strong>out_shape</strong> (tuple): Provided by the dataset loader, it describes the shape of the output tensor. For a classification task, this could be `(number of classes,)`.
- <strong>prm</strong> (dict): A dictionary of hyperparameters, e.g., `{'lr': 0.24, 'momentum': 0.93, 'dropout': 0.51}`.
- <strong>device</strong> (torch.device): PyTorch device used for the model training
4. All external information required for the correct building and training of the NN model for a specific dataset/transformer, as well as the list of hyperparameters, is extracted from <strong>in_shape</strong>, <strong>out_shape</strong> or <strong>prm</strong>, e.g.: </br>`batch = in_shape[0]` </br>`channel_number = in_shape[1]` </br>`image_size = in_shape[2]` </br>`class_number = out_shape[0]` </br>`learning_rate = prm['lr']` </br>`momentum = prm['momentum']` </br>`dropout = prm['dropout']`.
5. Every model script has function returning set of supported hyperparameters, e.g.: </br>`def supported_hyperparameters(): return {'lr', 'momentum', 'dropout'}`</br> The value of each hyperparameter lies within the range of 0.0 to 1.0.
6. Every class <strong>Net</strong> implements two functions: </br>`train_setup(self, prm)`</br> and </br>`learn(self, train_data)`</br> The first function initializes the `criteria` and `optimizer`, while the second implements the training pipeline. See a simple implementation in the <a href="https://github.com/ABrain-One/nn-dataset/blob/main/ab/nn/nn/AlexNet.py">AlexNet model</a>.
7. For each pull request involving a new NN model, please generate and submit training statistics for 100 Optuna trials (or at least 3 trials for very large models) in the <strong>ab/nn/stat</strong> directory. The trials should cover 5 epochs of training. Ensure that this statistics is included along with the model in your pull request. For example, the statistics for the ComplexNet model are stored in files <strong><epoch number>.json</strong> inside folder <strong>img-classification_cifar-10_acc_ComplexNet</strong>, and can be generated by:<br/>
```bash
python run.py -c img-classification_cifar-10_acc_ComplexNet -t 100 -e 5
```
<p>See more examples of models in <code>/ab/nn/nn</code> and generated statistics in <code>/ab/nn/stat</code>.</p>
### Available Modules
The `nn-dataset` package includes the following key modules:
1. **Dataset**:
- Predefined neural network architectures such as `AlexNet`, `ResNet`, `VGG`, and more.
- Located in `ab.nn.nn`.
2. **Loaders**:
- Data loaders for datasets such as CIFAR-10 and COCO.
- Located in `ab.nn.loader`.
3. **Metrics**:
- Common evaluation metrics like accuracy and IoU.
- Located in `ab.nn.metric`.
4. **Utilities**:
- Helper functions for training and statistical analysis.
- Located in `ab.nn.util`.
## Citation
If you find the LEMUR Neural Network Dataset to be useful for your research, please consider citing:
```bibtex
@misc{ABrain-One.NN-Dataset,
author = {Goodarzi, Arash Torabi and Kochnev, Roman and Khalid, Waleed and Qin, Furui and Kathiriya, Yash Kanubhai and Dhameliya, Yashkumar Sanjaybhai and Ignatov, Dmitry and Timofte, Radu},
title = {Neural Network Dataset: Towards Seamless AutoML},
howpublished = {\url{https://github.com/ABrain-One/nn-dataset}},
year = {2024},
}
```
## Licenses
This project is distributed under the following licensing terms:
<ul><li>for neural network models adopted from other projects
<ul>
<li> Python code under the legacy <a href="https://github.com/ABrain-One/nn-dataset/blob/main/Doc/Licenses/LICENSE-MIT-NNs">MIT</a> or <a href="https://github.com/ABrain-One/nn-dataset/blob/main/Doc/Licenses/LICENSE-BSD-NNs">BSD 3-Clause</a> license</li>
<li> models with pretrained weights under the legacy <a href="https://github.com/ABrain-One/nn-dataset/blob/main/Doc/Licenses/LICENSE-DEEPSEEK-LLM-V2">DeepSeek LLM V2</a> license</li>
</ul></li>
<li> all neural network models and their weights not covered by the above licenses, as well as all other files and assets in this project, are subject to the <a href="https://github.com/ABrain-One/nn-dataset/blob/main/LICENSE">MIT license</a></li>
</ul>
#### The idea of Dr. Dmitry Ignatov
Raw data
{
"_id": null,
"home_page": "https://ABrain.one",
"name": "NN-Dataset",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "ABrain One and contributors",
"author_email": "AI@ABrain.one",
"download_url": "https://files.pythonhosted.org/packages/10/94/5c00b33d10e240c9a241ea063b832e8bdc228d8f4cd30a705dfe48626f00/nn_dataset-1.0.3.tar.gz",
"platform": null,
"description": "## <img src='https://abrain.one/img/lemur-nn-icon-64x64.png' width='32px'/> Neural Network Dataset \n<a href='https://pypi.python.org/pypi/nn-dataset'><img src='https://img.shields.io/pypi/v/nn-dataset.svg'/></a>\n \nLEMUR - Learning, Evaluation, and Modeling for Unified Research\n\n<img src='https://abrain.one/img/lemur-nn-whit.jpg' width='25%'/>\n\nThe original version of the <a href='https://github.com/ABrain-One/nn-dataset'>LEMUR dataset</a> was created by <strong>Arash Torabi Goodarzi, Roman Kochnev</strong> and <strong>Zofia Antonina Bentyn</strong> at the Computer Vision Laboratory, University of W\u00fcrzburg, Germany.\n\n<h3>Overview \ud83d\udcd6</h3>\nThe primary goal of NN Dataset project is to provide flexibility for dynamically combining various deep learing tasks, datasets, metrics, and neural network models. It is designed to facilitate the verification of neural network performance under various combinations of training hyperparameters and data transformation algorithms, by automatically generating performance statistics. It is primarily developed to support the <a href=\"https://github.com/ABrain-One/nn-gen\">NN Gen</a> project.\n\n## Installation or Update of NN Dataset\nRemove old version of the LEMUR Dataset and its database:\n```bash\nsource .venv/bin/activate\npip uninstall nn-dataset -y\nrm -rf db\n```\nInstalling the stable version:\n```bash\nsource .venv/bin/activate\npip install nn-dataset --upgrade --extra-index-url https://download.pytorch.org/whl/cu124\n```\nInstalling from GitHub to get the most recent code and statistics updates:\n```bash\nsource .venv/bin/activate\npip install git+https://github.com/ABrain-One/nn-dataset --upgrade --force --extra-index-url https://download.pytorch.org/whl/cu124\n```\nAdding functionality to export data to Excel files and generate plots for <a href='https://github.com/ABrain-One/nn-stat'>analyzing neural network performance</a>:\n```bash\nsource .venv/bin/activate\npip install nn-stat --upgrade --extra-index-url https://download.pytorch.org/whl/cu124\n```\n\n## Environment for NN Dataset Contributors\n### Pip package manager\nCreate a virtual environment, activate it, and run the following command to install all the project dependencies:\n```bash\nsource .venv/bin/activate\npip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu124\n```\n\n### Docker\nAll versions of this project are compatible with <a href='https://hub.docker.com/r/abrainone/ai-linux' target='_blank'>AI Linux</a> and can be run inside a Docker image:\n```bash\ndocker run -v /a/mm:. abrainone/ai-linux bash -c \"PYTHONPATH=/a/mm python -m ab.nn.train\"\n```\n\n## Usage\n\nStandard use cases:\n1. Add a new neural network model into the `ab/nn/nn` directory.\n2. Run the automated training process for this model (e.g., a new ComplexNet training pipeline configuration):\n```bash\nsource .venv/bin/activate\npython -m ab.nn.train -c img-classification_cifar-10_acc_ComplexNet\n```\nor for all image segmentation models using a fixed range of training parameters and transformer:\n```bash\nsource .venv/bin/activate\npython run.py -c img-segmentation -f echo --min_learning_rate 1e-4 -l 1e-2 --min_momentum 0.8 -m 0.99 --min_batch_binary_power 2 -b 6\n```\nTo reproduce the previous result, set the minimum and maximum to the same desired values:\n```bash\nsource .venv/bin/activate\npython run.py -c img-classification_cifar-10_acc_AlexNet --min_learning_rate 0.0061 -l 0.0061 --min_momentum 0.7549 -m 0.7549 --min_batch_binary_power 2 -b 2 -f norm_299\n```\nTo view supported flags:\n```bash\nsource .venv/bin/activate\npython run.py -h\n```\n\n## Contribution\n\nTo contribute a new neural network (NN) model to the NN Dataset, please ensure the following criteria are met:\n\n1. The code for each model is provided in a respective \".py\" file within the <strong>/ab/nn/nn</strong> directory, and the file is named after the name of the model's structure.\n2. The main class for each model is named <strong>Net</strong>.\n3. The constructor of the <strong>Net</strong> class takes the following parameters:\n - <strong>in_shape</strong> (tuple): The shape of the first tensor from the dataset iterator. For images it is structured as `(batch, channel, height, width)`.\n - <strong>out_shape</strong> (tuple): Provided by the dataset loader, it describes the shape of the output tensor. For a classification task, this could be `(number of classes,)`.\n - <strong>prm</strong> (dict): A dictionary of hyperparameters, e.g., `{'lr': 0.24, 'momentum': 0.93, 'dropout': 0.51}`.\n - <strong>device</strong> (torch.device): PyTorch device used for the model training \n4. All external information required for the correct building and training of the NN model for a specific dataset/transformer, as well as the list of hyperparameters, is extracted from <strong>in_shape</strong>, <strong>out_shape</strong> or <strong>prm</strong>, e.g.: </br>`batch = in_shape[0]` </br>`channel_number = in_shape[1]` </br>`image_size = in_shape[2]` </br>`class_number = out_shape[0]` </br>`learning_rate = prm['lr']` </br>`momentum = prm['momentum']` </br>`dropout = prm['dropout']`.\n5. Every model script has function returning set of supported hyperparameters, e.g.: </br>`def supported_hyperparameters(): return {'lr', 'momentum', 'dropout'}`</br> The value of each hyperparameter lies within the range of 0.0 to 1.0.\n6. Every class <strong>Net</strong> implements two functions: </br>`train_setup(self, prm)`</br> and </br>`learn(self, train_data)`</br> The first function initializes the `criteria` and `optimizer`, while the second implements the training pipeline. See a simple implementation in the <a href=\"https://github.com/ABrain-One/nn-dataset/blob/main/ab/nn/nn/AlexNet.py\">AlexNet model</a>.\n7. For each pull request involving a new NN model, please generate and submit training statistics for 100 Optuna trials (or at least 3 trials for very large models) in the <strong>ab/nn/stat</strong> directory. The trials should cover 5 epochs of training. Ensure that this statistics is included along with the model in your pull request. For example, the statistics for the ComplexNet model are stored in files <strong><epoch number>.json</strong> inside folder <strong>img-classification_cifar-10_acc_ComplexNet</strong>, and can be generated by:<br/>\n```bash\npython run.py -c img-classification_cifar-10_acc_ComplexNet -t 100 -e 5\n```\n<p>See more examples of models in <code>/ab/nn/nn</code> and generated statistics in <code>/ab/nn/stat</code>.</p>\n\n### Available Modules\n\nThe `nn-dataset` package includes the following key modules:\n\n1. **Dataset**:\n - Predefined neural network architectures such as `AlexNet`, `ResNet`, `VGG`, and more.\n - Located in `ab.nn.nn`.\n\n2. **Loaders**:\n - Data loaders for datasets such as CIFAR-10 and COCO.\n - Located in `ab.nn.loader`.\n\n3. **Metrics**:\n - Common evaluation metrics like accuracy and IoU.\n - Located in `ab.nn.metric`.\n\n4. **Utilities**:\n - Helper functions for training and statistical analysis.\n - Located in `ab.nn.util`.\n\n\n## Citation\n\nIf you find the LEMUR Neural Network Dataset to be useful for your research, please consider citing:\n```bibtex\n@misc{ABrain-One.NN-Dataset,\n author = {Goodarzi, Arash Torabi and Kochnev, Roman and Khalid, Waleed and Qin, Furui and Kathiriya, Yash Kanubhai and Dhameliya, Yashkumar Sanjaybhai and Ignatov, Dmitry and Timofte, Radu},\n title = {Neural Network Dataset: Towards Seamless AutoML},\n howpublished = {\\url{https://github.com/ABrain-One/nn-dataset}},\n year = {2024},\n}\n```\n\n## Licenses\n\nThis project is distributed under the following licensing terms:\n<ul><li>for neural network models adopted from other projects\n <ul>\n <li> Python code under the legacy <a href=\"https://github.com/ABrain-One/nn-dataset/blob/main/Doc/Licenses/LICENSE-MIT-NNs\">MIT</a> or <a href=\"https://github.com/ABrain-One/nn-dataset/blob/main/Doc/Licenses/LICENSE-BSD-NNs\">BSD 3-Clause</a> license</li>\n <li> models with pretrained weights under the legacy <a href=\"https://github.com/ABrain-One/nn-dataset/blob/main/Doc/Licenses/LICENSE-DEEPSEEK-LLM-V2\">DeepSeek LLM V2</a> license</li>\n </ul></li>\n<li> all neural network models and their weights not covered by the above licenses, as well as all other files and assets in this project, are subject to the <a href=\"https://github.com/ABrain-One/nn-dataset/blob/main/LICENSE\">MIT license</a></li> \n</ul>\n\n#### The idea of Dr. Dmitry Ignatov\n",
"bugtrack_url": null,
"license": null,
"summary": "Neural Network Dataset",
"version": "1.0.3",
"project_urls": {
"Homepage": "https://ABrain.one"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0224f64c504b2de338d1d5a1c6cad1d6d8b9fd7e1e3fc71f05952998c4626fe1",
"md5": "b45f9c026d8cf9e4bcc421c722b8660f",
"sha256": "5749d288013a3f8b06396541824b93dc0a20b40689cf8360179ee7a4d584b33e"
},
"downloads": -1,
"filename": "NN_Dataset-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b45f9c026d8cf9e4bcc421c722b8660f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 2905810,
"upload_time": "2025-02-08T18:56:23",
"upload_time_iso_8601": "2025-02-08T18:56:23.831071Z",
"url": "https://files.pythonhosted.org/packages/02/24/f64c504b2de338d1d5a1c6cad1d6d8b9fd7e1e3fc71f05952998c4626fe1/NN_Dataset-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "10945c00b33d10e240c9a241ea063b832e8bdc228d8f4cd30a705dfe48626f00",
"md5": "a09dfe54c6375577e6aeba7bbfebca10",
"sha256": "ea84b878d0f90098d1f14f17a562238d755699f82c0ab51893102b9d5c85db57"
},
"downloads": -1,
"filename": "nn_dataset-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "a09dfe54c6375577e6aeba7bbfebca10",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 1196660,
"upload_time": "2025-02-08T18:56:25",
"upload_time_iso_8601": "2025-02-08T18:56:25.929310Z",
"url": "https://files.pythonhosted.org/packages/10/94/5c00b33d10e240c9a241ea063b832e8bdc228d8f4cd30a705dfe48626f00/nn_dataset-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-08 18:56:25",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "nn-dataset"
}
JSON