# 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

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.

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¶ ##### Stable packages¶ The latest stable source package for mrsimulator is available on PyPI. #### 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

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


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. (png, hires.png, pdf) 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.