Getting started with Tennlab Framework - GMU-ASRC/neuroswarm GitHub Wiki

To get started, you'll need to ensure you have access to the neuromorphic-utk workspace on BitBucket. Sign in using the same email you used to apply for access. If you see a non-empty list when signed in, then you have access.

Compatibility

You'll need one of the following operating systems:

  • Ubuntu 20.04 or newer (recommended)
  • MacOS
  • Windows with WSL (see section below)

Those using other Linux distros or older versions of MacOS should read this file.

WSL Installation

If you're on Windows, you'll need to run things through Windows Subsystem for Linux, or WSL. Use this guide to install WSL. Once you're done, ensure you can open Ubuntu in Windows Terminal like so:

MacOS and Ubuntu users can skip this step.

Pyenv

Pyenv helps separate your system Python install from the one we use for this project. On Ubuntu especially, the system Python install may be an older version, with packages tied to the system repositories.

Installing Pyenv

[!important] ARM Mac users should run arch -x86_64 $SHELL before executing any of these commands in the terminal to ensure you get the x86 version of Python.

Ubuntu and Mac users should follow sections A-D in the pyenv installation guide:

A. Getting Pyenv
B. Set up your shell environment for Pyenv
D. Install Python build dependencies

Installing Python

If you can run pyenv doctor without errors, then you're ready to install python.

Install a modern version of Python with:

pyenv install 3

Note: If you want to specify an exact version, you can list the available variants and versions of Python with pyenv install -l, and then you can pyenv install VERSION where VERSION is the exact version you want.

Switching Python versions.

Choose the version of python with pyenv global VERSION where VERSION is the version you want.
global refers to the python version that will be used at the global level, but Pyenv can also do things like use a certain python version when you're in a specific folder. You don't need to use this feature, but if you're curious, see more about Pyenv Usage. List the versions you have installed with pyenv versions.
system is the system python install.

SSH key setup

You should use SSH git URLs when installing the framework. If you don’t have an SSH key on your system, you’ll need to generate one.

Check if you have an SSH key already:

ls -A ~/.ssh
id_rsa  id_rsa.pub  known_hosts

You should see id_rsa.pub or id_ed25519.pub in the output. If you don’t, you’ll need to generate a new SSH key.

[!Caution] Be aware that existing SSH keys may be used by other applications. If you delete or overwrite an existing key, you may need to re-add it wherever it was used.

Generate a new SSH key with:

ssh-keygen

Copy & paste the contents of your id_rsa.pub or id_ed25519.pub file into your Bitbucket account’s SSH keys page (Settings Icon > Personal Bitbucket Settings > SSH keys). Make sure to give the key a descriptive title; you won’t be able to change it later. If you're using WSL, you may want to note this in the name to tell the WSL/Ubuntu key for your computer apart from the Windows key, if you have SSH keys for both.

See the Bitbucket documentation for more information.

Install the framework

Set up a project folder

If you haven't already, make a project folder for your stuff:

mkdir ~/neuromorphic
cd ~/neuromorphic

Download the framework

You'll need the framework and caspian repositories:

git clone [email protected]:neuromorphic-utk/framework.git
git clone [email protected]:neuromorphic-utk/caspian.git framework/processors/caspian

Note that the contents of caspian should get cloned to ~/neuromorphic/framework/processors/caspian/.

Setup pyframework virtual environment

[!important] Don't forget to set the Python version with pyenv global VERSION BEFORE running any commands in this section!
Check by running python --version and pip --version. You should see the version you specified for both.
Also, which python and which pip paths should say shims somewhere in the path.

cd into the framework folder:

cd ~/neuromorphic/framework

Now, let's use uv and virtualenv to create and enter the virtual environment.

pip install uv
uv pip install virtualenv --system
virtualenv pyframework
source pyframework/bin/activate

source pyframework/bin/activate runs the activate file which sets up the $PATH and other shell/environment variables so that python uses the correct pyframework environment. However, activate is a bash/sh/zsh script. Users of other shells may need to run a different activate.* script. Run find pyframework/bin/activate.* to see the other activation scripts.

Once you've activated the virtual environment and see (pyframework) at the beginning of your prompt, we can install the prereqs using uv:

uv pip install -r requirements.txt

Compiling framework

To make the framework usable by Python, we need to compile it.

Make sure you're in framework, i.e. cd ~/neuromorphic/framework.

bash scripts/create_env.sh

This will do its own setup of the environment, clone eons to framework/eons, and then run update_env.sh which compiles the framework.

[!note] If this step fails, try using these commits for framework, eons, and caspian:

git checkout d4760b9ff485eced57cdcd8b69b3b39b328309d7
cd eons; git checkout abe8b5222a2e26a43147a7ac0f0bbf718f512426
cd ../processors/caspian; git checkout ea9cc0cc802a989fec53c9a6bfe9b306c71e73c1

Then, cd ~/neuromorphic/framework/ and try compiling the framework again:

bash scripts/update_env.sh clean

Checking that it works

Activate your environment i.e. source pyframework/bin/activate, then try to import neuro and caspian:

python -c "import neuro"
python -c "import caspian"

If both of these commands work, you have likely successfully installed the framework and caspian. Probably.

Installing RobotSwarmSimulator (dev install)

cd ~/neuromorphic
if [ -z "$VIRTUAL_ENV" ](/GMU-ASRC/neuroswarm/wiki/--z-"$VIRTUAL_ENV"-); then source framework/pyframework/bin/activate; fi
git clone [email protected]:kenblu24/RobotSwarmSimulator.git || git clone https://github.com/kenblu24/RobotSwarmSimulator.git
uv pip install -e RobotSwarmSimulator
python -c "import swarmsim"

The fourth line tries to use an SSH link first, but you can't clone via SSH if you don't have perms to the RobotSwarmSimulator repository. If it fails, it'll try using the HTTPS link.

Downloading your fork of neuroswarm

Go to your fork of neuroswarm and get the SSH link by clicking on the green Code button.

Now, cd to your project folder and clone your repo:

cd ~/neuromorphic 
git clone YOUR_REPO_URL turtwig

Finally, install the requirements.txt:

cd ~/neuromorphic
if [ -z "$VIRTUAL_ENV" ](/GMU-ASRC/neuroswarm/wiki/--z-"$VIRTUAL_ENV"-); then source framework/pyframework/bin/activate; fi
cd turtwig
uv pip install -r requirements.txt

Checking if it works

You should now be able to run this:

python experiment_tenn2.py run config/241104-121312-connorsim_snn_eons-v01 --caspian

A window should appear (check your taskbar) with 6 agents milling in a circle, and then disappear.