Installing PlasmaPy for Development¶
Obtaining PlasmaPy source code¶
After creating your GitHub account, go to the PlasmaPy repository on GitHub 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 firstname.lastname@example.org: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 email@example.com:namurphy/PlasmaPy.git (fetch) origin firstname.lastname@example.org:namurphy/PlasmaPy.git (push) upstream email@example.com:PlasmaPy/PlasmaPy.git (fetch) upstream firstname.lastname@example.org: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.
To set up a development environment for PlasmaPy, we strongly recommend the Anaconda distribution.
After installing Anaconda, launch any conda environment. By default,
conda installs a
root environment, which you should be able to
source /home/user/anaconda3/bin/activate root
/home/user/anaconda3/ can be swapped to wherever your anaconda
On newer versions of Anaconda the recommended activation process has changed to:
. /home/user/anaconda3/etc/profile.d/conda.sh conda activate
On Windows, the way to do this is via running
from the Start Menu.
Git Bash may also work if you have added
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
On Windows, skip the
source part of the previous command.
In newer Conda versions, the command to run is
conda activate plasmapy
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
will notice that virtualenv has created a number of subdirectories:
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:
You should now see that your shell session is prepended with (plasmapy), like so:
This indicates that the virtualenv is running. Congratulations! When your’re done working on PlasmaPy, you can deactivate the virtualenv by running
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
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
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 .
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
import plasmapy from an interactive session. The exception
is Cython code.
Working with Cython code¶
We are still figuring this part out. Contributions are very welcome!
Cython poses a whole new set of issues for code development. When
writing Cython code, you need to recompile your current files for your
changes to take effect. This is accomplished, to the best of our current
understanding , via
python setup.py build_ext -i, as recommended by
the Cython development guide and as supported by the Astropy package
astropy_helpers. This places compiled
.so compiled libraries in the same location as your
.py sources - this plays well with import
python setup.py install or
pip install will also build
For now, the
.cpp sources are not included with the
source code, meaning that they are compiled on installation. This
solution is what we got working for distribution, but may change in the
The safest bet for running tests and checking documentation is using
python setup.py test and
python setup.py build_docs provided by
astropy_helpers. These commands copy the entire code base into a
temporary directory for isolation and build all Cython extensions there
before running tests and documenation builds.