mrsimulator has the following strict requirements:
See Package dependencies for a full list of requirements.
Make sure you have the required version of python by typing the following in the terminal,
You may also click the copy-button located at the top-right corner of the code cell area in the HTML docs, to copy the code lines without the prompts and then paste it as usual. Thanks to Sphinx-copybutton)
$ python --version
For Mac users, python version 3 is installed under the name python3. You may replace python for python3 in the above command and all subsequent python statements.
For Windows users, we recommend the Anaconda or miniconda distribution of python>3.6. Anaconda distribution for python comes with popular python packages that are frequently used in scientific computing. Miniconda is a minimal installer for conda. It is a smaller version of Anaconda that includes conda, Python, and the packages they depend on, along with other useful packages such as pip.
On Google Colab Notebook¶
Colaboratory is a Google research project. It is a Jupyter notebook environment that runs entirely in the cloud. Launch a new notebook on Colab. To install the mrsimulator package, type
!pip install mrsimulator
in the first cell, and execute. All done! You may now proceed to the next section and start using the library.
On Local machine (Using pip)¶
PIP is a package manager for Python packages and is included with python version 3.4 and higher. PIP is the easiest way to install python packages.
If you get a
PermissionError, it usually means that you do not have the required
administrative access to install new packages to your Python installation. In this
case, you may consider adding the
--user option, at the end of the statement, to
install the package into your home directory. You can read more about how to do this in
the pip documentation.
Upgrading to a newer version¶
If you are upgrading to a newer version of
mrsimulator, you have all the prerequisites
installed on your system. In this case, type the following in the terminal/Prompt
$ pip install mrsimulator -U
Building from the source¶
You will need a C-compiler suite and the development headers for the BLAS and FFTW
libraries, along with development headers from Python and Numpy, to build the
mrsimulator library from source.
The mrsimulator package utilizes the BLAS and FFTW routines for numerical computation.
To leverage the best performance, we recommend installing the BLAS and FFTW libraries,
which are optimized and tuned for your system. In the following,
we list recommendations on how to install the c-compiler (if applicable), BLAS, FFTW,
and building the mrsimulator libraries.
Obtaining the Source Packages¶
Installing OS-dependent prerequisites is a one-time process. If you are upgrading to a newer version of mrsimulator, skip to Building and Installing section.
Building and Installing¶
Use the terminal/Prompt to navigate into the directory containing the package (usually, the folder is named mrsimulator),
$ cd mrsimulator
From within the source code folder, type the following in the terminal to install the library.
$ pip install .
If you get an error that you don’t have the permission to install the package into
site-packages directory, you may try installing with the
$ pip install . --user
Test your build¶
If the installation is successful, you should be able to run the following test file in your terminal. Download the test file here.
$ python test_file.py
The above statement should produce the following figure.
Setup for developers and contributors¶
A GitHub account is required for developers and contributors. Make sure you have git installed on your system.
Step-A (Optional) Create a virtual environment. It is a good practice to create separate virtual python environments for packages when in developer mode. The following is an example of a Conda environment.
$ conda create -n mrsimulator-dev python=3.7 $ conda activate mrsimulator-dev
Step-B Clone the mrsimulator repository using git and navigate into the package folder.
$ git clone git://github.com/DeepanshS/mrsimulator.git $ cd mrsimulator
Step-C Follow the instruction under OS-dependent prerequisites from Building from the source section. For developers and contributors using mac OSX, please run the setup by binding to the openblas libraries.
Step-D You will need cython for development build.
$ pip install cython
Step-E Build and install the package in the development (editable) mode using pip.
$ pip install -e .
Step-F: Install the required packages for developers using pip.
$ pip install -r requirements-dev.txt
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 options at the end of the statements in steps D-F.
Note for the developers and contributors¶
Running tests: For unit tests, we use the pytest module. At the root directory of the mrsimulator package folder, type
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.