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 canpyenv install VERSION
whereVERSION
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/
.
pyframework
virtual environment
Setup [!important] Don't forget to set the Python version with
pyenv global VERSION
BEFORE running any commands in this section!
Check by runningpython --version
andpip --version
. You should see the version you specified for both.
Also,which python
andwhich pip
paths should sayshims
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
, andcaspian
: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.
neuroswarm
Downloading your fork of 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.