Getting Started: for Developers

• Purpose: To download and set up your environment for using and developing within SimPEG.

Installing Python

SimPEG runs is written in Python! To install and maintain your Python 2.7 environment, Anaconda is a package manager that you can use. SimPEG requires Python 2.7. If you and Python are not yet acquainted, we highly recommend checking out Software Carpentry.

Working with Git and GitHub

To keep track of your code changes and contribute back to SimPEG, you will need a github account and fork the SimPEG repository (How to fork a repo). Software

Next, clone your fork so that you have a local copy. We recommend setting up a directory called git in your home directory to put your version- controlled repositories. There are two ways you can clone a repository: (1) from a terminal (checkout: https://try.github.io for an tutorial):

git clone https://github.com/YOUR-USERNAME/SimPEG

or (2) using a desktop client such as SourceTree.

If this is your first time managing a github repository through SourceTree, it is also handy to set up the remote account so it remembers your github user name and password

For managing your copy of SimPEG and contributing back to the main repository, have a look at the article: A successful git branching model

Setting up your environment

So that you can access SimPEG from anywhere on your computer, you need to add it to your path. This can be done using symlinks. In your git directory, create a directory called python_symlinks.

Open a terminal in this directory and create a symlink for SimPEG

ln -s ../SimPEG/SimPEG .

Then, in your shell, you need to add a PYTHONPATH variable. For Mac and Linux, if you are using Z shell (Oh My Zsh is used by a lot of SimPEG developers) or bash open the config in a text editor, ie:

nano ~/.zshrc

or:

nano ~/.bash_profile

and add a PYTHONPATH variable:

export PYTHONPATH="$PYTHONPATH:/Users/USER/git/python_symlinks"

and save and close. If you then restart the terminal, and run:

echo $PYTHONPATH

the output should be:

/Users/USER/git/python_symlinks

Text Editors

Sublime is a text editor used by many SimPEG developers.

You can configure the Sublime so that you can use the sublime build (Tools / Build) to run Python code.

Open your user settings

and edit them to include the path to your python_symlinks:

{
"added_words":
[
    "electromagnetics"
],
"ensure_newline_at_eof_on_save": true,
"extra_paths":
[
    "/Users/USER/git/python_symlinks/"
],
"font_size": 11,
"ignored_packages":
[
    "Vintage"
],
"translate_tabs_to_spaces": true,
"trim_trailing_white_space_on_save": true,
"word_wrap": false
}

There are a few other things configured here. In particular you will want to ensure that "translate_tabs_to_spaces": true is configured (Python is sensitive to tabs and spaces), that "trim_trailing_white_space_on_save": true so that your git flow does not get cluttered with extra spaces that are not actually changes to code and that "ensure_newline_at_eof_on_save": true, so that there is a blank line at the end of all saved documents. The rest are up to you.

Jupyter Notebook

The SimPEG team loves the Jupyter notebook. It is an interactive development environment. It is installed it you used Anaconda and can be launched from a terminal using:

jupyter notebook

If all is well ...

You should be able to open a terminal within SimPEG/SimPEG/Examples and run an example, ie.:

python Inversion_Linear.py

and open a Jupyter Notebook, and run the linear inversion

and see

(Source code)

You are now set up to SimPEG!

Note

you likely got a message that said:

Efficiency Warning: Interpolation will be slow, use setup.py!
    python setup.py build_ext --inplace

This is because we use Cython to speed up interpolation. To set this up open up a command prompt in git/simpeg, and run:

python setup.py build_ext --inplace

Which might output a bunch of warnings, but so long as there are no errors, you should be good to go. To check, re-run the example and see if the efficiency warning still appears.

If all is not well ...

Submit an issue and change this file!

Advanced: Installing Mumps

Mumps is a direct solver that can be used for solving large(ish) [1] linear systems of equations. To install, follow the instructions to download and install pymatsolver.

• Disclaimer for Windows users: we have not figured out a stable way to install and connect Mumps for Windows Machines. If you have one, please change this file!

If you open a Jupyter notebook and are able to run:

from pymatsolver import MumpsSolver

then you have succeeded! Otherwise, make an issue in pymatsolver.

Footnotes

[1]	These instructions are for serial (not parallel) Mumps installation. The definition of large also depends on the size of your computer