{"id":13472425,"url":"https://github.com/mlech26l/ncps","last_synced_at":"2025-05-14T10:14:05.029Z","repository":{"id":41198995,"uuid":"290199641","full_name":"mlech26l/ncps","owner":"mlech26l","description":"PyTorch and TensorFlow implementation of NCP, LTC, and CfC wired neural models","archived":false,"fork":false,"pushed_at":"2024-08-14T13:50:44.000Z","size":6062,"stargazers_count":2100,"open_issues_count":25,"forks_count":337,"subscribers_count":70,"default_branch":"master","last_synced_at":"2025-04-02T00:18:49.229Z","etag":null,"topics":["cfc","keras","nature-machine-intelligence","ncp","recurrent-neural-network","tensorflow"],"latest_commit_sha":null,"homepage":"https://www.nature.com/articles/s42256-020-00237-3","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlech26l.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-25T11:43:27.000Z","updated_at":"2025-03-31T16:02:27.000Z","dependencies_parsed_at":"2024-01-16T07:22:17.530Z","dependency_job_id":"8b395e0c-4549-4ba5-9752-9735f514880a","html_url":"https://github.com/mlech26l/ncps","commit_stats":{"total_commits":122,"total_committers":9,"mean_commits":"13.555555555555555","dds":0.4098360655737705,"last_synced_commit":"695ec22d7d1831f2ced67346ef7d2f08c525bd47"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlech26l%2Fncps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlech26l%2Fncps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlech26l%2Fncps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlech26l%2Fncps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlech26l","download_url":"https://codeload.github.com/mlech26l/ncps/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247954086,"owners_count":21024155,"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":["cfc","keras","nature-machine-intelligence","ncp","recurrent-neural-network","tensorflow"],"created_at":"2024-07-31T16:00:54.547Z","updated_at":"2025-04-09T01:23:50.076Z","avatar_url":"https://github.com/mlech26l.png","language":"Python","funding_links":[],"categories":["Python","Frameworks","Spiking and Neuromorphic Frameworks"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/mlech26l/ncps/master/docs/img/banner.png\" width=\"800\"/\u003e\u003c/div\u003e\n\n# Neural Circuit Policies (for PyTorch and TensorFlow)\n\n[![DOI](https://zenodo.org/badge/290199641.svg)](https://zenodo.org/badge/latestdoi/290199641)\n![ci_badge](https://github.com/mlech26l/ncps/actions/workflows/python-test.yml/badge.svg) \n![pyversion](misc/pybadge.svg)\n![PyPI version](https://img.shields.io/pypi/v/ncps)\n![Documentation Status](https://readthedocs.org/projects/ncps/badge/?version=latest)\n![downloads](https://img.shields.io/pypi/dm/ncps)\n\n## 📜 Papers\n\n[Neural Circuit Policies Enabling Auditable Autonomy (Open Access)](https://publik.tuwien.ac.at/files/publik_292280.pdf).  \n[Closed-form continuous-time neural networks (Open Access)](https://www.nature.com/articles/s42256-022-00556-7)\n\nNeural Circuit Policies (NCPs) are designed sparse recurrent neural networks loosely inspired by the nervous system of the organism [C. elegans](http://www.wormbook.org/chapters/www_celegansintro/celegansintro.html). \nThe goal of this package is to making working with NCPs in PyTorch and keras as easy as possible.\n\n[📖 Docs](https://ncps.readthedocs.io/en/latest/index.html)\n\n```python\nimport torch\nfrom ncps.torch import CfC\n\nrnn = CfC(20,50) # (input, hidden units)\nx = torch.randn(2, 3, 20) # (batch, time, features)\nh0 = torch.zeros(2,50) # (batch, units)\noutput, hn = rnn(x,h0)\n```\n\n\n## Installation\n\n```bash\npip install ncps\n```\n\n## 🔖 Colab Notebooks\n\nWe have created a few Google Colab notebooks for an interactive introduction to the package\n\n- [Google Colab (Pytorch) Basic usage](https://colab.research.google.com/drive/1VWoGcpyqGvrUOUzH7ccppE__m-n1cAiI?usp=sharing)\n- [Google Colab (Tensorflow): Basic usage](https://colab.research.google.com/drive/1IvVXVSC7zZPo5w-PfL3mk1MC3PIPw7Vs?usp=sharing)\n- [Google Colab (Tensorflow): Processing irregularly sampled time-series](https://colab.research.google.com/drive/1wBojTMMMVWl2WbF6hASbST1-XhK_xs5u?usp=sharing)\n- [Google Colab (Tensorflow) Stacking NCPs with other layers](https://colab.research.google.com/drive/1-mZunxqVkfZVBXNPG0kTSKUNQUSdZiBI?usp=sharing)\n\n## End-to-end Examples\n\n- [Quickstart (torch and tf)](https://ncps.readthedocs.io/en/latest/quickstart.html)\n- [Atari Behavior Cloning (torch and tf)](https://ncps.readthedocs.io/en/latest/examples/atari_bc.html)\n- [Atari Reinforcement Learning (tf)](https://ncps.readthedocs.io/en/latest/examples/atari_ppo.html)\n\n## Usage: Models and Wirings\n\nThe package provides two models, the liquid time-constant (LTC) and the closed-form continuous-time (CfC) models.\nBoth models are available as ```tf.keras.layers.Layer``` or ```torch.nn.Module``` RNN layers.\n\n```python\nfrom ncps.torch import CfC, LTC\n\ninput_size = 20\nunits = 28 # 28 neurons\nrnn = CfC(input_size, units)\nrnn = LTC(input_size, units)\n```\n\nThe RNNs defined above consider fully-connected layers, i.e., as in LSTM, GRUs, and other RNNs.\nThe distinctiveness of NCPs is their structured wiring diagram. \nTo combine the LTC or CfC model with a \n\n```python\nfrom ncps.torch import CfC, LTC\nfrom ncps.wirings import AutoNCP\n\nwiring = AutoNCP(28, 4) # 28 neurons, 4 outputs\ninput_size = 20\nrnn = CfC(input_size, wiring)\nrnn = LTC(input_size, wiring)\n```\n\n![alt](https://github.com/mlech26l/ncps/raw/master/docs/img/things.png)\n\n## Tensorflow\n\nThe Tensorflow bindings are available via the ```ncps.tf``` module.\n\n```python\nfrom ncps.tf import CfC, LTC\nfrom ncps.wirings import AutoNCP\n\nunits = 28\nwiring = AutoNCP(28, 4) # 28 neurons, 4 outputs\ninput_size = 20\nrnn1 = LTC(units) # fully-connected LTC\nrnn2 = CfC(units) # fully-connected CfC\nrnn3 = LTC(wiring) # NCP wired LTC\nrnn4 = CfC(wiring) # NCP wired CfC\n```\n\nWe can then combine the NCP cell with arbitrary ```tf.keras.layers```, for instance to build a powerful image sequence classifier:\n\n```python\nfrom ncps.wirings import AutoNCP\nfrom ncps.tf import LTC\nimport tensorflow as tf\nheight, width, channels = (78, 200, 3)\n\nncp = LTC(AutoNCP(32, output_size=8), return_sequences=True)\n\nmodel = tf.keras.models.Sequential(\n    [\n        tf.keras.layers.InputLayer(input_shape=(None, height, width, channels)),\n        tf.keras.layers.TimeDistributed(\n            tf.keras.layers.Conv2D(32, (5, 5), activation=\"relu\")\n        ),\n        tf.keras.layers.TimeDistributed(tf.keras.layers.MaxPool2D()),\n        tf.keras.layers.TimeDistributed(\n            tf.keras.layers.Conv2D(64, (5, 5), activation=\"relu\")\n        ),\n        tf.keras.layers.TimeDistributed(tf.keras.layers.MaxPool2D()),\n        tf.keras.layers.TimeDistributed(tf.keras.layers.Flatten()),\n        tf.keras.layers.TimeDistributed(tf.keras.layers.Dense(32, activation=\"relu\")),\n        ncp,\n        tf.keras.layers.TimeDistributed(tf.keras.layers.Activation(\"softmax\")),\n    ]\n)\nmodel.compile(\n    optimizer=tf.keras.optimizers.Adam(0.01),\n    loss='sparse_categorical_crossentropy',\n)\n```\n\n```bib\n@article{lechner2020neural,\n  title={Neural circuit policies enabling auditable autonomy},\n  author={Lechner, Mathias and Hasani, Ramin and Amini, Alexander and Henzinger, Thomas A and Rus, Daniela and Grosu, Radu},\n  journal={Nature Machine Intelligence},\n  volume={2},\n  number={10},\n  pages={642--652},\n  year={2020},\n  publisher={Nature Publishing Group}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlech26l%2Fncps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlech26l%2Fncps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlech26l%2Fncps/lists"}