Initial import of NeuroSwarms source code package for sharing

LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright (c) 2020 Joseph Monaco, Johns Hopkins University.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,56 @@
+# NeuroSwarms Example Model: Source Code
+
+This package contains the source code for a neural swarming controller model
+that supports simulations of both multi-agent swarming and single-entity
+navigation (based on the activity of an internal 'mental' swarm of virtual
+particles). Findings based on research using this code were published in the
+following paper that appeared in the *Biological Cybernetics* Special Issue
+on neuroscience-inspired robotics for navigation in complex environments.
+
+[Monaco, J.D., Hwang, G.M., Schultz, K.M., and Zhang, K. (2020). Cognitive
+swarming in complex environments with attractor dynamics and oscillatory
+computing. Biol Cybern 114, 269–284).](https://doi.org/10.1007/s00422-020-00823-z)
+
+**Abstract**
+
+Neurobiological theories of spatial cognition developed with respect to
+recording data from relatively small and/or simplistic environments compared
+to animals’ natural habitats. It has been unclear how to extend theoretical
+models to large or complex spaces. Complementarily, in autonomous systems
+technology, applications have been growing for distributed control methods
+that scale to large numbers of low-footprint mobile platforms. Animals and
+many-robot groups must solve common problems of navigating complex and
+uncertain environments. Here, we introduce the NeuroSwarms control framework
+to investigate whether adaptive, autonomous swarm control of minimal
+artificial agents can be achieved by direct analogy to neural circuits of
+rodent spatial cognition. NeuroSwarms analogizes agents to neurons and
+swarming groups to recurrent networks. We implemented neuron-like agent
+interactions in which mutually visible agents operate as if they were
+reciprocally connected place cells in an attractor network. We attributed a
+phase state to agents to enable patterns of oscillatory synchronization
+similar to hippocampal models of theta-rhythmic (5–12 Hz) sequence
+generation. We demonstrate that multi-agent swarming and reward-approach
+dynamics can be expressed as a mobile form of Hebbian learning and that
+NeuroSwarms supports a single-entity paradigm that directly informs
+theoretical models of animal cognition. We present emergent behaviors
+including phase-organized rings and trajectory sequences that interact with
+environmental cues and geometry in large, fragmented mazes. Thus, NeuroSwarms
+is a model artificial spatial system that integrates autonomous control and
+theoretical neuroscience to potentially uncover common principles to advance
+both domains.
+
+**Installation**
+
+First, either set up a new python environment (with either venv or anaconda) and install the required dependencies. Using Anaconda, this would look like,
+
+```bash
+$ conda create -n neuroswarms python numpy scipy matplotlib pytables pillow
+$ conda activate neuroswarms
+```
+
+Then, in the top-level `neuroswarms` folder (either cloned or downloaded from this repository), you can do a developer install of neuroswarms if you are interested in working with the code. In your shell,
+
+```bash
+$ cd /path/to/neuroswarms
+$ pip install -e .
+```

mapdata/hairpin/info.json

@@ -0,0 +1,31 @@
+{
+  "G_scale": 233.826805702828, 
+  "N_0": 4, 
+  "N_B": 20, 
+  "N_C": 7, 
+  "N_H": 1000, 
+  "N_R": 3, 
+  "alpha": 10.0, 
+  "extent": [
+    0, 
+    885, 
+    0, 
+    519
+  ], 
+  "figsize": [
+    6.020408163265306, 
+    3.5306122448979593
+  ], 
+  "height": 519, 
+  "k_H": 20.0, 
+  "name": "hairpin", 
+  "origin": [
+    0, 
+    0
+  ], 
+  "shape": [
+    885, 
+    519
+  ], 
+  "width": 885
+}

mapdata/test/info.json

@@ -0,0 +1,31 @@
+{
+  "G_scale": 143.24083549575158, 
+  "N_0": 3, 
+  "N_B": 16, 
+  "N_C": 7, 
+  "N_H": 370, 
+  "N_R": 3, 
+  "alpha": 10.0, 
+  "extent": [
+    0, 
+    519, 
+    0, 
+    519
+  ], 
+  "figsize": [
+    2.2863436123348015, 
+    2.2863436123348015
+  ], 
+  "height": 519, 
+  "k_H": 20.0, 
+  "name": "test", 
+  "origin": [
+    0, 
+    0
+  ], 
+  "shape": [
+    519, 
+    519
+  ], 
+  "width": 519
+}

neuroswarms/__init__.py

@@ -0,0 +1,48 @@
+"""
+Source code package for the NeuroSwarms controller model.
+
+Author: Joseph Monaco ([email protected])
+Affiliation: Johns Hopkins University
+Created: 2019-08-18
+Updated: 2020-11-17
+
+Requirements: numpy, scipy, matplotlib, pytables, pillow.
+
+Related paper: 
+
+  Monaco, J.D., Hwang, G.M., Schultz, K.M. et al. Cognitive swarming in complex
+      environments with attractor dynamics and oscillatory computing. Biol Cybern
+      114, 269–284 (2020). https://doi.org/10.1007/s00422-020-00823-z
+
+This software is provided AS IS under the terms of the Open Source MIT License. 
+See http://www.opensource.org/licenses/mit-license.ph
+"""
+
+NAME = 'neuroswarms'
+VERSION = '1.0.0'
+
+import os
+import sys
+
+
+# Configure movie parameters
+
+MOVIE_FPS = 100.0  # 100.0 = frame-rate match for simulation timescale
+MOVIE_DPI = 227    # 151 = default scaled resolution of Macbook Pro retina screen
+
+
+# Set up project and data paths
+#
+# Note: Edit the definition of PROJDIR to set the path for simulation output.
+# It defaults to ~/neuroswarms as defined below.
+
+if sys.platform == 'win32':
+    HOME = os.getenv('USERPROFILE')
+else:
+    HOME = os.getenv('HOME')
+
+REPOPATH = os.path.split(__file__)[0]
+MAPDIR = os.path.join(os.path.dirname(REPOPATH), 'mapdata')
+PROJDIR = os.path.join(HOME, NAME)
+RUNDIR = os.path.join(PROJDIR, 'output')
+DATADIR = os.path.join(PROJDIR, 'data')