diff --git a/.vale.ini b/.vale.ini index c46e0ba8..69665c25 100644 --- a/.vale.ini +++ b/.vale.ini @@ -2,7 +2,7 @@ StylesPath = .vale/styles Vocab = TBP [{docs/*.md,README.md}] -BasedOnStyles = Docs +BasedOnStyles = Vale, Docs [*.md] BlockIgnores = (?s) *\[block:embed\].*?\[/block\] diff --git a/.vale/styles/Docs/Programming.yml b/.vale/styles/Docs/Programming.yml deleted file mode 100644 index 4f61ea68..00000000 --- a/.vale/styles/Docs/Programming.yml +++ /dev/null @@ -1,5 +0,0 @@ -extends: spelling -message: "Did you really mean '%s'?" -level: error -filters: - - '[a-z]+(_[a-z]+)+' \ No newline at end of file diff --git a/.vale/styles/config/vocabularies/TBP/accept.txt b/.vale/styles/config/vocabularies/TBP/accept.txt index 4c3b16bf..45f69a24 100644 --- a/.vale/styles/config/vocabularies/TBP/accept.txt +++ b/.vale/styles/config/vocabularies/TBP/accept.txt @@ -1,48 +1,48 @@ -\bBluesky\b -neocortex -\bMountcastle\b -\bconfigs\b -\bConfig\b -\bconfig\b +# This file is case-sensitive by default and you can use regex +# see the docs here: https://vale.sh/docs/keys/vocab#file-format +Bluesky +[Nn]eocortex +[a-zA-Z.]+(_[a-zA-Z.]+)+ +Mountcastle +[Cc]onfigs? skillset -\bLMs*\b -\bSMs*\b -\bSDRs*\b -hippocampal -\bheterarchy\b +LMs? +SMs? +SDRs? +[hH]ippocampal +[hH]eterarchy saccading -\bHTM\b -\bANNs*\b -\bCNNs*\b -\bGNNs*\b -\bDNNs*\b -\bLLMs*\b -\bCPUs*\b -\bTGZ\b +HTM +ANNs? +CNNs? +GNNs? +DNNs? +LLMs? +CPUs? +TGZ|tgz saccade colliculus affordances -subgoals +[Ss]ubgoals KDTree resampling wandb distractor parallelization -arxiv -\bNum\b +[aA]rXiv +Num bioRxiv worldimages -neocortical -Initializer +[nN]eocortical +[Ii]nitializer resample actuations Calli -Omniglot +[oO]mniglot iter Dataloader kd -thresholding -Thresholding +[Tt]hresholding multimodal heterarchical subfolders @@ -63,20 +63,19 @@ voxel voxels subclassed youtube -url +URL fullscreen favicon href dataclass -Pretrained -pretrained -runtimes +[pP]retrained +[Rr]untimes neurophysiologist -mixin -Conda -Miniconda +[Mm]ixin +[cC]onda +[mM]iniconda zsh -wandb +[Ww]andb utils matplotlib timeseries @@ -85,17 +84,17 @@ misclassification _all_ args eval -dataloader +[Dd]ata[Ll]oader docstring Leyman Sampath Shen -Neuromorphic +[nN]euromorphic interpretability Walkthrough presynaptic subcortically -Pytorch +PyTorch Guillery Blekeslee Felleman @@ -125,8 +124,8 @@ Aru Scheinkman Klukas Purdy -xyz -readme +xyz|XYZ +[Rr]eadme|README substep CLA unmerged @@ -139,16 +138,15 @@ repo rdme cli semver -callouts -discretized -discretize +[Cc]allouts +[Dd]iscretized? discretization profiler overconstrained loopdown perceptrons bool -gaussian +[gG]aussian Cui learnable Eitan @@ -156,22 +154,23 @@ Azoff Sync'ing subdocuments sync'd -\bNumpy\b -\bNumenta\b -\bLeadholm\b -\bKalman\b +NumPy|Numpy +Numenta +Leadholm +Kalman biofilm -\bTolman's\b -\befference\b -\bEfference\b -\bTriaged\b -neuroscientists +Tolman's +[eE]fference +[Tt]riaged +YouTube +GitHub +[nN]euroscientists Constantinescu O'Keefe Nadel Milner Goodale -allocentric +[aA]llocentric Hebbian Hopfield -Arcimboldo \ No newline at end of file +Arcimboldo diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 4c59d9fd..13df9219 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -11,7 +11,7 @@ We appreciate all of your contributions. Below, you will find a list of ways to There are many ways in which you can contribute to the code. For some suggestions, see the [Contributing Code Guide](ways-to-contribute-to-code.md). -Monty integrates code changes using Github Pull Requests. For details on how Monty uses Pull Requests, please consult the [Contributing Pull Requests](ways-to-contribute-to-code.md) guide. +Monty integrates code changes using GitHub Pull Requests. For details on how Monty uses Pull Requests, please consult the [Contributing Pull Requests](ways-to-contribute-to-code.md) guide. # Document diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index 23778386..42bcf8c6 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -17,12 +17,16 @@ We use [Vale](https://vale.sh/) to lint our documentation. The linting process c The linting rules are defined in the `/.vale/` directory. -### How to Install and Use Vale +## Adding New Words to the Dictionary -1. **Install Vale** +You can add new words to the dictionary by adding them to `.vale/styles/config/vocabularies/TBP/accept.txt` - for more information see [Vale's documentation](https://vale.sh/docs/keys/vocab#file-format). + +## How to Install and Use Vale + +1. **Install Vale** Download Vale from its [installation page](https://vale.sh/docs/install). -2. **Run Vale** +2. **Run Vale** Use the following command in your terminal to run Vale: ```bash @@ -35,7 +39,6 @@ The linting rules are defined in the `/.vale/` directory. ✔ 0 errors, 0 warnings and 0 suggestions in 141 files. ``` - # Relative Links Links to other documents should use the standard markdown link syntax, and should be relative to the documents location. @@ -78,7 +81,7 @@ title: 'New Placeholder Example Doc' >Please put the title in single quotes and, if applicable, escape any single quotes using two single quotes in a row. Example: `title: 'My New Doc''s'` -> 🚧 Your title must match the url-safe slug +> 🚧 Your title must match the URL-safe slug > >If your title is `My New Doc's` then your file name should be `my-new-docs.md` diff --git a/docs/contributing/guides-for-maintainers/triage.md b/docs/contributing/guides-for-maintainers/triage.md index a6f80bf7..bce00d20 100644 --- a/docs/contributing/guides-for-maintainers/triage.md +++ b/docs/contributing/guides-for-maintainers/triage.md @@ -64,7 +64,7 @@ The desired cadence for Pull Request Triage is at least once per business day. First, review any Pull Requests pending CLA. > [!NOTE] ->Pending CLA link (is pull request, is open, is not a draft, is not triaged, is pending cla) +>Pending CLA link (is pull request, is open, is not a draft, is not triaged, is pending CLA) > > @@ -73,7 +73,7 @@ If the Pull Request CLA check is passing (you may need to rerun the CLA check), ## 2. Triage > [!NOTE] -> Triage link (is pull request, is open, is not a draft, is not triaged, is not pending cla) +> Triage link (is pull request, is open, is not a draft, is not triaged, is not pending CLA) > > diff --git a/docs/contributing/pull-requests.md b/docs/contributing/pull-requests.md index 1356cd3a..1233f43e 100644 --- a/docs/contributing/pull-requests.md +++ b/docs/contributing/pull-requests.md @@ -1,7 +1,7 @@ --- title: Pull Requests --- -Monty uses Github Pull Requests to integrate code changes. +Monty uses GitHub Pull Requests to integrate code changes. # Before Making a Pull Request @@ -36,7 +36,7 @@ Before submitting a Pull Request, you should set up your development environment ```shell git push ``` -7. [Create a new Github Pull Request from your fork to the official Monty repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). +7. [Create a new GitHub Pull Request from your fork to the official Monty repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). 8. Respond to and address any comments on your Pull Request. See [Pull Request Flow](pull-requests/pull-request-flow.md) for what to expect. 9. Once your Pull Request is approved, it will be merged by one of the Maintainers. Thank you for contributing! 🥳🎉🎊 diff --git a/docs/contributing/style-guide.md b/docs/contributing/style-guide.md index e5c0dbe2..721fa5a0 100644 --- a/docs/contributing/style-guide.md +++ b/docs/contributing/style-guide.md @@ -21,13 +21,13 @@ We adopted the Google Style for docstrings. For more details, see the [Google Py ## Libraries -### Numpy Preferred Over PyTorch +### 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. +After discovering that PyTorch-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! +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](../how-monty-works/faq-monty.md#why-does-monty-not-make-use-of-deep-learning). diff --git a/docs/contributing/ways-to-contribute-to-code.md b/docs/contributing/ways-to-contribute-to-code.md index 4f6fb68b..ee030ecf 100644 --- a/docs/contributing/ways-to-contribute-to-code.md +++ b/docs/contributing/ways-to-contribute-to-code.md @@ -18,4 +18,4 @@ There are many ways in which you can contribute to the code. The list below is n # How To Contribute Code -Monty integrates code changes using Github Pull Requests. To start contributing code to Monty, please consult the [Contributing Pull Requests](pull-requests.md) guide. \ No newline at end of file +Monty integrates code changes using GitHub Pull Requests. To start contributing code to Monty, please consult the [Contributing Pull Requests](pull-requests.md) guide. \ No newline at end of file diff --git a/docs/future-work/learning-module-improvements/implement-test-gnns-to-model-object-behaviors-states.md b/docs/future-work/learning-module-improvements/implement-test-gnns-to-model-object-behaviors-states.md index c16c7dd5..edce90c7 100644 --- a/docs/future-work/learning-module-improvements/implement-test-gnns-to-model-object-behaviors-states.md +++ b/docs/future-work/learning-module-improvements/implement-test-gnns-to-model-object-behaviors-states.md @@ -4,7 +4,7 @@ title: Implement & Test GNNs to Model Object Behaviors & States We would like to test using local functions between nodes of an LM's graph to model object behaviors. In particular, we would like to model how an object evolves over time due to external and internal influences, by learning how nodes within the object impact one-another based on these factors. This relates to graph-neural networks, and [graph networks more generally](https://arxiv.org/pdf/1806.01261), however learning should rely on sensory and motor information local to the LM. Ideally learned relations will generalize across different edges, e.g. the understanding that two nodes are connected by a rigid edge vs. a spring. -As noted, all learning should happen locally within the graph, so although gradient descent can be used, we should not back-propagate error signals through other LMs. Please see our related policy on [using Numpy rather than Pytorch for contributions](../../contributing/style-guide#numpy-preferred-over-pytorch). For further reading, see our discussion on [Modeling Object Behavior Using Graph Message Passing](https://github.com/thousandbrainsproject/monty_lab/tree/main/object_behaviors#implementation-routes-for-the-relational-inference-model) in the Monty Labs repository. +As noted, all learning should happen locally within the graph, so although gradient descent can be used, we should not back-propagate error signals through other LMs. Please see our related policy on [using Numpy rather than PyTorch for contributions](../../contributing/style-guide#numpy-preferred-over-pytorch). For further reading, see our discussion on [Modeling Object Behavior Using Graph Message Passing](https://github.com/thousandbrainsproject/monty_lab/tree/main/object_behaviors#implementation-routes-for-the-relational-inference-model) in the Monty Labs repository. We have a dataset that should be useful for testing approaches to this task, which can be found in [Monty Labs](https://github.com/thousandbrainsproject/monty_lab/tree/main/object_behaviors). diff --git a/docs/how-monty-works/experiment.md b/docs/how-monty-works/experiment.md index 8bb00779..edd9fc40 100644 --- a/docs/how-monty-works/experiment.md +++ b/docs/how-monty-works/experiment.md @@ -14,13 +14,13 @@ In reality an agent interacts continuously with the world and time is not explic - **monty_step** (model.episode_steps total_steps): number of observations sent to the Monty model. This includes observations that were not interesting enough to be sent to an LM such as off-object observations. It includes both matching and exploratory steps. - - **monty_matching_step** (model.matching_steps): At least one LM performed a matching step (updating its possible matches using an observation). There are also exploratory steps which do not update possible matches and only store an observation in the LMs buffer. These are not counted here. + - **monty_matching_step** (`model.matching_steps`): At least one LM performed a matching step (updating its possible matches using an observation). There are also exploratory steps which do not update possible matches and only store an observation in the LMs buffer. These are not counted here. - - **num_steps** (lm.buffer.get_num_matching_steps): Number of matching steps that a specific LM performed. + - **num_steps** (`lm.buffer.get_num_matching_steps`): Number of matching steps that a specific LM performed. - - **lm_step** (max(num_steps)): Number of matching steps performed by the LM that took the most steps. + - **lm_step** (`max(num_steps)`): Number of matching steps performed by the LM that took the most steps. - - **lm_steps_indv_ts** (lm.buffer\["individual_ts_reached_at_step"\]): Number of matching steps a specific LM performed until reaching a local terminal state. A local terminal state means that a specific LM has settled on a result (match or no match). This does not mean that the entire Monty system has reached a terminal state since it usually requires multiple LMs to have reached a local terminal state. For more details see section [Terminal Condition](doc:evidence-based-learning-module#terminal-condition) + - **lm_steps_indv_ts** (`lm.buffer["individual_ts_reached_at_step"]`): Number of matching steps a specific LM performed until reaching a local terminal state. A local terminal state means that a specific LM has settled on a result (match or no match). This does not mean that the entire Monty system has reached a terminal state since it usually requires multiple LMs to have reached a local terminal state. For more details see section [Terminal Condition](doc:evidence-based-learning-module#terminal-condition) - **Episode:** putting a single object in the environment and taking steps until a terminal condition is reached, like recognizing the object or exceeding max steps. diff --git a/docs/how-monty-works/faq-monty.md b/docs/how-monty-works/faq-monty.md index 60609915..02be21b5 100644 --- a/docs/how-monty-works/faq-monty.md +++ b/docs/how-monty-works/faq-monty.md @@ -150,7 +150,7 @@ So while there is hierarchy in both CNNs and the human visual system, the former Concepts from symbolic AI have some similarities to the Thousand Brains Theory, including the importance of discrete entities, and mapping how these are structurally related to one another. However, we believe that it is important that representations are grounded in a sensorimotor model of the world, whereas symbolic approaches typically begin at high levels of abstraction. -However, the approach we are adopting contrasts to some "neuro-symbolic" approaches that have been proposed. In particular, we are not attempting to embed entangled, object-impoverished deep-learning representations within abstract, symbolic spaces. Rather, we believe that object-centric representations using reference frames should be the representational substrate from the lowest-level of representations (vision, touch) all the way up to to abstract concepts (languages, societies, mathematics, etc.). Such a commonality in representation is consistent with the re-use of the same neural hardware (the cortical column) through the human neocortex, from sensory regions to higher-level, "cognitive" regions. +However, the approach we are adopting contrasts to some "neuro-symbolic" approaches that have been proposed. In particular, we are not attempting to embed entangled, object-impoverished deep-learning representations within abstract, symbolic spaces. Rather, we believe that object-centric representations using reference frames should be the representational substrate from the lowest-level of representations (vision, touch) all the way up to abstract concepts (languages, societies, mathematics, etc.). Such a commonality in representation is consistent with the re-use of the same neural hardware (the cortical column) through the human neocortex, from sensory regions to higher-level, "cognitive" regions. # Applications of Monty diff --git a/docs/how-to-use-monty/common-issues-and-how-to-fix-them.md b/docs/how-to-use-monty/common-issues-and-how-to-fix-them.md index a6f034de..80100d4f 100644 --- a/docs/how-to-use-monty/common-issues-and-how-to-fix-them.md +++ b/docs/how-to-use-monty/common-issues-and-how-to-fix-them.md @@ -7,7 +7,7 @@ Below we highlight a few issues that often crop up and can present problems when ## Quaternions -Be aware that in Numpy, and in the saved CSV result files, quaternions follow the wxyz format, where "w" is the real component. Thus the identity rotation would be [1, 0, 0, 0]. In contrast however, Scipy.Rotation expects them to be in xyzw format. When operating with quaternions, it is therefore important to be aware of what format you should be using for the particular setting. +Be aware that in Numpy, and in the saved CSV result files, quaternions follow the wxyz format, where "w" is the real component. Thus the identity rotation would be [1, 0, 0, 0]. In contrast however, `Scipy.Rotation` expects them to be in xyzw format. When operating with quaternions, it is therefore important to be aware of what format you should be using for the particular setting. ## XYZ Conventions