# Neural Fields – Old Idea, New Glory
[![license][license-badge]][license]
[![docs][docs-stable-badge]][docs-stable]
[![docs][docs-latest-badge]][docs-latest]
[![pre-commit][pre-commit-badge]][pre-commit]
[![bandit][bandit-badge]][bandit-hp]
[![isort][isort-badge]][isort-hp]
[![black][black-badge]][black]
[![ci][ci-badge]][ci]
[![tests][tests-badge]][tests]
[![coverage][coverage-badge]][coverage]
## About
In 1977, Shun-ichi Amari introduced _neural fields_, a class of potential-based recurrent neural networks [1].
This architecture was developed as a simplistic model of the activity of neurons in a (human) brain.
It's main characteristic is the lateral in-/exhibition of neurons though their accumulated potential.
Due to its simplicity and expressiveness, Amari’s work was highly influential and led to several follow-up papers such
as [2-6] to only name a few.
## Support
If you use code or ideas from this repository for your projects or research, **please cite it**.
```
@misc{Muratore_neuralfields,
author = {Fabio Muratore},
title = {neuralfields - A type of potential-based recurrent neural networks implemented with PyTorch},
year = {2023},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/famura/neuralfields}}
}
```
## Features
* There are two variants of the neural fields implemented in this repository: one called `NeuralField` that matches
the model of Amari closely using 1D convolutions, as well as another one called `SimpleNeuralField` that replaces the
convolutions and introduces custom potential dynamics function.
* Both implementations have by modern standards very few, i.e., typically less than 1000, parameters. I suggest that you
start with the `NeuralField` class since it is more expressive. However, the `SimpleNeuralField` has the benefit of
operating with typically less than 20 parameters, which allows you to use optimizers that otherwise might not scale.
* Both, `NeuralField` and `SimpleNeuralField`, model classes are subclasses of `torch.nn.Module`, hence able to process
batched data and run on GPUs.
* The [examples](https://github.com/famura/neuralfields/blob/main/examples) contain a script for time series learning.
However, it is also possible to use neural fields as generative models.
* This repository is a spin-off from [SimuRLacra](https://github.com/famura/SimuRLacra) where the neural fields have
been used as the backbone for control policies. In `SimuRLacra`, the focus is on reinforcement learning for
sim-to-real transfer. However, the goal of this repository is to make the implementation **as general as possible**,
such that it could for example be used as generative model.
### Time series learning example
 
### Time series generation example
 
## Getting Started
To install this package, simply run
```sh
pip install neuralfields
```
For further information, please have a look at the [getting started guide][docs-getting-started].
In the documentation, you can also find the [complete reference of the source code][docs-code-reference].
---
### References
[1] S-I. Amari. _Dynamics of pattern formation in lateral-inhibition type neural fields_. Biological Cybernetics.
1977.<br />
[2] K. Kishimoto and S-I. Amari. _Existence and stability of local excitations in homogeneous neural fields_. Journal
of Mathematical Biology, 1979.<br />
[3] W. Erlhagen and G. Schöner. _Dynamic field theory of movement preparation_. Psychological Review, 2002.<br />
[4] S-I. Amari, H. Park, and T. Ozeki. _Singularities affect dynamics of learning in neuromanifolds_. Neural
Computation, 2006.<br />
[5] T. Luksch, M. Gineger, M. Mühlig, T. Yoshiike, _Adaptive Movement Sequences and Predictive Decisions based on
Hierarchical Dynamical Systems_. International Conference on Intelligent Robots and Systems, 2012.<br />
[6] C. Kuehn and J. M. Tölle. _A gradient flow formulation for the stochastic Amari neural field model_. Journal of
Mathematical Biology, 2019.
<!-- URLs -->
[bandit-badge]: https://img.shields.io/badge/security-bandit-green.svg
[bandit-hp]: https://github.com/PyCQA/bandit
[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
[black]: https://github.com/psf/black
[ci-badge]: https://github.com/famura/neuralfields/actions/workflows/ci.yaml/badge.svg
[ci]: https://github.com/famura/neuralfields/actions/workflows/ci.yaml
[coverage-badge]: https://famura.github.io/neuralfields/latest/exported/coverage/badge.svg
[coverage]: https://famura.github.io/neuralfields/latest/exported/coverage/report
[docs-stable-badge]: https://img.shields.io/badge/docs-stable-informational
[docs-latest-badge]: https://img.shields.io/badge/docs-latest-informational
[docs-code-reference]: https://famura.github.io/neuralfields/stable/reference
[docs-getting-started]: https://famura.github.io/neuralfields/stable/getting_started
[docs-stable]: https://famura.github.io/neuralfields/stable
[docs-latest]: https://famura.github.io/neuralfields/latest
[isort-badge]: https://img.shields.io/badge/imports-isort-green
[isort-hp]: https://pycqa.github.io/isort/
[license-badge]: https://img.shields.io/badge/license-MIT--v4-informational
[license]: https://github.com/famura/neuralfields/LICENSE.txt
[pre-commit-badge]: https://img.shields.io/badge/pre--commit-enabled-green
[pre-commit]: https://github.com/pre-commit/pre-commit
[tests-badge]: https://famura.github.io/neuralfields/latest/exported/tests/badge.svg
[tests]: https://famura.github.io/neuralfields/latest/exported/tests/report
Raw data
{
"_id": null,
"home_page": "https://github.com/famura/neuralfields",
"name": "neuralfields",
"maintainer": "Fabio Muratore",
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": "robot-learning@famura.net",
"keywords": null,
"author": "Fabio Muratore",
"author_email": "robot-learning@famura.net",
"download_url": "https://files.pythonhosted.org/packages/de/f3/39c9863f80457e187e4981c274ea335eafd32e5700463f5e538137eedaf1/neuralfields-0.4.5.tar.gz",
"platform": null,
"description": "# Neural Fields – Old Idea, New Glory\n\n[![license][license-badge]][license]\n[![docs][docs-stable-badge]][docs-stable]\n[![docs][docs-latest-badge]][docs-latest]\n[![pre-commit][pre-commit-badge]][pre-commit]\n[![bandit][bandit-badge]][bandit-hp]\n[![isort][isort-badge]][isort-hp]\n[![black][black-badge]][black]\n[![ci][ci-badge]][ci]\n[![tests][tests-badge]][tests]\n[![coverage][coverage-badge]][coverage]\n\n## About\n\nIn 1977, Shun-ichi Amari introduced _neural fields_, a class of potential-based recurrent neural networks [1].\nThis architecture was developed as a simplistic model of the activity of neurons in a (human) brain.\nIt's main characteristic is the lateral in-/exhibition of neurons though their accumulated potential.\nDue to its simplicity and expressiveness, Amari\u2019s work was highly influential and led to several follow-up papers such\nas [2-6] to only name a few.\n\n## Support\n\nIf you use code or ideas from this repository for your projects or research, **please cite it**.\n\n```\n@misc{Muratore_neuralfields,\n author = {Fabio Muratore},\n title = {neuralfields - A type of potential-based recurrent neural networks implemented with PyTorch},\n year = {2023},\n publisher = {GitHub},\n journal = {GitHub repository},\n howpublished = {\\url{https://github.com/famura/neuralfields}}\n}\n```\n\n## Features\n\n* There are two variants of the neural fields implemented in this repository: one called `NeuralField` that matches\n the model of Amari closely using 1D convolutions, as well as another one called `SimpleNeuralField` that replaces the\n convolutions and introduces custom potential dynamics function.\n* Both implementations have by modern standards very few, i.e., typically less than 1000, parameters. I suggest that you\n start with the `NeuralField` class since it is more expressive. However, the `SimpleNeuralField` has the benefit of\n operating with typically less than 20 parameters, which allows you to use optimizers that otherwise might not scale.\n* Both, `NeuralField` and `SimpleNeuralField`, model classes are subclasses of `torch.nn.Module`, hence able to process\n batched data and run on GPUs.\n* The [examples](https://github.com/famura/neuralfields/blob/main/examples) contain a script for time series learning.\n However, it is also possible to use neural fields as generative models.\n* This repository is a spin-off from [SimuRLacra](https://github.com/famura/SimuRLacra) where the neural fields have\n been used as the backbone for control policies. In `SimuRLacra`, the focus is on reinforcement learning for\n sim-to-real transfer. However, the goal of this repository is to make the implementation **as general as possible**,\n such that it could for example be used as generative model.\n\n### Time series learning example\n \n\n### Time series generation example\n \n\n## Getting Started\n\nTo install this package, simply run\n\n```sh\npip install neuralfields\n```\n\nFor further information, please have a look at the [getting started guide][docs-getting-started].\nIn the documentation, you can also find the [complete reference of the source code][docs-code-reference].\n\n---\n### References\n\n[1] S-I. Amari. _Dynamics of pattern formation in lateral-inhibition type neural fields_. Biological Cybernetics.\n1977.<br />\n[2] K. Kishimoto and S-I. Amari. _Existence and stability of local excitations in homogeneous neural fields_. Journal\nof Mathematical Biology, 1979.<br />\n[3] W. Erlhagen and G. Sch\u00f6ner. _Dynamic field theory of movement preparation_. Psychological Review, 2002.<br />\n[4] S-I. Amari, H. Park, and T. Ozeki. _Singularities affect dynamics of learning in neuromanifolds_. Neural\nComputation, 2006.<br />\n[5] T. Luksch, M. Gineger, M. M\u00fchlig, T. Yoshiike, _Adaptive Movement Sequences and Predictive Decisions based on\nHierarchical Dynamical Systems_. International Conference on Intelligent Robots and Systems, 2012.<br />\n[6] C. Kuehn and J. M. T\u00f6lle. _A gradient flow formulation for the stochastic Amari neural field model_. Journal of\nMathematical Biology, 2019.\n\n\n<!-- URLs -->\n[bandit-badge]: https://img.shields.io/badge/security-bandit-green.svg\n[bandit-hp]: https://github.com/PyCQA/bandit\n[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg\n[black]: https://github.com/psf/black\n[ci-badge]: https://github.com/famura/neuralfields/actions/workflows/ci.yaml/badge.svg\n[ci]: https://github.com/famura/neuralfields/actions/workflows/ci.yaml\n[coverage-badge]: https://famura.github.io/neuralfields/latest/exported/coverage/badge.svg\n[coverage]: https://famura.github.io/neuralfields/latest/exported/coverage/report\n[docs-stable-badge]: https://img.shields.io/badge/docs-stable-informational\n[docs-latest-badge]: https://img.shields.io/badge/docs-latest-informational\n[docs-code-reference]: https://famura.github.io/neuralfields/stable/reference\n[docs-getting-started]: https://famura.github.io/neuralfields/stable/getting_started\n[docs-stable]: https://famura.github.io/neuralfields/stable\n[docs-latest]: https://famura.github.io/neuralfields/latest\n[isort-badge]: https://img.shields.io/badge/imports-isort-green\n[isort-hp]: https://pycqa.github.io/isort/\n[license-badge]: https://img.shields.io/badge/license-MIT--v4-informational\n[license]: https://github.com/famura/neuralfields/LICENSE.txt\n[pre-commit-badge]: https://img.shields.io/badge/pre--commit-enabled-green\n[pre-commit]: https://github.com/pre-commit/pre-commit\n[tests-badge]: https://famura.github.io/neuralfields/latest/exported/tests/badge.svg\n[tests]: https://famura.github.io/neuralfields/latest/exported/tests/report\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A type of potential-based recurrent neural networks implemented with PyTorch",
"version": "0.4.5",
"project_urls": {
"Documentation": "https://famura.github.io/neuralfields",
"Homepage": "https://github.com/famura/neuralfields",
"Repository": "https://github.com/famura/neuralfields"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9892267bf80cbcfd204be580889c47c026ffba9cfaf3534b772263cf2d4216ed",
"md5": "b46a0d282b85d0ae99eee9b2e91ccf08",
"sha256": "3424d6016a90a076eaeee82018a5914914f1871950da5ed207defe4e583f4ab6"
},
"downloads": -1,
"filename": "neuralfields-0.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b46a0d282b85d0ae99eee9b2e91ccf08",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 26473,
"upload_time": "2024-11-20T13:44:51",
"upload_time_iso_8601": "2024-11-20T13:44:51.978996Z",
"url": "https://files.pythonhosted.org/packages/98/92/267bf80cbcfd204be580889c47c026ffba9cfaf3534b772263cf2d4216ed/neuralfields-0.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "def339c9863f80457e187e4981c274ea335eafd32e5700463f5e538137eedaf1",
"md5": "be595b8b8b566cb4275bce449022a3ed",
"sha256": "9d5b095c73371d1b8355e2c402cdc225d4593562fbe521ede43cdb2a1c79a5b3"
},
"downloads": -1,
"filename": "neuralfields-0.4.5.tar.gz",
"has_sig": false,
"md5_digest": "be595b8b8b566cb4275bce449022a3ed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 20905,
"upload_time": "2024-11-20T13:44:52",
"upload_time_iso_8601": "2024-11-20T13:44:52.975302Z",
"url": "https://files.pythonhosted.org/packages/de/f3/39c9863f80457e187e4981c274ea335eafd32e5700463f5e538137eedaf1/neuralfields-0.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 13:44:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "famura",
"github_project": "neuralfields",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "neuralfields"
}
JSON
