Installing for Development#
This page describes how to install RobotSwarmSimulator for development.
This is a guide for internal contributors to RobotSwarmSimulator.
It assumes you’re added to the github repository as a collaborator and uses SSH URLs for git. External contributors should fork the repository <kenblu24/RobotSwarmSimulator>
See also
This guide was written with a Unix-like operating system in mind, such as Linux or macOS. If you’re on Windows, consider using WSL Installing Windows Subsystem for Linux which allows you to follow this guide as if you were on Linux. Then, see Post-Installation for further setup.
Installing git#
If you’re contributing to RobotSwarmSimulator, you should probably be using git version control.
Once you have git, make sure you can run git from the command line. If not, you may need to restart your terminal.
SSH keys#
This guide uses SSH URLs for git. You’ll need to have an SSH key set up and added to your GitHub account to clone, pull, or push to/from the remote repository. If you don’t have an SSH key on your system, you’ll need to generate one.
$ 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.
$ ssh-keygen
Copy & paste the contents of your id_rsa.pub or id_ed25519.pub file into your GitHub account’s SSH keys page.
Make sure to give the key a descriptive title; you won’t be able to change it later.
See the GitHub documentation for more information.
Python Installation#
If you’re on Ubuntu or a Debian-based Linux distribution (including WSL), you should use pyenv
to install Python 3.11 or later.
This allows you to install any Python version you want, without affecting your system Python installation. See the pyenv installation instructions.
pyenv install 3.13
pyenv global 3.13
Then, make sure we’re actually using the right version of Python. You should see something similar to this:
_ctypes is available#$ which python
/home/username/.pyenv/shims/python
$ python --version
Python 3.13.0
$ python -c "import _ctypes"
$ pip --version
pip 24.2 from /home/username/.pyenv/versions/3.13.0/lib/python3.13/site-packages/pip (python 3.13)
Native Windows users can use a Python installer from Python.org. Make sure to check the box to add Python to PATH.
Hint
This needs to be done before creating the virtual environment, as uv venv or virtualenv
will use whatever version of Python it finds when you run it. Running which python may help you know more.
If you already made the virtual environment, the easiest way to fix this is to delete the virtual environment and start over.
See also
If you’re running Tennlab simulations on the Hopper cluster, please use the hopper install scripts.
Downloading & Installing as editable#
We recommend using UV which provides environment tools and faster installs.
Install UV for faster installs
First, let’s make a project folder and virtual environment. Pick a place
to store your virtual environment. In this example, we’ll use the swarm/ folder.
mkdir swarm
cd swarm
Next, we can create the virtual environment.
uv venv
pip install virtualenv
virtualenv .venv --prompt .
Now, we need to activate the virtual environment.
.venv\Scripts\activate
source .venv/bin/activate
Activating fish, Nushell, or PowerShell
The above activation command is for the default shell environments, such as bash, zsh, or sh on Unix, or cmd and powershell on Windows.
If you’re using a different shell, such as fish or Nushell, or if you’re using PowerShell and have activation issues, you may need to use a different activation file.
source .venv/bin/activate.fish
.venv\Scripts\activate.ps1
Note: Windows users may need to change their PowerShell script execution policy. See the dropdown below:
Script Execution Policy
If you see an error like this:
PS > .\.venv\Scripts\activate.ps1
.\.venv\Scripts\activate.ps1 : File .venv\Scripts\activate.ps1 cannot be loaded because running
scripts is disabled on this system. For more information, see about_Execution_Policies at
https:/go.microsoft.com/fwlink/?LinkID=135170 .
At line:1 char:1
+ .\.venv\Scripts\activate.ps1
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : SecurityError: (:) [], PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess
Your script execution policy may be set to Restricted (check with Get-ExecutionPolicy).
To fix this, first open an administrator terminal. You can do this by right-clicking on the Start button or pressing ⊞Win+x and selecting Terminal (Admin) (or similar). Then, run the following command:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
You will need to close and re-open your terminal windows for this to take effect.
overlay use .venv\Scripts\activate.nu
overlay use .venv/bin/activate.nu
You can deactivate the virtual environment with the deactivate command.
Then, let’s git clone the RobotSwarmSimulator repository.
cd into it#git clone https://github.com/kenblu24/RobotSwarmSimulator.git
cd RobotSwarmSimulator
SSH URLs
If you’re contributing to or modifying RobotSwarmSimulator, you should use SSH URLs for git. See SSH keys for more information.
GitHub won’t let you push to HTTPS remote URLs using password authentication. If you choose to use the HTTPS URL as shown above, you’ll need to create a personal access token and use that as the password every time you push.
However, if you successfully set up your SSH key in the section above, and have contributor-level permissions on GitHub, you can use the SSH URL instead.
cd into it#git clone git@github.com:kenblu24/RobotSwarmSimulator.git
cd RobotSwarmSimulator
Again, if you’re not an internal contributor, you’ll need to fork the <kenblu24/RobotSwarmSimulator> repository and use the URL for your fork.
A pip --editable install allows you to make changes to the code and see the effects immediately.
Install UV for faster installs
It’s finally time to install RobotSwarmSimulator into our virtual environment!
We’ll use a pip --editable install allows you to make changes to the code and see the effects immediately.
Hint
Don’t forget to activate the virtual environment, and make sure you’re in the RobotSwarmSimulator folder before running this command!
(The . refers to the current directory. If you’re one level above, you can do something like pip install -e RobotSwarmSimulator[dev,docs].)
uv pip install -e .[dev,docs]
pip install -e .[dev,docs]
The . refers to the current directory, and the [docs,dev] refers to the optional dependencies.
[docs] refers to the dependencies for building the documentation, and [dev] refers to development and testing dependencies.
All these dependencies are specified in the RobotSwarmSimulator/pyproject.toml file, in the [project] dependencies section,
and the [project.optional-dependencies] section.
While you’re here, let’s also install pyreadline3 which makes the python shell much more user-friendly.
uv pip install pyreadline3
pip install pyreadline3
If the installation was successful, you should be able to open a python shell and import the package:
python#Python 3.11.0 (or newer)
Type "help", "copyright", "credits" or "license" for more information.
>>> import swarmsim
>>>
If you installed pyreadline3 or are using Python 3.13 or newer, you can exit the python shell with Ctrl+C to stop
currently running commands and then Ctrl+D. Or you can type quit() to quit the python REPL.
Finished installing? Check out the Basic Usage tutorial.