Setting up your environment

Install Python

First you will need to install Python. You can find instructions in Prerequisite: Installing Python. We highly encourage to install Anaconda or Miniforge.

Create environment

To get started developing SimPEG we recommend setting up an environment using the conda package manager that includes all odthe packages necessary to both develop SimPEG and run tests locally. Most of the packages that we use are available through the conda-forge project. We provide an environment.yml in the base level directory.

To create the environment and install all packages needed to run and write code for SimPEG, navigate to the directory where you cloned SimPEG’s repository and run:

conda env create -f environment.yml

Note

Since version 23.10.0, conda makes use of the libmamba solver to resolve dependencies. It makes creation of environments and installation of new packages much faster than when using older versions of conda.

Since this version, conda can achieve the same performance as mamba, so there’s no need to install mamba if you have an updated version of conda. If not, either update conda, or keep using mamba instead.

Once the environment is successfully created, you can activate it with

conda activate simpeg-dev

Install SimPEG in developer mode

There are many options to install SimPEG into this local environment, we recommend using pip. After ensuring that all necessary packages from environment.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.

Check your installation

You should be able to open a terminal within simpeg/tutorials and run an example, i.e.

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!

Note

If all is not well, please submit an issue and change this file!

Configure pre-commit (optional)

We recommend using pre-commit to ensure that your new code follows the code style of SimPEG. pre-commit will run Black and flake8 before any commit you make. To configure it, you need to navigate to your cloned SimPEG repo and run:

pre-commit install

Note

Using pre-commit is recommended, but not necessary. You can still manually run Black and flake8. See our Code style page for more details.

If for some reason you want to stop using pre-commit on SimPEG, you can permanently configure it to stop running automatically with:

pre-commit uninstall

Alternatively, you can temporarily bypass pre-commit when committing some changes by running:

git commit --no-verify

This is specially useful if the checks run by pre-commit are failing, but you want to commit them nonetheless.

Update your environment

Every once in a while, the minimum versions of the packages in the environment.yml file get updated. After this happens, it’s better to update the simpeg-dev environment we have created. This way we ensure that we are checking the style and testing our code using those updated versions.

To update our environment we need to navigate to the directory where you cloned SimPEG’s repository and run:

conda env update -f environment.yml