Installation¶
Requirements¶
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,
Tip
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.
See also
If you do not have python or have an older version of python, you may visit the Python downloads or Anaconda websites and follow their instructions on how to install python.
Installing mrsimulator¶
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.
For Linux users, we provide the binary distributions of the mrsimulator package for python versions 3.6-3.8. Install the package using pip as follows,
$ pip install mrsimulator
For Mac users, we provide the binary distributions of the mrsimulator package for python versions 3.6-3.8. Install the package using pip as follows,
$ pip install mrsimulator
If the above statement didn’t work, you are probably using mac OS system python, in which case, use the following,
$ python3 -m pip install mrsimulator --user
Note
We currently do not provide binary distributions for windows. You’ll need to compile and build the mrsimulator library from source. The following instructions are one-time installation only. If you are upgrading the package, see the Upgrading to a newer version sub-section.
Install conda
Skip this step if you already have miniconda or anaconda for python>=3.6 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
Launch the 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 2019.
Install the package.
From within the Anaconda Prompt, build and install the mrsimulator package
using pip.
$ pip install mrsimulator
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¶
Prerequisites¶
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¶
OS-dependent prerequisites¶
Note
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.
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.
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
homebrew.
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, Building and Installing.
(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.
Open the 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.
Install conda
Skip this step if you already have miniconda or anaconda for python>=3.6 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
Launch the 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 2019.
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
the default site-packages directory, you may try installing with the --user
options as,
$ 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.
Figure 1 A test example simulation of solid-state NMR spectrum.¶
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
$ 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.