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
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 |