{"id":18734189,"url":"https://github.com/nico-curti/numpynet","last_synced_at":"2025-04-12T18:32:10.005Z","repository":{"id":65261138,"uuid":"199490280","full_name":"Nico-Curti/NumPyNet","owner":"Nico-Curti","description":"Neural Networks library in pure numpy","archived":false,"fork":false,"pushed_at":"2024-02-20T13:21:44.000Z","size":3586,"stargazers_count":67,"open_issues_count":3,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-26T13:21:39.081Z","etag":null,"topics":["deep-learning","deep-neural-networks","documentation","learning-by-doing","neural-networks"],"latest_commit_sha":null,"homepage":"https://nico-curti.github.io/NumPyNet","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nico-Curti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null}},"created_at":"2019-07-29T16:36:09.000Z","updated_at":"2025-01-15T04:03:19.000Z","dependencies_parsed_at":"2024-02-20T14:46:40.357Z","dependency_job_id":null,"html_url":"https://github.com/Nico-Curti/NumPyNet","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nico-Curti%2FNumPyNet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nico-Curti%2FNumPyNet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nico-Curti%2FNumPyNet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nico-Curti%2FNumPyNet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nico-Curti","download_url":"https://codeload.github.com/Nico-Curti/NumPyNet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248613643,"owners_count":21133562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","deep-neural-networks","documentation","learning-by-doing","neural-networks"],"created_at":"2024-11-07T15:12:42.265Z","updated_at":"2025-04-12T18:32:09.333Z","avatar_url":"https://github.com/Nico-Curti.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"| **Author**   | **Project** | **Documentation** | **Build Status** | **Code Quality** | **Coverage** |\n|:------------:|:-----------:|:-----------------:|:----------------:|:----------------:|:------------:|\n|   [**N. Curti**](https://github.com/Nico-Curti) \u003cbr/\u003e [**M. Ceccarelli**](https://github.com/Mat092) | **NumPyNet**  | [![docs](https://img.shields.io/badge/documentation-latest-blue.svg?style=plastic)](https://nico-curti.github.io/NumPyNet/) | **Linux/MacOS** : [![travis](https://travis-ci.com/Nico-Curti/NumPyNet.svg?branch=master)](https://travis-ci.com/Nico-Curti/NumPyNet) \u003cbr/\u003e **Windows** : [![appveyor](https://ci.appveyor.com/api/projects/status/qbn3ml2q04j9rbat?svg=true)](https://ci.appveyor.com/project/Nico-Curti/numpynet) | **Codacy** : [![Codacy Badge](https://api.codacy.com/project/badge/Grade/bc07a2bf6ba84555a7b9647891cc309d)](https://www.codacy.com/manual/Nico-Curti/NumPyNet?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=Nico-Curti/NumPyNet\u0026amp;utm_campaign=Badge_Grade) \u003cbr/\u003e **Codebeat** : [![Codebeat](https://codebeat.co/badges/3ac26bf3-44ae-47ff-9b93-2f9785c4a7d6)](https://codebeat.co/projects/github-com-nico-curti-numpynet-master) | [![codecov](https://codecov.io/gh/Nico-Curti/NumPyNet/branch/master/graph/badge.svg)](https://codecov.io/gh/Nico-Curti/NumPyNet) |\n\n[![NumPyNet CI](https://github.com/Nico-Curti/NumPyNet/workflows/NumPyNet%20CI/badge.svg)](https://github.com/Nico-Curti/NumPyNet/actions?query=workflow%3A%22NumPyNet+CI%22)\n\n[![GitHub pull-requests](https://img.shields.io/github/issues-pr/Nico-Curti/NumPyNet.svg?style=plastic)](https://github.com/Nico-Curti/NumPyNet/pulls)\n[![GitHub issues](https://img.shields.io/github/issues/Nico-Curti/NumPyNet.svg?style=plastic)](https://github.com/Nico-Curti/NumPyNet/issues)\n\n[![GitHub stars](https://img.shields.io/github/stars/Nico-Curti/NumPyNet.svg?label=Stars\u0026style=social)](https://github.com/Nico-Curti/NumPyNet/stargazers)\n[![GitHub watchers](https://img.shields.io/github/watchers/Nico-Curti/NumPyNet.svg?label=Watch\u0026style=social)](https://github.com/Nico-Curti/NumPyNet/watchers)\n\n\u003ca href=\"https://github.com/UniboDIFABiophysics\"\u003e\n\u003cdiv class=\"image\"\u003e\n\u003cimg src=\"https://cdn.rawgit.com/physycom/templates/697b327d/logo_unibo.png\" width=\"90\" height=\"90\"\u003e\n\u003c/div\u003e\n\u003c/a\u003e\n\n# Neural Networks in Pure NumPy - NumPyNet\n\nImplementation in **pure** `Numpy` of neural networks models.\n`NumPyNet` supports a syntax very close to the `Keras` one but it is written using **only** `Numpy` functions: in this way it is very light and fast to install and use/modify.\n\n* [Overview](#overview)\n* [Theory](#theory)\n* [Prerequisites](#prerequisites)\n* [Installation](#installation)\n* [Efficiency](#efficiency)\n* [Usage](#usage)\n* [Contribution](#contribution)\n* [References](#references)\n* [Authors](#authors)\n* [License](#license)\n* [Acknowledgments](#acknowledgments)\n* [Citation](#citation)\n\n## Overview\n\n`NumPyNet` is born as educational framework for the study of Neural Network models.\nIt is written trying to balance code readability and computational performances and it is enriched with a large documentation to better understand the functionality of each script.\nThe library is written in pure `Python` and the only external library used is [`Numpy`](http://www.numpy.org/) (a base package for the scientific research).\n\nDespite all common libraries are correlated by a wide documentation is often difficult for novel users to move around the many hyper-links and papers cited in them.\n`NumPyNet` tries to overcome this problem with a minimal mathematical documentation associated to each script and a wide range of comments inside the code.\n\nAn other \"problem\" to take in count is related to performances.\nLibraries like [`Tensorflow`](http://tensorflow.org/) are certainly efficient from a computational point-of-view and the numerous wrappers (like *Keras* library) guarantee an extremely simple user interface.\nOn the other hand, the deeper functionalities of the code and the implementation strategies used are unavoidably hidden behind tons of code lines.\nIn this way the user can perform complex computational tasks using the library as black-box package.\n`NumPyNet` wants to overcome this problem using simple `Python` codes, with extremely readability also for novel users, to better understand the symmetry between mathematical formulas and code.\n\n## Theory\n\nWe propose a full list of mathematical instructions about each layer model into our [online](https://nico-curti.github.io/NumPyNet) documentation.\nEach script is also combined with a very simple usage into its `__main__` section: in this way we can easily visualize the results produced by each function into a test image.\n\nThe full list of available layers is the following:\n\n- [Activation Layer](./docs/NumPyNet/layers/activation_layer.md)\n- [Avgpool Layer](./docs/NumPyNet/layers/avgpool_layer.md)\n- [BatchNorm Layer](./docs/NumPyNet/layers/batchnorm_layer.md)\n- [Connected Layer](./docs/NumPyNet/layers/connected_layer.md)\n- [Convolutional Layer](./docs/NumPyNet/layers/convolutional_layer.md)\n- [Cost Layer](./docs/NumPyNet/layers/cost_layer.md)\n- [DropOut Layer](./docs/NumPyNet/layers/dropout_layer.md)\n- [Input Layer](./docs/NumPyNet/layers/input_layer.md)\n- [L1norm Layer](./docs/NumPyNet/layers/l1norm_layer.md)\n- [L2norm Layer](./docs/NumPyNet/layers/l2norm_layer.md)\n- [Logistic Layer](./docs/NumPyNet/layers/logistic_layer.md)\n- [LSTM Layer](./docs/NumPyNet/layers/lstm_layer.md) : **TODO**\n- [MaxPool Layer](./docs/NumPyNet/layers/maxpool_layer.md)\n- [RNN Layer](./docs/NumPyNet/layers/rnn_layer.md) : **TODO**\n- [Route Layer](./docs/NumPyNet/layers/route_layer.md)\n- [PixelShuffle Layer](./docs/NumPyNet/layers/pixelshuffle_layer.md)\n- [Shortcut Layer](./docs/NumPyNet/layers/shortcut_layer.md)\n- [UpSample Layer](./docs/NumPyNet/layers/upsample-layer.md)\n- [YOLO Layer](./docs/NumPyNet/layers/yolo_layer.md)\n\n## Prerequisites\n\nPython version supported : ![Python version](https://img.shields.io/badge/python-2.7|3.4|3.5|3.6|3.7|3.8-blue.svg)\n\nFirst of all ensure that a right `Python` version is installed (`Python` \u003e= 2.7 is required).\nThe [Anaconda/Miniconda](https://www.anaconda.com/) python version is recommended.\n\n**Note:** some utilities (e.g image and video objects) required `OpenCV` library.\n`OpenCV` does not support `Python2.6` and `Python3.3`.\nIf you are working with these two versions, please consider to remove the utilities objects or simply convert the `OpenCV` dependencies with other packages (like [Pillow](https://pypi.org/project/Pillow) or [scikit-image](https://pypi.org/project/scikit-image)).\n\n## Installation\n\nDownload the project or the latest release:\n\n```bash\ngit clone https://github.com/Nico-Curti/NumPyNet\ncd NumPyNet\n```\n\nThe principal `NumPyNet` requirements are `numpy`, `matplotlib`, `enum34` and `configparser`.\nFor layer visualizations we use the `Pillow` package while the `OpenCV` library is used to wrap some useful image processing objects.\nYou can simply install the full list of requirements with the command:\n\n```bash\npip install -r ./requirements.txt\n```\n\nThe testing procedure of this library is performed using `PyTest` and `Hypothesis` packages.\nPlease consider to install also these libraries if you want a complete installation of `NumPyNet`.\n\nIn the `NumPyNet` directory execute:\n\n```bash\npython setup.py install\n```\n\nor for installing in development mode:\n\n```bash\npython setup.py develop --user\n```\n\n### Testing\n\nA full set of testing functions is provided in the [testing](https://github.com/Nico-Curti/NumPyNet/tree/master/testing) directory.\nThe tests are performed against the `Keras` implementation of the same functions (we tested only the `Tensorflow` backend in our simulations).\nYou can run the full list of tests with:\n\n```bash\ncd NumPyNet/testing\npytest\n```\n\nThe continuous integration using `Travis` and `Appveyor` tests each function in every commit, thus pay attention to the status badges before use this package or use the latest stable version available.\n\n## Efficiency\n\n**TODO**\n\n## Usage\n\nFirst of all we have to import the main modules of the `NumPyNet` package as\n\n\n```python\nfrom NumPyNet.network import Network\nfrom NumPyNet.layers.connected_layer import Connected_layer\nfrom NumPyNet.layers.convolutional_layer import Convolutional_layer\nfrom NumPyNet.layers.maxpool_layer import Maxpool_layer\nfrom NumPyNet.layers.softmax_layer import Softmax_layer\nfrom NumPyNet.layers.batchnorm_layer import BatchNorm_layer\nfrom NumPyNet.optimizer import Adam\n```\n\nNow we can try to create a very simple model able to classify the well known MNIST-digit dataset.\nThe MNIST dataset can be extracted from the `sklearn` library as\n\n```python\nfrom sklearn import datasets\nfrom sklearn.model_selection import train_test_split\n\ndigits = datasets.load_digits()\nX, y = digits.images, digits.target\n\nX = np.asarray([np.dstack((x, x, x)) for x in X])\nX = X.transpose(0, 2, 3, 1)\n\nX_train, X_test, y_train, y_test = train_test_split(X, y, test_size=.33, random_state=42)\n```\n\nNow we have to create our model.\nWe can use a syntax very close to the *Keras* one and simply define a model object adding a series of layers\n\n```python\nmodel = Network(batch=batch, input_shape=X_train.shape[1:])\n\nmodel.add(Convolutional_layer(size=3, filters=32, stride=1, pad=True, activation='Relu'))\nmodel.add(BatchNorm_layer())\nmodel.add(Maxpool_layer(size=2, stride=1, padding=True))\nmodel.add(Connected_layer(outputs=100, activation='Relu'))\nmodel.add(BatchNorm_layer())\nmodel.add(Connected_layer(outputs=num_classes, activation='Linear'))\nmodel.add(Softmax_layer(spatial=True, groups=1, temperature=1.))\n\nmodel.compile(optimizer=Adam(), metrics=[accuracy])\n\nmodel.summary()\n```\n\nThe model automatically creates an `InputLayer` if it is not explicitly provided, but pay attention to the right `input_shape` values!\n\nBefore feeding our model we have to convert the image dataset into categorical variables.\nTo this purpose we can use the simple *utilities* of the `NumPyNet` package.\n\n```python\nfrom NumPyNet.utils import to_categorical\nfrom NumPyNet.utils import from_categorical\nfrom NumPyNet.metrics import mean_accuracy_score\n\n# normalization to [0, 1]\nX_train *= 1. / 255.\nX_test  *= 1. / 255.\n\nn_train = X_train.shape[0]\nn_test  = X_test.shape[0]\n\n# transform y to array of dimension 10 and in 4 dimension\ny_train = to_categorical(y_train).reshape(n_train, 1, 1, -1)\ny_test  = to_categorical(y_test).reshape(n_test, 1, 1, -1)\n```\n\nNow you can run your `fit` function to train the model as\n\n```python\nmodel.fit(X=X_train, y=y_train, max_iter=100)\n```\n\nand evaluate the results on the testing set\n\n```python\nloss, out = model.evaluate(X=X_test, truth=y_test, verbose=True)\n\ntruth = from_categorical(y_test)\npredicted = from_categorical(out)\naccuracy  = mean_accuracy_score(truth, predicted)\n\nprint('\\nLoss Score: {:.3f}'.format(loss))\nprint('Accuracy Score: {:.3f}'.format(accuracy))\n```\n\nYou should see something like this\n\n```bash\nlayer       filters  size              input                output\n   0 input                   128 x   8 x   3 x   8   -\u003e   128 x   8 x   3 x   8\n   1 conv     32 3 x 3 / 1   128 x   8 x   3 x   8   -\u003e   128 x   8 x   3 x  32  0.000 BFLOPs\n   2 batchnorm                       8 x   3 x  32 image\n   3 max         2 x 2 / 1   128 x   8 x   3 x  32   -\u003e   128 x   7 x   2 x  32\n   4 connected               128 x   7 x   2 x  32   -\u003e   128 x 100\n   5 batchnorm                       1 x   1 x 100 image\n   6 connected               128 x   1 x   1 x 100   -\u003e   128 x  10\n   7 softmax x entropy                                    128 x   1 x   1 x  10\n\nEpoch 1/10\n512/512 |██████████████████████████████████████████████████| (0.7 sec/iter) loss: 26.676 accuracy: 0.826\n\nEpoch 2/10\n512/512 |██████████████████████████████████████████████████| (0.6 sec/iter) loss: 22.547 accuracy: 0.914\n\nEpoch 3/10\n512/512 |██████████████████████████████████████████████████| (0.7 sec/iter) loss: 21.333 accuracy: 0.943\n\nEpoch 4/10\n512/512 |██████████████████████████████████████████████████| (0.6 sec/iter) loss: 20.832 accuracy: 0.963\n\nEpoch 5/10\n512/512 |██████████████████████████████████████████████████| (0.5 sec/iter) loss: 20.529 accuracy: 0.975\n\nEpoch 6/10\n512/512 |██████████████████████████████████████████████████| (0.3 sec/iter) loss: 20.322 accuracy: 0.977\n\nEpoch 7/10\n512/512 |██████████████████████████████████████████████████| (0.3 sec/iter) loss: 20.164 accuracy: 0.986\n\nEpoch 8/10\n512/512 |██████████████████████████████████████████████████| (0.3 sec/iter) loss: 20.050 accuracy: 0.992\n\nEpoch 9/10\n512/512 |██████████████████████████████████████████████████| (0.3 sec/iter) loss: 19.955 accuracy: 0.994\n\nEpoch 10/10\n512/512 |██████████████████████████████████████████████████| (0.3 sec/iter) loss: 19.875 accuracy: 0.996\n\nTraining on 10 epochs took 21.6 sec\n\n300/300 |██████████████████████████████████████████████████| (0.0 sec/iter) loss: 10.472\nPrediction on 300 samples took 0.1 sec\n\nLoss Score: 2.610\nAccuracy Score: 0.937\n```\n\nObviously the execution time can vary according to your available resources!\n\nYou can find a full list of example scripts [here](https://github.com/Nico-Curti/NumPyNet/tree/master/examples)\n\n## Contribution\n\nAny contribution is more than welcome :heart:. Just fill an [issue](https://github.com/Nico-Curti/NumPyNet/blob/master/ISSUE_TEMPLATE.md) or a [pull request](https://github.com/Nico-Curti/NumPyNet/blob/master/PULL_REQUEST_TEMPLATE.md) and we will check ASAP!\n\nSee [here](https://github.com/Nico-Curti/NumPyNet/blob/master/CONTRIBUTING.md) for further informations about how to contribute with this project.\n\n## References\n\n\u003cblockquote\u003e1- Travis Oliphant. \"NumPy: A guide to NumPy\", USA: Trelgol Publishing, 2006. \u003c/blockquote\u003e\n\n\u003cblockquote\u003e2- Bradski, G. \"The OpenCV Library\", Dr. Dobb's Journal of Software Tools, 2000. \u003c/blockquote\u003e\n\n**TODO**\n\n## Authors\n\n* \u003cimg src=\"https://avatars0.githubusercontent.com/u/24650975?s=400\u0026v=4\" width=\"25px\"\u003e **Nico Curti** [git](https://github.com/Nico-Curti), [unibo](https://www.unibo.it/sitoweb/nico.curti2)\n\n* \u003cimg src=\"https://avatars0.githubusercontent.com/u/41483077?s=400\u0026v=4\" width=\"25px;\"/\u003e **Mattia Ceccarelli** [git](https://github.com/Mat092)\n\nSee also the list of [contributors](https://github.com/Nico-Curti/NumPyNet/contributors) [![GitHub contributors](https://img.shields.io/github/contributors/Nico-Curti/NumPyNet.svg?style=plastic)](https://github.com/Nico-Curti/NumPyNet/graphs/contributors/) who participated in this project.\n\n## License\n\nThe `NumPyNet` package is licensed under the MIT \"Expat\" License. [![License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/Nico-Curti/NumPyNet/blob/master/LICENSE.md)\n\n## Acknowledgment\n\nThanks goes to all contributors of this project.\n\n## Citation\n\nIf you have found `NumPyNet` helpful in your research, please consider citing this project repository\n\n```BibTex\n@misc{NumPyNet,\n  author = {Curti, Nico and Ceccarelli, Mattia},\n  title = {NumPyNet},\n  year = {2019},\n  publisher = {GitHub},\n  journal = {GitHub repository},\n  howpublished = {\\url{https://github.com/Nico-Curti/NumPyNet}},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnico-curti%2Fnumpynet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnico-curti%2Fnumpynet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnico-curti%2Fnumpynet/lists"}