For developers and contributors

Setting up a dedicated code editor

Using a code editor or IDE is useful when contributing to a codebase. There are many products available and you may use whatever you’re comfortable with. For new developers, we recommend VS Code since it is lightweight, free and has a breadth of community extensions.

Make your own copy of mrsimulator on GitHub

Making a copy of someone’s code on GitHub is the same as making a fork. A fork is a complete copy of the code and all of its revision history.

  1. Log into a GitHub account.

  2. Go to the mrsimulator Github home page.

  3. Click on the fork button.

You will see a short animation of Octocat scanning a book on a flatbed scanner. After that, you should find yourself at the home page for your forked copy of mrsimulator.

Create a development environment

It is good practice to create separate virtual python environments for packages when in developing packages. There are many environment managers available; however, we recommend using Anaconda or Miniconda

The following is an example of creating Conda environment

$ conda create -n mrsimulator-dev python=3.9

The above command will create a new environment named mrsimulator-dev using python 3.9. To activate the environment, use

$ conda activate mrsimulator-dev

Make sure git is installed on your computer

Git is the name of a source code management system. It keeps track of the changes made to the code and manages contributions from several different individuals. You may read more about git at the Git Basics.

If you are using anaconda/miniconda, you probably have git pre-installed. To check, type in terminal

$ git --version
# if git is installed, will get something like: git version 2.30.2

If git is not installed, install it.

Basic git configuration:

Follow the instructions at Set Up Git at GitHub to configure:

  • Your user name and email in your copy of git.

  • Authentication, so you don’t have to type your GitHub password every time you need to access GitHub from the command line.

Copy your fork of mrsimulator from GitHub to your computer

Unless you plan on always editing the code using the online Github editor, you may need to copy the fork of mrsimulator from your GitHub account to your computer. Make a complete copy of the fork with

$ git clone --recursive

Insert your-user-name with your GitHub account username. If there is an error at this stage, it is probably an error in setting up authentication.

You now have a copy of the mrsimulator fork from your GitHub account to your local computer into a mrsimulator folder.

Understanding Remotes

In git, the name for another location of the same repository is remote. The repository that contains the latest “official” development version is traditionally called the upstream remote. You can read more about remotes on Git Basics.

At this point, your local copy of mrsimulator doesn’t know where the upstream development version of mrsimulator is. To let git know, change into the mrsimulator folder you created in the previous step, and add a remote:

cd mrsimulator
git remote add mrsimulator git://

You can check that everything is set up properly so far by asking git to show you all of the remotes it knows about for your local repository of mrsimulator with git remote -v, which should display something like

mrsimulator   git:// (fetch)
mrsimulator   git:// (push)
origin (fetch)
origin (push)

Build the development version of mrsimulator

OS-dependent prerequisites


Installing OS-dependent prerequisites is a one-time process. If you are upgrading to a newer version of mrsimulator, skip to next section.

OpenBLAS and FFTW libraries

On Linux, the package manager for your distribution is usually the easiest route to ensure you have the prerequisites to building the mrsimulator library. To build from source, you will need the OpenBLAS and FFTW development headers for your Linux distribution. Type the following command in the terminal, based on your Linux distribution.

For (Debian/Ubuntu):

$ sudo apt-get install libopenblas-dev libfftw3-dev

For (Fedora/RHEL):

$ sudo yum install openblas-devel fftw-devel

Install a C/C++ compiler

The C-compiler comes with your Linux distribution. No further action is required.

Build and install

Before building the development version of mrsimulator, install the development requirement packages with pip. In the directory where your copy of mrsimulator is, type:

$ pip install -r requirements-dev.txt
$ pip install -e .

As always, if you get an error that you don’t have the permission to install the package into the default site-packages directory, you may try installing by adding the --user option.

Note for the developers and contributors

Before commits: Mrsimulator follows python community standards for writing code and documentation. To help guide the developers and contributors towards these standards, we have created a .pre-commit-config.yaml file, that when used with pre-commit, will inspect the code and document for issues. Type pre-commit run before git commits to inspect the changes.

You can also set up the git hook script to automatically run pre-commit on git commits with the pre-commit install. Read more about pre-commit.

Running tests: For unit tests, we use the pytest module. At the root directory of the mrsimulator package folder, type

$ pytest

which will run a series of tests.

Building docs: We use the sphinx python documentation generator for building docs. Navigate to the docs folder within the mrsimulator package folder, and type,

$ make html

The above command will build the documentation and store the build at mrsimulator/docs/_build/html. Double click the index.html file within this folder to view the offline documentation.