Installing for Development

This page describes how to install SuperNeuroMAT for development.

This is a guide for internal contributors to SuperNeuroMAT.

It assumes you’re added to the github repository as a collaborator and uses SSH URLs for git. External contributors should fork the repository <ornl/superneuromat>

See also

This guide assumes you’re using a Unix-like operating system, such as Linux or macOS. If you’re on Windows, please use WSL Installing Windows Subsystem for Linux and then follow this guide as if you were on Linux (because you are). Then, see Post-Installation for further setup.

Installing git

If you’re contributing to SuperNeuroMAT, you should probably be using git version control.

Download git

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.

“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

$ 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.

Add GitHub SSH key

See the GitHub documentation for more information.

Python Installation

If you’re on Ubuntu or a Debian-based Linux distribution, 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.

Install & switch to Python>=3.11

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:

Check the python version and make sure _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)

Hint

This needs to be done before creating the virtual environment, as 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.

Downloading & Installing as editable

We recommend using UV which provides environment tools and faster installs.

Install UV for faster installs

Install uv <pyuv/uv> for faster installs

pip install uv -U

The -U flag is shorthand for --upgrade.

You can preface most pip install commands with uv for much faster installation. uv pip install may not work for some packages. If you get an error, try using regular pip install first.

First, let’s make a project folder and virtual environment. Pick a place to store your virtual environment, and then cd into it.

Make a project folder and virtual environment

mkdir snm
cd snm

Next, we can create the virtual environment.

uv

Create a virtual environment

uv venv

pip

Create a virtual environment

pip install virtualenv
virtualenv .venv --prompt .

Now, we need to activate the virtual environment.

Windows

.venv\Scripts\activate

Linux / macOS / WSL

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.

fish

source .venv/bin/activate.fish

PowerShell

.venv\bin\activate.ps1

Nushell

Windows

overlay use .venv\Scripts\activate.nu

Linux / macOS / WSL

overlay use .venv/bin/activate.nu

You can deactivate the virtual environment with the deactivate command.

Now, let’s git clone the SuperNeuroMAT repository.

git clone the SuperNeuroMAT repository (using HTTPS URL) and cd into it

git clone https://github.com/ORNL/superneuromat.git
cd superneuromat

SSH URLs

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.

git clone the SuperNeuroMAT repository (using SSH URL) and cd into it

git clone git@github.com:ORNL/superneuromat.git
cd superneuromat

Again, if you’re not an internal contributor, you’ll need to fork the <ornl/superneuromat> repository and use the URL for your fork.

It’s finally time to install SuperNeuroMAT into our virtual environment:

We’ll use a pip --editable install allows you to make changes to the code and see the effects immediately.

uv

uv pip install -e .[docs,jit]

pip

pip install -e .[docs,jit]

The . refers to the current directory, and the [docs,jit] refers to the optional dependencies. [docs] refers to the dependencies for building the documentation, and [jit] refers to the 'jit' backend dependencies.

The other optional dependency is [cuda], which refers to the 'gpu' backend dependencies. The [cuda] dependency set includes everything in the [jit] dependency set, plus the numba-cuda package. It also has the most stringent requirements on package versioning, i.e. it requires a specific version of numpy to be installed, and this requirement is not managed by the numba package.

All these dependencies are specified in the superneuromat/pyproject.toml file, in the [project] dependencies section, and the [project.optional-dependencies] section.

Note that the [cuda] dependency testing must be done manually, as we have not setup tox to work with system CUDA installs.

While you’re here, let’s also install pyreadline3 which makes the python shell much more user-friendly.

uv

uv pip install pyreadline3

pip

pip install pyreadline3

If the installation was successful, you should be able to open a python shell and import the package:

python

Python 3.10.0 (or newer)
Type "help", "copyright", "credits" or "license" for more information.
>>> import superneuromat
>>>

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.

First Run Tutorial