Style Guide
Code Style Guide
We follow the PEP8 Python style guide.
Additional style guidelines are enforced by Ruff and configured in pyproject.toml.
To quickly check if your code is formatted correctly, run ruff check in the tbp.monty directory.
Code Formatting
We use Ruff to check proper code formatting with a line length of 88.
A convenient way to ensure your code is formatted correctly is using the ruff formatter. If you use VSCode, you can get the Ruff VSCode extension and set it to format on save (modified lines only) so your code always looks nice and matches our style requirements.
Code Docstrings
We adopted the Google Style for docstrings. For more details, see the Google Python Style Guide - 3.8 Comments and Docstrings.
Libraries
Numpy Preferred over PyTorch
After discovering that torch-to-numpy conversions (and the reverse) were a significant speed bottleneck in our algorithms, we decided to consistently use NumPy to represent the data in our system.
We still require the PyTorch library since we use it for certain things, such as multiprocessing. However, please use NumPy operations for any vector and matrix operations whenever possible. If you think you cannot work with NumPy and need to use Torch, consider opening an RFC first to increase the chances of your PR being merged.
Another reason we discourage using PyTorch is to add a barrier for deep-learning to creep into Monty. Although we don't have a fundamental issue with contributors using deep learning, we worry that it will be the first thing someone's mind goes to when solving a problem (when you have a hammer...). We want contributors to think intentionally about whether deep-learning is the best solution for what they want to solve. Monty relies on very different principles than those most ML practitioners are used to, and so it is useful to think outside of the mental framework of deep-learning. More importantly, evidence that the brain can perform the long-range weight transport required by deep-learning's cornerstone algorithm - back-propagation - is extremely scarce. We are developing a system that, like the mammalian brain, should be able to use local learning signals to rapidly update representations, while also remaining robust under conditions of continual learning. As a general rule therefore, please avoid Pytorch, and the algorithm that it is usually leveraged to support - back-propagation!
You can read more about our views on deep learning in Monty in our FAQ.
Source Code Copyright and License Header
All source code files must have a copyright and license header. The header must be placed at the top of the file, on the first line, before any other code. For example, in Python:
# Copyright <YEARS> Numenta Inc.
#
# Copyright may exist in Contributors' modifications
# and/or contributions to the work.
#
# Use of this source code is governed by the MIT
# license that can be found in the LICENSE file or at
# https://opensource.org/licenses/MIT.
The <YEARS> is the year of the file's creation, and an optional sequence or range of years if the file has been modified over time. For example, if a file was created in 2024 and not modified again, the first line of the header should be # Copyright 2024 Numenta Inc.. If the file has been modified in consecutive years between 2022 and 2024, the header should be # Copyright 2022-2024 Numenta Inc.. If the file has been modified in multiple non-consecutive years in 2022, then in 2024 and 2025, the header should be # Copyright 2022,2024-2025 Numenta Inc..
In other words, if you are creating a new file, add the copyright and license header with the current year. If you are modifying an existing file and the header does not include the current year, then add the current year to the header. You should never need to modify anything aside from the year in the very first line of the header.
While we deeply value and appreciate every contribution, the source code file header is reserved for essential copyright and license information and will not be used for contributor acknowledgments.
Documentation Style Guide
Headings
In a document your first level of headings should be the # , then ## and so on. This is slightly confusing as usually # is reserved for the title, but on readme.com the h1 tag is used for the actual title of the document.
Use headings to split up long text block into managable chunks.
Headings can be referenced in other documents using a hash link [Headings](doc:style-guide#headings). For example Style Guide - Headings
All headings should use capitalization following APA convention. For detailed guidelines see the APA heading style guide.
Footnotes
Footnotes should be referenced in the document with a [1] notation that is linked to a section at the bottom # Footnotes
For example
This needs a footnote[1](#footnote1)
# Footnotes
<a name="footnote1">1</a>: Footnote text
Images
Images should be placed in /docs/figures in the repo.
Images use snake_case.ext
Images should generally be png or svg formats. Use jpg if the file is actually a photograph.
Use the optimal image size. If the file is larger than the display port on readme, consider shrinking it.
For example, the following markdown creates the image below:
caption text
Caption text is only visible on readme.com
Callouts
Readme supports four color coded callouts
> 👍 Something good
Something good
> 📘 Information
Information
> ⚠️ Warning
Warning
> ❗️ Alert
Alert
Numbers
Billions of people use commas as a thousands separator, and billions use the period as the thousands separator. As this documentation is expected to be widely used, we will use space as the separator, as this is the internationally recommended convention.
For example, 1 million is written numerically as 1 000 000.
Updated 1 day ago