.. _getting_started_developers: Getting Started: for Developers =============================== - **Purpose:** To download and set up your environment for using and developing within SimPEG. .. _getting_started_installing_python: Installing Python ----------------- .. image:: https://upload.wikimedia.org/wikipedia/commons/thumb/c/c3/Python-logo-notext.svg/220px-Python-logo-notext.svg.png :align: right :width: 100 :target: https://www.python.org/ 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 `_. .. _Python: https://www.python.org/ .. _Anaconda: https://www.anaconda.com/products/individual .. _getting_started_working_with_git_and_github: Working with Git and GitHub --------------------------- .. image:: https://github.githubassets.com/images/modules/logos_page/Octocat.png :align: right :width: 100 :target: http://github.com 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 `_). .. _github: http://github.com 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 :code:`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 .. _SourceTree: https://www.sourcetreeapp.com/ .. _GitKraken: https://www.gitkraken.com/ 2. Using a desktop client such as SourceTree_ or GitKraken_. .. image:: ../../images/sourceTreeSimPEG.png :align: center :width: 400 :target: https://www.sourcetreeapp.com/ 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 .. image:: ../../images/sourceTreeRemote.png :align: center :width: 400 For managing your copy of SimPEG and contributing back to the main repository, have a look at the article: `A successful git branching model `_ .. _getting_started_setting_up_your_environment: 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. .. _getting_started_jupyter_notebook: Jupyter Notebook ---------------- .. image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Square%20Logo/squarelogo-greytext-orangebody-greymoons/squarelogo-greytext-orangebody-greymoons.svg :align: right :width: 100 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 .. _getting_started_if_all_is_well: 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 :ref:`notebook from the docs `. .. image:: /content/tutorials/02-linear_inversion/images/sphx_glr_plot_inv_1_inversion_lsq_003.png You are now set up to SimPEG! If all is not well ... ---------------------- Submit an issue_ and `change this file`_! .. _issue: https://github.com/simpeg/simpeg/issues .. _change this file: https://github.com/simpeg/simpeg/edit/main/docs/content/api_getting_started_developers.rst 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_. .. _Pardiso: https://www.pardiso-project.org .. _pymatsolver: https://github.com/rowanc1/pymatsolver If you open a `Jupyter notebook`_ and are able to run:: from pymatsolver import Pardiso .. _Jupyter notebook: http://jupyter.org/ then you have succeeded! Otherwise, make an `issue in pymatsolver`_. .. _issue in pymatsolver: https://github.com/rowanc1/pymatsolver/issues