diff --git a/.gitignore b/.gitignore index 1d1b4f06..f7b5189d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -lmu.egg-info +keras_lmu.egg-info *.swo *.swp *.ipynb_checkpoints diff --git a/.nengobones.yml b/.nengobones.yml index b7a5799c..f91b795b 100644 --- a/.nengobones.yml +++ b/.nengobones.yml @@ -1,7 +1,7 @@ -project_name: NengoLMU -pkg_name: lmu -repo_name: nengo/lmu -description: Legendre Memory Units +project_name: KerasLMU +pkg_name: keras_lmu +repo_name: nengo/keras-lmu +description: Keras implementation of Legendre Memory Units copyright_start: 2019 @@ -16,7 +16,7 @@ manifest_in: {} setup_py: python_requires: ">=3.6" install_req: - - scipy + - scipy>=1.0.0 - tensorflow>=2.1.0 tests_req: - pytest>=6.1.0 @@ -31,7 +31,6 @@ setup_py: - numpydoc>=0.6 classifiers: - "Development Status :: 3 - Alpha" - - "Framework :: Nengo" - "Intended Audience :: Science/Research" - "License :: Free for non-commercial use" - "Operating System :: OS Independent" @@ -51,10 +50,10 @@ docs_conf_py: html_redirects: getting_started.html: getting-started.html autoautosummary_change_modules: - lmu: - - lmu.layers.LMUCell - - lmu.layers.LMU - - lmu.layers.LMUFFT + keras_lmu: + - keras_lmu.layers.LMUCell + - keras_lmu.layers.LMU + - keras_lmu.layers.LMUFFT extensions: - nengo_sphinx_theme.ext.autoautosummary doctest_setup: diff --git a/CHANGES.rst b/CHANGES.rst index 360915ae..252ece1b 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -19,9 +19,20 @@ Release history - Removed - Fixed -0.2.1 (unreleased) +0.3.0 (unreleased) ================== +**Changed** + +- Renamed module from ``lmu`` to ``keras_lmu`` (so it will now be imported via + ``import keras_lmu``), renamed package from ``lmu`` to + ``keras-lmu`` (so it will now be installed via ``pip install keras-lmu``), and + changed any references to "NengoLMU" to "KerasLMU" (since this implementation is + based in the Keras framework rather than Nengo). In the future the ``lmu`` namespace + will be used as a meta-package to encapsulate LMU implementations in different + frameworks. (`#24`_) + +.. _#24: https://github.com/abr/lmu/pull/24 0.2.0 (November 2, 2020) ======================== @@ -80,7 +91,7 @@ Release history 0.1.0 (June 22, 2020) ===================== -Initial release of NengoLMU 0.1.0! Supports Python 3.5+. +Initial release of KerasLMU 0.1.0! Supports Python 3.5+. The API is considered unstable; parts are likely to change in the future. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 8eae63cd..61536332 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,19 +1,19 @@ .. Automatically generated by nengo-bones, do not edit this file directly ************************ -Contributing to NengoLMU +Contributing to KerasLMU ************************ Issues and pull requests are always welcome! -We appreciate help from the community to make NengoLMU better. +We appreciate help from the community to make KerasLMU better. Filing issues ============= -If you find a bug in NengoLMU, +If you find a bug in KerasLMU, or think that a certain feature is missing, please consider -`filing an issue `_! +`filing an issue `_! Please search the currently open issues first to see if your bug or feature request already exists. If so, feel free to add a comment to the issue @@ -22,7 +22,7 @@ so that we know that multiple people are affected. Making pull requests ==================== -If you want to fix a bug or add a feature to NengoLMU, +If you want to fix a bug or add a feature to KerasLMU, we welcome pull requests. Ensure that you fill out all sections of the pull request template, deleting the comments as you go. diff --git a/CONTRIBUTORS.rst b/CONTRIBUTORS.rst index ed841266..26ee4a76 100644 --- a/CONTRIBUTORS.rst +++ b/CONTRIBUTORS.rst @@ -1,11 +1,11 @@ .. Automatically generated by nengo-bones, do not edit this file directly ********************* -NengoLMU contributors +KerasLMU contributors ********************* -See https://github.com/nengo/lmu/graphs/contributors -for a list of the people who have committed to NengoLMU. +See https://github.com/nengo/keras-lmu/graphs/contributors +for a list of the people who have committed to KerasLMU. Thank you for your contributions! For the full list of the many contributors to the Nengo ecosystem, diff --git a/LICENSE.rst b/LICENSE.rst index 68c1faef..4d00d040 100644 --- a/LICENSE.rst +++ b/LICENSE.rst @@ -1,18 +1,18 @@ .. Automatically generated by nengo-bones, do not edit this file directly **************** -NengoLMU license +KerasLMU license **************** Copyright (c) 2019-2020 Applied Brain Research -NengoLMU is made available under a proprietary license +KerasLMU is made available under a proprietary license that permits using, copying, sharing, and making derivative works from -NengoLMU and its source code for any non-commercial purpose, +KerasLMU and its source code for any non-commercial purpose, as long as the above copyright notice and this permission notice are included in all copies or substantial portions of the software. -If you would like to use NengoLMU commercially, +If you would like to use KerasLMU commercially, licenses can be purchased from Applied Brain Research. Please contact info@appliedbrainresearch.com for more information. diff --git a/README.rst b/README.rst index eb6c5ff2..e70ff193 100644 --- a/README.rst +++ b/README.rst @@ -1,9 +1,9 @@ -Legendre Memory Units: Continuous-Time Representation in Recurrent Neural Networks ----------------------------------------------------------------------------------- +KerasLMU: Recurrent neural networks using Legendre Memory Units +--------------------------------------------------------------- `Paper `_ -This is a python software library containing various implementations of the +This is a Keras-based implementation of the Legendre Memory Unit (LMU). The LMU is a novel memory cell for recurrent neural networks that dynamically maintains information across long windows of time using relatively few resources. It has been shown to perform as well as standard LSTM or diff --git a/docs/api-reference.rst b/docs/api-reference.rst index 07d3cf77..d92e99df 100644 --- a/docs/api-reference.rst +++ b/docs/api-reference.rst @@ -9,7 +9,7 @@ API reference LMU Layers ========== -.. automodule:: lmu.layers +.. automodule:: keras_lmu.layers - .. autoautosummary:: lmu.layers + .. autoautosummary:: keras_lmu.layers :nosignatures: diff --git a/docs/basic-usage.rst b/docs/basic-usage.rst index 8490bcb9..78d525be 100644 --- a/docs/basic-usage.rst +++ b/docs/basic-usage.rst @@ -5,15 +5,15 @@ Basic usage *********** The standard Legendre Memory Unit (LMU) layer -implementation in NengoLMU is defined in the -``lmu.LMU`` class. The following code creates +implementation in KerasLMU is defined in the +``keras_lmu.LMU`` class. The following code creates a new LMU layer: .. testcode:: - import lmu + import keras_lmu - lmu_layer = lmu.LMU( + lmu_layer = keras_lmu.LMU( memory_d=1, order=256, theta=784, @@ -30,7 +30,7 @@ and ``units`` represents the dimensionality of the hidden component. To learn more about these parameters, check out the :ref:`LMU class API reference `. -Creating NengoLMU layers +Creating KerasLMU layers ------------------------ The ``LMU`` class functions as a standard diff --git a/docs/citation.rst b/docs/citation.rst index abab68f9..d298f676 100644 --- a/docs/citation.rst +++ b/docs/citation.rst @@ -2,7 +2,7 @@ Citation ******** -If you would like to cite NengoLMU in your research, please cite `this +If you would like to cite KerasLMU in your research, please cite `this paper `_: Aaron R. Voelker, Ivana Kajić, and Chris Eliasmith. Legendre Memory Units: diff --git a/docs/conf.py b/docs/conf.py index ddec5dc9..16a2cec9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,7 +4,7 @@ import os -import lmu +import keras_lmu extensions = [ "sphinx.ext.autodoc", @@ -31,7 +31,7 @@ # -- sphinx.ext.doctest doctest_global_setup = """ -import lmu +import keras_lmu import numpy as np import tensorflow as tf """ @@ -52,23 +52,23 @@ # -- notfound.extension notfound_template = "404.html" -notfound_urls_prefix = "/lmu/" +notfound_urls_prefix = "/keras-lmu/" # -- numpydoc config numpydoc_show_class_members = False # -- nengo_sphinx_theme.ext.autoautosummary autoautosummary_change_modules = { - "lmu": [ - "lmu.layers.LMUCell", - "lmu.layers.LMU", - "lmu.layers.LMUFFT", + "keras_lmu": [ + "keras_lmu.layers.LMUCell", + "keras_lmu.layers.LMU", + "keras_lmu.layers.LMUFFT", ], } # -- nengo_sphinx_theme.ext.sourcelinks -sourcelinks_module = "lmu" -sourcelinks_url = "https://github.com/nengo/lmu" +sourcelinks_module = "keras_lmu" +sourcelinks_url = "https://github.com/nengo/keras-lmu" # -- sphinx nitpicky = True @@ -84,20 +84,20 @@ linkcheck_anchors = True default_role = "py:obj" pygments_style = "sphinx" -user_agent = "lmu" +user_agent = "keras_lmu" -project = "NengoLMU" +project = "KerasLMU" authors = "Applied Brain Research" copyright = "2019-2020 Applied Brain Research" -version = ".".join(lmu.__version__.split(".")[:2]) # Short X.Y version -release = lmu.__version__ # Full version, with tags +version = ".".join(keras_lmu.__version__.split(".")[:2]) # Short X.Y version +release = keras_lmu.__version__ # Full version, with tags # -- HTML output templates_path = ["_templates"] html_static_path = ["_static"] html_theme = "nengo_sphinx_theme" -html_title = "NengoLMU {0} docs".format(release) -htmlhelp_basename = "NengoLMU" +html_title = "KerasLMU {0} docs".format(release) +htmlhelp_basename = "KerasLMU" html_last_updated_fmt = "" # Default output format (suppressed) html_show_sphinx = False html_favicon = os.path.join("_static", "favicon.ico") diff --git a/docs/examples.rst b/docs/examples.rst index ad48660b..f80a9d1d 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -9,7 +9,7 @@ are Jupyter notebooks and if you would like to run them yourself, refer to the `Jupyter documentation `_ for instructions on how to install and run Jupyter. -If you would like to see NengoLMU used to solve the Permuted Sequential MNIST task, +If you would like to see KerasLMU used to solve the Permuted Sequential MNIST task, which is the problem used in the `original paper `_, you can look through the example below: diff --git a/docs/examples/psMNIST.ipynb b/docs/examples/psMNIST.ipynb index eb09525f..11fde84e 100644 --- a/docs/examples/psMNIST.ipynb +++ b/docs/examples/psMNIST.ipynb @@ -27,7 +27,7 @@ "to perform the task successfully, the network needs to process information across the\n", "whole length of the input sequence.\n", "\n", - "The following notebook uses a single NengoLMU layer inside a simple TensorFlow model to\n", + "The following notebook uses a single KerasLMU layer inside a simple TensorFlow model to\n", "showcase the accuracy and efficiency of performing the psMNIST task using these novel\n", "memory cells. Using the LMU for this task currently produces state-of-the-art results\n", "this task ([see\n", @@ -47,7 +47,7 @@ "from IPython.display import Image, display\n", "import tensorflow as tf\n", "\n", - "import lmu" + "import keras_lmu" ] }, { @@ -257,7 +257,7 @@ "n_pixels = X_train.shape[1]\n", "\n", "lmu_layer = tf.keras.layers.RNN(\n", - " lmu.LMUCell(\n", + " keras_lmu.LMUCell(\n", " memory_d=1,\n", " order=256,\n", " theta=n_pixels,\n", diff --git a/docs/getting-started.rst b/docs/getting-started.rst index cb310b28..c83b3dc3 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -5,36 +5,34 @@ Getting started Installation ============ -To install NengoLMU, we recommend using ``pip``. +To install KerasLMU, we recommend using ``pip``. .. code:: bash - pip install lmu - -Before running this command, please ensure your system meets the NengoLMU requirements. + pip install keras-lmu Requirements ------------ -NengoLMU works with Python 3.6 or later. After installing NumPy and TensorFlow, ``pip`` +KerasLMU works with Python 3.6 or later. After installing NumPy and TensorFlow, ``pip`` will do its best to install all of the package's other requirements when it installs -NengoLMU. However, if anything goes wrong during this process, you can install each -required package manually and then try to ``pip install lmu`` again. +KerasLMU. However, if anything goes wrong during this process, you can install each +required package manually and then try to ``pip install keras-lmu`` again. Developer installation ---------------------- -If you want to modify NengoLMU, or get the very latest updates, you will need to +If you want to modify KerasLMU, or get the very latest updates, you will need to perform a developer installation: .. code-block:: bash - git clone https://github.com/abr/lmu - pip install -e ./lmu + git clone https://github.com/nengo/keras-lmu + pip install -e ./keras-lmu Installing TensorFlow --------------------- -NengoLMU is designed to work within TensorFlow. Assuming you have the required libraries +KerasLMU is designed to work within TensorFlow. Assuming you have the required libraries installed, the latest version of TensorFlow can be using ``pip install tensorflow`` To use TensorFlow with GPU support, you will need to have the CUDA/cuDNN libraries @@ -68,33 +66,33 @@ instructions below: Installing other packages ------------------------- -The steps above will only install NengoLMU's required dependencies. -Optional NengoLMU features require additional packages to be installed. +The steps above will only install KerasLMU's required dependencies. +Optional KerasLMU features require additional packages to be installed. - Running the test suite requires pytest. - Building the documentation requires Sphinx, NumPyDoc, nengo_sphinx_theme, and a few other packages. These additional dependencies can also be installed through ``pip`` when -installing NengoLMU. +installing KerasLMU. .. code-block:: bash - pip install lmu[tests] # Needed to run unit tests - pip install lmu[docs] # Needed to build docs - pip install lmu[all] # All of the above + pip install keras-lmu[tests] # Needed to run unit tests + pip install keras-lmu[docs] # Needed to build docs + pip install keras-lmu[all] # All of the above Next steps ========== -* If you want to learn how to use NengoLMU in your +* If you want to learn how to use KerasLMU in your models, read through the :ref:`basic usage ` page. * For a more detailed understanding of the various - classes and functions in the NengoLMU package, + classes and functions in the KerasLMU package, refer to the :ref:`API reference `. * If you are interested to learn the theoretical background behind how the Legendre Memory Unit works, we recommend reading `this technical overview `_. -* If you would like to see how NengoLMU is incorporated into various +* If you would like to see how KerasLMU is incorporated into various models, check out our :ref:`examples `. diff --git a/docs/index.rst b/docs/index.rst index 690fee19..3122303e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,10 +1,5 @@ -.. NengoLMU documentation master file, created by - sphinx-quickstart on Mon Jul 6 09:47:09 2020. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - ******** -NengoLMU +KerasLMU ******** .. include:: ../README.rst diff --git a/lmu/__init__.py b/keras_lmu/__init__.py similarity index 73% rename from lmu/__init__.py rename to keras_lmu/__init__.py index d92431e7..b1d8e991 100644 --- a/lmu/__init__.py +++ b/keras_lmu/__init__.py @@ -1,4 +1,4 @@ -"""LMU provides a package for deep learning with Legendre Memory Units.""" +"""KerasLMU provides a package for deep learning with Legendre Memory Units.""" from .layers import ( LMUCell, diff --git a/lmu/layers.py b/keras_lmu/layers.py similarity index 99% rename from lmu/layers.py rename to keras_lmu/layers.py index 58434e82..f41dd409 100644 --- a/lmu/layers.py +++ b/keras_lmu/layers.py @@ -1,5 +1,5 @@ """ -Core classes for the LMU package. +Core classes for the KerasLMU package. """ import numpy as np diff --git a/lmu/tests/__init__.py b/keras_lmu/tests/__init__.py similarity index 100% rename from lmu/tests/__init__.py rename to keras_lmu/tests/__init__.py diff --git a/lmu/tests/test_layers.py b/keras_lmu/tests/test_layers.py similarity index 99% rename from lmu/tests/test_layers.py rename to keras_lmu/tests/test_layers.py index d918e3e7..6a304228 100644 --- a/lmu/tests/test_layers.py +++ b/keras_lmu/tests/test_layers.py @@ -4,7 +4,7 @@ import pytest import tensorflow as tf -from lmu import layers +from keras_lmu import layers def test_multivariate_lmu(rng): diff --git a/lmu/version.py b/keras_lmu/version.py similarity index 78% rename from lmu/version.py rename to keras_lmu/version.py index be4d8ddf..cc8cbfdd 100644 --- a/lmu/version.py +++ b/keras_lmu/version.py @@ -1,4 +1,4 @@ -"""LMU version information. +"""KerasLMU version information. We use semantic versioning (see http://semver.org/). and conform to PEP440 (see https://www.python.org/dev/peps/pep-0440/). @@ -6,8 +6,8 @@ a release version. Release versions are git tagged with the version. """ -name = "lmu" -version_info = (0, 2, 1) # (major, minor, patch) +name = "keras_lmu" +version_info = (0, 3, 0) # (major, minor, patch) dev = 0 version = ( diff --git a/setup.cfg b/setup.cfg index b26ba0b4..64cdbbee 100644 --- a/setup.cfg +++ b/setup.cfg @@ -6,7 +6,7 @@ build-dir = docs/_build all_files = 1 [coverage:run] -source = lmu +source = keras_lmu [coverage:report] # Regexes for lines to exclude from consideration diff --git a/setup.py b/setup.py index 101cef2c..60e784d1 100644 --- a/setup.py +++ b/setup.py @@ -27,10 +27,10 @@ def read(*filenames, **kwargs): root = os.path.dirname(os.path.realpath(__file__)) -version = runpy.run_path(os.path.join(root, "lmu", "version.py"))["version"] +version = runpy.run_path(os.path.join(root, "keras_lmu", "version.py"))["version"] install_req = [ - "scipy", + "scipy>=1.0.0", "tensorflow>=2.1.0", ] docs_req = [ @@ -49,15 +49,15 @@ def read(*filenames, **kwargs): ] setup( - name="lmu", + name="keras-lmu", version=version, author="Applied Brain Research", author_email="info@appliedbrainresearch.com", packages=find_packages(), - url="https://www.nengo.ai/lmu", + url="https://www.nengo.ai/keras-lmu", include_package_data=False, license="Free for non-commercial use", - description="Legendre Memory Units", + description="Keras implementation of Legendre Memory Units", long_description=read("README.rst", "CHANGES.rst"), zip_safe=False, install_requires=install_req, @@ -70,7 +70,6 @@ def read(*filenames, **kwargs): python_requires=">=3.6", classifiers=[ "Development Status :: 3 - Alpha", - "Framework :: Nengo", "Intended Audience :: Science/Research", "License :: Free for non-commercial use", "Operating System :: OS Independent",