install_dev.rst

Installing PlasmaPy for Development

Obtaining PlasmaPy source code

After creating your GitHub account, go to PlasmaPy's GitHub repository and fork a copy of PlasmaPy to your account.

To access Git commands on Windows, try Git Bash.

Next you must clone your fork to your computer. Go to the directory that will host your PlasmaPy directory, and run one of the following commands (after changing your-username to your username). If you would like to use HTTPS (which is the default and easier to set up), then run:

git clone https://github.com/your-username/PlasmaPy.git

SSH is a more secure option, but requires you to set up an SSH key beforehand. The equivalent SSH command is:

git clone git@github.com:your-username/PlasmaPy.git

After cloning, we must tell git where the development version of PlasmaPy is by running:

cd PlasmaPy
git remote add upstream git://github.com/PlasmaPy/PlasmaPy.git

To check on which remotes exist, run git remote -v. You should get something like this:

origin   git@github.com:namurphy/PlasmaPy.git (fetch)
origin   git@github.com:namurphy/PlasmaPy.git (push)
upstream git@github.com:PlasmaPy/PlasmaPy.git (fetch)
upstream git@github.com:PlasmaPy/PlasmaPy.git (push)

Setting up an environment for development

Setup procedures for the two most popular virtual environments, conda and virtualenv, are listed below.

Conda

To set up a development environment for PlasmaPy, we strongly recommend the Anaconda distribution.

Activate Anaconda

After installing Anaconda, launch any conda environment. By default, conda installs a root environment, which you should be able to activate via

source /home/user/anaconda3/bin/activate root

where /home/user/anaconda3/ can be swapped to wherever your anaconda installation resides.

On newer versions of Anaconda the recommended activation process has changed to:

. /home/user/anaconda3/etc/profile.d/conda.sh
conda activate

Note

On Windows, the way to do this is via running Anaconda Prompt from the Start Menu. Git Bash may also work if you have added Anaconda to PATH.

Create your environment

Having activated Anaconda, enter PlasmaPy's repository root directory and create an environment with our suggested packages by executing the following:

conda env create -f requirements/environment.yml

You may now enter the environment via

source activate plasmapy

Note

On Windows, skip the source part of the previous command.

In newer Conda versions, the command to run is

conda activate plasmapy

Virtualenv

Create a directory for holding the PlasmaPy repository, move into it and create the virtual environment

virtualenv -p python3 .

You may need to make sure that this directory's path doesn't contain any spaces, otherwise virtualenv may throw an error.

Your virtual environment should now be created. If you run ls you will notice that virtualenv has created a number of subdirectories: bin/, lib/, and include/. This is why we're not creating the virtualenv within the repository itself - so as to not pollute it. To activate the virtualenv you will run:

source ./bin/activate

You should now see that your shell session is prepended with (plasmapy), like so:

(plasmapy) user@name:~/programming/plasmapy$

This indicates that the virtualenv is running. Congratulations! When your're done working on PlasmaPy, you can deactivate the virtualenv by running

source deactivate

Now that you have plasmapy on your local computer and you have a virtual environment, you will want to "install" this development version of PlasmaPy along with its dependencies. Start by activating your virtual environment. Next you want install the PlasmaPy dependencies. One way to do this is to do

(plasmapy) user@name:~/programming/plasmapy$ pip install -r requirements/environment.txt

Next, setup the development version of PlasmaPy which you just cloned by moving into the root directory of the cloned repo and running the setup.py script there:

(plasmapy) user@name:~/programming/plasmapy/PlasmaPy$ pip install -e .

You should now be all set to run development versions of PlasmaPy modules via import PlasmaPy in your test scripts!

Running anaconda with virtualenv

If you are running the Anaconda suite and want to use virtualenv to setup your virtual environment, you will have to let the system know where the Python interpreter can be found. On Linux this is done with (for example, assuming having installed Anaconda into ~/anaconda3):

export LD_LIBRARY_PATH="$HOME/anaconda3/lib/"

Exporting the library path to the dynamic linker will only last for the duration of the current shell session.

You will have to add the python library directory to LD_LIBRARY_PATH, as described in a previous step, prior to activating the virtualenv for every new shell session.

Installing your own dev version

To be able to import PlasmaPy from your source version, enter the repository root and use one of

python setup.py develop
pip install -e .

Note

If you are not working within a virtual environment, this may end in a permission error - this can be avoided via also adding the --user flag. But seriously, use a virtual environment and spare yourself the trouble.

Either one of these commands will create a soft link to your cloned repository. Any changes in Python code you make there will be there when you import plasmapy from an interactive session.