Getting Started: for Developers

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

Installing Python

SimPEG is written in Python! To install and maintain your Python environment, Anaconda is a package manager that you can use. 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, then fork the SimPEG repository to your local account. (How to fork a repo).

Next, clone your fork to your computer so that you have a local copy. We recommend setting up a directory in your home directory to put your version-controlled repositories (e.g. called git). There are two ways you can clone a repository:

1. From a terminal (checkout: https://docs.github.com/en/get-started/quickstart/set-up-git for an tutorial)

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

2. Using a desktop client such as SourceTree or GitKraken.

   

   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

To get started developing SimPEG we recommend setting up an environment using the conda``( or ``mamba) package manager that mimics the testing environment used for continuous integration testing. Most of the packages that we use are available through the conda-forge project. This will ensure you have all of the necessary packages to both develop SimPEG and run tests locally. We provide an environment_test.yml in the base level directory.

conda env create -f environment_test.yml

Note

If you find yourself wanting a faster package manager than conda check out the mamba project at https://mamba.readthedocs.io/. It usually is able to set up environments much quicker than conda and can be used as a drop-in replacement (i.e. replace conda commands with mamba).

There are many options to install SimPEG into this local environment, we recommend using pip. After ensuring that all necessary packages from environment_test.yml are installed, the most robust command you can use, executed from the base level directory would be

pip install --no-deps -e .

This is called an editable mode install (-e). This will make a symbolic link for you to the working simpeg directory for that python environment to use and you can then make use of any changes you have made to the repository without re-installing it. This command (–no-deps) also ensures pip won’t unintentionally re-install a package that was previously installed with conda. This practice also allows you to uninstall SimPEG if so desired

pip uninstall SimPEG

Note

We no longer recommend modifying your python path environment variable as a way to install SimPEG for developers.

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/tutorials and run an example, ie.:

python 02-linear_inversion/plot_inv_1_inversion_lsq.py

or you can download and run the notebook from the docs.

You are now set up to SimPEG!

If all is not well …

Submit an issue and change this file!

Advanced: Installing Solvers

Pardiso is a direct solvers that can be used for solving large(ish) linear systems of equations. The provided testing environment should install the necessary solvers for you. pymatsolver If you wish to modify pymatsolver as well follow the instructions to download and install pymatsolver.

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

from pymatsolver import Pardiso

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