For developers and contributors¶
Setting up a dedicated code editor¶
Using a code editor or IDE is useful when contributing to a codebase. Many products are available; use what is most familiar. For new developers, we recommend VS Code since it is lightweight, free, and has a breadth of community extensions.
Make your 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 its revision history.
You will see a short animation of Octocat scanning a book on a flatbed scanner. After that, you should find yourself on the home page for your forked copy of mrsimulator.
Create a development environment¶
It is good practice to create separate virtual environments when developing packages. There are many environment managers available; however, we recommend using Anaconda or Miniconda.
If your Python is built for Apple Silicon, the following command should display similar output.
$ file `which python` /some/path/to/python: Mach-O 64-bit executable arm64
The following is an example of creating a 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 a source code management system. It keeps track of the changes made to the code and manages contributions from several individuals. You may notice that much of its terminology comes from river and tree metaphors, i.e., source, fork, branch, upstream, etc. You may read 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, you will get something like git version 2.30.2
If git is not installed, install it before continuing.
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
You’ll 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 https://github.com/your-user-name/mrsimulator.git
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.
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://github.com/deepanshs/mrsimulator.git
You can check that everything is set up correctly 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
upstream git://github.com/deepanshs/mrsimulator.git (fetch) upstream git://github.com/deepanshs/mrsimulator.git (push) origin firstname.lastname@example.org:your-user-name/mrsimulator.git (fetch) origin email@example.com:your-user-name/mrsimulator.git (push)
Build the development version of mrsimulator¶
Installing OS-dependent prerequisites is a one-time process. If you are upgrading to a newer version of mrsimulator, skip to the 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.
$ sudo apt-get install libopenblas-dev libfftw3-dev
$ 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.
OpenBLAS/Accelerate and FFTW libraries
You will require the
brew package manager to install the development headers for the
OpenBLAS (if applicable) and FFTW libraries. Read more on installing brew from
Step-1 Install the FFTW library using the homebrew formulae.
$ brew install fftw
Step-2 By default, the mrsimulator package links to the openblas library for BLAS operations. Mac users may opt to choose the in-build Apple’s Accelerate library. If you opt for Apple’s Accelerate library, skip to Step-3. If you wish to link the mrsimulator package to the OpenBLAS library, type the following in the terminal,
$ brew install openblas
Step-3 If you choose to link the mrsimulator package to the OpenBLAS library, skip to the next section.
(a) You will need to install the BLAS development header for Apple’s Accelerate library. The easiest way is to install the Xcode Command Line Tools. Note, this is a one-time installation. If you have previously installed the Xcode Command Line Tools, you may skip this sub-step. Type the following in the terminal,
$ xcode-select --install
(b) The next step is to let the mrsimulator setup know your preference.
settings.py file, located at the root level of the mrsimulator source
code folder, in a text editor. You should see
# -*- coding: utf-8 -*- # BLAS library use_openblas = True # mac-os only use_accelerate = False
To link the mrsimulator package to the Apple’s Accelerate library, change the fields to
# -*- coding: utf-8 -*- # BLAS library use_openblas = False # mac-os only use_accelerate = True
Install a C/C++ compiler
The C-compiler installs with the Xcode Command Line Tools. No further action is required.
Skip this step if you already have miniconda or anaconda for python>=3.7 installed on your system. Download the latest version of conda on your operating system from either miniconda or Anaconda websites. Make sure you download conda for Python 3. Double click the downloaded .exe file and follow the installation steps.
OpenBLAS and FFTW libraries
Anaconda prompt (it should be located under the start menu). Within the
anaconda prompt, type the following to install the package dependencies.
$ conda install -c conda-forge openblas fftw
Install a C/C++ compiler
Because the core of the mrsimulator package is written in C, you will require a C-compiler to build and install the package. Download and install the Microsoft Visual C++ compiler from Build Tools for Visual Studio.
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 before, 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
If you are using a Mac with Apple Silicon and unable to install mrsimulator, open an issue on the GitHub page.
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 toward 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. To set up
pre-commit, type the following one-time
install statement in the terminals,
$ pre-commit install
Once set up, navigate to the root level of the mrsimulator folder and type
$ pre-commit run
The above statement auto-fixes some issues and lists others for you to fix. Review the changes and address the listed issues before a git commit.
The pre-commit command ignores unstaged changes. Before running
pre-commit run, make sure
to stage files for a commit.
Running tests: We use the pytest module for unit tests. At the root level of the mrsimulator folder, type
which will run a series of tests alerting you to any unit tests that fail.
Checking test coverage: To check which lines in the codebase are covered when running a test, use the following command.
$ pytest --cov-report=html
To view the unit test coverage report, open the mrsimulator/htmlcov/index.html file in a web browser.
Building docs: We use the sphinx Python documentation generator for building docs. Navigate to the docs directory within the mrsimulator folder, and type,
$ make html
The above command will build the documentation and store the build at mrsimulator/docs/_build/html. Open the index.html file in a web browser within this folder to view the locally-built documentation.